Public API
Read jobs, candidates and applications, add candidates, and move applications from your own tools with the InsightHire REST API and an API key.
The InsightHire API lets your own tools and partners work with your hiring data over HTTPS. You can list jobs, read and add candidates, create applications, move or reject them, and push in candidates from a partner system with the source credited.
This page is for the person who builds the connection. If you only want hiring alerts sent to another system, use Outbound webhooks. If you want to show your open jobs on your own website, see Embed your jobs on your website.
Availability
The API is switched on for each organization. If Settings → Integrations → API keys says the API isn't turned on for your organization, contact InsightHire support to enable it. Until then every request is refused.
Who can do what
- Organization Admins create and revoke API keys under Settings → Integrations → API keys, and see each key's requests, errors and changes over the last 30 days.
- Everyone else can't open the page.
Create an API key
- Open Settings → Integrations and choose API keys.
- Under Create a key, enter a Name that tells you what the key is for, such as "Careers site sync".
- Choose when it Expires: in 30 days, 90 days, a year or never.
- Under Access, tick only what the connection needs (see the table below). A key needs at least one.
- Choose to create the key, then copy it straight away. It starts with
ih_and is shown once. InsightHire keeps only a scrambled copy, so a lost key can't be looked up. Make a new one instead.
To stop a key, revoke it from the Keys list. It stops working at once. Treat a key like a password: keep it on your server, never in a web page or a mobile app.
What a key can see
A key acts as the person who created it. It sees and changes only what that person can in InsightHire, including which jobs they can see. If that person leaves or is turned off, their keys stop working and you need to create new ones. Make keys from an account with only the access the connection needs.
Access choices
| Access | Lets the key |
|---|---|
| Read jobs | List jobs, departments and offices |
| Read candidates | List and fetch candidate profiles |
| Write candidates | Create and update candidate profiles |
| Read applications | List and fetch applications |
| Write applications | Create applications, move them between stages and reject them |
| Read users | List the people on your team |
| Candidate ingestion | For partners: send a candidate to a job with source attribution |
A request outside a key's access is refused with insufficient_scope.
Connect
Base address
https://api.insighthire.com/v1Authentication. Send the key in the Authorization header of every request:
Authorization: Bearer ih_your_key_hereRequests and replies are JSON. Send Content-Type: application/json with a body. Dates are ISO 8601 in UTC, for example 2026-11-07T15:30:00.000Z.
A first call to check your key:
curl https://api.insighthire.com/v1/jobs?limit=5 \
-H "Authorization: Bearer ih_your_key_here"Endpoints
The access a key needs is in the second column.
Jobs and organization
| Request | Access | What it does |
|---|---|---|
GET /jobs | Read jobs | List jobs. Filter by status (draft, open, posted, on_hold, closed, filled), department_id or office_id |
GET /jobs/{id} | Read jobs | One job |
GET /departments | Read jobs | List departments |
GET /offices | Read jobs | List offices (your locations) |
GET /users | Read users | List the active people on your team |
A job has id, title, code, status, description, requirements, location, employment_type, department and office (each {id, name} or null), hiring_manager_id, salary (min, max, currency), openings, hires, published_on_careers_page, external_id, created_at, updated_at and closed_at.
A department has id, name, parent_id, external_id, created_at and updated_at. An office has the same fields plus type. A user has id, first_name, last_name, email, role, created_at and updated_at.
Candidates
| Request | Access | What it does |
|---|---|---|
GET /candidates | Read candidates | List candidates. Filter by email, job_id or kind (applicant or prospect) |
GET /candidates/{id} | Read candidates | One candidate |
POST /candidates | Write candidates | Create a candidate, and optionally put them on a job |
PATCH /candidates/{id} | Write candidates | Change a candidate's details |
A candidate has id, email, first_name, last_name, phone, location, linkedin_url, current_title, current_company, tags, external_id, source, kind, status, do_not_contact, application_ids, created_at and updated_at.
To create a candidate, email is required. Optional fields are first_name, last_name, phone, location, linkedin_url, current_title, current_company, tags, external_id (your own id for the person), source and job_id. With job_id, the person is also added to that job and the reply includes application_id.
If a candidate with that email already exists, you get that candidate back with status 200 and nothing new is created. A new candidate returns 201. Changing a candidate's email to one that another candidate already has returns 409 email_in_use.
Applications
| Request | Access | What it does |
|---|---|---|
GET /applications | Read applications | List applications. Filter by job_id, candidate_id or status |
GET /applications/{id} | Read applications | One application |
POST /applications | Write applications | Put an existing candidate on a job |
POST /applications/{id}/move | Write applications | Move to a status or a pipeline stage |
POST /applications/{id}/reject | Write applications | Reject the application |
An application has id, candidate_id, job_id, job_post_id, status, stage ({id, name} or null), source, applied_at, rejected_at, rejection_reason, hired_at, withdrawn_at, external_id, external_source and updated_at.
Statuses are new, reviewing, screening, interviewing, reference_check, offer_pending, offer_rejected, offer_sent, offer_accepted, offer_declined, hired, rejected and withdrawn.
- Create: send
candidate_idandjob_id.source,notesandexternal_idare optional. If the candidate already applied to the job you get that application back with200; a new one returns201. - Move: send exactly one of
statusorstage_id, and optionallynotes.statuscan be any of the statuses above exceptoffer_rejected,rejectedandwithdrawn. Astage_idmust be a stage on that job's interview plan, otherwise you get422 stage_not_on_job. - Reject: send an optional
reasonandnotes.
Changes made through the API are recorded in your audit log, with the key's name.
Candidate ingestion for partners
POST /ingestion/candidates (access: Candidate ingestion) is for a partner or job source that sends you candidates. Send:
| Field | Notes |
|---|---|
source | Required. The partner or channel name. Shown as the source on the candidate and application |
external_id | Required. The partner's own id for this candidate |
job_id | Required. The job to put the candidate on |
candidate | Required. Needs email. Optional first_name, last_name, phone, location, linkedin_url, current_title, current_company |
notes | Optional |
It is safe to retry. Sending the same source and external_id again returns the first result (200) and creates nothing new. The reply has candidate_id, application_id, created_candidate and created_application. A first delivery returns 201. If the person is already on that job under another profile you get 409 duplicate_application.
Public job board (no key)
These two requests need no API key. They return only jobs listed on your careers page, with nothing internal.
| Request | What it does |
|---|---|
GET /boards/{careers-page-name}/jobs | List listed jobs. Optional department_id, limit, cursor |
GET /boards/{careers-page-name}/jobs/{id} | One job, with the full description and temporary links to attachments (good for about an hour) |
Each listed job has id, job_post_id, title, summary, location, employment_type, department, client_name, listed_at and url, the job's page on your careers site where candidates apply. The careers page name is the part after /careers/ in your careers page address.
Machine-readable description
GET /openapi.json returns an OpenAPI description of every request above. It needs no key. Import it into a tool such as Postman or a code generator.
Pagination and changes since
List requests return the same shape:
{
"data": [ { "id": "..." } ],
"next_cursor": "eyJ0Ijoi..."
}limitsets the page size: 1 to 100, 50 by default.- When
next_cursoris not null, pass it ascursorto get the next page.next_cursoris null on the last page. Treat the cursor as an opaque value. A cursor that isn't valid returns400 invalid_cursor; start again without one. - Lists run from the oldest change to the newest. To keep another system in sync, remember the newest
updated_atyou saw and next time ask forupdated_after=<that time>.
curl "https://api.insighthire.com/v1/applications?job_id=JOB_ID&limit=100&updated_after=2026-11-01T00:00:00Z" \
-H "Authorization: Bearer ih_your_key_here"The public job board pages with limit and cursor the same way.
Rate limits
Each key can make 300 requests a minute. Every keyed reply carries:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Requests allowed per minute |
X-RateLimit-Remaining | Requests you have left in this minute |
Over the limit you get 429 with a Retry-After header: the number of seconds to wait. Wait that long, then continue. Replies are never cached (Cache-Control: no-store), so there is no need to bypass a cache.
Errors
Every error uses one shape:
{
"error": {
"code": "insufficient_scope",
"message": "This API key does not have the candidates:write scope"
}
}Invalid fields add a details list with the field name and what is wrong. Branch on code, not on message.
| Status | code | Meaning |
|---|---|---|
| 400 | invalid_request | A field is missing or not valid. See details |
| 400 | invalid_cursor | The cursor isn't valid |
| 400 | bad_request | Malformed request, such as invalid JSON |
| 401 | unauthorized | No key sent, or the key is invalid, expired or revoked |
| 403 | api_not_enabled | The API isn't turned on for your organization |
| 403 | insufficient_scope | The key doesn't have the access this request needs |
| 403 | forbidden | The person behind the key can't access this record |
| 403 | key_owner_inactive or key_owner_missing | The person who created the key no longer has access. Create a new key |
| 403 | org_read_only | Your organization is read-only right now. Reads work, changes don't |
| 404 | not_found | No such record or endpoint, or you can't see it |
| 409 | email_in_use, duplicate_application | The change would duplicate an existing candidate or application. details points to it |
| 422 | stage_not_on_job | The stage isn't on that job's interview plan |
| 429 | rate_limited | Too many requests. Wait Retry-After seconds |
| 500 | internal_error | Something went wrong on our side. Try again; if it keeps happening, contact support |
Example calls
Get one job
curl https://api.insighthire.com/v1/jobs/JOB_ID \
-H "Authorization: Bearer ih_your_key_here"Find a candidate by email
curl "https://api.insighthire.com/v1/candidates?email=jordan@example.com" \
-H "Authorization: Bearer ih_your_key_here"Add a candidate to a job
curl -X POST https://api.insighthire.com/v1/candidates \
-H "Authorization: Bearer ih_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"email": "jordan@example.com",
"first_name": "Jordan",
"last_name": "Lee",
"source": "Career fair",
"job_id": "JOB_ID"
}'Move an application to a status
curl -X POST https://api.insighthire.com/v1/applications/APPLICATION_ID/move \
-H "Authorization: Bearer ih_your_key_here" \
-H "Content-Type: application/json" \
-d '{ "status": "interviewing", "notes": "Passed the phone screen" }'Reject an application
curl -X POST https://api.insighthire.com/v1/applications/APPLICATION_ID/reject \
-H "Authorization: Bearer ih_your_key_here" \
-H "Content-Type: application/json" \
-d '{ "reason": "Position filled" }'Send a candidate from a partner system
curl -X POST https://api.insighthire.com/v1/ingestion/candidates \
-H "Authorization: Bearer ih_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"source": "Acme Staffing",
"external_id": "acme-48213",
"job_id": "JOB_ID",
"candidate": { "email": "sam@example.com", "first_name": "Sam", "last_name": "Rivera" }
}'List the public job board (no key)
curl "https://api.insighthire.com/v1/boards/your-careers-page-name/jobs?limit=20"Events and webhooks
The API is for reading and changing data when your system asks. It has no requests for subscribing to events. To be told when something happens, such as a new application or a finished journey, set up Outbound webhooks in Settings → Integrations. A common pattern is to react to a webhook, then call the API for the full record.
Good practice
- Give each connection its own key and name, so you can revoke one without breaking the others.
- Choose the shortest expiry you can live with, and rotate keys when an administrator leaves.
- Retry
429and500replies after a pause. Don't retry4xxerrors without fixing the request. - Use
external_idto match InsightHire records to your own, andupdated_afterinstead of re-reading everything. - Candidates are personal information. Pull only the fields you need and follow your organization's retention and deletion policies.
Background checks
Connect Accurate Background, collect the candidate's signed permission, order checks from a candidate profile, and record the steps when a check raises a concern.
Outbound webhooks
Send signed InsightHire events, such as new applications, finished journeys and offer decisions, to an HTTPS endpoint your organization controls.
