Skip to content

HireLayer Resume Parser · Resume Parsing API

Resume Parsing API that turns any CV into structured JSON

Send a resume file in one multipart request. HireLayer Resume Parser returns candidate details, work history, education, languages and skills as normalized JSON in the same response, ready to store in your ATS or product, and keeps the resume under an application_id to score or search later.

Try the parser demo
Endpoint
POST /api/v4/resumes/parse
Input
CV file · 15 formats
Response
Synchronous JSON
Billing
1 credit per resume
API requests processed
2M+
In production since
2024
Parse success rate
~99.7%
HireLayer Resume Parser, POST /api/v4/resumes/parse. A PDF resume is sent as multipart form data and returned as JSON: an application_id, then the resume with candidate details, work experiences, languages and typed skills. Values come from the documented API example.

What the Resume Parsing API extracts

Problems it solves

  • Every CV uses a different layout

    Columns, tables, scans and office formats put the same information in different places. Manual entry does not scale with application volume.

  • Free text cannot be filtered

    “Since 2019”, “C1 English” or “5 yrs” mean little to a database. Search, filters and reporting need normalized values.

  • Wrong uploads pollute records

    IDs, job ads or blank scans uploaded in the CV slot end up as empty or misleading candidate profiles.

  • 01

    15 file formats, one endpoint

    PDF, DOC, DOCX, ODT, PPT, PPTX, ODP, XLS, RTF, TXT, HTML, Markdown, JPG/JPEG, PNG and BMP go through the same multipart request.

  • 02

    Normalized values

    Experience brackets, EQF education levels, CEFR language levels, canonical contract types and ISO country codes.

  • 03

    Location and mobility

    City, postal code, region and coordinates, plus the other cities a candidate says they can work in.

  • 04

    Typed skills

    Each skill is classified as a hard, soft or software skill, with a domain, a subcategory and a raw or normalized status.

  • 05

    Occupation codes

    rome_jobs maps the profile to ROME occupation codes with a prediction score, useful for French labour-market classification.

  • 06

    Document guardrails

    A document that may not be a CV comes back with a warning; an unreadable file or one without text returns a 422 instead of an empty profile.

A JSON field map built for candidate databases

Every group sits in resume, next to application_id.

  • info_candidate

    Identity, contact and status

    full_nameemailphone_numberjob_titlebirth_dateavailability_nowavailability_datedriver_license[]linkedin_urlgithub_url
  • info_candidate.location · mobility

    Where the candidate is and can work

    citypostal_coderegioncountry_codelatitudelongitudecan_work_in_other_citiesother_cities[]
  • work_experiences[]

    Career history

    company_namejob_titledescriptioncontract_typestart_dateend_datecurrently_activeexperience_duration
  • educations[]

    Degrees and schools

    degree_titleschool_namedegree_typestart_dateend_datelocation
  • skills[] · languages[]

    Competencies

    skill_titleskill_typestatusdomainsubcategorylanguagelevel
  • info_resume · rome_jobs[]

    Document and classification

    languagetextface_urlurlrome_codeprediction_scorecertifications[]interests[]

Normalized vocabularies

These fields always use the same values, so you can build filters and reports on them. Except skill_type, each one can also be null when the CV does not say.

FieldValues
experience_level0 to 1 year · 1 to 3 years · 3 to 5 years · 5 to 10 years · More than 10 years
education_levelLevel 1 to Level 8 (EQF) · Other
languages[].levelCEFR A1 to C2, with a label
contract_typePermanent contract · Fixed-term contract · Temporary assignment · Internship · Apprenticeship · Freelance · Volunteering · Other
skill_typeHard skill · Soft skill · Software skill

Parse a resume with one request, in cURL or Python

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

RequestPOST /api/v4/resumes/parse
curl -X POST https://hirelayer.co/api/v4/resumes/parse \
  -H "X-API-Key: $HIRELAYER_API_KEY" \
  -F "file=@resume.pdf"
Pythonrequests
import os

import requests

with open("resume.pdf", "rb") as file:
    response = requests.post(
        "https://hirelayer.co/api/v4/resumes/parse",
        headers={"X-API-Key": os.environ["HIRELAYER_API_KEY"]},
        files={"file": ("resume.pdf", file, "application/pdf")},
        timeout=150,
    )
response.raise_for_status()

data = response.json()
print(data["resume"]["info_candidate"])
Response200 OK · application/json
{
  "application_id": "file_d7e21d373637a897b17b8fdf63122807",
  "request_id": "8a4adbed-13fe-42cb-a5d5-5b1890b4dd81",
  "stored": true,
  "already_stored": false,
  "resume": {
    "info_resume": {
      "language": "EN",
      "face_url": "https://files.hirelayer.co/faces/elias-moreau-resume-face.jpg"
    },
    "info_candidate": {
      "full_name": "Elias MOREAU",
      "email": "elias.moreau@example.com",
      "job_title": "AI Engineer",
      "experience_level": "5 to 10 years",
      "education_level": "Level 7",
      "availability_now": true,
      "location": { "region": "Île-de-France", "country_code": "FR" }
    },
    "work_experiences": [
      {
        "company_name": "Novalys AI",
        "job_title": "AI Engineer",
        "start_date": "2024-01-01",
        "end_date": "2025-12-31",
        "experience_duration": 24
      }
    ],
    "languages": [
      { "language": "English", "level": "Full Professional Proficiency (C1)" }
    ],
    "skills": [
      {
        "skill_title": "Node.js",
        "skill_type": "Software skill",
        "status": "normalized",
        "domain": "Software Development",
        "subcategory": "Backend development"
      }
    ]
  },
  "warnings": [],
  "credits_used": 1
}
application_id
The stored resume’s id: derived from the file, or yours when you send application_id.
resume.info_resume.face_url
The candidate photo, cropped from the CV, or null.
resume.languages[].level
Normalized to CEFR levels A1 to C2.
already_stored · credits_used
The same file sent again returns the stored resume, for 0 credits.

