Getting Started with the Bullhorn REST API

The Bullhorn REST API gives partner a simple yet powerful way to interact with the Bullhorn system. Because it uses HTTP requests and responses and standard data structures, the REST API is accessible from many programming languages and is particularly well-suited to mobile applications and applications that use the most current web technologies.

Get access to the Bullhorn REST API

Bullhorn uses OAuth 2.0 as the authorization mechanism for the Bullhorn REST API. See OAuth authorization for the Bullhorn REST API for high-level information about how Bullhorn uses OAuth with the REST API. Bullhorn customers can obtain OAuth keys for developing applications with the Bullhorn REST API by creating a support ticket via the Bullhorn Resource Center.

You must have a valid OAuth 2.0 API key that contains the following data before your application can perform the OAuth authorization process described below:

params description
redirect_uri URI for the location of your application provided to Bullhorn when registered
client_id ID generated by Bullhorn identifiny your account
client_secret Password for your application to authenticate into the system

Complete the authorization process

Get an authorization code

Your application must complete these steps to get an authorization code. These steps require Bullhorn user credentials, but may be performed programmatically or manually. Here we show the manual steps so you can quickly understand the process.

  1. Access the following URL, substituting your actual values for the placeholders in the query parameters:

    https://auth.bullhornstaffing.com/oauth/authorize?client_id={client_id}&response_type=code&redirect_uri={optional redirect_uri}&state={recommended state value}

    A login page is displayed.

    The state query parameter is recommended.The client uses this value to maintain state between the request and the callback. It should be used for preventing cross-site request forgery.

    The redirect_uri query parameter is optional. If used, the redirect_uri must match one of the redirect_uris specified in the OAuth API key.

  2. On the login page, user enters a valid Bullhorn username/password combination and clicks the Login button. A Terms of Service page is displayed.

  3. User clicks the Agree button to accept the terms of service.

    The page is redirected to the redirect URI with a code query parameter on the URL. The code value is the authorization code required to get an access token, which you use to get a Bullhorn session key required for REST API calls.

Get an access token

Your application uses the authorization code to get an access token. A valid access token is a required query parameter on a REST login request. This part of the process requires no direct user interaction.

Note: To get an access token, your application must make a POST request. For learning purposes, you can make manual POST, PUT, and DELETE requests in your web browser after installing an extension. On Google Chrome, install the Postman extension. On Mozilla Firefox, install the HTTP Resource Test extension.

Make a POST request with the following URL, substituting your actual values for the placeholders in the query parameters. If you specified a redirect_uri in the oauth/authorize request, you must specify the same redirect_uri in this request.

https://auth.bullhornstaffing.com/oauth/token?grant_type=authorization_code&code={auth_code}&client_id={client_id}&client_secret={client_secret}&redirect_uri={optional redirect_uri}

The POST response contains an access token that you use in REST API /login requests to obtain a Bullhorn session token and a base REST URL. The access token is valid for 10 minutes.

If Bullhorn has provided you with the ability to generate refresh tokens, the POST response also contains a refresh token. When the Bullhorn session expires, you use a refresh token to get a new access token without reauthorizing (getting another authorization code). A new refresh token is returned with every new access token. The refresh token has no expiration date/time, but it does expire when a new access token and refresh token are generated.

Use a refresh token to get a new access token

To obtain an access token with a refresh token, make a POST request with the following URL, substituting your actual values for the placeholders in the query parameters:

https://auth.bullhornstaffing.com/oauth/token?grant_type=refresh_token&refresh_token={refresh_token}&client_id={client_id}&client_secret={client_secret}

Familiarize yourself with the REST API

Making a REST call is as simple as sending an HTTP request to a server and getting an HTTP response back. Calls that get data from the server are simple URLs. The Bullhorn REST API uses JSON (JavaScript Object Notation) to structure all response data. The REST API also accepts JSON-formatted data for create, update, and delete (CRUD) requests. JSON uses a simple data structure that is very easy to read and understand.

