- Job Boards
AdCourier integration for Job Boards & Client career sites
AdCourier 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 public website/job board.
For new builds of corporate 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 websites and job boards 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 the website or job board should employ, neither does it provide or recommend specific concepts beyond the remit of simply creating the interface.
- A basic understanding of the concepts of job posting.
- A basic understanding of handling XML documents.
- A basic understanding of HTTP requests & responses.
The end user will log into AdCourier when they have an advert to publish. They will select one or more destination job boards (this may include their own career site) and AdCourier creates a unique form based upon the selection. This ensures that the advert is as searchable and of the same quality, as if it was posted directly.
AdCourier 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 submit field value pairs where XML cannot be supported.
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.
The 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/
When an advert is posted successfully the interface should print a success message back to the page. 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.
The following requirements should be considered when designing the interface:
- The interface must accept one advert per transaction
- The interface must be multi-threaded as we may make concurrent transactions
- Each advert transaction must be able to handle a new, unique email address. In most cases the address we provide will be job specific as we use this to link the response back to the correct job record, and then 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 data will be passed to the interface in a specific format, however the format can be defined by the 3rd party. We take this approach because each site has different requirements.
A simple XML example is provided below and can be followed or adapted where necessary. We support bespoke fields where needed.
All the fields in the table "XML Overview" below are available to a feed as standard, however it is unlikely any feed will require all fields.
For example, it would be pointless for the interface to require all salary fields, as the
Example XML Submission
<?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>email@example.com</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>firstname.lastname@example.org</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_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>
|command||Add||one of either 'Add' or 'Delete'|
|username||bobsmith||Issued by interface provider|
|password||p455w0rd||Issued by interface provider|
|contact_name||Bob Smith||Free Text, recruiter name as stored on AdCourier|
|email@example.com||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 number of days the advert should be live on the website/job board for|
|firstname.lastname@example.org||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.|
|job_reference||abc123||Freetext, the reference number assigned to the advert by the recruiter|
|job_title||Test Engineer||Freetext, the job title of the advert|
|job_type||Contract||one of: Contract, Permanent, Temporary|
|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||Freetext, 6000 char limit, detailed job description|
|job_location||London||Freetext, from list provided|
|job_industry||Marketing||Freetext, from list provided|
|salary_currency||gbp||one of: gbp, usd, eur|
|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 by 3rd party prior to integration
In order to set up integration to the 3rd part interface, the following information will be required prior to feed development:
- URL - This is the URL to the page on your site which will accept the data. This is normally either a page expecting XML, a web service or a HTML form expecting field value pairs.
- Required Fields - A table similar to "XML Overview" should be provided. This will outline the fields you are expecting, plus any predetermined values for those fields (for example for industry and location).
- An example of the expected XML
- Support telephone number and Support email address - These will be used internally by Broadbean.
- Contact telephone and Contact Email address - These will be displayed on our site within the subscriptions area.