canonical: https://jentic.com/apis/bullhornstaffing.com/bullhornstaffing

# Bullhornstaffing Bullhorn Resume Parsing API

Jentic publishes the only available OpenAPI specification for Bullhorn Resume Parsing API, keeping it validated and agent-ready. The Bullhorn Resume Parsing API turns inbound resume documents into structured Bullhorn candidate records and lets recruiting tools enrich those candidates with education history, work history, primary skills, and original file attachments. The API runs against Bullhorn's per-corporation REST host and uses Bullhorn's standard OAuth 2.0 authorization-code flow. It is the same surface published under the bullhorn.github.io vendor entry, scoped to the candidate intake path.

## For AI agents

Parse resumes and create Bullhorn ATS candidates with education, work history, skills, and file attachments via the bullhornstaffing.com REST host.

## Scope

Does not handle job postings, interview scheduling, or payroll - use for resume parsing and candidate creation in Bullhorn only.

## Capabilities

- Parse a resume document into a Bullhorn candidate via `/resume/parseToCandidate`
- Create a candidate entity in the Bullhorn ATS
- Retrieve a candidate by ID after creation
- Attach education and work history records to a candidate
- Read a single work history record by ID
- Add primary skills to a candidate from the Bullhorn skill taxonomy
- Attach the original resume file to a candidate and list candidate files

## Use cases

### Resume to candidate pipeline

Receive a resume by email or upload, parse it through `/resume/parseToCandidate`, and persist the resulting candidate in the Bullhorn ATS. The pipeline ends with the original document attached to the candidate so recruiters can review the source. Suitable for staffing agencies that handle steady inbound resume volume and want to skip manual data entry.

Example prompt: Parse a resume with POST `/resume/parseToCandidate`, create the candidate via PUT `/entity/Candidate`, then attach the file with PUT `/file/Candidate/{candidateId}/raw.`

### Candidate profile enrichment

After creating a candidate from a parsed resume, attach the structured education and work history records and assign primary skills. The `/entity/CandidateWorkHistory` endpoint also supports retrieving a single record by ID, useful for verification before downstream steps such as outreach.

Example prompt: For candidate 12345, PUT `/entity/CandidateEducation` per school, PUT `/entity/CandidateWorkHistory` per role, then PUT `/entity/Candidate/12345/primarySkills/{skillIds}` with matched skill IDs.

### Resume document retention

Keep the original resume binary attached to the Bullhorn candidate record for compliance and audit purposes. The file attachment endpoint stores the raw document, and the entityFiles endpoint confirms what is on the candidate. This is a common requirement in regulated staffing verticals where source documents must be retrievable.

Example prompt: Attach the source PDF to candidate 12345 via PUT `/file/Candidate/12345/raw` and verify with GET `/entityFiles/Candidate/12345.`

### AI agent recruiting via Jentic

An AI assistant can take a resume from a recruiter's inbox, call the Bullhorn parse and create operations through Jentic, and reply with the new candidate ID - without holding raw OAuth credentials. Jentic isolates Bullhorn refresh tokens and corpToken values so the agent only sees structured operation responses.

