HireLayer Resume Scorer · Candidate & Job Matching API
Candidate & Job Matching API with evidence for every criterion
Send a job and its resumes, as files, text, parsed JSON or stored ids. HireLayer Resume Scorer extracts the job’s criteria, evaluates every resume against them with a quote from the resume and an explanation, then returns each one scored from 0 to 1 with a verdict, best first.
- Endpoint
- POST /api/v4/resumes/score
- Input
- 1 job · up to 100 resumes, mixed
- Response
- score · verdict · criteria[]
- Billing
- 1 credit per resume evaluated
What the Candidate Matching API does
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.
Re-scoring every candidate is slow and costly
When a recruiter changes priorities, a stateless scoring call has to evaluate the whole pipeline again.
01
Criteria from the job description
Send the job text or file and its criteria are extracted, typed and weighted. Or send your own with it.
02
Evidence for every criterion
Each criterion is met, partial, missing or unknown, with a quote from the resume and a one-sentence explanation.
03
A score and a verdict
A score from 0 to 1, a verdict from highly_relevant to not_relevant, and a summary in the job’s language.
04
Any resume, mixed in one call
Files, plain text, parsed resume JSON or stored application_ids, up to 100 resumes in one request.
05
Scored once, free to ask again
A job and resume pair already scored costs nothing the next time. Changing a weight re-ranks at once, for free.
06
Precise ranking, an option
precise_ranking compares the 10 best resumes against each other and explains each place, for 1 more credit per call.
How the matching score is calculated
| status | Value | Typical meaning |
|---|---|---|
| met | 1 | The resume meets or exceeds the criterion, with explicit evidence. |
| partial | 0.67 | Partly met: below the threshold, a neighbouring skill, or credible indirect evidence. |
| missing | 0.33 or 0 | Only a weak hint (0.33), or absent or contradicted (0). |
| unknown | left out | Information a resume often leaves out, such as availability or mobility. |
Worked example
The resume of the example below: 7 criteria counted, 1 unknown.
score = Σ(weight × value) / Σ(weight), unknown left out
= (3 × ⅔ + 3 + 2 + 2 + 2 + 1 × ⅔ + 1) / 14
= 12.67 / 14 = 0.90
- Each
requiredcriterion clearly missing multiplies the score by 0.75 and is listed inrequired_missing: the candidate is never eliminated outright. - A weight change re-ranks at once, with no new evaluation. A weight of 0 turns a criterion off.
- highly_relevantShortlist
- relevantWorth a call
- marginally_relevantWeak
- not_relevantOff-topic
With the precise_ranking option
| Property | precise_ranking: true | Default scoring |
|---|---|---|
| Question answered | Who should I review first for this job? | How well does each resume meet the job? |
| Order | By score, then the 10 best side by side | By score |
| Per resume | score · verdict · criteria · ranking_reason | score · verdict · criteria |
| Credits | 1 per resume evaluated, plus 1 per call | 1 per resume evaluated |
| Typical moment | Shortlist review | Screening, pre-screen |
Score a resume file against a job
Values below come from the API reference example. Field names and shapes match the live contract.
jq -n --rawfile text job.txt '{job: {text: $text}, resumes: [{file: "cv1"}]}' > request.json
curl -X POST https://hirelayer.co/api/v4/resumes/score \
-H "X-API-Key: $HIRELAYER_API_KEY" \
-F "request=<request.json;type=application/json" \
-F "cv1=@resume.pdf"{
"request_id": "bfd08cb3-fd31-4e93-8210-dbe4512d245f",
"job": {
"job_id": "job_020cb8c5f1f8eb650cec00dc3d90f8ea",
"title": null,
"language": "en"
},
"precise_ranking": false,
"scores": [
{
"rank": 1,
"application_id": "file_d7e21d373637a897b17b8fdf63122807",
"file_name": "elias-moreau-resume.pdf",
"evaluation_status": "completed",
"score": 0.9,
"verdict": "highly_relevant",
"summary": "Strong AI/Backend profile with excellent LLM production experience and AWS skills, though slightly below the 3-year Node.js seniority threshold.",
"required_missing": [],
"to_verify": [{ "criterion_id": "crit_9", "label": "On-call duty" }],
"criteria": [
{
"criterion_id": "crit_2",
"label": "Backend development with Node.js / TypeScript",
"status": "partial",
"score": 0.67,
"evidence": "API stack (serverless AWS): API Gateway, Lambda, S3, DynamoDB, Terraform, Node.js",
"explanation": "The candidate has production experience with Node.js backend, but the duration at Novalys AI (2024-25) is approximately 1-2 years, below the 3-year threshold required."
},
{
"criterion_id": "crit_3",
"label": "LLM integration in production",
"status": "met",
"score": 1,
"evidence": "Built a SaaS platform with several generative AI features. [...] Cut the average latency of the main AI features by 50%. Scalable solution, 500k+ documents processed.",
"explanation": "The candidate clearly demonstrates hands-on LLM integration in production with a SaaS platform processing 500k+ documents, exceeding the requirement."
},
{
"criterion_id": "crit_9",
"label": "On-call duty",
"status": "unknown",
"score": null,
"evidence": "",
"explanation": "The CV does not mention acceptance of on-call duty; this must be verified during the interview."
}
]
}
],
"credits_used": 2
}- score
- Weighted mean of the criterion scores, unknown ones left out, × 0.75 per required criterion clearly missing.
- verdict
- highly_relevant · relevant · marginally_relevant · not_relevant: the overall reading.
- criteria[].status
- met · partial · missing · unknown, with the quote from the resume in evidence. 3 of 8 shown.
- credits_used
- 1 to parse the file, 1 to evaluate it. The same pair sent again costs 0.
Where teams use candidate–job matching
HireLayer Resume Scorer is used by recruiting software and recruiting services. Each use case links to the full workflow.
- 01
Ranked pipeline in an ATS
Show each job’s candidates best first, with the verdict, the per-criterion statuses and quotes next to every application.
Resume Scorer for ATS platforms - 02
Pre-screen before a consultant call
Evaluate the shortlist against the job order’s criteria and prepare questions for the criteria listed in to_verify.
Resume Scorer for Staffing & temp agencies - 03
Screen applications as they arrive
Score each new application against the job and route the highly_relevant ones to a recruiter first.
Resume Scorer for AI resume screening
Integrate matching into your ATS
Call the API from your backend and keep the key server-side. Your product keeps its records, interface and review process.
STEP 01
Send the job and its resumes
POST the job text or file with the resumes, as files or stored application_ids. Set a client timeout of 150 seconds.
STEP 02
Show the scores
Display each resume’s score, verdict and summary, best first, with the criteria statuses and quotes on demand.
STEP 03
Score new applications as they come
Send the job_id with the new resumes. Pairs already scored come back for free, and the job’s whole ranking can be read at any time.
Technical specifications
- Authentication
- X-API-Key header
- Content-Type
- application/json, or multipart with the JSON in request
- Job
- One of file, text or job_id, with your criteria if you want
- Resumes
- 1 to 100: file, text, parsed resume or application_id
- Response time
- About a minute for 50 resumes; 202 past 10 files or 50 resumes
- Workspaces
- HireLayer-Workspace header, one per client company
- Billing
- 1 credit per resume evaluated, +1 per file parsed; 0 for a pair already scored
No backend to write? Use Resume Scorer from Make, Power Automate, ChatGPT, Claude, Google Sheets or your ATS.
Where Resume Scorer fits in the HireLayer pipeline
Each product works on its own. Chain them when a workflow needs CV data, job criteria, a search and a decision aid together.
- CV filePDF, DOCX, image…Resume ParserResume Parsing API→ application_id · resumeJob RecommendationsJob Recommendation APIresume → closest open jobsResume ScorerCandidate & Job Matching APIjob + resumes → score · verdict
- Job descriptionText or fileJob Criteria ExtractorJob Parsing API→ job_id · criteria[]Talent Pool SearchTalent Pool Search APIjob → closest stored resumesResume ScorerCandidate & Job Matching API+ precise_ranking → ranking_reason
- Free-text skillsFrom CVs, jobs or usersSkills NormalizerSkills Matching API→ taxonomy skill ids
Store skill ids on profiles and jobs for search and facets.
Resume Parser and Job Criteria Extractor store what they read. The searches find the closest resumes or jobs; Resume Scorer explains the fit. One API key and one credit balance cover every call.
Candidate Matching API questions
Answers based on the current API contract.
Which candidate matching API explains why a candidate scores high or low?
How is the candidate matching score calculated?
What does the verdict say?
Does a required criterion exclude a candidate automatically?
Can I score against criteria I wrote myself?
Are resumes evaluated again each time I ask?
In which language are the results written?
How many resumes can I score in one call?
When should I turn on precise ranking?
How is resume scoring billed?
Make your first call to HireLayer Resume Scorer today.
Create an account to get an API key. Credits are shared across all six HireLayer products.
Related HireLayer products
- Job Parsing APIHireLayer Job Criteria ExtractorTurn job descriptions into typed, weighted criteria.
- Talent Pool Search APIHireLayer Talent Pool SearchFind the stored resumes closest to a job.
- Job Recommendation APIHireLayer Job RecommendationsFind the open jobs closest to a resume.
Solutions using Resume Scorer
- AI resume screening
- ATS platforms
- Staffing & temp agencies
- Recruitment agencies
- Job boards & career sites