- Job Boards
Broadbean integration for Job Boards & Client career sites
Broadbean is an advert distribution tool which enables adverts to be submitted to multiple job boards via a single posting form. More information on the product can be found here.
This document is intended to provide detail specific to creating a 3rd party job advert posting interface on a job board/career site.
For new builds of websites, which intend to include a searchable jobs area, this document should be considered prior to site planning in order to avoid convoluted solutions later on.
For established job boards/career sites which require the addition of a 3rd party posting interface, this document explains the public facing aspects.
This document does not cover the internal database structure your website or job board should employ, nor does it provide or recommend specific concepts, beyond the remit of simply creating the interface.
How Adcourier works with Job Boards and Client career sites
- Client will login to their Broadbean Account when they have an advert to publish.
- Client will be able to select multiple channels, they wish to post their job advert to, this may include their own career site
- Based on the clients selection of websites to post to, Broadbean will create a posting form for the client to populate with their job data. The fields on this form will change dependent on which websites the client has selected. This ensures that the advert is as searchable and of the same quality, as if it was posted directly.
- The Client will then be able to see from within their Broadbean account, which of the adverts have been successfully posted and which have failed, this information is provided to Broadbean by each of the job boards/websites
- When the adverts receive applications, the client will be able to view and manage these CV's in their Broadbean account. This product is called Aplitrak (response tracking) and must be supported by all job boards/websites that we integrate with.
- A good understanding of the concepts of job posting.
- A good understanding of handling XML documents, or other methods
- A good understanding of HTTP requests & responses.
- The interface must accept one advert per transaction
- The interface must be multi-threaded / thread safe as we may make concurrent transactions
- Each advert transaction must be able to handle a new, unique email address (application_email). The email address we provide will be job specific as we use this to link the response back to the correct job record, and then Broadbean forward the application to the consultant's inbox.
- We block duplicate applications from the same applicant for the same job, thus we need the applicant's email address sent in the "From" field of the response or in the "Reply-To" address.
- Where the end user is likely to include direct employers / corporate companies, each advert transaction must be able to handle a new and unique application URL. Many of our direct employers / corporate companies prefer applicants to apply via an online application form and where this is the case the application URL field will be populated. The URL should be used when populated, otherwise applications should be sent to the email address field.
- In the event of a failure / error being encountered, the API must send a meaningful response. Examples include "Username/Password not recognised", "insufficient credit", "Database unable to serve request" etc. Please do not return error codes as these are meaningless to users.
The client will log into Broadbean when they have an advert to publish. They will select one or more destination job boards (this may include their own career site) and Broadbean creates a unique form based upon the selection.
Broadbean processes the data entered and sends an individual feed to each site. Each submission contains data for one advert, which is submitted as and when a user chooses to post.
The data will be sent to the 3rd party interface over a HTTP POST (the data will be in the body of the post). XML is our preferred format, but we can support other methods where XML cannot be supported. We can only submit data to a single posting URL.
The 3rd party interface (this interface is not created by Broadbean but is the responsibility of the 3rd party) should receive the data, process it and load the advert into the website database.
Your interface must accept a unique email address with each advert. This address should be used for applications, as we receive responses back into our system for applicant tracking purposes (Aplitrak).This is a mandatory requirement for all job boards and as part of this requirement job boards must return the candidates CV back to us along with the application.
When an advert is posted successfully the interface should print a success message back to the page, we are flexible in the format of your success message eg. Plain text/XML/HTML. Where the advert fails validation (for example "Invalid credentials" or "Invalid value in field Industry") an error message should be returned.
Where possible, we will recognise this error and forward the information to the end user.
The success message should include the URL to the advert on the site, as this enables us to provide a direct link to the job from our system.
A delete request can be actioned by the end user and this should remove the advert from the site prior to its natural expiry. Again, this will be submitted to the 3rd party interface over a HTTP POST.
Our Requirements from your API
We strongly recommend the client and website developers discuss and agree the website specification before signing any development order with Broadbean.
The following requirements should be considered when designing the interface:
The data will be passed to your interface in a specific format, however the format can be defined by you. We take this approach because each site has different requirements.
An XML example is provided below and can be followed or adapted where necessary. We support bespoke fields where needed. This information should be provided to us in your Supporting documentation.
XML Submission - Example
<?xml version="1.0" encoding="UTF-8"?> <job> <command>add</command> <username>bobsmith</username> <password>p455w0rd</password> <contact_name>Bob Smith</contact_name> <contact_email>firstname.lastname@example.org</contact_email> <contact_telephone>020 7987 6900</contact_telephone> <contact_url>www.smith.com</contact_url> <days_to_advertise>7</days_to_advertise> <application_email>email@example.com</application_email> <application_url>http://www.url.com/ad.asp?adid=12345123</application_url> <job_reference>abc123</job_reference> <job_title>Test Engineer</job_title> <job_type>Contract</job_type> <job_id>abc123_1234567</job_id> <job_duration>6 Months</job_duration> <job_startdate>ASAP</job_startdate> <job_skills>VB, C++, PERL, Java</job_skills> <job_description>This is the detailed description</job_description> <job_location>London</job_location> <job_industry>Marketing</job_industry> <salary_currency>gbp</salary_currency> <salary_from>25000</salary_from> <salary_to>30000</salary_to> <salary_per>annum</salary_per> <salary_benefits>Bonus and Pension</salary_benefits> <salary>£25000 - £30000 per annum + Bonus and Pension</salary> </job>
If XML cannot be supported please see examples of other available methods.
Field Overview - Example
|command||Add||one of either 'Add' or 'Delete'|
|username||bobsmith||Issued by third party developer, where your interface will require a username for authentication.|
|password||p455w0rd||Issued by third party developer, where your interface will require a password for authentication.|
|contact_name||Bob Smith||Free Text|
|firstname.lastname@example.org||Freetext, recruiter email address as stored on AdCourier|
|contact_telephone||020 7987 6900||Freetext, recruiter phone number as stored on AdCourier|
|contact_url||www.smith.com||Freetext, recruiters own website URL as stored on AdCourier|
|days_to_advertise||7||An Integer. The client can choose the number of days the advert should be live on the website/job board for. eg. 7 days/14 days.|
|email@example.com||Aplitrak support is mandatory for job board integrations.|
|application_url||http://url.com/ad.asp?adid=12345123||Apply-on-line support is advised for job board integrations. This will not need to be used for integrations with clients own career sites.|
|job_reference||abc123||Freetext, the reference number assigned to the advert by the recruiter. 20 char limit|
|job_title||Test Engineer||Freetext, the job title of the advert. 63 char limit.|
|job_type||Contract||one of: Contract, Permanent, Temporary|
|job_id||abc123_1234567||A unique string. To be used as an identifier for adding and deleting jobs from interface|
|job_duration||6 months||Freetext, duration of the position (Contract roles)|
|job_startdate||ASAP||Freetext, start date of the position|
|job_skills||vb, c++, perl, java||Freetext, specific skills/keywords relevant to the position|
|job_description||Detailed Job Description||Freetext, 6000 char limit, detailed job description. This field can accept HTML if required. This must be specified in your supporting documentation.|
|job_location||London||Freetext, from list provided|
|job_industry||Marketing||Freetext, from list provided|
|salary_currency||gbp||one of: gbp, usd, eur - Broadbean Recommend IS0.|
|salary_from||25000||A number (float) for the lower salary|
|salary_to||30000||A number (float) for the upper salary|
|salary_per||annum||Salary term, one of: annum, month, week, day, hour|
|salary_benefits||+ Bonus and Pension||Freetext, additional salary information|
|salary||£25000 - £30000 per annum + Bonus and Pension||Freetext salary information for display purposes (build from other salary objects)|
Information to be supplied to Broadbean prior to integration development
In order for us to set up integration to your 3rd party interface. Please use our online form to submit your feed specification to us.
Broadbean Contact Details
Integrations Project Co-Ordinator: Ali Bhatti, firstname.lastname@example.org, 0207 536 1661
Sales executive: UK Sales (Broadbean), email@example.com, 0207 536 1667