DocuShell
PProduct HuntLaunch offer: reserve 1 month of Pro free before limited slots open.Reserve free Pro

ATS Reference

Resume Parse

POST /v1/resume/parse runs the deterministic Parse pipeline with resume-optimized settings locked in, then maps the result into ATS-ready fields under result.resume. No AI or LLM is involved.

Reference
View as Markdown
Try Resume PlaygroundOpen the ATS-focused playground with a sample resume and live API execution.General Parse PDFUse this when you need general document artifacts and parser controls instead of resume fields.Getting startedReview auth, idempotency, status polling, and downloads.

Endpoint

/v1/resume/parse

Multipart upload route for ATS-ready resume extraction.

Credits

15 per job

Flat cost regardless of page count, unlike the per-page Parse PDF lane.

AI / LLM

None

Parser output plus deterministic DocuShell mapping only.

Section

Parse PDF Versus Resume Parse

Use Parse PDF when you want general-purpose document extraction, parser tuning controls, and artifact-first output for reports, invoices, papers, forms, or mixed business PDFs.

Use Resume Parse when the input is a resume and your application needs ATS-friendly fields such as candidate identity, contact channels, normalized skills, normalized experience, normalized education, projects, keywords, date ranges, confidence scores, and warnings.

Resume Parse is not an AI layer. It runs the deterministic Parse pipeline, fixes the parser settings that work best for resumes, then maps the extracted text into a resume-specific response shape.

  • Parse PDF response focus: result.document and downloadable artifacts.
  • Resume Parse response focus: result.resume plus result.raw.document for QA.
  • Parse PDF exposes parser knobs; Resume Parse keeps them fixed to protect section detection quality.

Section

ATS Fields

These are the structured fields developers and businesses should integrate first.

FieldShapeUse
candidatename, headline, locationCandidate profile cards, CRM records, and dedupe flows.
contactemails[], phones[], links[]Recruiter outreach, enrichment, and candidate matching.
skillsstring[]Normalized skill indexing, filtering, and job matching.
experienceobjects[]Work history import with title, company, dates, current flag, description, and bullets.
educationobjects[]Education import with institution, degree, dates, graduation date, location, and description.
sectionssummary, skills, experience, education, projects, and moreATS import, review UI, search indexing, and compliance exports.
ats.keyword_textnormalized stringKeyword search, matching, and analytics pipelines.
ats.section_coveragestring[]Quality checks for missing resume sections.
ats.date_rangesstring[]Timeline extraction and review hints.
ats.confidencename/contact/sections/overallBest-effort confidence display and routing decisions.
ats.warningsstring[]Missing-field and extraction-quality warnings.

Section

Deterministic Settings

Resume Parse hardcodes the parser settings that the resume profile expects. Callers cannot toggle sanitization, reading order, table method, structure-tree usage, output mode, or line-break preservation on this route.

This keeps ATS output predictable. For example, sanitize=false preserves emails and phone numbers, keep_line_breaks=true improves heading and section detection, and formats always includes JSON, Markdown, and text even when callers request only an extra debug artifact.

If you need full parser control, use /v1/parse instead of /v1/resume/parse.

Reference

Endpoint Reference

POST/v1/resume/parse

Submit a resume PDF for queued deterministic parsing and receive ATS-focused structured candidate data under result.resume.

Auth

Bearer token required on submit, status, and artifact download requests.

Idempotency

Server-minted job_id values with optional Idempotency-Key replay support.

Content Type

multipart/form-data

Headers

NameTypeRequiredLocationDescription
AuthorizationBearer <API_KEY>YesheaderUser-owned API key created in the DocuShell dashboard.
Idempotency-KeystringNoheaderRecommended for safely retrying submit requests without creating duplicate jobs.

Request Fields

