A resume parser belongs between the ATS upload flow and the candidate record: the user submits a document, your backend sends it for parsing, and your application maps the structured response into its own data model. Parsing can reduce manual entry, but it does not decide whether a candidate is suitable. Keep extraction and hiring decisions separate.
Where parsing fits in your upload flow
- Validate the incoming file and create a candidate or application record in your ATS.
- Send the file from a trusted backend service to the parser endpoint.
- Associate the response with your internal record and map only fields your schema uses.
- Flag warnings, missing values, and uncertain fields for review before downstream use.
This boundary keeps the vendor-specific response out of the rest of your product. Your internal adapter can normalize date formats, retain source references, and make it easier to change parser versions without rewriting every candidate workflow.
This guide focuses on the implementation. If you are still deciding how parsing should fit your product, see how HireLayer works as an ATS resume parser API for application intake.
If your incoming files are mostly PDFs and you are deciding between custom extraction and a parser API, see the PDF-to-JSON implementation examples. For a larger import backlog, use the queue and retry pattern in the bulk parsing guide.
Send a resume from your backend
The HireLayer Resume Parser is exposed at POST /api/v4/resumes/parse. It takes one
document in multipart/form-data and authenticates with the
X-API-Key header. The documented formats include PDF,
DOC/DOCX, ODT, PPT/PPTX, ODP, XLS, RTF, TXT, HTML, Markdown, JPG/JPEG,
PNG, and BMP. The file limit is 4.5 MB.
Keep the API key in a server environment variable or secret store, and
call the service from an API route or worker. Do not expose it in
client-side JavaScript. The following Node.js example uses
axios and form-data; install both packages in
your backend project.
import fs from 'node:fs'
import axios from 'axios'
import FormData from 'form-data'
export async function parseResume(filePath, applicationId) {
const form = new FormData()
form.append('file', fs.createReadStream(filePath))
form.append('application_id', applicationId)
const response = await axios.post(
'https://hirelayer.co/api/v4/resumes/parse',
form,
{
headers: {
...form.getHeaders(),
'X-API-Key': process.env.HIRELAYER_API_KEY,
},
timeout: 150_000,
}
)
// { application_id, request_id, stored, already_stored, resume, warnings, credits_used }
return response.data
}The request includes your application’s reference as
application_id. Use a value that lets your service connect
the parser response to the correct ATS record; HireLayer also stores
the parsed resume under that id. The response is synchronous. With the
optional webhook_url form field, the call answers
202 at once instead, and the result is posted to your URL,
signed with the HireLayer-Signature header: check the
signature before you trust the body, as the webhooks guide shows.
Map the response into your candidate model
A successful response includes a request_id, the
application_id, and the parsed resume under
resume, with structured sections such as
info_candidate, work_experiences,
educations, languages, and skills. Common mappings include
resume.info_candidate.full_name to the ATS display name and
each resume.work_experiences[] entry to an employment
record. Use the live API reference for the complete response schema and current field definitions.
| Parser response | Possible ATS destination | Integration check |
|---|---|---|
resume.info_candidate.full_name | Candidate display name | Handle absent or single-name values. |
resume.work_experiences[].company_name | Employment organization | Keep each role linked to its own dates and title. |
resume.educations[].degree_title | Education entry | Do not invent a degree if the source is ambiguous. |
resume.skills[] | Searchable skills | Preserve the returned skill type and status where relevant. |
Store the parser request_id, your application reference,
and the integration version for troubleshooting. Keep the original file
available for review only under your organization’s access and retention
rules. Avoid silently overwriting candidate-entered values when the
source of truth is unclear.
Inspect a real response before mapping fields
Try a representative resume in the live demo, then compare its response with your ATS schema and the API field reference.
Handle validation and service errors
| HTTP status | Documented meaning | Suggested application action |
|---|---|---|
| 400 | Missing file or invalid input. | Check the upload and form fields before sending again. |
| 401 | Missing or invalid API key. | Check backend secret configuration; never show the secret to the user. |
| 403 | Insufficient credits. | Alert an account operator and pause further submissions as needed. |
| 413 | File too large. | Apply size checks before sending. |
| 422 | Non-resume, empty, or unreadable document. | Ask for another file or route the case for manual review. |
| 429 | Too many files parsed at once. | Retry after the Retry-After delay. |
| 502 / 503 | Service briefly unavailable for document processing. | Use a bounded retry policy and record the attempt outcome. |
Every error body has the same shape,
{"error": {"code", "message", "param", "doc_url"}}:
branch on code. The documented response can contain
warnings about skipped steps; failures always come back as
non-2xx statuses. Preserve those signals instead of treating every
returned JSON object as complete. For transient service errors, retry
with a limit and backoff. Decide how to reconcile ambiguous client
timeouts before automatic resubmission: a file already stored under the
same application_id comes back with
already_stored: true and costs no credit.
Protect files, keys, and candidate data
- Validate extensions, actual file content, size, and upload permissions on your server.
- Keep API credentials in backend secrets and rotate them through your normal access process.
- Set
do_not_store_data=truewhen parsed data must not be retained; the API documentation says the default is false. - Define separate retention and deletion rules for original files, parsed results, logs, and backups.
- Do not put candidate names, email addresses, resume text, or API keys in routine application logs.
The API’s storage option describes parser-side retention behavior; it does not determine how your ATS stores or uses candidate information. Review your organization’s own data handling requirements and the provider’s current documentation.
Test the integration before launch
Build a small permissioned test set with clean PDFs, scanned documents, DOCX files, two-column layouts, different languages, and resumes with missing dates. Have a reviewer mark expected values, then track errors per field instead of judging only whether the overall response “looks right.” Include timeout, invalid-file, insufficient-credit, and malformed-response handling in your service tests.
Measure request latency, successful calls, partial results, API errors, and manual corrections. Confirm your credit estimate using the current pricing details and your expected successful request volume. A parser integration is ready when both the happy path and operator recovery path are clear.
Frequently asked questions
Can I call a resume parser directly from the browser?
Use a backend service for production requests so the API key remains private and your application can validate uploads and control data handling.
Does application_id make a request idempotent?
In part. It is your own id for the stored resume: the same file
sent again under it returns the stored resume with
already_stored: true, without a new parse or credit. A
different file under an existing application_id
replaces the stored resume.
Should an ATS automatically trust every extracted field?
No. Validate fields required by your workflow and preserve a human review path for missing, ambiguous, or consequential information.
Sources and further reading
- HireLayer API documentation: parse request and response
- An Employer’s Guide to Resume Parsing, Indeed
- OWASP File Upload Cheat Sheet
Louis Desclous
Updated on · Reading time: 9 minutes
