Hiring API overview
The hiring API lets your own systems read and update the hiring portal: applications, scorecards, schedules, offers, job goals, agent proposals, jobs, candidates, invitations and webhooks. Every call runs inside one organisation, under one API key and its scopes. Moves that decide a candidate’s outcome need a key a person controls.
Explanation · Last checked against the product on
What the API covers
There are four ways to connect. All of them use the same API keys, created under Settings → Developers in the hiring portal.
| Surface | Where | Use it to |
|---|---|---|
| REST API | /api/v1/hiring/… | Read and update hiring records. 16 operations come from one shared list, plus jobs, candidates and webhook subscriptions. |
| Bulk invitations | /api/v1/invitations | Invite candidates to a job’s interview from another system. |
| MCP server | /api/mcp | Let an AI agent call the same operations as tools, with the same scopes. |
| Webhooks | Your HTTPS endpoint | Receive signed events when something changes in the portal. |
Each operation is listed with its method, path, scopes and fields in the API reference.
One organisation per key
A key belongs to the organisation it was created in. Every request reads and writes only that organisation’s data: an application, job or offer from another organisation answers as not found.
A key also stops working at once if the organisation is suspended or locked for deletion, and when someone revokes it in the portal. Writes made with a key are recorded under the person who created it.
People make hiring decisions
Agents and integrations may propose; a person decides. The API enforces this with the decisions:human scope:
- Moving an application to
REJECTED,SCREENED_OUT,OFFERED,ACCEPTEDorHIREDis refused unless the key carriesdecisions:human. - Approving or overriding an agent proposal needs it too.
- An offer can only be drafted through the API. Sending it to the candidate stays with a person in the portal.
Grant decisions:human only to a key that a person operates, never to an unattended agent. The full scope list is in Authentication and scopes.
Versioning and the OpenAPI document
Every path starts with /api/v1. The REST operations are also published as an OpenAPI 3.1 document, which needs no key: /api/v1/openapi.json. Import it into an API client or a code generator to get request and response types.
The REST routes, the OpenAPI document and the MCP server read one list of operations, so a field added to one appears in all three.
Where you’ll see this
In the hiring portal, open Settings → Developers. The page has two cards, API Keys and Webhooks, and links to the quickstart, this reference and the OpenAPI document. Only people whose role includes Manage Integrations & API Keys see the tab; see Roles and permissions.