APIs

HireLayer Job Extract

Extract explicit, weighted and mandatory criteria from a job description, ready to send to HireLayer Match.

Endpoint: POST /api/v1/jobs/extract-criteria
Input: JSON · job_text up to 50,000 characters
Output: Weighted criteria with a French label and rationale
Billing: 1 credit per successful call

Extract job criteria

POST/api/v1/jobs/extract-criteria

Turn a job description into weighted criteria that can be checked against a resume.

Authentication: X-API-Key header
Billing: 1 credit per successful call
Client timeout: Client timeout ≥ 65 s

Request body

Content type application/json

job_textstringrequired
Full job description, in any language. Trimmed before validation.
1–50,000 characters

Response

200Extracted criteria.

matching_criteriaMatchingCriterion[]
Criteria sorted by weight, highest first, with IDs crit_1…crit_n in that order. Can be empty.
›Show 5 child fieldsHide child fields
- idstring
  Criterion ID. Job Extract generates crit_1…crit_n; Match accepts any non-empty string.
  non-empty
- labelstring
  What is evaluated, in a short phrase.
  non-empty
- weightinteger
  Importance: 3 essential, 2 important, 1 nice to have.
  1–3
- is_mandatoryboolean
  Whether the job states it as a hard requirement. Informational: it does not change the Match score.
- rationalestring
  Why the criterion matters for the job.
  non-empty

Errors

400
Request body must be a JSON object
The body is missing, is a JSON array, or Content-Type is not application/json.
Do not retry
400
The request contains unsupported fields
The body contains a field that is not documented for this endpoint.
Do not retry
400
The 'job_text' field is required
job_text is missing or not a string.
Do not retry
400
job_text cannot be empty
job_text is empty after trimming.
Do not retry
400
job_text must be 50000 characters or less
job_text is longer than 50,000 characters after trimming.
Do not retry
401
Missing API Key
The X-API-Key header is absent. Authorization: Bearer is not accepted.
Do not retry
401
Invalid API Key
The key is malformed, unknown or revoked. Rotating a key revokes the previous one immediately.
Do not retry
403
Insufficient credits available
The account has no credit left. availableCredits is the current balance.
Fix, then retry
500
Internal server error
Unexpected gateway failure.
Retry with backoff
500
Internal server error. Please try again later.
The body is not valid JSON, is a JSON primitive or exceeds 10 MB, or the service failed unexpectedly. Check the payload: if it is valid, retry.
Retry with backoff
502
Upstream API unavailable
The service did not answer within 60 seconds, or could not be reached.
Retry with backoff
502
The AI processing step failed. Please try again later.
Criteria extraction failed or returned an invalid result after the service's internal retries.
Retry with backoff
503
Credit service temporarily unavailable
Credits could not be checked or deducted. No credit is consumed, including when the operation itself had completed.
Retry with backoff

Behavior

Latency: Synchronous. The gateway waits up to 60 seconds, then returns 502 Upstream API unavailable. Use a client timeout of at least 65 seconds.
Retries: Transient model errors are retried by the service before it answers. Retry 502 and 503 with exponential backoff; never retry 4xx unchanged. Failed requests are not charged.
Validation: Validation stops at the first error, so one call reports one problem. Text fields are trimmed before their length is checked.
Output: Only requirements a resume can prove are returned; the endpoint does not score candidates. label and rationale are written in French. The number of criteria is not fixed and can be zero.
Stability: Two calls with the same text can return slightly different criteria. Extract once per job, let a recruiter review the list, and store it with the job.

Request

curl -X POST https://onlineresumeparser.com/api/v1/jobs/extract-criteria \
  -H "X-API-Key: $HIRELAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "job_text": "Senior Frontend Engineer, Paris (hybrid). You will build our recruiting platform with React and TypeScript. Requirements: 5+ years of frontend development, strong React and TypeScript skills, fluent English. Nice to have: experience with Next.js."
  }'

import os

import requests

response = requests.post(
    "https://onlineresumeparser.com/api/v1/jobs/extract-criteria",
    headers={"X-API-Key": os.environ["HIRELAYER_API_KEY"]},
    json={
        "job_text": "Senior Frontend Engineer, Paris (hybrid). You will build our recruiting platform with React and TypeScript. Requirements: 5+ years of frontend development, strong React and TypeScript skills, fluent English. Nice to have: experience with Next.js.",
    },
    timeout=65,
)
response.raise_for_status()

data = response.json()
print(data["matching_criteria"])

const response = await fetch('https://onlineresumeparser.com/api/v1/jobs/extract-criteria', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.HIRELAYER_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    job_text: 'Senior Frontend Engineer, Paris (hybrid). You will build our recruiting platform with React and TypeScript. Requirements: 5+ years of frontend development, strong React and TypeScript skills, fluent English. Nice to have: experience with Next.js.',
  }),
  signal: AbortSignal.timeout(65_000),
})

if (!response.ok) {
  throw new Error(`HireLayer ${response.status}: ${await response.text()}`)
}

const data = await response.json()
console.log(data.matching_criteria)

Response

{
  "matching_criteria": [
    {
      "id": "crit_1",
      "label": "Maîtrise de React",
      "weight": 3,
      "is_mandatory": true,
      "rationale": "React est explicitement exigé pour le poste."
    },
    {
      "id": "crit_2",
      "label": "Maîtrise de TypeScript",
      "weight": 3,
      "is_mandatory": true,
      "rationale": "TypeScript est explicitement exigé pour le poste."
    },
    {
      "id": "crit_3",
      "label": "Au moins 5 ans d’expérience en développement frontend",
      "weight": 3,
      "is_mandatory": true,
      "rationale": "L’offre demande plus de cinq ans d’expérience frontend."
    },
    {
      "id": "crit_4",
      "label": "Anglais courant",
      "weight": 2,
      "is_mandatory": true,
      "rationale": "Un anglais courant est demandé."
    },
    {
      "id": "crit_5",
      "label": "Expérience avec Next.js",
      "weight": 1,
      "is_mandatory": false,
      "rationale": "Next.js est présenté comme un atout."
    }
  ]
}

{
  "success": false,
  "error": "Request body must be a JSON object"
}