Broadbean Technology FAQs

This will be a route on the receiving application or integration and not the candidate hub. This route will accept standard candidate data and return a standard response to be consumed by the hub.

If parsing is enabled, two additional candidate documents will be included. The raw parsed XML as a "tagged_cv" and a JSON document of type "parsed_cv" (both Base64 encoded).

Parsed CV example:

{ "email": "[email protected]", "last_name": "Frog", "first_name": "Leap", "locale": "en_gb", "street": "4 Apple Croft", "country": "England", "county": "West Midlands", "post_code": "CW3 9EW", "town": "Madeley", "skills": [ { "skill_name": "meeting facilitation", "experience": 2 } ] }

The candidate data will be signed, there is an authentication section at the end of the JSON.

The key purpose of the signature is to verify that the data has come from us and this is slightly different to the signature used for submitting data into us. This particular signature is generated by signing the following string (no username): <api_key>|<time_ms>

Request

POST https://candidateimporter.adcourier.com/url_of_your_candidate_importer.com/importer_route

Headers

Content-Type:application/json

Body

{

"meta_info" : {

"hub_transaction_id" : "UniqueHubTransactionId",

"hub_client_id" : "ClientIDFromCandidateHub",

"hub_candidate_id" : "CandidateIDFromHub",

"hub_source_id" : "SourceIDFromHub",

"hub_geostore_id" : "GeoRegionIDFromHub",

"hub_schema_version" : 1,

"import_process_report_url" : "http://candidatehub.adcourier.com/report/onetimetoken" # Report of processing to this URL

},

"candidate" : {

"name" : "John Renbourn",

"email" : "[email protected]",

"contact_telephone" : "0123 456 7890",

"mobile_telephone" : "0123 456 7890",

"location_address" : "Address Details",

"location_city" : "Edinburgh",

"location_county" : "Leith",

"location_country" : "Scotland",

"location_postcode" : "EH6 4AU",

"location_longitude" : "-0.564736",

"location_latitude" : "51.803398",

"current_job_title" : "Guitar Maestro",

"current_job_employer" : "Broadbean Technology",

"current_job_startdate" : "1944-08-08T00:00:00",

"current_job_enddate" : "2015-03-26T00:00:00",

"documents" : [

{

"filename" : "blah.doc",

"type" : "cv",

"content" : "base64"

},

{

"filename" : "blah.xml",

"type" : "tagged_cv",

"content" : "base64"

},

{

"filename" : "blah.json",

"type" : "parsed_cv",

"content" : "base64"

}

]

},

"context" : {

"job_id" : "129",

"shortlist_id" : "869",

"supplementary" : {

"arbitrary_context_1" : "12",

"arbitrary_context_2" : "13"

}

},

"authentication" : {

"api_key" : "123456789",

"time" : "1395834265000",

"signature" : "s6f74hd756heg6sgr6gfts64g6sgdf5462yehdg5fbrys7rjek9ksjurhdytchs65"

}

}

Response

Headers

Content-Type:application/json

Body

{

"success": 1,

"message": "Candidate Received for processing"

}

This a typical configuration you can use as a guide when creating you job posting API.

Content

Typical Advert Fields

Supported Formats of Advert Data

Default Values

Typical Advert Fields

This is an example of advert fields we can send to your site. if you require custom information please specify in your technical specification.

Node

Example Value

Notes

command/action

Add

One of either 'Add', 'Delete' or 'Update'.

username

bobsmith

Issued by you/your developer, where your interface requires a username for authentication.

password

p455w0rd

Issued by you/your developer, where your interface requires a password for authentication.

contact_name

Bob Smith

Recruiter name as stored within a client's AdCourier (Brodabean) account.

contact_email

[email protected]

Recruiter email address as stored within a client's AdCourier (Brodabean) account.

contact_telephone

020 7987 6900

Recruiter phone number as stored within a client's AdCourier (Brodabean) account.

contact_url

www.smith-recruitment-agency.com

Client's own website URL as stored within a client's AdCourier (Brodabean) account.

days_to_advertise

7

An Integer. A client can choose the number of days the advert should be active for on your career site/job board. Default options are: 7,14,21,28 days.

application_email

[email protected]

Email address used for forwarding applications to. Please read about Aplitrak - our applicant tracking system.

application_url

http://url.com/ad.asp?adid=12345123

Applications via a URL is advised for job board integrations. This, normally, is not used for integrations with clients' own career sites. Please read about Aplitrak - our applicant tracking system.

job_reference

abc123

Freetext. 20 char limit. Can be made unique if requested (by appending a time-stamp).

job_title

Test Engineer

Freetext. 63 char limit.

job_type

Permanent

Please see our Default Values.

job_duration

6 months

Freetext, duration of the position (Normally used for Contract positions).

job_startdate

ASAP

Freetext, a 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. This field can accept HTML if required. This must be specified in your technical specification.

job_location

London

For more information please see our Default Values.

job_industry

Marketing

For more information please see our Default Values.

salary_currency

gbp

For more information please see our Default Values.

salary_from

25000

A number (float) for the lower salary.