Where teams use CV parsing

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

  1. 01

    CV upload that prefills a profile

    Parse the file at signup, prefill experience, education and skills, then let the candidate confirm before saving.

    Resume Parser for Job boards & career sites
  2. 02

    Structured intake in an ATS

    Parse each application CV from your upload service and attach your application reference as application_id.

    Resume Parser for ATS platforms
  3. 03

    Search by availability and mobility

    Store availability_now, availability_date and mobility cities so consultants can filter a pool for a job order.

    Resume Parser for Staffing & temp agencies

Integrate the resume parser in your backend

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

  1. STEP 01

    Upload from your backend

    Post the file to /api/v4/resumes/parse from a server-side service with your API key and, if you have one, your own application_id.

  2. STEP 02

    Map the field groups

    Store resume.info_candidate, work_experiences, educations, languages and skills in your profile model. Keep application_id, and request_id for support.

  3. STEP 03

    Chain the next product

    Send the application_id to HireLayer Resume Scorer to score the resume against a job, and normalize raw skills with HireLayer Skills Normalizer.

Technical specifications

Authentication
X-API-Key header
Content-Type
multipart/form-data
Fields
file (required) · application_id · webhook_url · do_not_store_data
File size
About 4.5 MB (6 MiB encoded)
Response time
About 25 to 35 s; set a 150 s client timeout
Callback
webhook_url: 202 at once, the signed result posted to it
Billing
1 credit per resume; 0 when the file is already stored

No backend to write? Use Resume Parser from Make, Power Automate, ChatGPT, Claude, Google Sheets or your ATS.

Where Resume Parser 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.

Resume Parsing API questions

Answers based on the current API contract.

Which resume formats does the Resume Parsing API accept?

PDF, DOC, DOCX, ODT, PPT, PPTX, ODP, XLS, RTF, TXT, HTML, Markdown, JPG/JPEG, PNG and BMP. A file must stay under about 4.5 MB (6 MiB once encoded).

Is resume parsing synchronous?

Yes. The parsed JSON comes back in the HTTP response, in about 25 to 35 seconds; set a client timeout of 150 seconds. To receive it by callback instead, add a webhook_url: the call answers 202 Accepted at once and the result is posted to your URL, signed with the HireLayer-Signature header.

What happens if someone uploads a document that is not a CV?

A cover letter, a diploma or a certificate is still parsed: the response holds what the document contains and a warning that it may not be a resume. A document that cannot be read as a resume, an unreadable file or a file without text returns HTTP 422 with the code resume_unreadable and uses no credit, so your product can ask for another file instead of saving an empty profile.

Does the Resume Parsing API return language levels?

Yes. Every language on the CV comes back with a CEFR-based level, one of six fixed values from “Introductory Proficiency (A1)” to “Native or Bilingual (C2)”, or null when the resume states no level. Because the value always comes from the same list, you can filter candidates on “B2 or above” whatever wording the CV used.

Does the Resume Parsing API extract the candidate photo?

Yes. When the CV contains a photo, including a PDF CV, resume.info_resume.face_url links to the face cropped from it, at no extra credit and with no option to switch on. It is null when no face is found. With do_not_store_data=true the link expires 10 minutes after parsing, as stated in face_url_expires_at.

Which resume languages can it parse?

Resumes in 70 languages, each covered by HireLayer’s internal tests. Dates, language levels and education levels come back as normalized values whatever the language of the CV.

Does the Resume Parsing API handle scanned PDFs and phone photos?

Yes. A scanned PDF or a photo of a CV (JPG, PNG or BMP) is read with OCR and returns the same JSON as a text PDF, for the same single credit, in any of the 70 supported languages. Scans take longer than the usual 35 seconds or so. When no text can be read even with OCR, the API returns HTTP 422 resume_unreadable and no credit is used. When OCR is skipped on some pages, the response is still 200 with a note in warnings. In the public resume parser benchmark, HireLayer returned the contact details, every position and the diplomas from both the scanned resume and the phone photo.

Does HireLayer parse scanned CVs from candidates in multiple languages?

Yes. HireLayer combines OCR and multilingual parsing in a single API call. A scanned PDF or phone photo in French, German, Arabic, Chinese or any of the 70 supported languages returns the same structured JSON as a text PDF, for the same single credit. No language configuration is needed: HireLayer detects the language automatically and normalizes dates, education levels and CEFR language levels whatever the document language.

Can I stop parsed data from being retained?

Yes. Set do_not_store_data to true in the request when parsed data must not be retained: nothing is stored and application_id comes back null. It defaults to false.

What is the difference between resume parsing software and a resume parsing API?

Resume parsing software usually comes with its own screens, where recruiters upload CVs and review the extracted fields. A resume parsing API has no interface of its own: your ATS, job board or internal tool sends the file and stores the JSON it gets back. HireLayer Resume Parser is the API form, with a free online resume parser and a demo to test it on your own CVs before you write any code.

How is the Resume Parsing API billed?

Each parsed resume consumes one credit from the balance shared by all HireLayer products. A file already stored costs nothing: the stored resume comes back with already_stored set to true. A failed parse is not billed.

Make your first call to HireLayer Resume Parser today.

Create an account to get an API key. Credits are shared across all six HireLayer products.

Solutions using Resume Parser

Resume Parser in production

Guides for Resume Parser