NameTypeRequiredLocationDescription
filefileYesmultipartResume PDF upload. The gateway validates PDF magic bytes before forwarding the file.
file_namestringNomultipartOptional file name override used for storage metadata and downstream artifact names.
page_rangestringNomultipartOptional comma-separated pages or ranges such as 1-2. Resume Parse accepts at most 5 selected pages; use this when a resume PDF contains extra cover pages or attachments.
formats`json` | `markdown` | `html` | `text` | `annotated_pdf`NomultipartOptional extra artifact list. Resume Parse always includes json, markdown, and text internally; requested extras such as annotated_pdf are unioned in.

Request Notes

  • Resume Parse uses the same parse-pdf backend queue and worker as /v1/parse, but the public contract is distinct and returns service: "resume-parse".
  • Parser tuning is intentionally fixed for ATS extraction: include_header_footer=false, use_struct_tree=true, sanitize=false, reading_order=xycut, table_method=cluster, keep_line_breaks=true, and output_mode=all.
  • Resume Parse accepts up to 5 pages per resume. For longer documents, submit a page range of 5 pages or fewer, or use /v1/parse for general PDF extraction.
  • The mapper is deterministic only: parser output plus DocuShell regex, heading detection, date-range extraction, and section heuristics. No AI or LLM is used.
  • Resume Parse costs 15 credits per queued job.
  • Scanned or image-only resumes currently return ocr_required until OCR is enabled.

Multipart submit

bash

curl -X POST "https://api.docushell.com/api/v1/resume/parse" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: resume-demo-001" \
  -F "file=@./sample-smart-and-secure-resume.pdf;type=application/pdf" \
  -F "file_name=sample-smart-and-secure-resume.pdf"

Request annotated debug output too

bash

curl -X POST "https://api.docushell.com/api/v1/resume/parse" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: resume-debug-001" \
  -F "file=@./resume.pdf;type=application/pdf" \
  -F "formats=annotated_pdf"
The API still forces JSON, Markdown, and text for resume extraction, then adds requested extras.

Try It Now

Console placeholder for safe sandbox execution.

Coming soon

Queued response

json

{
  "job_id": "job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT",
  "status": "queued",
  "cost": 15,
  "service": "resume-parse",
  "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E",
  "links": {
    "status": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT"
  }
}

Resume parse status

json

{
  "job_id": "job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT",
  "status": "done",
  "service": "resume-parse",
  "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E",
      "result": {
    "resume": {
      "candidate": {
        "name": "RAM KUMAR",
        "headline": "XXPosition/TitleXX",
        "location": "xCityx, xStatex"
      },
      "contact": {
        "emails": ["[email protected]"],
        "phones": ["00.00000000"],
        "links": []
      },
      "skills": [
        "Process Improvement",
        "Operations Management",
        "Project Management",
        "Strategic Planning"
      ],
      "experience": [
        {
          "title": "xxTitlexx",
          "company": "xxCompanyNamexx",
          "location": "xCityx, xStatex",
          "start_date": "April 2014",
          "end_date": "Current",
          "current": true,
          "date_range": "April 2014 - Current",
          "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
          "bullets": ["Lorem ipsum dolor sit amet, consectetur adipiscing elit."]
        },
        {
          "title": "xxTitlexx",
          "company": "xxCompanyNamexx",
          "location": null,
          "start_date": "October 2011",
          "end_date": "March 2014",
          "current": false,
          "date_range": "October 2011 - March 2014",
          "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
          "bullets": ["Lorem ipsum dolor sit amet, consectetur adipiscing elit."]
        }
      ],
      "education": [
        {
          "institution": "Symbiosis Institute of Management Studies",
          "degree": "Masters, Business Administration",
          "field": null,
          "start_date": null,
          "end_date": null,
          "graduation_date": "July 2010",
          "location": "West Pune, Maharashtra",
          "description": "Masters, Business Administration..."
        }
      ],
      "sections": {
        "summary": "Multi-page resume profile with business and operations experience...",
        "skills": "Process Improvement, Operations Management, Project Management, Strategic Planning",
        "experience": "WORK EXPERIENCE April 2014 - Current...",
        "education": "Masters, Business Administration...",
        "projects": "PROJECTS Project Name...",
        "certifications": "CERTIFICATIONS Certification Name...",
        "awards": null,
        "publications": null,
        "languages": "LANGUAGES Language...",
        "volunteering": null,
        "other": "REFERENCES Available on request."
      },
      "ats": {
        "keyword_text": "process improvement operations management project management strategic planning",
        "section_coverage": ["skills", "experience", "education", "projects", "certifications", "languages", "other"],
        "date_ranges": ["April 2014 - Current", "October 2011 - March 2014"],
        "confidence": {
          "name": 0.8,
          "contact": 1,
          "sections": 1,
          "overall": 0.93
        },
        "warnings": []
      }
    },
    "raw": {
      "document": {
        "fileName": "sample-smart-and-secure-resume.pdf",
        "numberOfPages": 5,
        "kids": []
      }
    },
    "artifacts": {
      "markdown_download": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT/download?format=markdown",
      "json_download": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT/download?format=json",
      "text_download": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT/download?format=text"
    },
    "metadata": {
      "engine": "docushell_parse",
      "output_mode": "all",
      "formats": ["json", "markdown", "text"],
      "use_struct_tree": true,
      "sanitize": false,
      "reading_order": "xycut",
      "table_method": "cluster",
      "keep_line_breaks": true
    }
  },
  "links": {
    "status": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT",
    "download": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT/download"
  }
}
Resume Parse returns structured ATS fields under `result.resume` while still exposing the raw Parse document and companion artifacts for QA.

