InsightHireHelp Center

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

  1. Open Settings → Integrations and choose API keys.
  2. Under Create a key, enter a Name that tells you what the key is for, such as "Careers site sync".
  3. Choose when it Expires: in 30 days, 90 days, a year or never.
  4. Under Access, tick only what the connection needs (see the table below). A key needs at least one.
  5. 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

AccessLets the key
Read jobsList jobs, departments and offices
Read candidatesList and fetch candidate profiles
Write candidatesCreate and update candidate profiles
Read applicationsList and fetch applications
Write applicationsCreate applications, move them between stages and reject them
Read usersList the people on your team
Candidate ingestionFor 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/v1

Authentication. Send the key in the Authorization header of every request:

Authorization: Bearer ih_your_key_here

Requests 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

RequestAccessWhat it does
GET /jobsRead jobsList jobs. Filter by status (draft, open, posted, on_hold, closed, filled), department_id or office_id
GET /jobs/{id}Read jobsOne job
GET /departmentsRead jobsList departments
GET /officesRead jobsList offices (your locations)
GET /usersRead usersList 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

RequestAccessWhat it does
GET /candidatesRead candidatesList candidates. Filter by email, job_id or kind (applicant or prospect)
GET /candidates/{id}Read candidatesOne candidate
POST /candidatesWrite candidatesCreate a candidate, and optionally put them on a job
PATCH /candidates/{id}Write candidatesChange 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

RequestAccessWhat it does
GET /applicationsRead applicationsList applications. Filter by job_id, candidate_id or status
GET /applications/{id}Read applicationsOne application
POST /applicationsWrite applicationsPut an existing candidate on a job
POST /applications/{id}/moveWrite applicationsMove to a status or a pipeline stage
POST /applications/{id}/rejectWrite applicationsReject 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_id and job_id. source, notes and external_id are optional. If the candidate already applied to the job you get that application back with 200; a new one returns 201.
  • Move: send exactly one of status or stage_id, and optionally notes. status can be any of the statuses above except offer_rejected, rejected and withdrawn. A stage_id must be a stage on that job's interview plan, otherwise you get 422 stage_not_on_job.
  • Reject: send an optional reason and notes.

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:

FieldNotes
sourceRequired. The partner or channel name. Shown as the source on the candidate and application
external_idRequired. The partner's own id for this candidate
job_idRequired. The job to put the candidate on
candidateRequired. Needs email. Optional first_name, last_name, phone, location, linkedin_url, current_title, current_company
notesOptional

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.

RequestWhat it does
GET /boards/{careers-page-name}/jobsList 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..."
}
  • limit sets the page size: 1 to 100, 50 by default.
  • When next_cursor is not null, pass it as cursor to get the next page. next_cursor is null on the last page. Treat the cursor as an opaque value. A cursor that isn't valid returns 400 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_at you saw and next time ask for updated_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:

HeaderMeaning
X-RateLimit-LimitRequests allowed per minute
X-RateLimit-RemainingRequests 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.

StatuscodeMeaning
400invalid_requestA field is missing or not valid. See details
400invalid_cursorThe cursor isn't valid
400bad_requestMalformed request, such as invalid JSON
401unauthorizedNo key sent, or the key is invalid, expired or revoked
403api_not_enabledThe API isn't turned on for your organization
403insufficient_scopeThe key doesn't have the access this request needs
403forbiddenThe person behind the key can't access this record
403key_owner_inactive or key_owner_missingThe person who created the key no longer has access. Create a new key
403org_read_onlyYour organization is read-only right now. Reads work, changes don't
404not_foundNo such record or endpoint, or you can't see it
409email_in_use, duplicate_applicationThe change would duplicate an existing candidate or application. details points to it
422stage_not_on_jobThe stage isn't on that job's interview plan
429rate_limitedToo many requests. Wait Retry-After seconds
500internal_errorSomething 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 429 and 500 replies after a pause. Don't retry 4xx errors without fixing the request.
  • Use external_id to match InsightHire records to your own, and updated_after instead of re-reading everything.
  • Candidates are personal information. Pull only the fields you need and follow your organization's retention and deletion policies.