HireLayer logoHireLayer

HireLayer Rank · Candidate Ranking API

Candidate Ranking API that orders a shortlist against one job

Send one job description and up to 10 candidate profiles in a single request. HireLayer Rank compares them side by side and returns every candidate once, ranked, scored from 0 to 1 and explained.

Schedule a demo
Endpoint
POST /api/v1/matching/job-candidates/rank
Input
1 job · 1–10 candidates
Response
rankings[] 1 → n
Billing
1 credit per ranking

HireLayer Rank

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

200 OK
Three candidates sent in any order come back ranked 1 to 3 with scores of 0.92, 0.78 and 0.61. Values come from the documented API example.

Capabilities

What the Candidate Ranking API returns

Problems it solves

  • Reviewing in arrival order

    Recruiters open applications as they came in, not in order of relevance to the job.

  • Separate scores are hard to compare

    Evaluating candidates one at a time does not tell you who is stronger when two profiles are close.

  • Shortlists need a reason

    Clients and hiring managers ask why one candidate is ahead of another.

  • 01

    Comparative ranking in one call

    Up to 10 candidates are evaluated against the same job in a single request.

  • 02

    Every candidate returned once

    The response holds exactly one ranking per input candidate, sorted from rank 1 to n.

  • 03

    Your ids preserved

    candidate_id echoes the id you sent, so results map straight back to your records.

  • 04

    Score and rationale

    Each candidate gets a score from 0 to 1 and a short rationale explaining the position.

  • 05

    No criteria setup

    Only the job text is needed. No extraction step is required before ranking.

  • 06

    One credit per ranking

    A successful request consumes one credit, whether it ranks 2 or 10 candidates.

Under the hood

Ranking or matching: which call fits

PropertyHireLayer RankHireLayer Match
Question answeredWho should I review first for this job?How well does this candidate meet each requirement?
Candidates per request1 to 101
Criteria neededNo, job_text is enoughYes, matching_criteria
Outputrank · score · rationale per candidatescore · summary · status and explanation per criterion
Credits1 per request1 per candidate
Typical momentShortlist reviewProfile review, pre-screen

Request and response

Rank three candidates for one job

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

HireLayer Rank docs
RequestPOST /api/v1/matching/job-candidates/rank
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." }
    ]
  }'
Response200 OK · application/json
{
  "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."
    }
  ]
}
rankings[].rank
1-based position; ranks run from 1 to n.
rankings[].candidate_id
The id you sent, unchanged.
rankings[].score
Score between 0 and 1 for this job.
rankings[].rationale
Why the candidate holds this position, in French.

Use cases

Where teams rank candidates

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

  1. 01

    Order a consultant’s review queue

    Rank the candidates selected for a job order so consultants open the most relevant profiles first.

    Rank for Staffing & temp agencies
  2. 02

    Prepare a client shortlist

    Rank the final candidates and reuse each rationale as a starting point for the client presentation.

    Rank for Recruitment agencies
  3. 03

    Prioritize a sourced longlist

    Pick the 10 profiles a recruiter will actually review and rank them against the assignment.

    Rank for Sourcing tools

Integration

Integrate ranking into shortlist review

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

  1. STEP 01

    Select the set to compare

    Choose up to 10 candidates a recruiter will review for this job, using your own filters or pipeline stage.

  2. STEP 02

    Send job and candidate texts

    Use the job description and each candidate’s CV text, for example info_resume.text from HireLayer CV Extract.

  3. STEP 03

    Order the review queue

    Map candidate_id back to your records, sort by rank and show the rationale next to each profile.

Technical specifications

Authentication
X-API-Key header
Content-Type
application/json
Body
job_text · candidates; no other fields
Candidates
1 to 10, each with id and candidate_text
Ids
Non-empty and unique after trimming
Text limits
50,000 characters per text
Billing
1 credit per successful ranking

Where Rank 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 Ranking API questions

Answers based on the current API contract.

How many candidates can I rank in one request?

Between 1 and 10. Each candidate needs a unique id and a candidate_text, and the response contains exactly one ranking per candidate.

Should I use Rank or Match?

Use HireLayer Rank to compare up to 10 candidates for one job without preparing criteria. Use HireLayer Match when you need a criterion-by-criterion evaluation of a single candidate.

How is candidate ranking billed?

One credit per successful request, from the balance shared by all HireLayer APIs, whether it ranks 2 or 10 candidates.

Can I compare scores from different ranking requests?

A ranking compares the candidates sent together for one job. To compare two profiles directly, include both in the same request.

HireLayer Rank

Make your first HireLayer Rank call today.

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