API reference

Generated from the same OpenAPI 3.1 document the API serves, so it cannot drift from the code. All paths are relative to the base URL.

Base URL https://api.helixhumancapital.in. Download the spec: openapi.json. Authentication is Authorization: Bearer <key> on everything except /v1/plans. Common errors for every endpoint: 401 missing or invalid key, 402 plan ended or out of credits, 403 missing scope or disabled key, 429 rate limited. See error codes.

Account and billing

get/v1/plansno key needed

Public price list

Responses

200 Success

get/v1/me

This key: plan, scopes, credits left (free)

Responses

200 Success

get/v1/usage

Calls and credits per endpoint (free)

Parameters

Name	In	Type	Notes
`days`	query	integer	min 1, max 90, default 30

Responses

200 Success

post/v1/billing/checkout

Start a payment for a plan period or a top-up (INR, Cashfree)

Also works on a key whose period has ended. Paying starts a fresh 30-day period; unused credits do not carry over.

Request body (application/json)

Field	Type	Notes
`kind`required	"plan" \| "topup"
`plan`	"pro" \| "pro_scale"
`packs`	integer	Top-up packs of 1,000 credits. · min 1, max 20
`phone`required	string	10-digit mobile, required by the payment gateway.

Responses

200 Success · 400 Invalid request.

Candidates

post/v1/search

Ranked candidates for a natural-language query (1 credit; +5 per record when expand=true)

Scope: search. With expand=true each result is a full record limited to the field scopes the key has; every release is logged.

Request body (application/json)

Field	Type	Notes
`query`required	string	min length 2, max length 2000
`limit`	integer	min 1, max 25, default 10
`expand`	boolean	default false
`exclude`	integer[]	Candidate ids to skip (paging).
`filters`	object

filters fields:

Field	Type	Notes
`seniority`	"early" \| "mid" \| "senior" \| "leadership"[]
`maxNoticeDays`	integer
`city`	string
`maxExpectedLpa`	number
`minYears`	number

Responses

200 Success · 400 Invalid request.

get/v1/candidates/{id}

Full candidate record (5 credits)

Scope: search. Contact, compensation and document fields appear only with the pii:contact, pii:comp and pii:docs scopes.

Parameters

Name	In	Type	Notes
`id`required	path	integer

Responses

200 Success · 404 Not found.

get/v1/candidates/{id}/cv

10-minute resume download link (2 credits)

Scope: pii:docs.

Parameters

Name	In	Type	Notes
`id`required	path	integer

Responses

200 Success · 404 Not found.

post/v1/match

Best-fitting candidates for a job description (10 credits; +5 per record when expand=true)

Scope: match.

Request body (application/json)

Field	Type	Notes
`jobDescription`required	string	min length 80, max length 12000
`limit`	integer	min 1, max 25, default 10
`expand`	boolean	default false

Responses

200 Success · 400 Invalid request. · 503 Scoring temporarily unavailable. Not charged.

post/v1/fit

How well one candidate fits one job description (3 credits)

Scope: match.

Request body (application/json)

Field	Type	Notes
`candidateId`required	integer
`jobDescription`required	string	min length 80, max length 12000

Responses

200 Success · 404 Not found.

Parsing

post/v1/parse/resume

Resume file to structured JSON (2 credits)

Scope: parse. PDF, DOC or DOCX up to 5 MB. Nothing is stored.

Request body (multipart/form-data)

Field	Type	Notes
`file`required	string

Responses

200 Success · 422 Unreadable file. Not charged.

post/v1/parse/jd

Job description to a requirement checklist (2 credits)

Scope: parse.

Request body (application/json)

Field	Type	Notes
`jobDescription`required	string	min length 80, max length 12000

Responses

200 Success

Market and jobs

get/v1/market/pay-bands

Market pay for a role (free)

Scope: market. Curated benchmarks plus observed percentiles of self-reported fixed pay (INR lakh per annum) among the people nearest the role, overall and by seniority, with a confidence level. Groups smaller than 5 people are never shown.

