Skip to content

How to Parse a Resume to JSON in Python with requests

Parse a resume to JSON in Python: send a PDF, Word or image CV with requests, map it to dataclasses, retry 429 and 5xx, and batch a folder of files.

Published · 7 minutes read

Cover reading “Parse a resume to JSON in Python” with a code icon and a queue icon

To parse a resume to JSON in Python, send the file to a resume parser API with requests. One multipart POST to https://hirelayer.co/api/v4/resumes/parse with an X-API-Key header returns the candidate's contact details, work history, education, languages and skills as JSON in the same response. HireLayer Resume Parser reads PDF, Word and image files, scans included, in 70 languages, for 1 credit per resume, and the Free plan gives 50 credits a month.

Below: the call, typed results, errors and retries, a folder of files, and a FastAPI upload route. Every sample was run against the API on November 15, 2026.

EndpointPOST https://hirelayer.co/api/v4/resumes/parse, multipart file, optional application_id
AuthenticationX-API-Key header, key from Dashboard > API keys
FilesPDF, DOC, DOCX, ODT, RTF, TXT, HTML, Markdown, JPG, PNG and more, up to 4.5 MB
TimeAbout 25 to 35 seconds, scans longer: use a 150-second timeout
Price1 credit per resume, 0 when the same file is already stored, failed calls free
Python3.10+, requests; httpx for async code

Build it yourself or call an API?

Libraries such as pdfplumber or pypdf give you the text of a PDF, and a few regular expressions find the email and the phone number. In practice the rest is where it gets hard: two-column layouts, dates written ten diffrent ways, job titles mixed with company names, and scanned PDFs that have no text layer at all.

The usual open-source shortcut, pyresparser, has had no release since version 1.0.6 in December 2019 (PyPI, checked November 15, 2026). Training your own spaCy model works, but you'll need labelled resumes in every language you recieve. A parser API returns the same fields for every file, which is why the rest of this guide uses one.

1. Parse one resume

Install requests, export your key as HIRELAYER_API_KEY, then run this script next to a resume.pdf:

# parse_one.py: python -m pip install requests
import os

import requests

API_URL = "https://hirelayer.co/api/v4/resumes/parse"

with open("resume.pdf", "rb") as file:
    response = requests.post(
        API_URL,
        headers={"X-API-Key": os.environ["HIRELAYER_API_KEY"]},
        files={"file": ("resume.pdf", file)},
        data={"application_id": "candidate-123"},  # optional: your own id
        timeout=150,  # a parse takes about 25 to 35 seconds
    )

body = response.json()
if response.status_code != 200:
    error = body["error"]  # {"code", "message", "param", "doc_url"}
    raise SystemExit(f"{response.status_code} {error['code']}: {error['message']}")

resume = body["resume"]
print(resume["info_candidate"]["full_name"], "|", resume["info_candidate"]["job_title"])
print(len(resume["work_experiences"]), "positions,", len(resume["skills"]), "skills")

The parsed resume sits under resume, with your application_id next to it. Without one, the API derives an id from the file content, so the same file sent twice is the same resume and the second call costs nothing. A trimmed response:

{
  "application_id": "candidate-123",
  "already_stored": false,
  "resume": {
    "info_candidate": {
      "full_name": "Elias MOREAU",
      "email": "elias.moreau@example.com",
      "phone_number": "+33600000000",
      "job_title": "AI Engineer",
      "location": { "city": "Paris", "country_code": "FR" }
    },
    "work_experiences": [
      { "job_title": "AI Engineer", "company_name": "Novalys AI",
        "start_date": "2024-01-01", "end_date": "2025-12-31" }
    ],
    "languages": [{ "language": "English", "level": "Full Professional Proficiency (C1)" }],
    "skills": [{ "skill_title": "Python", "skill_type": "Software skill", "status": "normalized" }]
  },
  "credits_used": 1
}

2. Map the JSON to dataclasses

Dictionaries are fine for a script. In an app, map the fields you actually use to frozen dataclasses once, so a typo in a key fails in one place instead of everywhere:

# hirelayer_models.py
from dataclasses import dataclass


@dataclass(frozen=True)
class Position:
    job_title: str | None
    company_name: str | None
    start_date: str | None  # YYYY-MM-DD
    end_date: str | None  # None while the job is ongoing


@dataclass(frozen=True)
class Candidate:
    application_id: str | None
    full_name: str | None
    email: str | None
    phone_number: str | None  # E.164, such as +33612345678
    city: str | None
    positions: list[Position]
    languages: dict[str, str | None]  # {"English": "Full Professional Proficiency (C1)"}
    skills: list[str]

    @classmethod
    def from_response(cls, body: dict) -> "Candidate":
        resume = body["resume"]
        person = resume["info_candidate"]
        return cls(
            application_id=body["application_id"],
            full_name=person["full_name"],
            email=person["email"],
            phone_number=person["phone_number"],
            city=person["location"]["city"],
            positions=[
                Position(job["job_title"], job["company_name"], job["start_date"], job["end_date"])
                for job in resume["work_experiences"]
            ],
            languages={lang["language"]: lang["level"] for lang in resume["languages"]},
            skills=[skill["skill_title"] for skill in resume["skills"]],
        )

Fields the resume doesn't mention come back as null, hence the | None types. Language levels follow CEFR wording, and each skill is typed as a hard, soft or software skill. The Resume Parser reference lists every field.

3. Handle errors and retry safely

Errors come back as {"error": {"code", "message", "param", "doc_url"}}. Retry 429 and the 5xx statuses with backoff, and honor Retry-After when it's there. Everything else is final: 401 is the key, 403 means no credits left, 413 a file over 4.5 MB and 422 resume_unreadable a file that isn't a readable resume.

