Get started
Quickstart
Create a free HireLayer API key, then rank resume files for a job description in one call with cURL or Python.
Rank resumes for a job in one call: send the job description and the resume files to POST /api/v4/resumes/score. The answer lists every resume best first, with a score from 0 to 1, a verdict, a summary and the evidence for each criterion of the job. The Free plan includes 50 credits a month with no card.
- 1
Create an API key
Sign up, then create a key in Dashboard → API keys. Keep it in an environment variable on your server:
Shell export HIRELAYER_API_KEY="sk_xxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" - 2
Rank resumes for a job
Put the job description in
job.pdfnext to the resumes. Each file goes in its own part, and the JSON in therequestpart names them:curl -X POST https://hirelayer.co/api/v4/resumes/score \ -H "X-API-Key: $HIRELAYER_API_KEY" \ --form-string 'request={"job":{"file":"job"},"resumes":[{"file":"cv1"},{"file":"cv2"}]}' \ -F "job=@job.pdf;type=application/pdf" \ -F "cv1=@elias.pdf;type=application/pdf" \ -F "cv2=@rafael.pdf;type=application/pdf"import json import os import requests with open("job.pdf", "rb") as file1, open("elias.pdf", "rb") as file2, open("rafael.pdf", "rb") as file3: response = requests.post( "https://hirelayer.co/api/v4/resumes/score", headers={"X-API-Key": os.environ["HIRELAYER_API_KEY"]}, files={"job": ("job.pdf", file1, "application/pdf"), "cv1": ("elias.pdf", file2, "application/pdf"), "cv2": ("rafael.pdf", file3, "application/pdf")}, data={ "request": json.dumps({ "job": { "file": "job", }, "resumes": [ { "file": "cv1", }, { "file": "cv2", }, ], }), }, timeout=150, ) response.raise_for_status() data = response.json() print(data["scores"])- Files: the job as PDF, DOCX, TXT or HTML; resumes as 15 formats, PDF, Word, images, TXT, HTML and Markdown included.
- Texts instead of files: write
{"text": "…"}in place of{"file": "…"}, for the job or any resume, and send the JSON alone (below). - Price: 1 credit per resume scored, +1 per resume file parsed; the job is free. This call costs 4 credits, a resume sent as text 1.
- Time: about a minute for a few resumes; set a client timeout of 150 seconds. The answer is synchronous up to 10 resume files and 50 resumes (with storage, evaluations still running after about 100 seconds answer
202with aresults_urlto read); past that, see Webhooks.
The same call with texts curl -X POST https://hirelayer.co/api/v4/resumes/score \ -H "X-API-Key: $HIRELAYER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "job": { "text": "Senior Backend Engineer, Fernway, Lyon, France (hybrid, 3 days a week on site)\nFernway builds route-planning software used by 300 delivery companies.\nYou will design, build and run the APIs behind 40,000 deliveries a day.\nRequired: 5+ years of backend development, including 3 years with Node.js and TypeScript in production.\nRequired: PostgreSQL, from schema design to query optimization.\nExperience with a message queue such as RabbitMQ or Kafka.\nNice to have: AWS, Docker and Kubernetes.\nProfessional English; French is a plus." }, "resumes": [ { "text": "Alex Morgan, Senior Backend Engineer, Lyon, France. alex.morgan@example.com\n2021-present: Senior Backend Engineer, Parcelio, Lyon. Node.js and TypeScript APIs for 2 million parcels a month; PostgreSQL schema design and query tuning; RabbitMQ event pipeline.\n2018-2021: Backend Developer, Nimbus, Paris. Node.js REST APIs on PostgreSQL, deployed with Docker on AWS.\n2016-2018: Junior PHP Developer, Webcraft, Paris.\nSkills: Node.js, TypeScript, PostgreSQL, RabbitMQ, Docker, AWS (ECS, RDS).\nLanguages: French (native), English (fluent).", "reference": "alex" }, { "text": "Sam Lee, Backend Developer, Berlin, Germany. sam.lee@example.com\n2019-present: Backend Developer, Kestrel Pay, Berlin. Python and Django services for card payments on PostgreSQL; Kafka consumers.\n2017-2019: Full-stack Developer, Brightdesk, Berlin. React front end and a small internal Node.js API.\nSkills: Python, Django, PostgreSQL, Kafka, Docker, Kubernetes, JavaScript.\nEducation: BSc Computer Science, TU Berlin, 2017.\nLanguages: English (fluent), German (B2).", "reference": "sam" } ] }' - 3
Read the ranking
Response to the call with texts (excerpt) { "job": { "job_id": "job_01bbbe9e88640e9abb146c378537ce29", "language": "en", "criteria": […] }, "scores": [ { "rank": 1, "application_id": "text_05e4d9163af6e9818d5f2c84843e7e56", "reference": "alex", "score": 0.98, "verdict": "highly_relevant", "summary": "The candidate perfectly matches all mandatory requirements with significant experience in Node.js, TypeScript, and PostgreSQL, making them an excellent fit for the role.", "required_missing": [], "criteria": […] }, { "rank": 2, "application_id": "text_6de4e5ef69a941201584ccffc6a2ca48", "reference": "sam", "score": 0.41, "verdict": "marginally_relevant", "summary": "Strong backend profile but missing the core Node.js/TypeScript requirement and located abroad.", "required_missing": [ { "criterion_id": "crit_2", "label": "Node.js and TypeScript" }, { "criterion_id": "crit_8", "label": "Location (Lyon area)" } ], "criteria": […] } ], "credits_used": 2 }scores[]is sorted best first.scoreis the weighted mean of the criterion scores;verdictis one ofhighly_relevant,relevant,marginally_relevant,not_relevant.criteria[]gives, for each criterion, a status (met,partial,missing,unknown), the evidence quoted from the resume and an explanation.required_missinglists the required criteria the resume clearly lacks.- Criteria, summaries and explanations follow the job’s language, English or French, read from its text. To choose it, add
"language": "en"or"fr"tojob. - Give each resume a
reference({"file": "cv1", "reference": "your-id"}): it comes back inscores[].reference. Keepjob.job_idand eachapplication_id: sending them instead of the files scores the same pairs again for free. - Add
"precise_ranking": trueto the request to compare the 10 best resumes against each other, with aranking_reasoneach, for 1 credit more.
Every field is described in the Resume Scorer reference. Errors come as
{"error": {"code", …}}: see Errors and retries.