Skip to main content

Overview

StackOne allows you to integrate with Bullhorn for Assessment and Background Check to receive webhook notifications whenever a recruiter sends the test to a candidate, update the test result, and see the result on the candidate profile in Bullhorn. This guide covers how you can set up custom tabs in Bullhorn and integrate with StackOne.

Partnership Requirements

No formal partnership is required to configure the Bullhorn custom tab for Assessment & Background Check, however you must have administrative privileges for your Bullhorn account.

Provider Side Setup

1

Access View Layout

Log in to Bullhorn and click the Menu button.
Bullhorn Menu
Click the Admin button.
Admin Button
Click View Layout.
View Layout
Select the Candidate entity from the Field Map Entity dropdown menu.
Candidate Entity
2

Add a new Custom Tab

Navigate to the Custom Tab button.
Custom Tab Button
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 base 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:
  • User Types: Select the user types who will have visibility of this tab.
Custom Tab Configuration
Click the Save button.
Save Button
3

Locate the Custom Tab under Candidates

Navigate to the Candidates List page, click the Menu button, and then click Primary.
Primary Menu
Click the Candidates button.
Candidates Button
Click any candidate from the list.
Candidate List
You will find the custom tab on the candidate detail page either within the main tab area or under the More drop-down.
Custom Tab on Candidate Page

StackOne Configuration

1

Navigate to the ATS category

Navigate to the ATS category on the Integrations page and enable Bullhorn.
Bullhorn Integration Setup
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 specify different categories for integrations. It is up to you to determine which type of integration feature you want to offer your users within the Bullhorn Custom Tab. If your custom tab supports background check workflows, please select Background Checks.
  • 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: 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.
    The Package's List Endpoint URL allows StackOne to fetch a list of available packages from your system, while the Static Package ID is fixed and available for users to select on the provider's side.
    When you have a Package's List Endpoint URL
    A list of packages will be available to select in Bullhorn.
    Dynamic Package ID

    When you have a Static Package ID
    A static package ID will be available to select in Bullhorn.
    Static Package ID
    At least one field is necessary for making packages available in the Provider's UI. Preference will be given to the Package's List Endpoint URL, even if both fields are configured.
    Bullhorn Configuration Form
    Click on the Confirm or Save Changes button to enable OAuth APIs, which allows users to link their accounts via the StackOne Connector Hub.

ATS User Enablement

User can obtain an External Trigger Token if they wish to use a different token from another StackOne project. User can then update the externalTriggerToken in the query parameter of the endpoint URL.
Navigate to the Accounts page or the StackOne Connector Hub to link your Bullhorn account with StackOne.
Link Bullhorn account
You will receive the External Trigger Token, which must be passed as a query parameter along with the endpoint URL when setting up the custom tab in Bullhorn, as outlined in the Provider Side Setup.
External Trigger Token

ATS User Experience

After completing the configuration process, users will see the custom tab on the candidate detail page in Bullhorn.
Custom Tab on Candidate Page
Users can click on the Send Assessment/Background Check button, select one of the packages from the drop-down, and click on the Send button to send the assessment/background check test to the candidate.
Send Background Check Button
A webhook notification will be triggered and you will receive the notification. On Bullhorn UI, the status will be updated to Pending.
Webhook Notification
Once the result is updated in Bullhorn’s UI, users will see the updated results.
Updated Results

ATS User Experience Customisation

1

To Update the result via unified api

Utilise the following endpoints to update the results: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
ConditionUser sees in BullhornComments
Result statusStatus column will reflect the latest result’s statusResult enum values from Meta API result field
Result UrlVisible as a View Results link with 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.
Updated Results

Testing Checklist

Provider Setup Validation:
  • Logged-in with Admin account.
  • Selected valid User Types.
  • Valid StackOne URL along with the externalTriggerToken query parameter.
StackOne Configuration Validation: ATS User Activation Validation:
  • Valid externalTriggerToken to the query parameter.
Create a Webhook
  • Added a webhook for Bullhorn and enabled it with the events such as: Assessment Order or Background Check Order
  • Valid webhook URL to receive assessment/background check notifications.
ATS User Experience:
  • 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.
Update Result
  • Success response from the update result endpoint.
  • Updated result details to Bullhorn’s UI.

Troubleshooting

SymptomLikely causeFix
Unable to access/add custom tabLogged-in account is not an Admin accountLog in with an Admin account
External Trigger Token field is not visible at StackOne Connector HubSelected Authentication Type is incorrect.Select Authentication Type OAuth2 - Assessments/Background Checks instead.
Custom tab is not visible in candidate detail pageEnabled checkbox is not checked.Tick Enabled checkbox under the custom tab to enable the custom tab to visible within the candidate detail page.
Custom tab is visible however getting 500 Invalid URL.

Invalid External Trigger Token.

Invalid Package’s List Endpoint URL.
Verify the StackOne URL.

Verify External Trigger Token.

Verify Package’s List Endpoint URL.
Packages are not available to selectEmpty Response from the Package’s List Endpoint URL.Verify the Package’s List Endpoint URL and ensure it returns the expected package data.
Test notification is not received External Trigger Token is invalid.

Token is from the different StackOne Project.
Use a valid External Trigger Token from the correct StackOne Project.
Status updated to Pending but record not found when revisiting the custom tab Either invalid External Trigger Token.

Invalid webhook URL at StackOne.

Enabled events are not as expected.

Custom field is updated and not the previous one that is selected at the time of getting notification sent from the StackOne Connector Hub.

Custom Field data is corrupted due to reuse of that custom field at different places or for different custom tabs.
Verify the External Trigger Token.

Check webhook URL.

Check enabled events are expected.

Check the Custom Field data it can be corrupted.

Select the correct custom field from the StackOne Connector Hub.

Utilise a unique custom field and confirm it is not used elsewhere.
Results not updating in Bullhorn Custom field is updated and not the previous one that was selected at the time of notification sent from the StackOne Connector Hub.

Custom Field data is corrupted due to reuse of that custom field at different places or for different custom tabs.
Select the correct custom field from the StackOne Connector Hub.

Utilise a unique custom field and confirm it is not used elsewhere.
Result URL showing error when openedAdded result URL can be expired or is private.Ensure to add public or signed URLs; verify CORS and expiry.
For persistent issues, contact StackOne support with detailed error logs and configuration information.