How to Integrate a Resume Parser API: Requests, Mapping and Errors

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

1. Validate the incoming file and create a candidate or application record in your ATS.
2. Send the file from a trusted backend service to the parser endpoint.
3. Associate the response with your internal record and map only fields your schema uses.
4. 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 CV Extract resume parsing API is exposed at POST /api/v3/parser. 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, JPG/JPEG, PNG, and BMP. The encoded request limit is 6 MiB; the raw file must be smaller than that limit.

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)
  form.append('do_not_store_data', 'true')

  const response = await axios.post(
    'https://onlineresumeparser.com/api/v3/parser',
    form,
    {
      headers: {
        ...form.getHeaders(),
        'X-API-Key': process.env.HIRELAYER_API_KEY,
      },
      timeout: 150_000,
    }
  )

  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. The response is synchronous; the optional webhook_url is a callback option, not a reason to assume that the HTTP request itself is asynchronous.

Map the response into your candidate model

A successful response includes a request_id and structured sections such as info_candidate, work_experiences, educations, languages, and skills. Common mappings include info_candidate.full_name to the ATS display name and each work_experiences[] entry to an employment record. Use the live API reference for the complete response schema and current field definitions.

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.

Handle validation and service errors

The documented response can contain warnings, errors, or a partial upstream result. Preserve those signals instead of treating every returned JSON object as complete. For transient service errors, retry with a limit and backoff. The public reference does not describe an idempotency key, so decide how to reconcile ambiguous client timeouts before automatic resubmission.

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=true when 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

Sources and further reading

1. HireLayer API documentation: V3 request and response
2. An Employer’s Guide to Resume Parsing — Indeed
3. OWASP File Upload Cheat Sheet