Configure the Get Engagement Link API in Bullhorn Automation

The Get Engagement Link API lets external platforms, like a job board, generate a direct link to a Bullhorn Automation engagement. When a candidate applies for a job, the job board requests the link through this API and presents it on-screen so the candidate can complete a screener or survey as part of the application experience.

This article covers what the Get Engagement Link API does and how to configure it in Bullhorn Automation. For the Amplify screening setup and job board integration steps, see Using “Get Engagement Link” for Amplify Screen

Common Reasons You Might Use This

  • You want candidates to complete a screener or survey immediately after applying, without a separate follow-up message.

  • You are setting up a job board integration and need to configure the default engagement for the API.

  • Your integration partner has asked for your API key and endpoint details.

  • You want to use a submission-based screener so candidates are screened for the specific job they applied to.

  • You want to understand how the feature works before handing off the technical setup to a partner.

Before You Begin

To configure this setting, you need Admin access in Bullhorn Automation and an engagement already created to use as your default. If you haven't built your engagement yet, do that first before completing these steps.

Configure the Get Engagement Link API

Use these steps to connect a default engagement to the API and make your API key available for your integration partner.

  1. In Bullhorn Automation, go to Settings > API.

  2. In the Get Engagement Link section, use the Select Default Engagement drop-down to choose which engagement to use.

    • Only one default engagement can be configured.

  3. Click Save.

The default engagement must be saved before the API can be used. Only Admin users can access Settings > API.

How It Works

When an integration such as a job board calls the endpoint, Bullhorn Automation looks up the candidate or their job submission and returns a link to the default engagement. The candidate clicks the link and completes the screener or survey on your website.

If the candidate or submission doesn't exist in Bullhorn Automation yet, the system retrieves the records from the ATS and syncs them into Automation to generate the link.

Endpoint Parameters

Your integration partner uses these values when calling the endpoint. You won't configure them yourself. This section is here so you can share the details with your technical team or review them during setup.

Parameter

Required?

What it does

apiKey

Yes

Your Bullhorn Automation API key. Found in Settings > API.

candidateAtsId

Conditional

The candidate's ID in Bullhorn ATS.

Required when the default engagement is candidate-based.

submissionAtsId

Conditional

The job submission ID in Bullhorn ATS.

Required when the default engagement is submission-based.

engagementId

No

A specific engagement to use instead of the default.

If left out or invalid, the endpoint uses the default engagement.

Only one of candidateAtsId or submissionAtsId is needed per call, depending on whether the default engagement is candidate-based or submission-based. Passing the wrong ID type returns an error.

Troubleshooting

Use this section to diagnose common issues with the Get Engagement Link API.

If the API returns an error when called

Confirm that a default engagement is saved in Settings > API. The endpoint can't generate a link until one is configured.

If the wrong engagement link is generated

Check which engagement is selected as the default in Settings > API. To use a different engagement per call, use the engagementId parameter.

If a candidate ID error is returned

Check that the ID type matches the engagement type. Candidate-based engagements require candidateAtsId. Submission-based engagements require submissionAtsId. Passing the wrong type returns an error.

If the candidate record is not found

The system syncs the record from Bullhorn ATS automatically when the endpoint is called. If the candidate doesn't exist in the ATS either, the endpoint returns an error.

If your integration partner can't find the API key

The API key is only visible to Admin users in Settings > API.

Frequently Asked Questions

What engagement types work with this API?

Any engagement in Bullhorn Automation, including a survey, chatbot, or Amplify screening. The endpoint generates a link to whatever you set as the default.

Can this be used without a job board integration?

Yes. Any third-party system that can make an authenticated GET request can call this endpoint, as long as it works with candidate or submission records in Bullhorn ATS.

What happens if the candidate doesn't click the link?

They can still receive an invitation via email or text through an automation, as long as one is configured.

Is this available for all ATS platforms?

This feature is available for Bullhorn ATS only.

What about LinkedIn or Indeed?

This integration is designed for customer-owned job boards, or job boards managed by a Bullhorn Marketplace partner who controls the application experience. Platforms like LinkedIn and Indeed don't offer that level of customization on behalf of individual customers.