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 |
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.