# HireLayer API

This project calls the HireLayer recruiting APIs (resume parsing, job criteria extraction, candidate matching and ranking, skills normalization). Follow these rules when writing or changing that code.

## HireLayer integration rules

- Base URL: `https://onlineresumeparser.com/api`. HTTPS only. There is no official SDK and no MCP server: call the REST API directly (Python `requests`, Node.js 18+ `fetch`).
- Authentication: header `X-API-Key` on every request except `GET /api/v1/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.
- Every call is synchronous; there are no jobs to poll.
- Timeouts: use a client timeout of at least 150 s for `POST /api/v3/parser` and 65 s for `/api/v1/*`.
- Retries: retry 5xx responses and connection failures at most 3 times with exponential backoff and jitter; honour `Retry-After`. Never retry 4xx responses unchanged. There is no idempotency key.
- Errors: every error body has an `error` string. CV Extract errors add a `code` (`INVALID_FILE`, `DOCUMENT_NOT_A_RESUME`, `DOCUMENT_TEXT_EMPTY`, `DOCUMENT_UNREADABLE`, `DOCUMENT_TOO_LARGE`, `PARSER_UNAVAILABLE`). Job Extract, Match, Rank and Skills validation errors are `{"success": false, "error": "…"}` with status 400.
- Credits: each successful call costs 1 credit, whatever the API. `403` means no credit left.
- JSON bodies: Job Extract, Match and Rank reject unknown fields with 400. Text fields are trimmed and limited to 50,000 characters. Skills match takes `skill` or `skills` (≤ 100 items), never both.
- CV Extract: send the file as the multipart field `file` (about 4.5 MB max). On 200, `status` is always `"success"`; `upstream_status: "partial"` means optional steps were skipped. `info_resume.text` can reach 100,000 characters: truncate it to 50,000 before sending it to Match or Rank. Send `do_not_store_data=true` when the resume file must not be stored: HireLayer then does not store it and `info_resume.url` is `null`.
- Generated text (Job Extract labels and rationales, Match summaries and explanations, Rank rationales) is in French.
- Do not invent fields, endpoints or parameters. When unsure, read the OpenAPI document or the Markdown reference.

## Endpoints

- `POST /api/v3/parser` — HireLayer CV Extract: Upload one resume file and receive the structured candidate profile in the same response. (multipart/form-data, client timeout ≥ 150 s). Docs: https://onlineresumeparser.com/api-docs/extract.md
- `POST /api/v1/jobs/extract-criteria` — HireLayer Job Extract: Turn a job description into weighted criteria that can be checked against a resume. (JSON body, client timeout ≥ 65 s). Docs: https://onlineresumeparser.com/api-docs/job-extract.md
- `POST /api/v1/matching/job-candidate` — HireLayer Match: Evaluate one resume against each job criterion and get an explained 0–1 score. (JSON body, client timeout ≥ 65 s). Docs: https://onlineresumeparser.com/api-docs/match.md
- `POST /api/v1/matching/job-candidates/rank` — HireLayer Rank: Order up to 10 candidates for one job description, with a score and a rationale for each. (JSON body, client timeout ≥ 65 s). Docs: https://onlineresumeparser.com/api-docs/rank.md
- `POST /api/v1/skills/match` — HireLayer Skills: Map free-text skills, one or up to 100 at a time, to the closest catalog skills. (JSON body, client timeout ≥ 65 s). Docs: https://onlineresumeparser.com/api-docs/skills.md
- `GET /api/v1/skills` — HireLayer Skills: Download the whole reference catalog used for matching. (no body, client timeout ≥ 65 s). Docs: https://onlineresumeparser.com/api-docs/skills.md
- `GET /api/v1/health` — Platform: Check that the Job Extract, Match, Skills and Rank service is up. No API key needed. (no body, client timeout ≥ 10 s, no API key). Docs: https://onlineresumeparser.com/api-docs/health.md
- `POST /api/v2/parser` — HireLayer CV Extract: Legacy asynchronous contract: the request is accepted with `202` and the result is posted to `webhook_url`. (multipart/form-data, client timeout ≥ 50 s, LEGACY, do not use for new code). Docs: https://onlineresumeparser.com/api-docs/extract-v2.md

## References

- Index for agents: https://onlineresumeparser.com/llms.txt
- Full documentation in one file: https://onlineresumeparser.com/llms-full.txt
- OpenAPI 3.1: https://onlineresumeparser.com/openapi.json