Bullhorn integration · Event subscriptions + REST API
Score Bullhorn candidates with HireLayer
Bullhorn parses resumes itself and is rolling out a parser built with Textkernel technology, a company Bullhorn owns. HireLayer is an independent complement that processes data in the EU: it scores each submission against the job order with an explanation per criterion, and returns normalized skills your recruiters can search.
- Trigger
- Event subscription: JobSubmission inserted
- Bullhorn API
- REST API, OAuth 2.0 and a BhRestToken session
- Write-back
- Note, custom fields, work history, skills
- Cost
- 2 credits per submission
- 1Bullhorn logs the submissionBullhornA candidate is submitted to a job order, or applies from a job board as a web response. Bullhorn adds an INSERTED event for the JobSubmission to your subscription.
- 2Parse the resumeHireLayerYour service reads the events on a schedule, downloads the Resume attachment with /file/Candidate/{id}/{fileId} and sends it, with the job order ID, to HireLayer Resume Scorer, which parses it first.
- 3Score against the job orderHireLayerResume Scorer compares the resume with criteria taken from the job order description and returns a score and an explanation per criterion.
- 4Write back to BullhornBullhornA note on the candidate linked to the job order, the score in a custom field of the submission, and skills or work history when the record lacks them.
What staffing teams do with HireLayer and Bullhorn
Sort web responses
Job board applicants arrive as submissions with the status New Lead. A score on each one lets recruiters call the strongest maches first instead of working in arrival order.
Prepare client shortlists
Send the candidates of a job order, already parsed, by their application_id to HireLayer Resume Scorer with precise_ranking on, and get them back in order, each with a score and a ranking reason to support the submittal.
Searchable skills
Match HireLayer’s normalized skills to your Bullhorn Skill list and add them to primarySkills, so candidates parsed years appart share the same skill names.
Backfill imported records
Candidates imported from an older system may have a resume attachment but no work history. Parse the attachment and create CandidateWorkHistory and CandidateEducation entries.
Connect Bullhorn to HireLayer
This is a service you run on a schedule, for example a serverless function or an n8n workflow. It needs Bullhorn REST API access, which Bullhorn does not include in ATS Growth (formerly Team Edition).
- 1
Request API credentials
Open a support ticket in the Bullhorn Resource Center to get an OAuth client ID, client secret and registered redirect URI. Use a dedicated API user whose entitlements cover candidates, submissions, files and notes.
- 2
Log in and keep the session
Call GET https://rest.bullhornstaffing.com/rest-services/loginInfo?username=… to find your data center, get an OAuth access token (valid 10 minutes), then POST /rest-services/login for a BhRestToken and your restUrl. Refresh the token instead of logging in before every call.
- 3
Subscribe to submissions
Create the subscription once with PUT /event/subscription/hirelayer?type=entity&names=JobSubmission&eventTypes=INSERTED, then read it on a schedule, for example every 30 minutes, with GET /event/subscription/hirelayer?maxEvents=100.
- 4
Extract criteria, parse, score and write back
Send each job order’s description once to HireLayer Job Criteria Extractor with the job order ID as job_id: HireLayer stores it with its criteria, for free. For each event, load the submission, download the resume, send it to Resume Scorer, which parses and scores it in one call, and create a note with PUT /entity/Note.
Where HireLayer results go in Bullhorn
Bullhorn creates entities with PUT and updates them with POST. Work history and education are separate entities linked to the candidate, and custom fields are set up per account in Field Mappings. Resume Scorer keeps the parsed resume: read its fields for free with GET /api/v4/resumes/{application_id}.
| HireLayer field | Bullhorn REST API | Note |
|---|---|---|
| score + summary + criteria[] | PUT /entity/Note (personReference, commentingPerson, action, comments) | action must be in your commentActionList |
| score | JobSubmission customInt1–5 (POST /entity/JobSubmission/{id}) | For example score × 100 |
| resume.work_experiences[] | PUT /entity/CandidateWorkHistory (companyName, title, startDate, endDate, comments) | title holds 50 characters |
| resume.educations[] | PUT /entity/CandidateEducation (school, degree, startDate, endDate) | |
| resume.skills[].skill_title | primarySkills (PUT /entity/Candidate/{id}/primarySkills/{skillIds}) | IDs from your Skill list, or skillSet as text |
| resume.info_candidate.job_title | occupation (POST /entity/Candidate/{id}) |
A polling job in TypeScript
A minimal Node.js job: it reads new JobSubmission events, downloads each candidate’s Resume attachment, parses and scores it in one Resume Scorer call, and adds a note linked to the job order. Add your own session refresh and retries.
const HIRELAYER = 'https://hirelayer.co'
const headers = { 'X-API-Key': process.env.HIRELAYER_API_KEY! }
// restUrl and BhRestToken come from POST /rest-services/login.
// Reuse the session: do not log in again before every call.
export async function poll(restUrl: string, bhRestToken: string) {
const bh = (path: string, init?: RequestInit) =>
fetch(`${restUrl}${path}${path.includes('?') ? '&' : '?'}BhRestToken=${bhRestToken}`, init)
.then((r) => r.text())
.then((text) => (text ? JSON.parse(text) : null))
// Created once: PUT event/subscription/hirelayer?type=entity&names=JobSubmission&eventTypes=INSERTED
const batch = await bh('event/subscription/hirelayer?maxEvents=100')
for (const event of batch?.events ?? []) {
const { data: submission } = await bh(
`entity/JobSubmission/${event.entityId}?fields=id,candidate,jobOrder(id,clientCorporation)`
)
const candidateId = submission.candidate.id
const files = await bh(`entity/Candidate/${candidateId}/fileAttachments?fields=id,name,type`)
const resume = files.data.find((f: { type: string }) => f.type === 'Resume')
if (!resume) continue
// 1. Download (JSON with base64 content), then parse and score in one call
// (about a minute), against the job order stored with its criteria by
// POST /api/v4/jobs/extract-criteria in the same workspace
const { File } = await bh(`file/Candidate/${candidateId}/${resume.id}`)
const form = new FormData()
form.append('request', JSON.stringify({
job: { job_id: String(submission.jobOrder.id) },
resumes: [{ file: 'resume', application_id: String(submission.id) }],
}))
form.append('resume', new Blob([Buffer.from(File.fileContent, 'base64')]), File.name)
// One workspace per client company: its candidates and jobs stay apart.
const workspace = `client-${submission.jobOrder.clientCorporation.id}`
const response = await fetch(`${HIRELAYER}/api/v4/resumes/score`, {
method: 'POST',
headers: { ...headers, 'HireLayer-Workspace': workspace },
body: form,
signal: AbortSignal.timeout(150_000),
})
// Errors come as { error: { code, message } } (no credits, unknown job): skip.
if (!response.ok) continue
const { scores: [result] } = await response.json()
// An unreadable file fails only its own score, unbilled.
if (result.evaluation_status !== 'completed') continue
// 2. Note on the candidate, linked to the job order (PUT creates)
await bh('entity/Note', {
method: 'PUT',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
personReference: { id: candidateId },
commentingPerson: { id: Number(process.env.BULLHORN_USER_ID) },
jobOrder: { id: submission.jobOrder.id },
action: 'HireLayer score', // a value of your commentActionList
comments: `HireLayer score: ${Math.round(result.score * 100)}/100\n${result.summary}`,
}),
})
}
}Good to know
API access depends on your edition
ATS Growth (formerly Team Edition) has no REST API access, only Marketplace integrations. On other editions, Bullhorn allows up to 1,500 requests per minute and 50 concurrent sessions; on HTTP 429, wait one second and retry.
Events are pulled, not pushed
Bullhorn has no push webhooks. Events contain IDs only, and Bullhorn purges the ones nobody reads in time, so keep the schedule runing. The number of subscriptions per database is limited too.
Bullhorn already parses resumes
Its parser fills the candidate, work history and education, also through POST /resume/parseToCandidate, and its upgrade with Textkernel technology rolls out through 2026. Use HireLayer for job-specific scores and normalized skills, and write history only to records that lack it.
Not a Marketplace app
HireLayer is not listed in the Bullhorn Marketplace. Your service uses your own API credentials, so its calls count toward your API limits; usage tied to validated Bullhorn partners does not.
HireLayer APIs used on this page
HireLayer and Bullhorn: questions
Does HireLayer integrate with Bullhorn?
Which resume parser does Bullhorn use?
Can I screen Bullhorn candidates with AI?
Does Bullhorn send webhooks?
Where is candidate data processed?
Connect Bullhorn to HireLayer today
The Free plan includes 50 credits a month, no card required. Parsing a resume costs one credit, scoring one per resume evaluated, and extracting job criteria is free.
Other integrations
- GreenhouseScore every new Greenhouse application against the job and write the result back as a note, with Greenhouse web hooks and Harvest v3.
- Zoho RecruitScore new Zoho Recruit candidates against their job opening and add notes, tags and skills, with a workflow-rule webhook and the Recruit API v2.
- SalesforceTurn CVs uploaded to Salesforce into Contact fields and scores, with an Apex Queueable job and a Named Credential that holds your API key.