Use the Bullhorn Automation API
The Bullhorn Automation API lets you build custom integrations between Bullhorn Automation and external platforms. Use it to create and update contacts, manage list membership, sync placements, run job matching, and generate engagement links. This article covers each available endpoint, including the HTTP method, request URL, and required and optional fields.
This documentation is only accessible to Admin users. Navigate to to find your API key.
Common Reasons You Use the Bullhorn Automation API
Use this API when you need to connect an external platform directly to Bullhorn Automation. Common scenarios include:
- Adding candidates from a website sign-up form directly into a Bullhorn Automation list
- Removing a contact from a list when they opt out through a third-party tool
- Syncing placement data from your ATS to trigger follow-up automation workflows
- Finding candidates who match an open job using Bullhorn Automation's matching engine
- Showing a candidate the best matching jobs from a job board integration
- Generating a direct engagement link for a candidate mid-application
API Key
All API requests require a valid API key. To generate a new key, navigate to and click Generate New API Key.
Treat your API key like a password. If it is compromised, generate a new one immediately. All previous requests using the old key will stop working.
Add/Update Contact
Use this endpoint to create a new contact in Bullhorn Automation or update an existing one. You can optionally add the contact to a list in the same request.
Before using this endpoint:
- If you specify a ListName, it must match an existing list in Bullhorn Automation exactly
- Contacts can only be added to One Time lists
- Candidates can only be added to Candidate-based lists
- Sales Contacts can only be added to Sales Contact-based lists
HTTP Method: POST
Request: https://api.herefish.com/candidates/addToList?apiKey={API_KEY}
| Field | Description | Required |
|---|---|---|
| The contact's email address | Yes | |
| ListName | The name of an existing Bullhorn Automation list | No |
| IsSalesContact | Set to true for Sales Contacts; false for Candidates | No |
| AtsCandidateId | The numeric candidate ID from your ATS | No |
| AtsCandidateIdString | The string-based candidate ID from your ATS | No |
| AtsOwnerId | The numeric owner ID from your ATS | No |
| AtsOwnerIdString | The string-based owner ID from your ATS | No |
| FirstName | Contact's first name | No |
| LastName | Contact's last name | No |
| Status | Contact's status (for example, Active) | No |
| Type | Contact type (for example, Hot) | No |
| Position | Contact's job title or position | No |
| Category | Contact category (for example, Technology) | No |
| PhoneNumber | Contact's phone number | No |
| City | Contact's city | No |
| State | Contact's state | No |
| ZipCode | Contact's ZIP code | No |
Remove from List
Use this endpoint to remove a contact from a specific list in Bullhorn Automation. Both Email and ListName are required.
HTTP Method: POST
Request: https://api.herefish.com/candidates/removeFromList?apiKey={API_KEY}
| Field | Description | Required |
|---|---|---|
| The contact's email address | Yes | |
| ListName | The name of the list to remove the contact from | Yes |
Get Contact
Use this endpoint to retrieve a contact record when you know the Bullhorn Automation contact ID.
HTTP Method: GET
Request: https://api.herefish.com/candidates/getContact/{ID}?apiKey={API_KEY}
| Parameter | Description | Required |
|---|---|---|
| {ID} | The Bullhorn Automation contact ID (path parameter) | Yes |
| apiKey | Your API key | Yes |
Add/Update Placement
Use this endpoint to create a new placement record in Bullhorn Automation or update an existing one.
Start Date and End Date values must use ISO 8601 format. For example: 2024-05-28T19:40:36+00:00.
HTTP Method: POST
Request: https://api.herefish.com/matches/placement?apiKey={API_KEY}
| Field | Description | Required |
|---|---|---|
| AtsPlacementId | The numeric placement ID from your ATS | Yes |
| AtsPlacementIdString | The string-based placement ID from your ATS | No |
| AtsCandidateId | The numeric candidate ID from your ATS | Yes |
| AtsCandidateIdString | The string-based candidate ID from your ATS | No |
| AtsOwnerId | The numeric owner ID from your ATS | No |
| AtsOwnerIdString | The string-based owner ID from your ATS | No |
| StartDate | Placement start date in ISO 8601 format | Yes |
| EndDate | Placement end date in ISO 8601 format | No |
| Status | Placement status (for example, Approved) | Yes |
| JobTitle | Job title for the placement | No |
| EmploymentType | Employment type (for example, Contract) | No |
| EmployeeType | Employee type (for example, W2) | No |
| Company | The company name for the placement | No |
Get Candidates For Job
Use this endpoint to return a ranked list of candidate IDs that best match a specific job in your ATS.
About automationId:
- This parameter is optional. Leave it unset to use your default matching settings.
- Set it to the automation ID whose matching settings you want to use for this request.
- Set it to -1 if you have a single automation with an AutoMatch step.
HTTP Method: GET
Request: https://api.herefish.com/jobs/getCandidatesForJob?apiKey={API_KEY}&id={ATS_JOB_ID}&automationId={AUTOMATION_ID}
| Parameter | Description | Required |
|---|---|---|
| apiKey | Your API key | Yes |
| id | The ATS job ID to match against | Yes |
| automationId | The automation ID to load matching settings from | No |
Find Similar Jobs
Use this endpoint to return a list of job IDs most similar to a specified job. This is useful for surfacing related opportunities to candidates.
The maxCount parameter is optional. The maximum allowed value is 50.
HTTP Method: GET
Request: https://api.herefish.com/jobs/findSimilarJobs?apiKey={API_KEY}&id={ATS_JOB_ID}&maxCount={MAX_COUNT}
| Parameter | Description | Required |
|---|---|---|
| apiKey | Your API key | Yes |
| id | The ATS job ID to find similar jobs for | Yes |
| maxCount | Maximum number of results to return (up to 50) | No |
Get Jobs For Candidate
Use this endpoint to return a ranked list of job IDs that best match a specific candidate.
The maxCount parameter is optional. The maximum allowed value is 50.
HTTP Method: GET
Request: https://api.herefish.com/candidates/getJobsForCandidate?apiKey={API_KEY}&id={ATS_CANDIDATE_ID}&maxCount={MAX_COUNT}
| Parameter | Description | Required |
|---|---|---|
| apiKey | Your API key | Yes |
| id | The ATS candidate ID to match against | Yes |
| maxCount | Maximum number of results to return (up to 50) | No |
Match Candidates Webhook
Configure this webhook to override the Bullhorn Automation candidate matching algorithm. When a job enters an automation with the Match Candidates step set to third-party matching, Bullhorn Automation calls your specified endpoint and uses the response to determine which candidates to match. This option is only visible if third-party matching is enabled for your account.
This feature requires Bullhorn Automation Enterprise Edition and the Webhooks and API tabs enabled. Contact your Account Manager if you are unsure which package you have.
To configure, navigate to and select Edit. Complete the following fields:
| Field | Description |
|---|---|
| Method | The HTTP method for the request: GET, POST, or PUT. |
| URL | The endpoint Bullhorn Automation will call. Supports Bullhorn Automation merge tags, including the required tags listed below. |
| Header | Optional. Configure one or more headers using a Header Prefix | Header Content format. Use this for authentication, since the webhook does not support direct user auth. |
| Response | The format of the response from your endpoint. Options: Array of objects (candidate ID is a property on an object, which may include a match score) or Array of Candidate IDs (candidate IDs returned directly in an array). |
| Candidate IDs Field Name | The name of the field in the response that contains the candidate ID(s). Use dot notation for nested fields. For example: ParentObject.ChildObject.CandidateID. |
| Match Score Field Name | Optional. Only available when Response is set to Array of objects. The field name containing the match score from your algorithm. Expected value is between 0 and 1. If provided, the score will display in Bullhorn Automation. |
The following merge tags are required in either the URL or Data fields so your algorithm can filter candidates correctly:
- MinScore: The minimum score a candidate must meet to be included. Value between 0–1.
- MaxCandidateCount: The maximum number of candidates to return.
- MaxDistanceMiles: The maximum distance in miles between the candidate and the job.
- CandidateIdsInList: The response must be a subset of this list of ATS candidate IDs.
Test the Match Candidates Webhook
- Navigate to .
- Confirm the webhook is set to Active.
- Select Test Webhook.
- Fill out the form and select Test Webhook to send a test request to your endpoint.
Get Engagement Link
Use this endpoint to generate a direct URL to a Bullhorn Automation engagement for a specific candidate or submission. This is commonly used by job boards to embed an engagement in the application experience.
For full configuration steps, see Configure the Get Engagement Link API in Bullhorn Automation.
Troubleshooting
Use this section to resolve common issues when working with the Bullhorn Automation API.
- If your request returns a 401 error, your API key may be invalid or expired. Regenerate it in .
- If a contact is not added to a list, verify that the ListName matches an existing list exactly, including capitalization.
- If Add/Update Contact fails, confirm that the Email field is included in the request body.
- If a Sales Contact fails to add to a list, confirm IsSalesContact is set to true and the list is a Sales Contact-based list.
- If Add/Update Placement fails, confirm that AtsPlacementId, AtsCandidateId, Status, and StartDate are all present.
- If Get Candidates For Job returns no results, verify the id matches a valid ATS job ID and that matching is configured in the referenced automation.
Frequently Asked Questions
Answers to common questions about using the Bullhorn Automation API.
Where do I find my API key?
Navigate to . Click Generate New API Key to create one. Only Admin users can access this page.
Can I add a contact to multiple lists in one request?
No. Make one request per list.
What date format do I use for placement start and end dates?
ISO 8601 format. For example: 2024-05-28T19:40:36+00:00.
What is the maximum number of results I can get from the matching endpoints?
50. Set maxCount=50 to return the maximum number of results.
My API request is not working. Where do I start?
Confirm your API key is valid and included in every request, and that all required fields are present in the request body.