DocumentationCandidate Matching

04 / MATCHING

Candidate Matching

Evaluate a candidate against job criteria or rank a small candidate set against the same job description.

Endpoints

Input

JSON

Ranking limit

10 candidates

Reference

Endpoints

2 endpoints

Endpoint

Match one candidate

Evaluate a candidate against a job and its extracted criteria.

POST/api/v1/matching/job-candidate

Request

Content-Typeapplication/json

job_text

stringrequired

Job description, up to 50,000 characters.

candidate_text

stringrequired

Candidate CV text, up to 50,000 characters.

matching_criteria

MatchingCriterion[]required

Criteria with id, label, weight, is_mandatory, and rationale. Reuse the objects returned by extraction.

Errors

401

Missing or invalid API key. The public façade returns { error: "Missing API Key" } or { error: "Invalid API Key" }; direct HireLayer returns { success: false, error: "Unauthorized. Valid API key required." } when API_KEY is configured.

400

The request body is missing or invalid.

404

The requested endpoint does not exist.

502

Bedrock failed or returned an invalid response.

500

Unexpected server-side failure.

Example request

Request example

curl -X POST https://onlineresumeparser.com/api/v1/matching/job-candidate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"job_text":"React required. Fluent English required. Paris-based.","candidate_text":"Senior React and TypeScript developer based in Paris with professional English.","matching_criteria":[{"id":"crit_1","label":"React","weight":3,"is_mandatory":true,"rationale":"React is explicitly required for the role."},{"id":"crit_2","label":"English","weight":2,"is_mandatory":true,"rationale":"The job description requires fluent English for daily collaboration."},{"id":"crit_3","label":"Paris","weight":1,"is_mandatory":false,"rationale":"The position is described as Paris-based, but the requirement is not marked as mandatory."}]}'

Response

score is the historical weighted average using ideal = 1, potential = 0.6, not_mentioned = 0.5, and not_valid = 0. Every criterion remains in the weighted denominator.

{
  "score": 0.8666666666666667,
  "summary": "Le candidat couvre les compétences techniques principales et peut être considéré pour un entretien.",
  "evaluated_criteria": [
    {
      "id": "crit_1",
      "label": "React",
      "weight": 3,
      "is_mandatory": true,
      "rationale": "React is explicitly required for the role.",
      "match_status": "ideal",
      "match_explanation": "Le CV mentionne quatre ans d'expérience avec React sur des applications web en production."
    },
    {
      "id": "crit_2",
      "label": "English",
      "weight": 2,
      "is_mandatory": true,
      "rationale": "The job description requires fluent English for daily collaboration.",
      "match_status": "potential",
      "match_explanation": "Le CV indique un niveau d'anglais professionnel, mais ne précise pas de certification ou de niveau CECRL."
    },
    {
      "id": "crit_3",
      "label": "Paris",
      "weight": 1,
      "is_mandatory": false,
      "rationale": "The position is described as Paris-based, but the requirement is not marked as mandatory.",
      "match_status": "ideal",
      "match_explanation": "La localisation actuelle du candidat est Paris, France."
    }
  ]
}

Allowed values in response

evaluated_criteria[].match_status

idealpotentialnot_validnot_mentioned

The public status assigned by the evidence-based evaluator for each supplied criterion.

Implementation notes. matching_criteria may be an empty array; the response is exactly score 0, summary "Aucun critère à évaluer.", and an empty evaluated_criteria array. Statuses are ideal, potential, not_valid, or not_mentioned. is_mandatory is informational and does not determine the status or score. job_text and candidate_text are trimmed, must be non-empty strings of at most 50,000 characters, and the body accepts no other top-level fields. Each criterion must contain exactly id, label, weight, is_mandatory, and rationale; weight is an integer from 1 to 3, id, label, and rationale are non-empty strings, and is_mandatory is boolean. The model evaluates only the supplied job text, candidate text, and matching_criteria.

Endpoint

Rank candidates

Rank up to 10 candidates against one job description.

POST/api/v1/matching/job-candidates/rank

Request

Content-Typeapplication/json

job_text

stringrequired

Job description, up to 50,000 characters.

candidates

Candidate[]required

1–10 unique candidates with id and candidate_text.

Errors

401

400

The request body is missing or invalid.

404

The requested endpoint does not exist.

502

Bedrock failed or returned an invalid response.

500

Unexpected server-side failure.

Example request

Request example

curl -X POST https://onlineresumeparser.com/api/v1/matching/job-candidates/rank \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"job_text":"React required. Fluent English required. Paris-based.","candidates":[{"id":"candidate_1","candidate_text":"Senior React and TypeScript developer based in Paris with professional English."},{"id":"candidate_2","candidate_text":"Frontend engineer with React experience and conversational English in Lyon."},{"id":"candidate_3","candidate_text":"JavaScript developer with limited React production experience."}]}'

Response

Every candidate appears once. Rankings include a 1-based rank, the original candidate id, a 0–1 score, and a French rationale.

{
  "rankings": [
    {
      "rank": 1,
      "candidate_id": "candidate_1",
      "score": 0.92,
      "rationale": "Le profil couvre clairement React, TypeScript et l'expérience attendue pour le poste."
    },
    {
      "rank": 2,
      "candidate_id": "candidate_2",
      "score": 0.78,
      "rationale": "Le candidat possède une solide expérience frontend, mais son expérience TypeScript est moins détaillée."
    },
    {
      "rank": 3,
      "candidate_id": "candidate_3",
      "score": 0.61,
      "rationale": "Le profil montre une base JavaScript pertinente, mais peu d'éléments sur React en production."
    }
  ]
}

Implementation notes. job_text and each candidate_text are trimmed, must be non-empty strings of at most 50,000 characters, and the body accepts no other top-level fields. Candidate ids must be non-empty, unique after trimming, and each candidate object must contain exactly id and candidate_text. The endpoint accepts 1 to 10 candidates. It returns exactly one ranking per input candidate, with ranks sorted from 1 to n.