Skip to content

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.

Schedule a demo
Endpoint
POST /api/v4/resumes/score
Input
1 job · up to 100 resumes, mixed
Response
score · verdict · criteria[]
Billing
1 credit per resume evaluated
HireLayer Resume Scorer, POST /api/v4/resumes/score. A resume file is scored against the nine criteria of a job: met, partial and unknown statuses, the unknown one left out, give a weighted score of 0.90 and the verdict highly_relevant. Values come from the documented API example.

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

statusValueTypical meaning
met1The resume meets or exceeds the criterion, with explicit evidence.
partial0.67Partly met: below the threshold, a neighbouring skill, or credible indirect evidence.
missing0.33 or 0Only a weak hint (0.33), or absent or contradicted (0).
unknownleft outInformation 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 required criterion clearly missing multiplies the score by 0.75 and is listed in required_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

Propertyprecise_ranking: trueDefault scoring
Question answeredWho should I review first for this job?How well does each resume meet the job?
OrderBy score, then the 10 best side by sideBy score
Per resumescore · verdict · criteria · ranking_reasonscore · verdict · criteria
Credits1 per resume evaluated, plus 1 per call1 per resume evaluated
Typical momentShortlist reviewScreening, 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.

RequestPOST /api/v4/resumes/score
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"
Response200 OK · application/json
{
  "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.

  1. 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
  2. 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
  3. 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.

  1. 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.

  2. STEP 02

    Show the scores

    Display each resume’s score, verdict and summary, best first, with the criteria statuses and quotes on demand.

  3. 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.

  1. CV filePDF, DOCX, image…
    Resume ParserResume Parsing API→ application_id · resume
    Job RecommendationsJob Recommendation APIresume → closest open jobs
    Resume ScorerCandidate & Job Matching APIjob + resumes → score · verdict
  2. Job descriptionText or file
    Job Criteria ExtractorJob Parsing API→ job_id · criteria[]
    Talent Pool SearchTalent Pool Search APIjob → closest stored resumes
    Resume ScorerCandidate & Job Matching API+ precise_ranking → ranking_reason
  3. Free-text skillsFrom CVs, jobs or users
    Skills 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?

HireLayer Resume Scorer. Every resume comes back with a score from 0 to 1, a verdict and each criterion of the job marked met, partial, missing or unknown, with a quote from the resume as evidence and a one-sentence explanation. required_missing lists the required criteria that pulled the score down, to_verify the ones to ask the candidate about, and summary gives the overall reading.

How is the candidate matching score calculated?

Each criterion scores 1 when met, 0.67 when partly met, 0.33 for a weak hint and 0 when missing. A skill, degree or experience the resume does not show is missing; only what resumes often leave out, such as availability or mobility, is unknown. The score is the mean of those values weighted by each criterion’s weight, leaving out the unknown ones, then × 0.75 for each required criterion clearly missing.

What does the verdict say?

The overall reading of the resume for the job: highly_relevant (shortlist), relevant (worth a call), marginally_relevant (weak) or not_relevant (off-topic). It sits next to the score and does not follow a weight you change later, so the two can disagree after a weight change.

Does a required criterion exclude a candidate automatically?

No. A candidate who clearly lacks a required criterion loses 25 % of their score and the criterion is listed in required_missing, but the candidate stays in the list: a resume may simply be incomplete. Hiring decisions stay with your recruiters.

Can I score against criteria I wrote myself?

Yes. Send your own criteria with the job text or file, in the format Job Criteria Extractor returns, or edit the criteria of the stored job. Changing a weight or a requirement is free and re-ranks at once; a new or reworded criterion means evaluating the job’s resumes again, billed per resume.

Are resumes evaluated again each time I ask?

No. Each job and resume pair is evaluated once and stored. Sending the same pair again, reading the ranking or re-ranking with other weights costs nothing; only a replaced resume or a changed criterion starts a new evaluation.

In which language are the results written?

Criteria, summaries and explanations are written in the job’s language, French or English; evidence quotes the resume in its own language.

How many resumes can I score in one call?

Up to 100. The answer comes back in the same call for up to 10 resume files and 50 resumes in all, in about a minute for 50. Beyond that, the call answers 202 and the scores can be read later or received by webhook.

When should I turn on precise ranking?

When the order of the best candidates matters. precise_ranking compares the 10 best resumes of the call against each other, can reorder close profiles and adds a ranking_reason to each. It costs 1 more credit per call that ranks at least 2 resumes.

How is resume scoring billed?

1 credit per resume evaluated, plus 1 per resume file parsed in the call, and 1 per call with precise_ranking. A pair already scored costs 0. A resume that fails is not billed and does not fail the call.

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.