Parameters

Name	In	Type	Notes
`role`required	query	string	min length 3
`city`	query	string	Restrict observed pay to people currently in this city.

Responses

200 Success

get/v1/market/skills

Most common skills near a role, or across the pool (free)

Scope: market.

Parameters

Name	In	Type	Notes
`role`	query	string
`limit`	query	integer	min 1, max 50, default 25

Responses

200 Success

get/v1/market/overview

Shape of the candidate pool (free)

Scope: market. Seniority mix, top cities, notice periods, work mode. Cached for an hour.

Responses

200 Success

get/v1/jobs

Open roles (free)

Scope: jobs.

Parameters

Name	In	Type	Notes
`team`	query	string
`level`	query	"junior" \| "mid" \| "senior" \| "lead"
`mode`	query	"ON_SITE" \| "HYBRID" \| "REMOTE"
`q`	query	string
`limit`	query	integer	min 1, max 100, default 50

Responses

200 Success

get/v1/jobs/{slug}

One open role (free)

Parameters

Name	In	Type	Notes
`slug`required	path	string

Responses

200 Success · 404 Not found.

Webhooks

post/v1/webhooks

https only. The signing secret is returned once. Each delivery carries `Helix-Signature: t=<unix>,v1=<hex>` where v1 is HMAC-SHA256 of `<t>.<raw body>` with the secret; reject signatures older than 5 minutes. Failed deliveries retry with backoff (30s, 2m, 10m, 1h, 6h, 24h). Events: credits.low, credits.exhausted, subscription.renewed, subscription.expiring, subscription.expired, webhook.test.

Request body (application/json)

Field	Type	Notes
`url`required	string
`events`	string[]	Defaults to all events.

Responses

201 Created · 400 Invalid URL or events. · 409 Endpoint limit reached.

get/v1/webhooks

List webhook endpoints (free)

Responses

200 Success

delete/v1/webhooks/{id}

Remove a webhook endpoint (free)

Parameters

Name	In	Type	Notes
`id`required	path	integer

Responses

200 Success · 404 Not found.

post/v1/webhooks/{id}/test

Send a signed test event now (free)

Parameters

Name	In	Type	Notes
`id`required	path	integer

Responses

200 Success · 404 Not found.

get/v1/webhooks/{id}/deliveries

Last 25 deliveries to an endpoint (free)

Parameters

Name	In	Type	Notes
`id`required	path	integer

Responses

200 Success · 404 Not found.

Agents and contribution

post/v1/mcp

Model Context Protocol server (JSON-RPC 2.0 over HTTP)

Stateless Streamable-HTTP MCP endpoint. Tools: search_candidates, get_candidate, get_candidate_cv, match_job_description, score_candidate_fit, parse_job_description, parse_resume, market_pay_bands, market_skills, market_overview, list_jobs, account_status. Each runs the same handler as its REST route, so scopes and credits are identical.

Request body (application/json)

Responses

200 Success · 202 Notification accepted.

post/v1/chat

Conversational search (anonymised), streamed. Scope: chat.

Responses

200 Server-sent event stream.

post/v1/resumes

Contribute resumes to the pool (multipart). Scope: ingest.

Responses

200 Success

post/v1/feedback

Rate candidates returned by chat. Scope: feedback.

Responses

200 Success

Schemas

Candidate

contact, compensation and cv appear only when the key holds pii:contact, pii:comp and pii:docs respectively.

Field	Type	Notes
`id`	integer
`role`	string \| null
`seniority`	string \| null
`yearsExperience`	number \| null
`skills`	string[]
`summary`	string
`fit`	"strong" \| "possible" \| "stretch" \| null
`contact`	object
`compensation`	object	INR, lakh per annum. Self-reported by the candidate; not verified.
`cv`	object

Error

{ "error": { "code": "missing_scope", "message": "…", "requestId": "…" } }

← PreviousGuides and recipes Next →Security and data handling