Developer API

Build on HeadHonta

A simple REST API to push jobs, pull candidates, and automate your hiring pipeline. Authenticate with an API key and start making requests in minutes.

Quick Start

Three steps to your first API call.

Create an API key

Go to Settings → Developer → API Keys and create a key with the scopes you need. Save the key — it's only shown once.

Set the header

Pass your key in the X-API-Key header on every request.

Make your first request

List open jobs

curl -s \
  -H "X-API-Key: hh_live_your_key_here" \
  https://head-honta-production.up.railway.app/api/v1/jobs?status=open&limit=10

Authentication

API Key Header

All requests must include your API key in the X-API-Key header. Keys are scoped to your organization — you can only access your own data.

X-API-Key: hh_live_a1b2c3d4e5f6...

Scoped Permissions

Each key has granular scopes controlling what it can access. Assign only what you need.

jobs:readView jobs in your organization

jobs:writeCreate and update jobs

candidates:readView candidate information

candidates:writeCreate and update candidates

pipeline:readView pipeline stages and candidate positions

pipeline:writeMove candidates between pipeline stages

applications:readView job applications

Pagination

All list endpoints use cursor-based pagination for stable, efficient traversal.

Parameters

limitResults per page (1-100, default 20)

cursorPass nextCursor from the previous response

Response

{
  "success": true,
  "data": [...],
  "pagination": {
    "hasMore": true,
    "nextCursor": "abc123",
    "limit": 20
  }
}

Endpoint Reference

All endpoints are prefixed with /api/v1 and require an API key. For interactive testing, use the Swagger UI.

Jobs

Create, read, and update job postings in your organization.

GET/api/v1/jobsList jobs (cursor-paginated)jobs:read

POST/api/v1/jobsCreate a new jobjobs:write

GET/api/v1/jobs/{id}Get a job by IDjobs:read

PUT/api/v1/jobs/{id}Update a jobjobs:write

Candidates

Manage candidate records in your talent pool.

GET/api/v1/candidatesList candidatescandidates:read

POST/api/v1/candidatesCreate a candidatecandidates:write

GET/api/v1/candidates/{id}Get a candidate by IDcandidates:read

PUT/api/v1/candidates/{id}Update a candidatecandidates:write

Pipeline

View stages and move candidates through your hiring pipeline.

GET/api/v1/pipeline/stagesList pipeline stagespipeline:read

GET/api/v1/pipeline/stages/{stageId}/candidatesGet candidates at a stagepipeline:read

PUT/api/v1/pipeline/candidates/{id}/moveMove candidate to a stagepipeline:write

Applications

View job applications and their statuses.

GET/api/v1/jobs/{jobId}/applicationsList applications for a jobapplications:read

Examples

Common workflows, ready to paste.

Create a job

curl -s -X POST \
  -H "X-API-Key: hh_live_your_key_here" \
  -H "Content-Type: application/json" \
  https://head-honta-production.up.railway.app/api/v1/jobs \
  -d '{
    "title": "Senior Backend Engineer",
    "description": "We are looking for...",
    "location": "Lagos, Nigeria",
    "employmentType": "full-time",
    "status": "open"
  }'

Get candidates at a pipeline stage

curl -s \
  -H "X-API-Key: hh_live_your_key_here" \
  https://head-honta-production.up.railway.app/api/v1/pipeline/stages/{stageId}/candidates?limit=20

Move a candidate to a new stage

curl -s -X PUT \
  -H "X-API-Key: hh_live_your_key_here" \
  -H "Content-Type: application/json" \
  https://head-honta-production.up.railway.app/api/v1/pipeline/candidates/{id}/move \
  -d '{ "stageId": "target-stage-uuid" }'

Rate Limits & Plans

API access is gated by subscription plan. Burst rate: 60 requests per minute per key.

Plan	API Access	Max Keys	Monthly Requests
Free	-	-	-
Starter		1	1,000
Professional		5	10,000
Enterprise		Unlimited	Unlimited