Artifacts

  • result.raw.document exposes the underlying Parse document tree for QA and fallback extraction.
  • JSON, Markdown, and text artifacts are always generated. Request HTML or annotated_pdf through formats.

Poll And Download

  • Poll GET /v1/jobs/:jobId until status becomes done or failed.
  • Read structured resume data from result.resume. See [Artifact Downloads](#artifact-downloads) for the underlying files.

Failure Notes

  • invalid_pdf, corrupt_pdf, and password_protected mirror the Parse PDF failure behavior.
  • ocr_required means the resume did not expose enough extractable text. Run OCR upstream before retrying.
  • invalid_page_range is returned when the submitted selector is malformed or selects no valid pages.
  • page_limit_exceeded is returned when the selected pages exceed the Resume Parse 5-page cap.
  • server_busy or backend_unavailable indicate temporary capacity problems. Retry with the same Idempotency-Key when safe.
  • Weak or missing fields do not fail the job; they appear as warnings and lower confidence values in result.resume.ats.

OCR required

400ocr_required

The uploaded resume appears to be scanned or image-only.

400 error

json

{
  "error": {
    "code": "ocr_required",
    "message": "This PDF appears to require OCR before it can be parsed.",
    "type": "invalid_request_error",
    "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E"
  }
}

Invalid PDF

400invalid_pdf

The uploaded file failed PDF validation before it reached the parse queue.

400 error

json

{
  "error": {
    "code": "invalid_pdf",
    "message": "This file is not a valid PDF.",
    "type": "invalid_request_error",
    "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E"
  }
}

Section

Artifact Downloads

JSON, Markdown, and text are always produced — use them to debug what the parser actually read. Swap format for markdown or text.

Download an artifact

bash

curl "https://api.docushell.com/api/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT/download?format=json" \
  -H "Authorization: Bearer YOUR_API_KEY"

Section

Known Limits

Resume Parse is best-effort deterministic extraction. It handles many common resume formats, but unusual visual layouts, very sparse text layers, scanned PDFs, or resumes with contact information only embedded in images can reduce confidence or return warnings.

The mapper never uses AI to infer missing facts. When it cannot find a field deterministically, it leaves the field empty and reports a warning instead of inventing candidate data.

  • Resume Parse accepts up to 5 pages per resume; use Parse PDF for longer general documents.
  • Scanned resumes currently return ocr_required.
  • Highly designed resumes can produce partial sections; inspect ats.warnings and ats.confidence.
  • Use the Markdown and text artifacts to debug what the parser actually extracted.