salary_to

30000

A number (float) for the upper salary.

salary_per

annum

For more information please see our Default Values.

salary_benefits

+ Bonus and Pension

Freetext, additional salary information.

salary

25000 - 30000 per annum + Bonus and Pension

Freetext salary information for display purposes (build as salary_from + salary_to + salary_benefits).

Supported Formats of Advert Data

Please see examples of the supported data formats Broadbean will send to your site. Please note, that the request structure can be altered to your requirements.

The data will be sent via HTTP POST and your website will receive, validate and display the data on the careers page. How the advert is displayed on the site is your decision, our main objective is to ensure the data we send across is displayed correctly.

XML

Content-Type: text/xml

Method: POST

Posting an advert

Request

<?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 protected]</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 protected]</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>

Response

<response>advert has been posted successfully</response>

<job_url>www.smith.com/jobs/12345</job_url>

Deleting an advert

Request

<?xml version="1.0" encoding="UTF-8"?>

<job>

<command>delete</command>

<username>bobsmith</username>

<password>p455w0rd</password>

<job_reference>abc123</job_reference>

</job

Response

<response>advert has been deleted successfully</response>

JSON

Content-Type: application/json

Method:POST

Posting an advert

Request

{

"command":"add",

"username":"bobsmith",

"password":"p455w0rd",

"contact_name":"BobSmith",

"contact_email":"[email protected]",

"contact_telephone":"02079876900",

"contact_url":"www.smith.com",

"days_to_advertise":"7",

"application_email":"[email protected]",

"application_url":"http://www.url.com/ad.asp?adid=12345123",

"job_reference":"abc123",

"job_title":"TestEngineer",

"job_type":"Contract",

"job_duration":"6Months",

"job_startdate":"ASAP",

"job_skills":"VB,C++,PERL,Java",

"job_description":"Thisisthedetaileddescription",

"job_location":"London",

"job_industry":"Marketing",

"salary_currency":"GBP",

"salary_from":"25000",

"salary_to":"30000",

"salary_per":"annum",

"salary_benefits":"BonusandPension",

"salary":"25000-30000perannum+BonusandPension"

}

Response

{

"status":"posted",

"job_url":"www.smith.com/jobs/12345"

}

Deleting an advert

Request

{

"command":"delete",

"username":"bobsmith",

"password":"p455w0rd",

"job_reference":"abc123"

}

Response

{

"status":"deleted"

}

URL Encoded

Content-Type: application/x-www-form-urlencoded

Method: GET

Posting an advert

Request

command=add&username=bobsmith&password=p455w0rd&contact_name=Bob Smith&

[email protected]&contact_telephone=020 7987 6900&

contact_url=www.smith.com&days_to_advertise=7&

[email protected]&

application_url=http://www.url.com/ad.asp?adid=12345123&

job_reference=abc123&job_title=Test Engineer&job_type=Contract&

job_duration=6 Months&job_startdate=ASAP&

job_skills=VB, C++, PERL, Java&

job_description=This is the detailed description&job_location=London&

job_industry=Marketing&salary_currency=gbp&salary_from=25000&

salary_to=30000&salary_per=annum&salary_benefits=Bonus and Pension&

salary=25000 - 30000 per annum + Bonus and Pension

Response

Advert has been posted successfully

www.smith.com/jobs/12345

Deleting an advert

Request

command=delete&username=bobsmith&password=p455w0rd&contact_name=Bob Smith&

[email protected]&contact_telephone=020 7987 6900&

contact_url=www.smith.com&days_to_advertise=7&

[email protected]&

application_url=http://www.url.com/ad.asp?adid=12345123&job_reference=abc123&

job_title=Test Engineer&job_type=Contract&job_duration=6 Months&

job_startdate=ASAP&job_skills=VB, C++, PERL, Java&

job_description=This is the detailed description&job_location=London&

job_industry=Marketing&salary_currency=gbp&salary_from=25000&

salary_to=30000&salary_per=annum&salary_benefits=Bonus and Pension&

salary=25000 - 30000 per annum + Bonus and Pension

Response

Advert has been deleted successfully

Default Values

Prior to starting an integration, we request from you lists/drop-down values you have on your site. However, you can set your site to use our default values provided below.

Job Types

Permanent

Contract

Temporary

Locations

We have 90,000+ global locations which can be selected from an autocomplete list on our job posting form.

When an advert is submitted to your site a location can be sent as a text, for example,Europe, England, London, City of London, or as a specific ID. As long as you provide us with a list of locations and corresponding IDs we can map them against our locations.

Industries

When an advert is submitted to your site an industry can be sent as a text, for example, Engineering, or as a specific ID. As long as you provide us with a list of industries and corresponding IDs we can map them against ours. Or alternatively, we can set it as a custom drop-down in case your industries differ too much from ours.

Accountancy

Admin and Secretarial

Advertising and PR

Aerospace

Agriculture Fishing and Forestry

Arts

Automotive

Banking

Building and Construction

Call Centre and Customer Service

Community Services

Consultancy

Defence and Military

Design and Creative

Education and Training

Electronics

Engineering