The easiest way to get started with the REST API is by making REST calls in a standard web browser. You can make REST GET calls by entering the REST URL in the browser URL field and pressing Enter. You can make PUT, POST, and DELETE calls for CRUD operations with the Postman extension on Chrome or the HTTP Resource Test extension on Firefox.

The next steps are:

  • Start making REST calls.
  • Read the REST API Reference.
  • Read the Bullhorn Style Guide for user interface design guidelines.

If you have a question, you can post it on the support forums.

Log in to the REST API

The first call you make with the Bullhorn REST API is a login call. The login call returns a session key that you can use for subsequent requests. The login call is an HTTP GET request that looks like this:

Using version=* to get the latest version:

POST https://rest.bullhornstaffing.com/rest-services/login?version=*&access_token={xxxxxxxx}

Using version=2.0 to get the current version:

POST https://rest.bullhornstaffing.com/rest-services/login?version=2.0&access_token={xxxxxxxx}

The login URL uses HTTPS and includes the following components:

rest.bullhornstaffing.com Bullhorn server name
/rest-services Context root of the Bullhorn web application
/login login command
version=* version query parameter:, where * indicates the latest version and 2.0 indicates the current version.

A successful login response looks like this:

{
   "BhRestToken": "a33da348-d562-4211-a48c-8d8cac14a38e",
   "restUrl": "https://rest0.bullhornstaffing.com/rest-services/{corpToken}/"
}

The login response contains a session key named BhRestToken as well as the base URL for subsequent REST calls. The URL includes the Bullhorn corpToken to use with the current login.

Make a REST call to get a Bullhorn entity

After obtaining a session key you can make REST calls that get data or perform CRUD operations on the Bullhorn server. For example, a request to get a specific Candidate looks like this:

GET https://rest0.bullhornstaffing.com/rest-services/{corpToken}/entity/Candidate/{id}?BhRestToken={session_key}&fields=firstName,lastName,address

The get entity by id URL uses HTTPS and includes the following components:

rest.bullhornstaffing.com Bullhorn server name
/rest-services Context root of the Bullhorn web application
/entity entity command
Candidate Type of entity to get
{id} id of the entity
BhRestToken={session_key} Session key from successful login
fields=firstName,lastName,address Entity fields to include in the response

The response to this request is in JSON format and looks like this:

{
  "data" : {
    "firstName" : "FName01",
    "lastName" : "LName01",
    "address" : {
      "address1" : "123 Address1 Ave",
      "address2" : "# suite address2",
      "city" : "Cityville",
      "state" : "MA",
      "zip" : "01754",
      "countryID" : 1
    }
  }
}

Make a REST call to create a Bullhorn entity

A REST request to create a new entity is very similar to a request to get an entity. The differences are that the request is an HTTP POST rather than an HTTP GET, no id parameter is specified on the URL, and the body of the HTTP request contains field values for the new entity.

For example, the URL of a PUT request to create a new Candidate entity looks like this:

PUT https://rest0.bullhornstaffing.com/rest-services/{corpToken}/entity/Candidate?BhRestToken={session_key}

The PUT request body looks like this, where the xxxx values would be real values:

{
    "firstName": "xxxx",
    "lastName": "xxxx",
    "name": "xxxx",
    "username": "xxxx",
    "category": { "id": xxxx },
    "password": "xxxx",
    "owner": { "id": xxxxx},
    "address": {
        "address1" : "xxxx",
        "address2" : "xxxx",
        "city" : "xxxx",
        "state" : "NY",
        "zip" : 12345,
        "countryID" : x
    },
    "secondaryAddress": {
        "address1" : "xxxx",
        "address2" : "xxxx",
        "city" : "pxxxx",
        "state" : "MA",
        "zip" : 54321,
        "countryID" : x
    },
    "customDate1": xxxx,
    "dateAvailableEnd": xxxx,
    "dateAdded": xxxx,
    "ownerCorporation": { "id": xxxx },
    "userType": { "id": xxxx }
}

Get more information about REST and JSON

There is a great deal of introductory information about RESTful web services available online. The following articles are good starting points:

The following articles provide good information about JSON and JSONP: