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
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_status | Value | Typical meaning |
|---|---|---|
| ideal | 1 | The CV clearly meets the criterion. |
| potential | 0.6 | The CV partly meets it, or the evidence is indirect. |
| not_mentioned | 0.5 | The CV says nothing either way. |
| not_valid | 0 | The 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_mandatoryis informational: it does not change the status or the score.- An empty
matching_criteriaarray 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.
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." }
]
}'{
"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.
- 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 - 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 - 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.
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.
STEP 02
Send the candidate text
Use info_resume.text from HireLayer CV Extract or the CV text you already store as candidate_text.
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.
- CV filePDF, DOCX, image…CV ExtractResume Parsing API→ info_resume.text · skills[]MatchCandidate & Job Matching APIjob_text + candidate_text + matching_criteria
- Job descriptionPlain job_textJob ExtractJob Parsing API→ matching_criteria[]RankCandidate Ranking APIjob_text + up to 10 candidate_text
- Free-text skillsFrom CVs, jobs or usersSkillsSkills 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.
Works well with
Related HireLayer APIs
- HireLayer Job ExtractJob Parsing APITurn job descriptions into weighted criteria.
- HireLayer RankCandidate Ranking APIRank up to 10 candidates against one job.
- HireLayer CV ExtractResume Parsing APITurn CV files into structured candidate JSON.
