Bullhorn public API for jobs

Summary

The Bullhorn public API for jobs is a REST API that provides read-only access to a limited set of fields associated with jobs a customer has marked “Published - Approved” in Bullhorn.

The public API also supports the candidate application process for published jobs. After the set of published jobs is retrieved, candidate applications, also known as web responses, can be sent back to Bullhorn.

Getting started with the API

To get started, Bullhorn Support provides you with the Bullhorn customer numeric cluster (cls) and alphanumeric corp token (token) identifiers. After the customer has authorized the integration, the Bullhorn marketplace support team enables the public API settings for the customer and provides them with their cls and token.

To test the sample calls below, update the {cls} and {token} values with the correct cls and token provided by Bullhorn Support. Note that not all cls and token identifiers are the same length.

Customers must use the standard job publishing workflow for a job to be accessible with the public API. This is available from Select an Action > Publish on a job record in Bullhorn. Identify published jobs Use the following GET call to identify published jobs. You can change the specific fields requested as well as the desired count, start, and sort:

https://public-rest{cls}.bullhornstaffing.com/rest-services/{token}/search/JobOrder?query=(isOpen:1)&fields=id,title,publishedCategory(id,name),address(city,state),employmentType,dateLastPublished,publicDescription&count=20&sort=-dateLastPublished&start=0

fields=* returns all available public JobOrder fields. The default set of available public JobOrder fields is address(address1, city, state, zip, countryID), benefits, bonusPackage, dateAdded, dateEnd, dateLastPublished, employmentType, id, isOpen, isPublic, payRate, publicDescription, publishedCategory(id, name), publishedZip, responseUser(id, firstName, lastName), salary, salaryUnit, startDate, title, travelRequirements, willRelocate, willSponsor, yearsRequired.

Available job fields can only be added or removed by Bullhorn Support with permission from the customer, via a system setting called publicRESTJobAPIFieldList.

Create web response/candidate application

After retrieving the published jobs, you can display the content for job seekers and begin to collect candidate applications. Use the POST /apply/{jobId} call, where {jobId} is the Bullhorn job id to send candidate data back to Bullhorn:

https://public-rest{cls}.bullhornstaffing.com/rest-services/{token}/apply/{jobId}/raw?externalID=Resume&type=Resume&firstName=Robert&lastName=Testman&email=robert%40testman.org&format=docx

You can send the following candidate value in the apply call firstName, lastName, email, phone,source.

The first five values can be added to an apply form if desired, but you may wish to send a uniform source value for all applicants originating from your integration.

A CV or resume file is also required. Data from the file is parsed to the candidate record, including name, email, and phone if not provided in the URL.

You must pass values in as URL parameters. Only the file gets passed in through the request body.

If you want to provide an option for the applicant to compose or copy and paste skills and experience information, input from a text block on a form can be submitted as a .txt file. For this workflow, you may want to establish a default file name that reflects the origin of the application.

The response to the POST call indicates whether a candidate record was created or updated, and if the resume parse was successful. The email address of the candidate is used for duplicate checking. For example:

{
  "candidateAlreadyExisted" : false,
  "wasResumeParsedSuccessfully" : true,
  "jobSubmission" : {
    "id" : 280,
    "status" : "New Lead"
  },
  "jobOrder" : {
    "id" : 105,
    "title" : "Admin Assistant II"
  },
  "candidate" : {
    "id" : 10617,
    "firstName" : "Robert",
    "lastName" : "Testman",
    "phone" : null,
    "email" : "robert@testman.org"
  }
}