FMCG

Fashion

Financial Services

Graduates and Trainees

Health and Safety

Hospitality and Catering

Human Resources and Personnel

IT

Insurance

Legal

Leisure and Sport

Logistics Distribution and Supply Chain

Manufacturing and Production

Marketing

Media

Medical and Nursing

Mining

New Media and Internet

Not for Profit and Charities

Oil and Gas

Pharmaceuticals

Property and Housing

Public Sector and Government

Purchasing and Procurement

Real Estate and Property

Recruitment Consultancy

Retail

Sales

Science and Research

Senior Appointments

Social Care

Telecommunications

Trade and Services

Transport and Rail

Travel and Tourism

Utilities

Salary Periods

annum

month

week

day

hour

Salary Currencies

GBP

EUR

USD

AUD

NZD

CAD

TWD

JPY

CHF

AED

PLN

HUF

MXN

SEK

NOK

DKK

SGD

HKD

CNY

MYR

ANG

ARS

AZN

BDT

BGN

BHD

BND

BOB

BRL

BWP

CLP

COP

CRC

CZK

DOP

DZD

EEK

EGP

FJD

HNL

HRK

IDR

ILS

INR

JMD

JOD

KES

KRW

KWD

KYD

KZT

LAK

LBP

LKR

LTL

LVL

MAD

MDL

MKD

MOP

MUR

MVR

NAD

NGN

NIO

NPR

OMR

PEN

PGK

PHP

PKR

PYG

QAR

RON

RSD

RUB

SAR

SCR

SKK

SLL

SVC

THB

TND

TRY

TTD

TZS

UAH

UGX

UYU

UZS

VEF

VND

XAF

XBT

XOF

YER

ZAR

ZMK

We strongly recommend the client/site owner and the website developer discuss and agree on the website specification before signing any development contract with Broadbean.

These are the requirements your API should meet in order for us to be able to integrate with it.

Overview

We have 3 main types of integration:

We send advert data to an end-point defined and hosted by you. Referred to as an Instant feed.

You fetch advert data from an end-point defined and hosted by Broadbean. Referred to as a Batch On Demand feed.

We upload advert data to an FTP server defined and hosted by you.Referred to as an FTP Batch feed.

Instant Feed - Requirements

Your API must fulfil the following requirements:

It must have only HTTPS end-points.

Accept one advert per transaction.

Be multi-threaded / thread safe as we may make concurrent transactions.

After an advert is sent to your API, we require you to return a clear success message. For example, "advert has been posted successfully".

Nice to have: After an advert is sent your API returns the advert URL as well as the sucess message.

Each advert transaction must be able to handle a new, unique email address or URL (Aplitrak). The email address/URL provided will be job specific. Please read about Aplitrak.

Email Application: Applications have to come from a unique applicant email address which can be sent in the "From" or "Reply-To" email header field. Otherwise, applications from the same email address will be de-duplicated.

In the event of an advert posting failure, your API must send a meaningful response. Examples include "Username/Password not recognised", "Insufficient credit". We will then be able to map your error codes to our user-facing messages.

The advert data will be sent to your API end-point in one of the supported formats: XML, JSON or URL encoded. Please see examples here.

Please familiarise yourself with the typical feed configuration here first then submit your technical specification here.

Batch On Demand Feed - Requirements

Your API must fulfil the following requirements:

Fetch adverts on a chosen frequency from our end-point.

For Job Boards: there has to be a node in the advert structure to identify what client the advert belongs to. Example, <company>Test Recruitment Agency</company>

Accommodate delete functionality: Broadbean will delete the XML advert data from the provided URL after a client sends a delete request.

Each advert must be able to handle a new, unique email address or URL (Aplitrak). The email address/URL provided will be job specific. Please read about Aplitrak.

Email Application: Applications have to come from a unique applicant email address which can be sent in the "From" or "Reply-To" email header field. Otherwise, applications from the same email address will be de-duplicated.

The advert data provided will be in one of the supported formats: XML or JSON. Please see examples here.

Please familiarise yourself with the typical feed configuration here first then submit your technical specification here.

FTP Batch Feed - Requirements

Your API must fulfil the following requirements:

Specify to us how frequent we can submit adverts to your FTP.

You must provide us with a username and password to login to the FTP server.

You must provide us with a file name we need to use for adverts. For example, Broadbean_job.xml.

For Job Boards: there has to be a node in the advert structure to identify what client the advert belongs to. Example, <company>Test Recruitment Agency</company>

Accommodate delete functionality.

Each advert must be able to handle a new, unique email address or URL (Aplitrak). The email address/URL provided will be job specific. Please read about Aplitrak.

Email Application: Applications have to come from a unique applicant email address which can be sent in the "From" or "Reply-To" email header field. Otherwise, applications from the same email address will be de-duplicated.

The advert data provided will be in one of the supported formats: XML or JSON. Please see examples here.

Please familiarise yourself with the typical feed configuration here first then submit your technical specification here.

Our Search product allows our clients to seek candidates on various job boards/platforms from a single interface. More information about this product can be found here.

