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
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
| Property | HireLayer Rank | HireLayer Match |
|---|---|---|
| Question answered | Who should I review first for this job? | How well does this candidate meet each requirement? |
| Candidates per request | 1 to 10 | 1 |
| Criteria needed | No, job_text is enough | Yes, matching_criteria |
| Output | rank · score · rationale per candidate | score · summary · status and explanation per criterion |
| Credits | 1 per request | 1 per candidate |
| Typical moment | Shortlist review | Profile 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.
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." }
]
}'{
"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.
- 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 - 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 - 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.
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.
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.
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.
- 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 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.
Works well with
Related HireLayer APIs
- HireLayer MatchCandidate & Job Matching APIScore one candidate against a job, criterion by criterion.
- HireLayer CV ExtractResume Parsing APITurn CV files into structured candidate JSON.
- HireLayer Job ExtractJob Parsing APITurn job descriptions into weighted criteria.
