Guides
Build with AI agents
Give Claude Code, Codex, Cursor or any coding agent the context to integrate HireLayer correctly: llms.txt, Markdown pages, OpenAPI and a ready-made rules file.
The documentation is published in machine-readable formats generated from the same source as these pages, so agents read exactly what you read.
| Resource | Contents |
|---|---|
/llms.txt | Index of every page with a one-line summary, following the llms.txt convention. |
/llms-full.txt | The whole documentation in one Markdown file. |
/api-docs/<page>.md | Any page as clean Markdown, e.g. /api-docs/score.md. |
/openapi.json · /openapi.yaml | OpenAPI 3.1 description of every endpoint, schema and error, for code generators, Postman or Insomnia. |
/api-docs/agent-rules.md | The rules file below, ready to download. |
Paste a prompt like this one in Claude Code, Codex or Cursor. The agent fetches the docs it needs.
Read https://hirelayer.co/api-docs/score.md and https://hirelayer.co/llms.txt, then help me integrate the HireLayer Resume Scorer (score and rank resumes for a job) into my project. Follow the documented authentication, timeouts, retries and error handling, and do not invent fields or endpoints.Every page also has Copy page (its Markdown), Copy for AI (the page plus integration rules) and Open in ChatGPT or Claude actions. Each endpoint has its own Copy for AI button.
Commit these rules to the repository that calls HireLayer, so every agent session follows them: authentication, timeouts, retries, limits and the exact endpoints.
| Agent | File |
|---|---|
| Codex, Cursor, and most agents | AGENTS.md at the repository root |
| Claude Code | CLAUDE.md, or @AGENTS.md imported from it |
| Cursor (project rule) | .cursor/rules/hirelayer.mdc |
| GitHub Copilot | .github/copilot-instructions.md |
curl -o AGENTS.md https://hirelayer.co/api-docs/agent-rules.md# HireLayer API
This project calls the HireLayer recruiting APIs (resume parsing, job criteria extraction, resume scoring and ranking, talent pool search, job recommendations, skills normalization). Follow these rules when writing or changing that code.
## HireLayer integration rules
- Base URL: `https://hirelayer.co/api/v4`. HTTPS only. There is no official SDK: in code, call the REST API directly (Python `requests`, Node.js 18+ `fetch`); working examples are in https://github.com/HireLayer/resume-parser-examples. The official MCP server (hosted at https://hirelayer.co/mcp with OAuth sign-in, or locally with npm `hirelayer-mcp`; source: https://github.com/HireLayer/hirelayer-mcp) is for AI assistants such as Claude, ChatGPT, Cursor or VS Code, not for application code.
- Authentication: header `X-API-Key` on every request except `GET /health`. Read the key from the `HIRELAYER_API_KEY` environment variable. Never hard-code it, log it, or send it from browser or mobile code. `Authorization: Bearer` is not supported.
- To rank resumes for a job, call `POST /resumes/score` once with the job (a file, a text or a stored `job_id`) and the resumes (files, texts, parsed JSON or stored `application_id`s). With files, send `multipart/form-data`: the JSON in the `request` part, each file in a part whose name the JSON cites (`{"file": "cv1"}`); `webhook_url`, `do_not_store_data` and every other field go inside that JSON, never as form fields (refused, `400`). Without files, send the JSON as `application/json`. Do not parse or extract criteria first unless you need the parse or the criteria themselves.
- Synchronous up to 10 resume files and 50 resumes per scoring call (about a minute for 50); at most 100 resumes per call. Larger calls answer `202` with `results_url` (poll it until no score is `pending`) or, with `webhook_url`, post the result to that URL, signed with `HireLayer-Signature` (HMAC-SHA256 of `"<t>.<raw body>"` with the account's `whsec_` secret; reject a `t` older than 5 minutes; deduplicate on `event_id`). With storage, a call within the synchronous limits whose evaluations still run after about 100 seconds answers `202` too: handle `202` on every scoring call.
- Timeouts: use a client timeout of at least 150 s for `POST /resumes/parse` and `POST /resumes/score`.
- Retries: retry `429` after `Retry-After`, and `502`, `503`, `504` and connection failures at most 3 times with exponential backoff and jitter. After a `504`, a change may still have been applied: read it before sending the call again. Never retry another 4xx unchanged. `PUT` to your own ids can be sent again safely, and a pair already scored is not billed again.
- Errors: always `{"error": {"code", "message", "param", "doc_url"}}`. Branch on `error.code` (`invalid_request`, `storage_required`, `missing_api_key`, `invalid_api_key`, `insufficient_credits`, `enterprise_plan_required`, `not_found`, `method_not_allowed`, `payload_too_large`, `resume_unreadable`, `job_unreadable`, `rate_limited`, `model_unavailable`, `internal_error`), never on the message. In a scoring call, a resume that fails comes last with `evaluation_status: "failed"` and its own `error`; the call still succeeds.
- HrFlow.ai format: only to keep code written for HrFlow.ai, `POST /resumes/parse?output_format=hrflow` answers `201` with HrFlow.ai's parsing body, and its errors as `{"code": <status>, "message", "error_code"}`. Otherwise leave `output_format` out. See https://hirelayer.co/api-docs/migrate-from-hrflow.
- Compatibility: responses and webhooks can gain new fields as the products improve; no existing field is ever removed or renamed. Ignore unknown fields: never validate a response with a schema that rejects extra keys.
- Ids: `application_id` is a resume, `job_id` a job, `criterion_id` a criterion. Send your own ids (letters, digits and . _ : ~ -, up to 200 characters) to keep HireLayer in step with your system; without one, the id is derived from the content (`file_`, `text_` or `job_` + 32 hex characters), so the same file is the same resume. A job text identical to the stored job returns the job as stored: `title`, `location` and `language` sent with it are ignored; change them with `PUT /jobs/{job_id}`. A resume parsed by the legacy `/api/v3/parser` is usable by its `info_resume.application_id`.
- Workspaces: platforms serving several companies send each company's id in the `HireLayer-Workspace` header; data never crosses workspaces. Without it, everything goes to `default`.
- Credits: Resume Parser 1 per resume (0 for a file already stored); Job Criteria Extractor free (except a new text sent under the `job_id` of a job already scored, as below); Resume Scorer 1 per resume scored + 1 per resume file parsed (0 for a pair already scored), +1 per call with `precise_ranking`; Talent Pool Search 1 per search (plus the re-evaluation below when its `job` text replaces a stored job); Job Recommendations 1 per search, +1 when the resume comes as a file; Skills Normalizer 1 per call. Reads (except `GET /skills`, 1 credit, and `GET /jobs/{job_id}/scores` with `precise_ranking=true`, 1 credit per read), storing a job or a resume, and changes of a criterion's weight, requirement or type are free; adding or rewording a criterion (a new label or threshold, or new criteria through `PUT /jobs/{job_id}` or a new text under a stored `job_id` in `POST /jobs/extract-criteria`, `POST /resumes/score` or `POST /resumes/search`) re-evaluates the job's stored scores, 1 credit each. The products return `credits_used`. `403 insufficient_credits` means nothing was processed; the Resume Scorer and Talent Pool Search check for the worst case (every stored score of the job counted as evaluated again) and bill only what they do.
- Re-rank without re-scoring: `GET /jobs/{job_id}/scores?weights[crit_3]=0` applies other weights for one read, free. `precise_ranking: true` compares the 10 best and adds `ranking_reason`, 1 credit per call or read.
- Storage: by default everything is stored in the workspace. `do_not_store_data=true` (Enterprise plan only, otherwise `403 enterprise_plan_required`) keeps nothing: ids come back `null`, give each resume a `reference`, and both searches answer `400 storage_required`.
- Languages: criteria, summaries and explanations are in the job's language: `language` is `en`, `fr`, `de`, `es` or `pt`; left out, it is the language of the job's text, and English for a text in any other language. Evidence quotes the resume as written.
- Text lengths: a job text holds at least 30 characters, and a Resume Scorer call needs at least one resume of 30 characters or more.
- Do not invent fields, endpoints or parameters. When unsure, read the OpenAPI document or the Markdown reference.
## Endpoints
Paths are relative to `https://hirelayer.co`.
- `POST /api/v4/resumes/parse` (Resume Parser): Reads a resume file and returns it structured, stored in the workspace under an application_id. (multipart/form-data, 1 credit; 0 when the file is already stored, client timeout ≥ 150 s). Docs: https://hirelayer.co/api-docs/parse-resume.md
- `POST /api/v4/jobs/extract-criteria` (Job Criteria Extractor): Reads a job description and returns the typed criteria it states (usually 4 to 10, fewer for a short posting: none is invented; at most 15), in the posting's order, the job stored under a job_id. A posting that states more requirements has its close ones grouped, and the 15 that weigh most are kept. The text holds at least 30 characters. (JSON body, free; 1 credit per stored score evaluated again when a new text replaces a stored job, client timeout ≥ 150 s). Docs: https://hirelayer.co/api-docs/extract-criteria.md
- `POST /api/v4/resumes/score` (Resume Scorer): Evaluates one or more resumes against a job, criterion by criterion, and returns them best first. (JSON body, 1 credit per resume evaluated, +1 per resume file parsed, +1 per call with precise_ranking; 0 for a pair already evaluated or a file already stored; 1 credit per other stored score evaluated again when a stored job comes with a new text or new criteria, client timeout ≥ 150 s). Docs: https://hirelayer.co/api-docs/score.md
- `POST /api/v4/resumes/search` (Talent Pool Search): Finds in the workspace's resume database the resumes closest to a job, to choose which ones to score. Proximity only: no evaluation, no explanation. Score the chosen ones with POST /resumes/score. (JSON body, 1 credit per search; 1 credit per stored score evaluated again when a new text replaces a stored job, client timeout ≥ 60 s). Docs: https://hirelayer.co/api-docs/search-resumes.md
- `POST /api/v4/jobs/search` (Job Recommendations): Finds the open stored jobs of the workspace closest to a resume. Proximity only: no evaluation, no explanation. Score the chosen ones with POST /resumes/score, one call per job. (JSON body, 1 credit per search, +1 for a resume file, client timeout ≥ 60 s). Docs: https://hirelayer.co/api-docs/search-jobs.md
- `POST /api/v4/skills/normalize` (Skills Normalizer): Maps the skills named in a free text to the HireLayer taxonomy. Nothing is stored. (JSON body, 1 credit, client timeout ≥ 60 s). Docs: https://hirelayer.co/api-docs/skills.md
- `GET /api/v4/resumes` (Data and account): The resume database of the workspace, most recently stored first. Free. (no body, free, client timeout ≥ 30 s). Docs: https://hirelayer.co/api-docs/resumes.md
- `GET /api/v4/resumes/{application_id}` (Data and account): Get a stored resume. (no body, free, client timeout ≥ 30 s). Docs: https://hirelayer.co/api-docs/resumes.md
- `PUT /api/v4/resumes/{application_id}` (Data and account): Stores under your application_id a resume you already have as text, or as the parsed resume JSON of POST /resumes/parse. Replaces the resume stored before. When its text changes, its scores become stale and are evaluated again only when asked; the same text sent again leaves them as they are. Free. To store a file, use POST /resumes/parse with application_id. (JSON body, free, client timeout ≥ 60 s). Docs: https://hirelayer.co/api-docs/resumes.md
- `DELETE /api/v4/resumes/{application_id}` (Data and account): Erases the resume, its file and all its scores (GDPR erasure). Erasing a resume that does not exist is not an error. Free. (no body, free, client timeout ≥ 30 s). Docs: https://hirelayer.co/api-docs/resumes.md
- `GET /api/v4/jobs` (Data and account): The jobs of the workspace, most recently updated first. Free. (no body, free, client timeout ≥ 30 s). Docs: https://hirelayer.co/api-docs/jobs.md
- `GET /api/v4/jobs/{job_id}` (Data and account): Get a stored job. (no body, free, client timeout ≥ 30 s). Docs: https://hirelayer.co/api-docs/jobs.md
- `PUT /api/v4/jobs/{job_id}` (Data and account): Creates or updates a job under your job_id, for an ATS that keeps its own ids. Without criteria on creation, they are extracted from its text, as by POST /jobs/extract-criteria. On update, criteria are kept unless you send criteria or recompute_criteria: true; a criterion with the same label and threshold as a current one keeps its id and its per-criterion results. (JSON body, free; 1 credit per stored score evaluated again, client timeout ≥ 150 s). Docs: https://hirelayer.co/api-docs/jobs.md
- `DELETE /api/v4/jobs/{job_id}` (Data and account): Deletes the job, its criteria and its scores. The resumes stay. Deleting a job that does not exist is not an error. Free. (no body, free, client timeout ≥ 30 s). Docs: https://hirelayer.co/api-docs/jobs.md
- `POST /api/v4/jobs/{job_id}/criteria` (Data and account): Adds a criterion. The job's stored scores are evaluated on it in the background, 1 credit each (their evaluation_status is pending meanwhile), and their verdict is null until their next full evaluation (see Verdict). (JSON body, 1 credit per stored score of the job, client timeout ≥ 150 s). Docs: https://hirelayer.co/api-docs/jobs.md
- `PATCH /api/v4/jobs/{job_id}/criteria/{criterion_id}` (Data and account): A new weight, requirement or type re-ranks at once, for free; weight 0 turns the criterion off. A new label or threshold evaluates the criterion again on the job's stored scores, 1 credit each, and sets their verdict to null until their next full evaluation. (JSON body, free for weight, requirement and type; 1 credit per stored score for label or threshold, client timeout ≥ 150 s). Docs: https://hirelayer.co/api-docs/jobs.md
- `DELETE /api/v4/jobs/{job_id}/criteria/{criterion_id}` (Data and account): The criterion leaves the scores at once, with no new evaluation, and the verdict of the job's scores is null until their next full evaluation. A job keeps at least one criterion. Free. (no body, free, client timeout ≥ 30 s). Docs: https://hirelayer.co/api-docs/jobs.md
- `GET /api/v4/jobs/{job_id}/scores` (Data and account): The stored scores of a job, best first, scored at read time with the priorities of this read. Free. precise_ranking=true costs 1 credit per read: it compares the 10 best of all the job's resumes and adds ranking_reason, and is billed when it ranks at least 2 completed scores (credits_used). It is made again only when those 10, the job's description or the priorities of the read (weights and requirements) change. In a workspace without storage (set after its jobs were stored), it is made again at every read and never kept. (no body, free; 1 with precise_ranking=true, client timeout ≥ 60 s). Docs: https://hirelayer.co/api-docs/jobs.md
- `GET /api/v4/jobs/{job_id}/scores/{application_id}` (Data and account): One resume's score for a job, criterion by criterion, with the priorities of this read. Free. (no body, free, client timeout ≥ 30 s). Docs: https://hirelayer.co/api-docs/jobs.md
- `DELETE /api/v4/jobs/{job_id}/scores/{application_id}` (Data and account): Deletes the score. The resume stays in the workspace. Free. (no body, free, client timeout ≥ 30 s). Docs: https://hirelayer.co/api-docs/jobs.md
- `GET /api/v4/skills` (Skills Normalizer): The whole taxonomy, most frequent in resumes first. 1 credit. (no body, 1 credit, client timeout ≥ 30 s). Docs: https://hirelayer.co/api-docs/skills.md
- `GET /api/v4/workspaces` (Data and account): default first, then the others, oldest first. Free. (no body, free, client timeout ≥ 30 s). Docs: https://hirelayer.co/api-docs/account.md
- `PUT /api/v4/workspaces/{workspace_id}` (Data and account): Creates a workspace for one of your customers, gives it a new display name, or imposes the no-storage mode on it. Its id never changes. Free. (JSON body, free, client timeout ≥ 30 s). Docs: https://hirelayer.co/api-docs/account.md
- `DELETE /api/v4/workspaces/{workspace_id}` (Data and account): Erases every job, resume, file and score of the workspace, for example when your customer leaves. Free. (no body, free, client timeout ≥ 60 s). Docs: https://hirelayer.co/api-docs/account.md
- `GET /api/v4/account` (Data and account): The plan and the credits left of the key's account. Free. (no body, free, client timeout ≥ 30 s). Docs: https://hirelayer.co/api-docs/account.md
- `GET /api/v4/health` (Data and account): No key needed. Free. (no body, free, client timeout ≥ 10 s, no API key). Docs: https://hirelayer.co/api-docs/account.md
- `POST /api/v3/parser` (Legacy parser): Upload one resume file and receive the parsed resume at the top level of the response. Legacy: new integrations use POST /api/v4/resumes/parse, which returns the same JSON under resume. (multipart/form-data, 1 credit per successful parse (http 200, or 201 in hrflow.ai’s format), client timeout ≥ 150 s, LEGACY, do not use for new code). Docs: https://hirelayer.co/api-docs/legacy-parsers.md
- `POST /api/v2/parser` (Legacy parser): Legacy asynchronous contract: the request is accepted with 202 and the result is posted to webhook_url. (multipart/form-data, 1 credit when the request is accepted (http 202), client timeout ≥ 50 s, LEGACY, do not use for new code). Docs: https://hirelayer.co/api-docs/legacy-parsers.md
## References
- Index for agents: https://hirelayer.co/llms.txt
- Full documentation in one file: https://hirelayer.co/llms-full.txt
- OpenAPI 3.1: https://hirelayer.co/openapi.json
HireLayer has no official SDK: the API is plain HTTPS with one header, which agents handle reliably with the docs above. For typed clients, generate one from /openapi.json.
To use HireLayer from an AI assistant (Claude, ChatGPT, Cursor, VS Code, Codex or any MCP client) rather than from your code, connect the official MCP server at https://hirelayer.co/mcp: the assistant opens the HireLayer sign-in page and you allow access, with no key to copy. It exposes the six products as tools (parse_resume, extract_job_criteria, score_resumes, search_resumes, search_jobs, normalize_skills), billed like the API; what they store follows the workspace setting, as in the API. The same server runs locally with npm hirelayer-mcp (open source on GitHub) and an API key. In Claude Code:
claude mcp add --transport http hirelayer https://hirelayer.co/mcpSee the MCP server page for Claude, ChatGPT, Cursor, VS Code and Codex. For code integrations, keep calling the REST API directly as described above.