Skip to content

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

    Rank resumes for a job

    Put the job description in job.pdf next to the resumes. Each file goes in its own part, and the JSON in the request part 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 202 with a results_url to 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. 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. score is the weighted mean of the criterion scores; verdict is one of highly_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_missing lists 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" to job.
    • Give each resume a reference ({"file": "cv1", "reference": "your-id"}): it comes back in scores[].reference. Keep job.job_id and each application_id: sending them instead of the files scores the same pairs again for free.
    • Add "precise_ranking": true to the request to compare the 10 best resumes against each other, with a ranking_reason each, for 1 credit more.

    Every field is described in the Resume Scorer reference. Errors come as {"error": {"code", …}}: see Errors and retries.