Bullhorn Assessment or Background Check Custom Tab Integration

​

Overview

​

Partnership Requirements

​

Provider Side Setup

1

Access View Layout

Log in to Bullhorn and click the Menu button.

Click the Admin button.

Click View Layout.

Select the Candidate entity from the Field Map Entity dropdown menu.

2

Add a new Custom Tab

Navigate to the Custom Tab.

Click the Add New button and enter the required information in the fields:

• Name: The name of the tab can be any text, e.g. Assessments or Background Checks
• Enabled: Tick this box to enable the tab
• URL: Enter the endpoint URL along with the query parameter: externalTriggerToken

https://api.stackone.com/external-trigger/bullhorn_ats?externalTriggerToken=<your-external-trigger-token>

The endpoint URL must include the externalTriggerToken query parameter, which you will receive from the StackOne Connector Hub. This token verifies requests from Bullhorn for the specific account.

To obtain the External Trigger Token, please follow these steps:

• StackOne Configuration
• ATS User Enablement

• User Types: Select the user types who will have visibility of this tab.

Click the Save button.

3

Locate the Custom Tab under Candidates

Navigate to the Candidates List page, click the Menu button, and then click Primary.

Click the Candidates button.

Click any candidate from the list.

You will find the custom tab on the candidate detail page either within the main tab area or under the More drop-down.

​

StackOne Configuration

1

Navigate to the ATS category

Navigate to the ATS category on the Integrations page and enable Bullhorn.

2

Complete the configuration form

Fill out the necessary fields in the Bullhorn - Configuration model:

• Authentication Type: Select OAuth2 - Assessments/Background Checks to utilise the assessments/background checks integrations.
• Partner Category: Bullhorn does not define separate integration categories. You choose which feature to surface in the custom tab. If the tab is for background checks or assessments, select the corresponding category: Background Checks or Assessments.
• Package’s List Endpoint URL: Implement and provide an endpoint to StackOne, which StackOne will use to retrieve the list of packages when the recruiter wants to send a test to a candidate. Implement the following POST endpoint:
  curl --location 'https://your-domain.com/<route-to-the-post-endpoint>' \
  --header 'Content-Type: application/json' \
  --header 'x-stackone-signature: string' \
  --header 'Authorization: Basic <base64encoded-bullhorn-api-key>' \
  --data '{
    "account_id": "456551489512493413",
    "provider": "bullhorn_ats"
  }'
  
  The expected response of the POST endpoint (list of packages). Refer to:
  • List Assessments Packages
  • List Background Check Packages
  Enter the endpoint into the designated field:
  https://your-domain.com/<route-to-the-post-endpoint>
  
• Package ID: If you do not have the Package’s List Endpoint URL, you can add a static package ID that will be visible to the recruiter when they want to send a test to the candidate.
  
  Click on the Confirm or Save Changes button to enable OAuth APIs, which allows users to link their accounts via the StackOne Connector Hub.

3

Create a Webhook

Navigate to the Webhooks page, click + Add webhook, and complete the form:

• Name: Enter a recognisable name for your webhook.
• URL: Enter the URL where the webhook will send notifications of enabled events.
  

4

Select webhook event

Navigate to the Events tab and enable webhook events for Assessment & Background Check, such as Assessments Order & Background Check Order.

Click the Confirm button to save the webhook.

​

ATS User Enablement

​

ATS User Experience

​

ATS User Experience Customisation

1

To Update the result via unified api

Utilise the following endpoints to update the results:

• Assessment Update Result
• Background Check Update Result

Utilise the following endpoint to get endpoint’s metadata to update the result of the assessment or background check:

• Connector Meta Information with the provider key bullhorn_ats for model assessments/results.update or background_checks/results.update

Fields (when provided)	User sees in Bullhorn	Comments
Score’s value	Score column will reflect the latest score’s value
Result	Status column will reflect the latest result’s status	Result enum values from Meta API result field
Submission Date	Date column will reflect the latest submission date
Result Url	Results URL column will reflect the latest Result URL as a View Result link

2

How will the results of the assessment/background check be displayed to the user in Bullhorn?

When a user opens a Assessment/Background Check custom tab, they will see the updated result with their score and status.

​

Testing Checklist

• Logged-in with Admin account.
• Created and enabled a custom tab with valid user types assigned.
• Added a custom tab for Assessment or Background Check as mentioned in the Provider Side Setup.
• Valid StackOne URL along with the externalTriggerToken query parameter.

• Selected OAuth2 - Assessments/Background Checks Authentication Type.
• Package’s List Endpoint URL is correct.
• Package’s List Endpoint response is expected according to the following endpoint’s response:
  • List Assessments Packages
  • List Background Check Packages

• Valid externalTriggerToken to the query parameter.

• Added a webhook for Bullhorn and enabled it with the events such as: Assessments Order or Background Check Order
• Valid webhook URL to receive assessment/background check notifications.

• Custom tab is visible in the candidate detail page either within the main tab area or under the More dropdown.
• When selecting a package and sending the webhook, the status is updated to Pending along with actions that is updated to Sent.

• Success response from the update result endpoint.
• Updated result details to Bullhorn’s UI.

​

Troubleshooting