• 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.

Introduction

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.

Prerequisites

  • A basic understanding of the concepts of job posting.
  • A basic understanding of handling XML documents.
  • A basic understanding of HTTP requests & responses.

Process

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.

API requirements

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 is simply a combination of the individual salary parts.

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>bob@smith.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>bob.12345.123@smith.aplitrak.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_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>

XML Overview

TagExampleNotes
commandAddone of either 'Add' or 'Delete'
usernamebobsmithIssued by interface provider
passwordp455w0rdIssued by interface provider
contact_nameBob SmithFree Text, recruiter name as stored on AdCourier
contact_emailbob@smith.comFreetext, recruiter email address as stored on AdCourier
contact_telephone020 7987 6900Freetext, recruiter phone number as stored on AdCourier
contact_urlwww.smith.comFreetext, recruiters own website URL as stored on AdCourier
days_to_advertise7An Integer. The number of days the advert should be live on the website/job board for
application_emailbob.12345.123@smith.aplitrak.comAplitrak support is mandatory for job board integrations.
application_urlhttp://url.com/ad.asp?adid=12345123Apply-on-line support is advised for job board integrations.
job_referenceabc123Freetext, the reference number assigned to the advert by the recruiter
job_titleTest EngineerFreetext, the job title of the advert
job_typeContractone of: Contract, Permanent, Temporary
job_duration6 monthsFreetext, duration of the position (Contract roles)
job_startdateASAPFreetext, start date of the position
job_skillsvb, c++, perl, javaFreetext, specific skills/keywords relevant to the position
job_descriptionFreetext, 6000 char limit, detailed job description
job_locationLondonFreetext, from list provided
job_industryMarketingFreetext, from list provided
salary_currencygbpone of: gbp, usd, eur
salary_from25000A number (float) for the lower salary
salary_to30000A number (float) for the upper salary
salary_perannumSalary term, one of: annum, month, week, day, hour
salary_benefits+ Bonus and PensionFreetext, additional salary information
salary25000 - 30000 per annum + Bonus and PensionFreetext 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.