The Bullhorn REST API gives partners 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:

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

Complete the authorization process

Determine the correct data center for your user

The example URLs below include a variable named {value_from_loginInfo} to represent the data center part of the URL. Run the following GET rest-services/loginInfo request with your API_Username to return the list of correct URLs for that user:
https://rest.bullhornstaffing.com/rest-services/loginInfo?username={API_Username}

If you do not use the correct URLs for a user, you will receive a 307 redirect to the correct data center. Your code must be written to handle that 307 redirect.

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-{value_from_loginInfo}.bullhornstaffing.com/oauth/authorize?client_id={client_id}&response_type=code&action=Login&username={username}&password={password}&redirect_uri={optional redirect_uri}&state={recommended state value}

If you do not include action=Login&username={username}&password={password} in the URL, you will be prompted with a login page if running in a browser:

https://auth-{value_from_loginInfo}.bullhornstaffing.com/oauth/authorize?client_id={client_id}&response_type=code&redirect_uri={optional redirect_uri}&state={recommended state value} * The user enters a valid Bullhorn username/password combination and clicks the Login button. A Terms of Service page is displayed. * 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.

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.

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-{value_from_loginInfo}.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-{value_from_loginInfo}.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 to the rest-services server for the data center. The login call returns a session key that you can use for subsequent requests. The login call is an HTTP POST request that looks like this:

Using version=* to get the latest version:

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

Using version=2.0 to get the current version:

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

The login URL uses HTTPS and includes the following components:

rest-{value_from_loginInfo}.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": "1234_5945926_32b73003-3b3a-4ebf-9a87-5894201b0ac3",

   "restUrl": "https://rest{swimlane#}.bullhornstaffing.com/rest-services/{corpToken}/"
}

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

Important: For performance and load reasons you must NOT perform a fresh REST API login before every API request. The session key from a single login response should be used for all subsequent requests until the session expires. When the current session key expires, your query will return a 401 response. On this response you should perform the OAuth refresh token flow to receive a new session token. Use the returned session token for subsequent API requests until it expires, at which point this process should be repeated. Note that Bullhorn will apply strict limits to login rates, and may block login requests that occur too frequently.

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, where you replace {swimlane#} with the actual swimlane number:

GET https://rest{swimlane#}.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{swimlane#}.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://rest{swimlane#}.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: