Custom components can utilize Bullhorn REST services in order to retrieve or update data. Authentication follows the same flow as typical user authentication, which is summarized here:

Getting Started with REST

Prerequisites

A partner API key must be configured by a Bullhorn administrator as a REST API key and also have a client ID set.

Customer Admin Setup

Navigate to Admin > View Layout for the desired entity. Select Custom Cards, Custom Tabs, or Custom Menu Actions for the type of component being configured.

Note: User type based access restriction is only available in novo.

When configuring a custom component, select the REST API partner key configured by an administrator:

custom_tab_key

Custom Component Redirect

When navigating to the custom component in Bullhorn, a call will be made to the CustomComponent/redirect service. That service will generate the proper endpoint for the custom component. The generated endpoint will include the following:

  • EntityType
  • UserID
  • CorporationID
  • PrivateLabelID
  • EntityID
  • currentBullhornUrl
  • authCode

The custom component will automatically redirect to the generated endpoint. The provided authCode parameter can then be used to perform authentication within the custom component.
A session can only be generated for a limited time using the authCode because it will expire for security reasons.

As an example, the generated endpoint to reach a custom component might look like this:

http://some-server:123/custom-component?EntityType=Candidate&UserID=123&CorporationID=12345&PrivateLabelID=100&authCode=1:14ef5acf-9cf7-4cb8-90aa-8649c94e5af8&EntityID=123&currentBullhornUrl=example.com

Custom Component Authentication

The custom component endpoint will be provided a valid authCode that can be used to generate a session with the Bullhorn REST API. In total, partners will need the following information to get a Bullhorn REST token:

  • code (AKA authCode, which is automatically provided as parameter)
  • client_id (must be the same one configured on the custom component by a Bullhorn admin)
  • client_secret

The client_id and client_secret values should already be known by the partner. For more information about how those values are used for OAUTH authentication, refer to the document linked above.
The authorization code has been automatically generated and provided as part of the endpoint params.

Note: The authCode will only be sent if the selected Partner API Key has an OAuth Shared Secret defined.

Getting an OAUTH Token

The partner’s custom component can then call the /oauth/token?grant_type=authorization_code service as described in the REST guide. They will provide the code (AKA authCode), client_id, and client_secret. As an example, that POST call might look like this:

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

The call will return the following:

  • access_token
  • token_type
  • expires_in
  • refresh_token

REST Login

The custom component will then have all the necessary information to perform a REST login and obtain a Bullhorn REST token which can be used to make REST service calls. That POST call might look like this:

https://rest.bullhornstaffing.com/rest-services/login?version=*&access_token=something

The response will contain…

  • BhRestToken
  • restUrl

The BhRestToken and restUrl can then be used like normal to execute REST calls against the Bullhorn API. For more information on how to do that, refer to the REST documentation linked above.