# hirelayer_client.py
import os
import time
from pathlib import Path

import requests

API_URL = "https://hirelayer.co/api/v4/resumes/parse"
RETRYABLE = {429, 500, 502, 503, 504}


class ParseError(Exception):
    def __init__(self, status: int, code: str, message: str):
        super().__init__(f"{status} {code}: {message}")
        self.status, self.code = status, code


def parse_resume(path: Path, application_id: str | None = None, attempts: int = 4) -> dict:
    """Parse one resume file and return the response body."""
    data = {"application_id": application_id} if application_id else {}
    for attempt in range(1, attempts + 1):
        with path.open("rb") as file:
            response = requests.post(
                API_URL,
                headers={"X-API-Key": os.environ["HIRELAYER_API_KEY"]},
                files={"file": (path.name, file)},
                data=data,
                timeout=150,
            )
        if response.status_code == 200:
            return response.json()
        if response.status_code in RETRYABLE and attempt < attempts:
            time.sleep(float(response.headers.get("Retry-After", 2**attempt)))
            continue
        try:
            error = response.json()["error"]
        except (ValueError, KeyError):  # an HTML error page from a proxy, say
            error = {"code": "http_error", "message": response.text[:200]}
        raise ParseError(response.status_code, error["code"], error["message"])

Keep the 150-second timeout. A request your client abandons can still finish and be charged, and a retry sent before it ends is parsed and billed again.

4. Parse a folder of resumes

Each call parses one file, so a batch is a loop. A small thread pool keeps four parses in flight, wich is plenty to start with; raise it slowly and let the client back off on 429.

# parse_folder.py
import json
from concurrent.futures import ThreadPoolExecutor, as_completed
from pathlib import Path

from hirelayer_client import ParseError, parse_resume

folder, out = Path("resumes"), Path("parsed")
out.mkdir(exist_ok=True)
files = [p for p in folder.iterdir() if p.suffix.lower() in {".pdf", ".docx", ".doc", ".jpg", ".png"}]

with ThreadPoolExecutor(max_workers=4) as pool:  # start small: a busy API answers 429
    futures = {pool.submit(parse_resume, path): path for path in files}
    for future in as_completed(futures):
        path = futures[future]
        try:
            body = future.result()
        except ParseError as error:  # 413 too large, 422 resume_unreadable...
            print(f"skipped {path.name}: {error}")
            continue
        target = out / f"{path.stem}.json"
        target.write_text(json.dumps(body["resume"], ensure_ascii=False, indent=2))
        print(path.name, body["application_id"], "credits:", body["credits_used"])

Because ids come from the file content, running the script again only pays for new files: the ones already parsed return with credits_used: 0. For queues and deduplication at scale, see the bulk resume parsing guide.

5. Accept uploads in FastAPI

To parse resumes that users upload to your own app, forward the file from your backend and never from the browser, so the key stays on the server:

# app.py: python -m pip install fastapi uvicorn httpx python-multipart
import os

import httpx
from fastapi import FastAPI, HTTPException, UploadFile

app = FastAPI()


@app.post("/candidates/resume")
async def upload_resume(file: UploadFile):
    async with httpx.AsyncClient(timeout=150) as client:
        response = await client.post(
            "https://hirelayer.co/api/v4/resumes/parse",
            headers={"X-API-Key": os.environ["HIRELAYER_API_KEY"]},
            files={"file": (file.filename or "resume", await file.read(), file.content_type)},
        )
    body = response.json()
    if response.status_code != 200:
        # The uploader can fix 400, 413 and 422 (empty, too large, not a resume).
        status = response.status_code if response.status_code in (400, 413, 422) else 502
        raise HTTPException(status_code=status, detail=body["error"]["message"])
    resume = body["resume"]
    return {
        "application_id": body["application_id"],
        "name": resume["info_candidate"]["full_name"],
        "skills": [skill["skill_title"] for skill in resume["skills"]],
    }

The route passes the uploader's own mistakes through as 400, 413 or 422, and turns key or credit problems into a 502, since the user can't fix those. Django works the same way with requests inside a view. In practice, move the call to a worker (Celery, RQ) when a page shouldn't wait 30 seconds for the ouput.

The same tutorial exists in PHP, Java and C#. To compare text extraction, OCR and an API on PDFs first, read resume PDF to JSON, and to score the parsed resumes against a job, the AI resume screener in Python.

Parse your first resume from Python

Create a free API key with 50 credits a month, or drop a resume into the online parser to see the JSON before you write any code.

Frequently asked questions

What is the best Python library for resume parsing?

For text, pdfplumber or pypdf for PDFs and python-docx for Word files; none of them returns resume fields. pyresparser has not been released since 2019. For structured fields from any format, call a resume parser API such as HireLayer Resume Parser with requests.

Can Python parse a scanned resume or a photo of one?

Not with a text extractor alone, because a scan has no text layer. The HireLayer Resume Parser runs OCR on scans and phone photos (JPG, PNG) for the same 1 credit per resume.

Is there a free resume parser API for Python?

HireLayer's Free plan includes 50 credits a month, one per resume, with no card. To try a single resume without code, use the free online resume parser.

How do I get only the text of a resume in Python?

Read resume.info_resume.text from the parse response: it holds the full extracted text, OCR included, next to the structured fields.

Sources and further reading

  1. HireLayer API documentation: Resume Parser
  2. HireLayer API documentation: Errors and retries
  3. HireLayer API documentation: Limits and credits
  4. Requests documentation: POST a multipart-encoded file
  5. FastAPI documentation: Request files (UploadFile)
  6. pyresparser on PyPI (release history)

Louis Desclous

Published on · Reading time: 7 minutes