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.
| Endpoint | POST https://hirelayer.co/api/v4/resumes/parse, multipart
file, optional application_id |
| Authentication | X-API-Key header, key from Dashboard > API keys |
| Files | PDF, DOC, DOCX, ODT, RTF, TXT, HTML, Markdown, JPG, PNG and more, up to 4.5 MB |
| Time | About 25 to 35 seconds, scans longer: use a 150-second timeout |
| Price | 1 credit per resume, 0 when the same file is already stored, failed calls free |
| Python | 3.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
- HireLayer API documentation: Resume Parser
- HireLayer API documentation: Errors and retries
- HireLayer API documentation: Limits and credits
- Requests documentation: POST a multipart-encoded file
- FastAPI documentation: Request files (UploadFile)
- pyresparser on PyPI (release history)
Louis Desclous
Published on · Reading time: 7 minutes
