Docs

APIs

HireLayer Match

Evaluate a resume against job criteria, criterion by criterion, with an explained status and a weighted 0–1 score.

Endpoint
POST /api/v1/matching/job-candidate
Input
JSON · job text, resume text and criteria
Output
Score from 0 to 1, a status and an explanation per criterion
Billing
1 credit per successful call

Match a candidate to a job

POST/api/v1/matching/job-candidate

Evaluate one resume against each job criterion and get an explained 0–1 score.

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

    Job description. Trimmed before validation.

    1–50,000 characters

  • candidate_textstringrequired

    Candidate resume as plain text, e.g. info_resume.text from HireLayer CV Extract. Trimmed before validation.

    1–50,000 characters

  • matching_criteriaMatchingCriterion[]required

    Criteria to evaluate, usually from HireLayer Job Extract. Can be empty. No other criterion field is accepted.

    ›Show 5 child fields
    • idstringrequired

      Criterion ID. Job Extract generates crit_1…crit_n; Match accepts any non-empty string.

      non-empty

    • labelstringrequired

      What is evaluated, in a short phrase.

      non-empty

    • weightintegerrequired

      Importance: 3 essential, 2 important, 1 nice to have.

      1–3

    • is_mandatorybooleanrequired

      Whether the job states it as a hard requirement. Informational: it does not change the Match score.

    • rationalestringrequired

      Why the criterion matters for the job.

      non-empty

Response

200Evaluation of every criterion.

  • scorenumber

    Weighted average of the criterion statuses. Not rounded.

    0–1

  • summarystring

    Overall assessment, in French.

  • evaluated_criteriaEvaluatedCriterion[]

    Every input criterion, in input order, with its evaluation.

    ›Show 7 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

    • match_statusstring

      ideal: clearly met · potential: partly or indirectly met · not_mentioned: the resume says nothing · not_valid: contradicted.

      "ideal""potential""not_valid""not_mentioned"
    • match_explanationstring

      Evidence from the resume, in French.

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

  • 400
    The 'candidate_text' field is required

    candidate_text is missing or not a string.

    Do not retry

  • 400
    candidate_text cannot be empty

    candidate_text is empty after trimming.

    Do not retry

  • 400
    candidate_text must be 50000 characters or less

    candidate_text is longer than 50,000 characters after trimming.

    Do not retry

  • 400
    The 'matching_criteria' field must be an array

    matching_criteria is missing or not an array.

    Do not retry

  • 400
    matching_criteria contains an invalid criterion

    A criterion has a missing, empty or extra field, or a weight outside 1–3.

    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.

    Matching 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.
Score
score = Σ(weight × value) / Σ weight with ideal = 1, potential = 0.6, not_mentioned = 0.5 and not_valid = 0. Every criterion counts in the denominator; is_mandatory has no effect on the score.
Empty criteria
With "matching_criteria": [] the model is not called and the response is exactly {"score": 0, "summary": "Aucun critère à évaluer.", "evaluated_criteria": []}.
Hard requirements
To reject candidates who miss a mandatory criterion, check is_mandatory and match_status in your code: the score alone does not do it.
curl -X POST https://onlineresumeparser.com/api/v1/matching/job-candidate \
  -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.",
    "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.",
    "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."
      }
    ]
  }'
{
  "score": 0.8916666666666666,
  "summary": "Profil très aligné : React, TypeScript et l’expérience demandée sont démontrés. Le niveau d’anglais reste à confirmer.",
  "evaluated_criteria": [
    {
      "id": "crit_1",
      "label": "Maîtrise de React",
      "weight": 3,
      "is_mandatory": true,
      "rationale": "React est explicitement exigé pour le poste.",
      "match_status": "ideal",
      "match_explanation": "Le CV décrit une équipe React dirigée depuis 2022 sur une plateforme en production."
    },
    {
      "id": "crit_2",
      "label": "Maîtrise de TypeScript",
      "weight": 3,
      "is_mandatory": true,
      "rationale": "TypeScript est explicitement exigé pour le poste.",
      "match_status": "ideal",
      "match_explanation": "La plateforme actuelle est développée en TypeScript."
    },
    {
      "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.",
      "match_status": "ideal",
      "match_explanation": "Le candidat cumule huit ans d’expérience en développement."
    },
    {
      "id": "crit_4",
      "label": "Anglais courant",
      "weight": 2,
      "is_mandatory": true,
      "rationale": "Un anglais courant est demandé.",
      "match_status": "potential",
      "match_explanation": "Le CV mentionne un anglais professionnel, sans préciser un niveau courant."
    },
    {
      "id": "crit_5",
      "label": "Expérience avec Next.js",
      "weight": 1,
      "is_mandatory": false,
      "rationale": "Next.js est présenté comme un atout.",
      "match_status": "not_mentioned",
      "match_explanation": "Le CV ne mentionne pas Next.js."
    }
  ]
}