# HireLayer Job Extract

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

Source: https://onlineresumeparser.com/api-docs/job-extract · Markdown: https://onlineresumeparser.com/api-docs/job-extract.md

- **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 https://onlineresumeparser.com/api/v1/jobs/extract-criteria`

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

- **Authentication:** `X-API-Key` header
- **Content type:** `application/json`
- **Billing:** 1 credit per successful call
- **Client timeout:** at least 65 seconds

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `job_text` | `string` | Yes | Full job description, in any language. Trimmed before validation. 1–50,000 characters. |

### Example request

**cURL**

```bash
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."
  }'
```

**Python**

```python
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"])
```

**TypeScript**

```typescript
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 `200`

Extracted criteria.

| Field | Type | Description |
| --- | --- | --- |
| `matching_criteria` | `MatchingCriterion[]` | Criteria sorted by `weight`, highest first, with IDs `crit_1`…`crit_n` in that order. Can be empty. |
| `matching_criteria[].id` | `string` | Criterion ID. Job Extract generates `crit_1`…`crit_n`; Match accepts any non-empty string. Non-empty. |
| `matching_criteria[].label` | `string` | What is evaluated, in a short phrase. Non-empty. |
| `matching_criteria[].weight` | `integer` | Importance: `3` essential, `2` important, `1` nice to have. 1–3. |
| `matching_criteria[].is_mandatory` | `boolean` | Whether the job states it as a hard requirement. Informational: it does not change the Match score. |
| `matching_criteria[].rationale` | `string` | Why the criterion matters for the job. Non-empty. |

```json
{
  "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."
    }
  ]
}
```

### Errors

| Status | `error` | `code` | When | Retry |
| --- | --- | --- | --- | --- |
| `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 |

Example error (`400`):

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

### 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.

> **Tip: Send the criteria to Match unchanged.** Each criterion has exactly the shape `matching_criteria` expects in [HireLayer Match](https://onlineresumeparser.com/api-docs/match.md). You can also edit, remove or write criteria yourself.

## Next

- [HireLayer Match](https://onlineresumeparser.com/api-docs/match.md): Evaluate a resume against job criteria, criterion by criterion, with an explained status and a weighted 0–1 score.
- [Build a screening pipeline](https://onlineresumeparser.com/api-docs/screening-pipeline.md): Chain HireLayer CV Extract, Job Extract, Rank and Match to parse resumes, score them against a job and explain the result.