This article provides an API guideline you (a job board) should follow in order for Broadbean to integrate with your CV/Rsum search.

Requirements for Your CV/Rsum API

Your API must:

Support the following calls:

Authentication

Keyword/criteria search

Candidate profile view

CV download

Respond in real-time; connections with no data flow will be terminated and marked as failed after 20 seconds

Be multi-threaded as we will make concurrent requests

In the event of a failure/error, send a meaningful response, eg. "Username/Password not recognised", "Insufficient credit" etc.

Support pagination

Be able to mirror searching directly on the job board as much as possible

Authentication

Authentication can be done as a separate request or be included into the keyword/criteria search call.

We support various types of authentication, eg. Basic Auth, OAuth, Bearer Token etc.

Keyword/Criteria Search

To make a request we need to know:

HTTPS end-point

Supported fields:

mandatory, optional

possible values if a drop-down, any mappings

validations/exceptions

How the pagination works

Request example. We support the following formats: XML, JSON, URL encoded

The response has to include:

A total number of results

A list of candidates' snippets/previews with a unique ID for each of them

Request example

{

"Account": {

"Username": "[email protected]",

"Password": "Password!$#"

},

"Search_Query": {

"Keywords": "IT manager OR Project manager",

"Location": "London",

"Radius": "10",

"Contract_Type": "Permanent",

"Salary_Cur": "GBP",

"Salary_Min": "30000",

"Salary_Max": "40000",

"Salary_Rate": "annum",

"Updated_within": "90",

"Results_per_page": "25",

"Page": "1"

}

Response example

{

"Search_Response": {

"Total_Results": "150",

"Results": [

{

"Record_Id": "12345",

"Name": "John Smith",

"Email": "[email protected]",

"Snippet": "Candidate description....",

"Last_updated": "10.05.2019"

},

{...},

{...},

{...},

{...}

]

}

}

Candidate Profile View

To make a request we need to know:

HTTPS end-point

Whether it is chargeable or not

How we pass a candidate ID

Request example. We support the following formats: XML, JSON, URL encoded

The response has to include:

The candidate profile including name and email address

Sometimes includes the CV text

Request example

{

"Account": {

"Username": "[email protected]",

"Password": "Password!$#"

},

"Candidate_Profile_Query": {

"Record_Id": "1234"

}

}

Response example

{

"Candidate_Profile_Response": {

"Address": "...",

"Education": [...],

"Experience": [...],

"Skills": [...],

"CV_text": "...",

...

}

}

CV Download

To make a request we need to know:

HTTPS end-point

Whether it is chargeable or not

How we pass a candidate ID

Request example. We support the following formats: XML, JSON, URL encoded

The response has to include:

1 CV file

In one of these supported formats: .doc, .docx, .pdf, .txt, .rtf, .html

Maximum size 10MB

Request example

{

"Account": {

"Username": "[email protected]",

"Password": "Password!$#"

},

"Candidate_CV_Query": {

"Record_Id": "1234"

}

}

Response example

{

"Candidate_CV_Response": {

"File": {

"Transform": "base64",

"Filename": "1234.doc",

"Content-type": "application/msword",

"File": "Base64 encoded file"

}

}

}

Introduction

Broadbean facilitates the ability to pre-populate a client's applicant tracking systems apply form in order to reduce the drop off rate and improve ROI for your clients.

In order to utilise this, you will first need to contact our Integration team on 0800 169 3921 to discuss and be set up with the relevant technical information required to access the API. Please note, this feature is currently in BETA and you may be added to a waiting list for the required information.

Technical Overview

In order to import a candidate's profile, you must send a HTTP request at the time of apply to our Candidate Hub if it is enabled on the job. We can send you a flag per job during posting that you can store to identify jobs with this feature, or you can check at runtime whether the application URL resides on aplitrak.com. The Candidate Hub will respond with a Transaction ID and a URL for you to redirect the candidate to.

Please note, we recommend strict timeout settings on the API call to the Candidate Hub and if you are not presented with a Candidate Hub ID for any reason, the applicant workflow should remain uninterrupted without the pre-population feature being utilised.

Technical Specification

The route accepts a JSON package with configuration information, basic authentication and a base64 encoded package of raw candidate information. It responds with a simple binary indicating whether the package was accepted and the Candidate Hub Transaction ID and the application URL of the job.

The endpoint for the Candidate Hub is https://candidatehub.adcourier.com/candidates/prepopulator_receiver and requests should be sent via POST with a content type of application/json.

Example request

{

"transaction" : {

"source_id" : "native"

},

"candidates" : [

{

"data" : "base64Data", # Arbitrary candidate data as base64 string

"context" : {

"candidate_source_id" : "provided",

"job_id" : "12345",

"job_data" : {

"apply_url" : "https://aplitrak.com...",

"reference" : "",

"title" : "",

"description" : "",

"contract_type" : "",

"industry" : "",

"salary_per" : "hour|day|week|month|annum",

"salary_from" : "",

"salary_to" : "",

"salary_currency" : "GBP", #iso4217

"location" : ""

},

"consent_level" : "future_roles|role_only"

}

}

]

}

Candidate data should be sent as a base64 string, the candidate data should be structured like the below example:

{"candidate" : {

"name" : "John Renbourn",

"email" : "[email protected]",

"contact_telephone" : "0123 456 7890",

"mobile_telephone" : "0123 456 7890",

"location_address" : "Address Details",

"location_city" : "Edinburgh",

"location_county" : "Leith",

"location_country" : "Scotland",

"location_postcode" : "EH6 4AU",

"location_longitude" : "-0.564736",

"location_latitude" : "51.803398",

"current_job_title" : "Guitar Maestro",

"current_job_employer" : "Broadbean Technology",

"current_job_startdate" : "1944-08-08T00:00:00",

"current_job_enddate" : "2015-03-26T00:00:00",

"documents" : [

{

"filename" : "blah.doc",

"type" : "cv",

"content" : "base64"

},

{

"filename" : "blah.json",

"type" : "parsed_cv",

"content" : "base64"

}

]

}

}

Response

{

"success": 1,

"message": "Data Received",

"hub_transaction_id": "1234566",

"url": "https://www.aplitrak.com/?adid=xyz&hub_transaction_id=1234566"

}

Please note, you will be provided with a candidate_source_id during onboarding with our Integration team. To get started, please call us on 0800 169 3921 to discuss.

Pre-Development Process

A contract has to be signed for a feed development with Broadbean.

When an agreement is in place, we will get in touch with you in order to acquire your tech team contact.

Once we have received your developer details we will ask for a technical specification of your site API and liaise in case of questions.

When we are clear on the configuration and it passes our initial testing (advert posted, an application made, advert deleted) we will schedule the work in. Please be aware of our lead-time, advised by Sales prior to signing a contract.

Development Process

Development (in average 2 week)

Our developers run multiple tests to see how the data is being displayed on your site; this includes posting, applying and deleting test adverts.

We need to contact you or your developers if we encounter any issues. This is often where the process slows and delays occur.

Please note: It is important that your technical specification doesn't get changed once we commence our work. Otherwise, it will lead to delays in the build process.

Quality Assurance (in average 1 week)

Our dedicated QA team test the full functionality of the feed.

Go Live

When the feed is ready we will release it to the Broadbean production system, activate it within your account and let you know that it is available to you.

Please note

Our release days are only Tuesdays and Thursdays.

If you need any updates to the feed, that are outside the original specification, we will need to schedule it.

At any stage of this process if we don't hear back from you or your developers for longer than 2 weeks we will have to remove the integration from the schedule. Lead times will apply when re-scheduling.

Common Problems

Lack of communication between a client and their developers when finalising an initial feed specification. This normally results in delays because the specification gets changed.

Additional costs - clients might not be fully aware of the additional costs that might be levied by their website developers to make their site compatible with Broadbean and able to receive a feed to job adverts. We urge you to discuss your website and inquire about additional costs with your developers BEFORE signing any development order with Broadbean. Broadbean will not be able to discuss estimated costs provided by your developers for the development work.

Long response time of client’s website developers.

A website not fully functional - Broadbean will test the basic functionality of the site to ensure the jobs we post can be found by your candidates i.e. keyword search, job type, salary, location etc. We often find issues with this requiring more work from your developers.

Candidate tracking (Aplitrak) support - An inability to work with our Aplitrak response tracking technology. We also look at the application process to make sure all responses are tracked back into Broadbean. We often find that the site is not set up and ready to handle this. This is covered in the technical link above and we would urge you to draw your developer’s attention to this.

We call it Aplitrak.

If you have a job board or a career site, that you would like us to integrate with, you must support at least one of the following application methods.

[email protected]

Aplitrak - Email

In every advert, sent out via our platform, we attach a unique email address which allows the tracking of applications back into our system and displays them against the corresponding advert.

When a candidate applies for an advert posted to your site via Broadbean your system should be able to send out an email to the unique tracking email address supplied with the advert. Please see the requirement below:

You need to specify an advert field where we will supply this email address to, e.g. <application_email>.

If you have an application form on your site, we just ask that once the candidate has entered their info into your system, you email that info over to the unique email address for that job. We recommend you hide our unique tracking email address behind the apply button on the application form.

CV should be sent as an attachment. Supported formats are .doc, .docx, .txt, .pdf. We do not accept .zip files.

Cover letter or any other candidate info should bee sent in the email body. The email can be in plain text or HTML.

Applications sent from the same candidate's email address will be de-duplicated.

Applicant's email address has to be passed in either of the email headers From or Reply-To. Including the applicant's name is beneficial as we will be able to display it against the application. Please see examples:

From: Candidate Name [email protected]

OR

Reply-To: Candidate Name

Application tracking support is a mandatory requirement for all job boards. As a part of this requirement, job boards must be able to return the candidates' CV into Broadbean.

Example of an Aplitrak email address: [email protected]

Aplitrak - URL

Broadbean also supports an application URL (apply online) as a response tracking method. This URL is sent with an advert and re-directs candidates to a page, hosted by Broadbean or on an employer site, to complete the application process. Applications will still be tracked into Broadbean. Please see the requirement below:

You need to specify an advert field where we will supply this URL to, e.g. <application_url>.

If you chose to use Broadbean apply online page you will not be able to customise it.

Example of our apply online page:

Broadbean Technology is the global, market-leading job posting system that enables our clients to instantly distribute adverts to thousands of job boards and social media channels. To find out more information about Broadbean's multiposting and other products, please visit our website.

This is a typical user workflow:

our development process here

Client Career Site

An integration with your career site will allow you to use Broadbean to post jobs onto it as well as to other job boards and social channels.

Job Board

An integration with your job board will allow our mutual clients to use Broadbean to post jobs to your website.

Both integration types, with a Career Site or a Job Board, are built by Broadbean’s Integrations team. Your website must have an API for receiving advert data from a 3rd party company, in this case Broadbean.

Please read about .

Fill out my Wufoo form!

Liza Shevchenko, Integrations Manager, EMEA

I'm Liza, the manager of the Integration team. I work alongside an amazing team which helps you to integrate your website with our system. We are here to helpyou throughout the development process and are here to save the day if needed!

Keeley Curtis,Project Coordinator, EMEA

I'm Keeley and I am aProject Coordinator in Integrations team. I am always happy to help with any integration questions. Also, I will be in touch with you throughout the whole integration process: from getting your technical specification to making your feed active within your account.

Darin Danker, APAC

I’m Darin and I am part of the Broadbean Integrations team in the APAC region. I work with job boards and client in our region to provide information and support at every stage of the integration process. Let’s discuss how we can help you.

At the time of application, you will receive a parameter "__BBPPID" on your application URL.

Using this information you can send a HTTP request to the Broadbean Candidate Hub to request the candidate's profile information (provided by the job board they have applied on in real-time) and pre-populate your apply form.

To fetch the candidate you will need to make a GET request to

https://candidatehub.adcourier.com/candidates/ats-prepop/<__BBPPID>

With the following custom headers:

X-PREPOP-SIGNATURE: <SIGNATURE_HASH>

X-PREPOP-DESTINATION: <DESTINATION_ID> (provided by BB)

X-PREPOP-SIGNATURE-TIME: <SIGNATURE_TIME_EPOCH>

<__BBPPID> is the param that Broadbean append to the apply URL during the pre-populate application redirection.

<SIGNATURE_HASH> is the SHA256/HMAC hash generated when using the private encryption token ( provided by BB ) on the string of "<DESTINATION_ID>|<SIGNATURE_TIME_EPOCH>"

We recommend strict timeouts around requests to the Candidate Hub and if the request is unsuccessful for any reason you should not block the applicants ability to apply without the pre-population.

The __BBPPID is only valid for 1 minute and after this time the retrieval will not be successful.

Example request

Headers:

X-PREPOP-SIGNATURE:e52cbe1ec5c26ff40652109b5620882bffcd6001ecd35ed83da3702538c1c8c4

X-PREPOP-DESTINATION: mydestination

X-PREPOP-SIGNATURE-TIME: 1541605485000

GET https://candidatehub.adcourier.com/candidates/ats-prepop/eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1NDE2MDU3ODEuMCwicHJlcG9wX2NhY2hlX2lkIjoiOTlEQzFCRkMtRTJBNC0xMUU4LUIxRTUtQjk0MTQ3NDRBMzEwIiwiY2xpZW50X2lkIjoiY2hyaXNwIn0.Rg-8gc8DEFklUIBCIO8xCmHIjgZPHBKW3MVAR5TM5Pc

Example response

{

"meta_info" : {

"hub_transaction_id" : "UniqueHubTransactionId",

"hub_client_id" : "ClientIDFromCandidateHub",

"hub_candidate_id" : "CandidateIDFromHub",

"hub_source_id" : "SourceIDFromHub",

"hub_geostore_id" : "GeoRegionIDFromHub",

"hub_schema_version" : 1,

"import_process_report_url" : "http://candidatehub.adcourier.com/report/onetimetoken"

},

"candidate" : {

"name" : "John Renbourn",

"email" : "[email protected]",

"contact_telephone" : "0123 456 7890",

"mobile_telephone" : "0123 456 7890",

"location_address" : "Address Details",

"location_city" : "Edinburgh",

"location_county" : "Leith",

"location_country" : "Scotland",

"location_postcode" : "EH6 4AU",

"location_longitude" : "-0.564736",

"location_latitude" : "51.803398",

"current_job_title" : "Guitar Maestro",

"current_job_employer" : "Broadbean Technology",

"current_job_startdate" : "1944-08-08T00:00:00",

"current_job_enddate" : "2015-03-26T00:00:00",

"documents" : [

{

"filename" : "blah.doc",

"type" : "cv",

"content" : "base64"

},

{

"filename" : "blah.json",

"type" : "parsed_cv",

"content" : "base64"

}

]

},

"context" : {

"candidate_source_id" : "provided",

"job_id" : "12345",

"job_data" : {

"apply_url" : "https://aplitrak.com...",

},

"consent_level" : "future_roles|role_only"

}

}

Callback

Upon a successful application, a POST request should be sent to the import_process_report_url to confirm a successful application:

POST https://candidateimporter.adcourier.com/candidate/report/onetimetokenRequest

Content-Type: application/json

{

"success" : 1, # boolean 1-successful 0-failed

"status": "success", # success, failure, duplicate, rejected

"message": "Application completed",

"hub_transaction_id" : "UniqueHubTransactionId",

"hub_candidate_id" : "CandidateIdinTransaction",

"destination_candidate_id" : "UID of candidate in ATS"

}

Response

Content-Type:application/json

{

"success": 1,

"message": "Process Report Received"

}

The context node in the outbound candidate object will look something like this:

{

"context" : {

"job_id" : "R-444",

"candidate_source_id" : "CB",

"candidate_source_name" : "Careerbuilder",

"source_candidate_id" : "cand-411402",

"supplementary" : {

"custom_field_user_id" : "bob-123",

"candidate_status" : "ranked"

},

"source" : {

"job_id" : "R-444",

"custom_field_user_id" : "bob-123"

},

"transformer" : {

"candidate_source_id" : "careerbuilder",

"candidate_source_name" : "Careerbuilder",

"source_candidate_id" : "cand-411402",

"candidate_status" : "ranked"

},

"plugin" : {

"source_mapper" : {

"candidate_source_id" : "CB"

}

}

}

}

The following context fields are “known” context fields, which are considered to be commonly found fields used in many candidate application workflows:

It is important to note that all context fields are not guaranteed and will only be included where sufficient data is available for the candidate.

“job_id” - ID of the job which the candidate applied to

“shortlist_id” - ID of a shortlist which a recruiter has selected to list the candidate against

“candidate_source_id” - ID of source from which this candidate originated

“candidate_source_name” - Nice name of source from which the candidate originated

“source_candidate_id” - ID of the candidate record within the source system

There will also be a supplementary context node

“supplementary” - aggregated context information that does not fall into any of the “known” context fields

The remaining context nodes contain all arbitrary context information ( name:value pairs ) that were available during the process at each stage before determining the final context

“source” - context information provided explicitly from the source

“transformer” - context information made available during transformation of thesource candidate format into the candidate hub format

“plugin” - context information generated by any plugins that were processed against the candidate

Fill out my Wufoo form!

Before any new ATS integration is added to the Broadbean product suite it needs to have to completed our approval process.

This is made up of the following steps:

Partner Kick-Off Call

Technical call / Workflow Sign Off

Development

Integration Pre- Approval

Training

Approval

With one API call you arrive on the Broadbean posting steps when a job is posted for the first time. When it has been posted before you’ll be directed to our BB dashboard.

The dashboard displays information about any previous postings and enables you to view the advert on the job board (if they make the link available to BB), delete, edit or resend the advert.

With any integration we need to consider five key areas:

User mapping Each user in your system will need to be able to enter their Broadbean username

Publish Post plus Dashboard will post the advert and give you access to the dashboard for other actions if the advert has been published before. You will find additional information on how to submit your content in the FAQ section.

Status This is the status of the advert on the individual jobboards and will be handled by the dashboard.

Delete The dashboard allows a global and channel level delete. We suggest that you send us a global delete request when the job is closed in your system and this can be handled by the Integration Light Box.

Source tracking Either You will send us the apply URL in the JSON request and we will append a source parameter to this or you will receive candidates with their source from our candidate hub. Information on our candidate hub can be found here

This route is used to query a report on a specific transaction

Request

GET https://candidateimporter.adcourier.com/candidate/report/hub_transaction_id

Headers

Content-Type:application/json

Response

Headers

Content-Type:application/json

Body

{

"hub_transaction_id" : "UniqueHubTransactionId",

"attempts" : [

{

"destination_id" : "1234",

"date_of_process" : "2015-02-09 18:57",

"success" : "1",

"status" : "success",

"message" : "Candidate Processed Successfully"

},

{

"destination_id" : "1234",

"date_of_process" : "2015-02-09 21:57",

"success" : "0",

"status" : "failed",

"message" : "Failed - Authentication details incorrect"

},

}

This route is used as a callback and is directed to the import_process_report_url supplied in the intial candidate push

Request

POST https://candidateimporter.adcourier.com/candidate/report/onetimetoken

Headers

Content-Type:application/json

Body

{

"success" : 1, # boolean 1-successful 0-failed

"status": "success", # success, failure, duplicate, rejected

"message": "Additional information on the Process report",

"hub_transaction_id" : "UniqueHubTransactionId",

"hub_candidate_id" : "CandidateIdinTransaction",

"destination_candidate_id" : "UID of candidate in ats"

}

Response

Headers

Content-Type:application/json

Body

{

"success": 1,

"message": "Process Report Received"

}

This route accepts a JSON package with configuration information, some basic authentication and a base64 encoded package of raw candidate information. It responds with a simple binary indicating whether the package was accepted. It also contains a message for display plus a transaction ID to be used to query the status of the processing.

Request

POST https://candidateimporter.adcourier.com/candidates/receiver

Headers

Content-Type:application/json

Body

{

"transaction" : {

"client_id" : "clientmapperID", # ID for the candidate importer client mapper

"source_id" : "transactionSourceID", # Source ID to link to transformer (Transaction/Publisher Source)

"geostore_id" : "russia" # Optional; Force any storage of candidate to region

},

"candidates" : [

{

"data" : "base64Data", # Arbitrary candidate data as base64 string

"context" : { # Optional; Candidate Context Information

"job_id" : "JobID", # ID of the Job the candidate is actioned against or within

"shortlist_id" : "ShortlistID", #ID of the Shortlist the candidate is actioned against or within

"candidate_source_id" : "CandidateSourceId", # Source of the Candidate i.e. Careerbuilder

"arbitrary_context_1" : "Context", # Any additional arbitrary context information

"arbitrary_context_2" : "Context"

}

},

{

"data" : "base64Data"

}

],

"authentication" : {

"api_key" : "123456789",

"time" : "1395834265000",

"signature" : "s6f74hd756heg6sgr6gfts64g6sgdf5462yehdg5fbrys7rjek9ksjurhdytchs65"

}

}

Response

Headers

Content-Type:application/json

Body

{

"success": 1,

"message": "Data Received",

"hub_transaction_id": "1234566"

}

A centralised hub to accept packages of candidate data in native formats, transform and normalise them, store central business logic and export a standardised result set to an endpoint.

Bean Widgets is a lightweight JSON API used to integrate a variety of Broadbean functionality into ATS and CRM systems using simple widgets.

It supports Posting, Job Post Dashboard, Search and Advert Responses management and is targeted at partners who want to deploy the core Broadbean functionality quickly and efficiently. All users will be supplied with an API Key and a secret key or encryption token for each client they act on behalf of.

There are several key concepts common to each call:

Identification node

client_id - An AdCourier Client ID

adc_username - Broadbean AdCourier username of ATS user

Authentication node

api_key - a Broadbean API access token (contact Broadbean Client Support for more details)

time - the current epoch time in milliseconds

signature - an HMAC SHA256 hex digest of the following string: sprintf( "\%s|\%s|\%s", ADC-USERNAME, TIME, API-KEY), using the CLIENT-SECRET-KEY - e.g. hmac_sha256_hex( adc_username + '|' + time + '|' + api_key )

Filters

All vacancies on Broadbean are identified using filters

It is strongly recommended that these are custom fields supplied for each vacancy posted

The custom fields should be a unique identifier (or identifiers) of the vacancy in the ats.

Every job posted from Broadbean's system is considered a new advert, if your system updates an advert based on the job reference, we will implement unique referencing. This ensures every advert sent to you will be a new advert and our systems will be synchronised.

In most cases, the unique reference will be the user entered information, appended by an underscore and the epoch time of the job posting.

There are two ways for advert to be removed from your website, the first is for it to expire after a set duration. This duration should be calculated by the 'days to advertise' sent to you during the initial posting. You are responsible for expiring adverts, Broadbean will not send a delete request to your system in this case.

The second is for the user to decide to remove the advert before its natural expiry. To achieve this the user will use the 'delete' function in the Broadbean interface, this will send a real time delete request to your website. You should act on this request immediately and provide Broadbean with a response if it has been successfully removed.

Broadbean has 2 methods of tracking applications, the first is via email. In this instance we will send you a unique email address per job which applications should be emailed to - you're likely already doing this but to end users.

For Job Boards, we can also provide an Application URL. When an Application URL is provided, you should redirect applicants to the URL at the time of application. Broadbean will record the click and provide this in reports to our clients, the applicant will be redirected to the client's own website to finish their application.

Having a good integration with job boards is key to what we do at Broadbean. We need to ensure that our clients experience the same level of advert quality as if they were advertising direct. Therefore, for every integration we ensure we can find the advert using the filtering on the website.

Broadbean recommend you display the region of the location when viewing a job, this is to ensure candidates don't apply for jobs that are outside of their desired location. For example, if Fred lives in Kent and he applies for a job in Gillingham - he would have quite the commute to Gillingham in Dorset.

Ensuring your website works for our global client base is very important to us, therefore, we ask that we can post a test advert that will include foreign characters to check that your website handles the encoding correctly. This allows us to catch any issues before it affects our mutual clients.

Broadbean checks the entire response for a success message including the response headers. By default, headers will include 'OK' and therefore Broadbean will always treat adverts as successful. It is important that the response body contains something more identifiable such as 'Advert successfully posted'.

The job reference field is free text in the Broadbean interface, however, if the client is using an ATS/CRM to post adverts via our system, this field can optionally be locked to ensure the value doesn't change. You should create your own ID for jobs posted to your website rather than rely upon the job reference field, this is not guaranteed to be unique or in the same format.

The short answer is no, but if you're interested in why, please read on. Our aplitrak email addresses are only sent for our Aplitrak customers, for customers without Aplitrak we send their own email address.

When an advert is 'Sent Without Changes' in the Broadbean system, the email address will remain the same on the advert too - this allows us to group responses together for the end user.