Example prompt: Search Jentic for 'parse a resume into Bullhorn', load the parseToCandidate schema, execute with the resume bytes, and report the new candidate ID.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/resume/parseToCandidate` | Parse a resume into candidate data |
| PUT | `/entity/Candidate` | Create a candidate entity |
| GET | `/entity/Candidate/{candidateId}` | Retrieve a candidate |
| PUT | `/entity/CandidateWorkHistory` | Create a work history record |
| GET | `/entity/CandidateWorkHistory/{workHistoryId}` | Retrieve a work history record |
| PUT | `/entity/Candidate/{candidateId}/primarySkills/{skillIds}` | Add primary skills to a candidate |
| PUT | `/file/Candidate/{candidateId}/raw` | Attach a resume file to a candidate |
| GET | `/entityFiles/Candidate/{candidateId}` | List files on a candidate |

## Key resources

- **Resume** — Parse uploaded resume documents into structured candidate data.
- **Candidate** — Create and retrieve Bullhorn candidate entities.
- **CandidateEducation** — Attach education records to a candidate.
- **CandidateWorkHistory** — Create and retrieve work history records on a candidate.
- **Skills** — Look up the Bullhorn skill taxonomy and assign primary skills.
- **Files** — Attach resume files to a candidate and list candidate file attachments.

## Why Jentic

- **Setup:** Wiring Bullhorn resume parsing by hand means running its OAuth 2.0 flow, resolving the per-user corpToken into the rest-services base path, and refreshing the access token yourself. Through Jentic you install once, import the Bullhorn Resume Parsing API from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** Bullhorn puts the candidate id in the URL path (`/entity/Candidate/{candidateId}/...`), so a rule can pin your agent to one candidate: it can parse a resume and read or update that candidate's work history and skills and nothing else. You choose the operations it may call, so it can create and enrich a candidate without being able to reach unrelated entities unless you add them.
- **Credential handling:** Your Bullhorn OAuth refresh token and corpToken are stored once, encrypted, by your own Jentic One instance, and only a scoped, short-lived access token is injected at execution time. The long-lived credentials never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a Bullhorn candidate' or 'parse a resume', and Jentic returns the matching Bullhorn operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Bullhorn Resume Parsing (bullhorn.github.io)** — Same Bullhorn surface published under the bullhorn.github.io vendor entry.
- **Greenhouse Harvest API** — Greenhouse Harvest covers the candidate and application surface for Greenhouse-based hiring teams.
- **Workable API** — Workable ATS API for candidates, jobs, and hiring stages.
- **Lever API** — Lever recruiting API for organisations running multiple ATS systems alongside Bullhorn.

## FAQ

### Why is there no official OpenAPI spec for Bullhorn Resume Parsing API?

Bullhorn does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Bullhorn Resume Parsing API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Bullhorn Resume Parsing API use?

It uses OAuth 2.0 authorization-code flow with auth and token URLs at https://auth.bullhornstaffing.com/oauth/authorize and `/oauth/token.` Each request runs against a per-corporation REST host that includes your corpToken in the path. Jentic stores the refresh token and corpToken in the vault and issues short-lived access tokens per call.

### Can I retrieve a single work history record after creating it?

Yes. GET `/entity/CandidateWorkHistory/{workHistoryId}` returns a previously created work history record so you can verify the data before chaining further calls.

### How do I attach the original resume file to a candidate?

PUT `/file/Candidate/{candidateId}/raw` accepts the raw binary and stores it as a candidate attachment. Confirm the upload with GET `/entityFiles/Candidate/{candidateId}`, which returns the file list for that candidate.

### What are the rate limits for the Bullhorn Resume Parsing API?

The OpenAPI spec does not declare explicit limits. Bullhorn applies per-corporation REST throttles documented in their developer portal - implement 429 retries with exponential backoff for batch resume imports.

### How do I parse a resume with Bullhorn through Jentic?

Run `pip install jentic`, then search for 'parse a resume into Bullhorn'. Jentic returns the parseToCandidate operation, you load its schema, and execute the call with the resume bytes - credential handling stays inside your Jentic One instance.

### Can I limit what my agent is allowed to do with the Bullhorn Resume Parsing API?

Yes. Because you run Jentic One yourself, your own rules decide which Bullhorn operations and credentials the agent may use, so you can allow it to parse a resume and create a candidate while blocking everything else. Bullhorn puts the candidate id in the URL path, such as `/entity/Candidate/{candidateId}/primarySkills/{skillIds}`, so a rule can pin the agent to a single candidate and let it read or update only that candidate's work history and skills. It cannot reach unrelated Bullhorn entities unless you add those operations to what it is permitted to call.