HireLayer logoHireLayer

HireLayer Match · Candidate & Job Matching API

Candidate & Job Matching API with evidence for every criterion

Compare one candidate with one job. HireLayer Match checks each criterion against the CV text, returns a status and an explanation for each, then computes a weighted score your recruiters can audit.

Schedule a demo
Endpoint
POST /api/v1/matching/job-candidate
Input
Job · candidate · criteria
Response
Score + per-criterion evidence
Billing
1 credit per match

HireLayer Match

POST /api/v1/matching/job-candidate

200 OK
Three criteria are evaluated as ideal, potential and ideal, giving a weighted score of 0.87. Values come from the documented API example.

Capabilities

What the Candidate Matching API evaluates

Problems it solves

  • Keyword overlap misses context

    “Led a React migration” and “React” in a skills list are not the same evidence, yet keyword filters treat them alike.

  • A bare score is not reviewable

    Recruiters and hiring managers need to see why a candidate fits before they act on a number.

  • Hidden weighting is hard to trust

    If you cannot reproduce how a score was built, you cannot explain it to a client or a candidate.

  • 01

    Four evidence statuses

    Each criterion is marked ideal, potential, not_mentioned or not_valid based on the CV text.

  • 02

    An explanation per criterion

    match_explanation states what the CV shows, or does not show, for that requirement.

  • 03

    A transparent weighted score

    Status values are averaged by criterion weight. Every criterion stays in the denominator, so you can recompute it.

  • 04

    Your criteria, your rules

    Send the criteria from HireLayer Job Extract or write your own with the same five fields.

  • 05

    Evaluates only what you send

    The model works from the job text, candidate text and criteria in the request, nothing else.

  • 06

    A recruiter-ready summary

    A short summary sentence comes with the score for a quick read in a review queue.

Under the hood

How the matching score is calculated

match_statusValueTypical meaning
ideal1The CV clearly meets the criterion.
potential0.6The CV partly meets it, or the evidence is indirect.
not_mentioned0.5The CV says nothing either way.
not_valid0The CV does not meet the criterion.

Worked example

score = Σ(weight × value) / Σ(weight)
= (3 × 1 + 2 × 0.6 + 1 × 1) / (3 + 2 + 1)
= 5.2 / 6 = 0.867

  • is_mandatory is informational: it does not change the status or the score.
  • An empty matching_criteria array returns a score of 0 and an empty evaluation.

Request and response

Match one candidate to one job

Values below come from the API reference example. Field names and shapes match the live contract.

HireLayer Match docs
RequestPOST /api/v1/matching/job-candidate
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." },
      { "id": "crit_3", "label": "Paris", "weight": 1, "is_mandatory": false, "rationale": "The position is Paris-based." }
    ]
  }'
Response200 OK · application/json
{
  "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,
      "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,
      "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,
      "match_status": "ideal",
      "match_explanation": "La localisation actuelle du candidat est Paris, France."
    }
  ]
}
score
Weighted average between 0 and 1; here (3 + 1.2 + 1) / 6.
evaluated_criteria[].match_status
ideal · potential · not_mentioned · not_valid.
evaluated_criteria[].match_explanation
The evidence found in the CV for this criterion.
summary · match_explanation
Generated in French in the current version. Response criteria also echo is_mandatory and rationale, trimmed here.

Use cases

Where teams use candidate–job matching

HireLayer Match is used by recruiting software and recruiting services. Each use case links to the full workflow.

  1. 01

    Fit panel on a candidate profile

    Show the per-criterion statuses next to the application so recruiters see strengths and gaps in one place.

    Match for ATS platforms
  2. 02

    Pre-screen before a consultant call

    Check a candidate against the job order’s criteria and prepare the questions for the not_mentioned items.

    Match for Staffing & temp agencies
  3. 03

    Candidate–job comparison on a marketplace

    Compare a candidate profile with a selected job post and explain the fit inside your job board.

    Match for Job boards & career sites

Integration

Integrate matching into your review flow

Call the API from your backend and keep the key server-side. Your product keeps its records, interface and review process.

  1. STEP 01

    Prepare criteria once per job

    Extract them with HireLayer Job Extract or write them yourself, then store the reviewed list with the job.

  2. STEP 02

    Send the candidate text

    Use info_resume.text from HireLayer CV Extract or the CV text you already store as candidate_text.

  3. STEP 03

    Store and apply your rules

    Save score and evaluated_criteria with the application. Apply your own knockout logic for mandatory criteria.

Technical specifications

Authentication
X-API-Key header
Content-Type
application/json
Body
job_text · candidate_text · matching_criteria; no other fields
Text limits
50,000 characters each, after trimming
Criterion shape
id · label · weight (1–3) · is_mandatory · rationale
Empty criteria
Allowed; returns score 0
Billing
1 credit per successful match

Where Match fits in the HireLayer pipeline

Each API works on its own. Chain them when a workflow needs CV data, job criteria and a decision aid together.

  1. CV filePDF, DOCX, image…
    CV ExtractResume Parsing API→ info_resume.text · skills[]MatchCandidate & Job Matching APIjob_text + candidate_text + matching_criteria
  2. Job descriptionPlain job_text
    Job ExtractJob Parsing API→ matching_criteria[]RankCandidate Ranking APIjob_text + up to 10 candidate_text
  3. Free-text skillsFrom CVs, jobs or users
    SkillsSkills Matching API→ catalog skill terms

    Store normalized terms on profiles and jobs for search and facets.

Match takes criteria from Job Extract and CV text from Extract. Rank only needs the job text and each candidate’s CV text. One API key and one credit balance cover every call.

Questions

Candidate Matching API questions

Answers based on the current API contract.

How is the candidate matching score calculated?

Each status has a value: ideal = 1, potential = 0.6, not_mentioned = 0.5 and not_valid = 0. The score is the average of those values weighted by each criterion’s weight, with every criterion kept in the denominator.

Does a mandatory criterion exclude a candidate automatically?

No. is_mandatory is informational and does not change the status or the score. Your application decides how to treat a not_valid mandatory criterion.

Can I match against criteria I wrote myself?

Yes. Send any criteria with exactly id, label, weight, is_mandatory and rationale. Weight must be an integer from 1 to 3.

Should I use Match or Rank?

Use HireLayer Match for a detailed, criterion-by-criterion evaluation of one candidate. Use HireLayer Rank to compare up to 10 candidates for the same job in a single request.

HireLayer Match

Make your first HireLayer Match call today.

Create an account to get an API key. Credits are shared across all five HireLayer APIs.