# HireLayer Rank

> Rank up to 10 candidates against one job description in a single call, with a score and a rationale for each.

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

- **Endpoint:** `POST /api/v1/matching/job-candidates/rank`
- **Input:** JSON · job text and 1–10 candidates
- **Output:** Ranks `1`…`n`, scores and French rationales
- **Billing:** 1 credit per successful call

## Rank candidates for a job

`POST https://onlineresumeparser.com/api/v1/matching/job-candidates/rank`

Order up to 10 candidates for one job description, with a score and a rationale for each.

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

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `job_text` | `string` | Yes | Job description. Trimmed before validation. 1–50,000 characters. |
| `candidates` | `RankingCandidate[]` | Yes | Candidates to rank against the same job. 1–10 items. |
| `candidates[].id` | `string` | Yes | Your candidate ID. Unique within the request after trimming. Non-empty. |
| `candidates[].candidate_text` | `string` | Yes | Resume as plain text. Trimmed before validation. 1–50,000 characters. |

### Example request

**cURL**

```bash
curl -X POST https://onlineresumeparser.com/api/v1/matching/job-candidates/rank \
  -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.",
    "candidates": [
      {
        "id": "candidate_1",
        "candidate_text": "Alex Morgan, Senior Software Engineer in Paris. 8 years of experience. Since 2022, leads a team building a React and TypeScript SaaS platform at Northstar Labs. Previously built Node.js APIs. Professional English."
      },
      {
        "id": "candidate_2",
        "candidate_text": "Frontend developer in Lyon with 3 years of React experience on e-commerce sites. JavaScript, some TypeScript. Conversational English."
      },
      {
        "id": "candidate_3",
        "candidate_text": "Full-stack JavaScript developer with 6 years of experience, mostly Vue.js and PHP. Fluent English."
      }
    ]
  }'
```

**Python**

```python
import os

import requests

response = requests.post(
    "https://onlineresumeparser.com/api/v1/matching/job-candidates/rank",
    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.",
        "candidates": [
            {
                "id": "candidate_1",
                "candidate_text": "Alex Morgan, Senior Software Engineer in Paris. 8 years of experience. Since 2022, leads a team building a React and TypeScript SaaS platform at Northstar Labs. Previously built Node.js APIs. Professional English.",
            },
            {
                "id": "candidate_2",
                "candidate_text": "Frontend developer in Lyon with 3 years of React experience on e-commerce sites. JavaScript, some TypeScript. Conversational English.",
            },
            {
                "id": "candidate_3",
                "candidate_text": "Full-stack JavaScript developer with 6 years of experience, mostly Vue.js and PHP. Fluent English.",
            },
        ],
    },
    timeout=65,
)
response.raise_for_status()

data = response.json()
print(data["rankings"])
```

**TypeScript**

```typescript
const response = await fetch('https://onlineresumeparser.com/api/v1/matching/job-candidates/rank', {
  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.',
    candidates: [
      {
        id: 'candidate_1',
        candidate_text: 'Alex Morgan, Senior Software Engineer in Paris. 8 years of experience. Since 2022, leads a team building a React and TypeScript SaaS platform at Northstar Labs. Previously built Node.js APIs. Professional English.',
      },
      {
        id: 'candidate_2',
        candidate_text: 'Frontend developer in Lyon with 3 years of React experience on e-commerce sites. JavaScript, some TypeScript. Conversational English.',
      },
      {
        id: 'candidate_3',
        candidate_text: 'Full-stack JavaScript developer with 6 years of experience, mostly Vue.js and PHP. Fluent English.',
      },
    ],
  }),
  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.rankings)
```

### Response `200`

Ranked candidates.

| Field | Type | Description |
| --- | --- | --- |
| `rankings` | `Ranking[]` | One entry per candidate, sorted by `rank`. |
| `rankings[].rank` | `integer` | Position from 1 (best) to the number of candidates. ≥ 1. |
| `rankings[].candidate_id` | `string` | The `id` you sent, trimmed. |
| `rankings[].score` | `number` | Relevance for the job. Use `rank` for ordering. 0–1. |
| `rankings[].rationale` | `string` | Why the candidate holds this position, in French. |

```json
{
  "rankings": [
    {
      "rank": 1,
      "candidate_id": "candidate_1",
      "score": 0.91,
      "rationale": "React et TypeScript sont démontrés en production, avec l’expérience demandée."
    },
    {
      "rank": 2,
      "candidate_id": "candidate_2",
      "score": 0.64,
      "rationale": "Bonne pratique de React, mais expérience plus courte et anglais seulement conversationnel."
    },
    {
      "rank": 3,
      "candidate_id": "candidate_3",
      "score": 0.38,
      "rationale": "Profil JavaScript solide, mais centré sur Vue.js sans expérience React mentionnée."
    }
  ]
}
```

### 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 |
| `400` | `The 'candidates' field must be an array` | — | `candidates` is missing or not an array. | Do not retry |
| `400` | `candidates cannot be empty` | — | `candidates` is `[]`. | Do not retry |
| `400` | `candidates must contain 10 candidates or fewer` | — | More than 10 candidates. | Do not retry |
| `400` | `candidates contains an invalid candidate` | — | A candidate has a missing, empty or extra field. | Do not retry |
| `400` | `candidate_text must be 50000 characters or less` | — | A `candidate_text` is longer than 50,000 characters after trimming. | Do not retry |
| `400` | `candidates contains duplicate ids` | — | Two candidates share the same `id` 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.` | — | Ranking 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.
- **Ordering:** Every candidate appears exactly once and ranks are `1`…`n`. `rank` is authoritative: `score` is not guaranteed to decrease strictly with rank.
- **More than 10 candidates:** Ranks are relative to one request. To screen a larger pool, pre-filter it, or score each candidate with [Match](https://onlineresumeparser.com/api-docs/match.md) against the same criteria, which gives comparable scores.

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