Parse Endpoint

Parse resumes into structured JSON data.

Response Structure

The API returns comprehensive data including:

Checks - Optional checks object (or null) with text validation and optional prompt-check results. When checks fail (text validation or prompt check), the job still finishes with status: "completed", credits are charged, and result and ai_features are null.

Resume Data - The result field (when present) contains structured resume data following The Resume Parser Schema

• Unified experience field (full-time, contract, freelance, volunteer, etc.)
• Normalized skills with proficiency levels
• ISO 8601 date formats

AI-Generated Features - Optional ai_features (or null when checks block output). When present: intelligent summaries and aggregations Job Matching - Optional matching object (or null), generated when input.job_description is provided and matching is enabled. Includes:

• score (0-100)

• summary

• ranked matched_skills (with reasons)

• ranked missing_skills (with criticality 0.0-1.0 and transferable_skills)

• Candidate profile summary (distinct from candidate's own result.summary)

• Skills with proficiency scores, years of experience, and last-used dates

• Skills aggregation by proficiency

• Experience timeline analysis

Parsing Metadata - Information about the parsing process

• Model and OCR methods used
• Credits consumed and remaining balance
• Processing duration and timestamps
• Source document details (format, page count)

Download the resume data schema: resume-schema.json

Create Parse Request

POST /v1/parse

Request Body

JSON body shape:

{
  "input": {
    "type": "url|file|text|result",
    "data": "https://example.com/resume.pdf",
    "job_description": "optional JD text (100-30000 chars)"
  },
  "config": {
    "extract": { "type": "file|ocr|auto" },
    "validate": { "prompt": { "skip": false, "level": "basic" } },
    "parse": { "skip": false, "model_tier": "basic", "skills": { "skip": false } },
    "matching": { "skip": true, "model_tier": "basic", "top_skills": 3 }
  }
}

config is optional. Omit it to use defaults.

Parameters

input (required)

• type: Input method - url, text, or result (pre-parsed JSON)
• data: URL string, text content, or full prior parse result object
• job_description (optional): JD text for matching (100-30,000 chars)

config (optional)

config.parse (optional)

• skip (default: false) — skip entire parse stage. When true, raw/extracted text is sent directly to matching.
• model_tier (default: basic) — parse model tier: basic, standard, premium
• skills.skip — skip parse skills sub-steps (normalisation + enrichment)

config.matching (optional)

• skip (default: auto; false when JD provided)
• model_tier (default: basic if parse skipped, otherwise parse tier)
• top_skills range: 1-10, default 3

config.validate.prompt (optional)

• skip and level (basic implemented; advanced and professional currently return 501)

Response

{
  "request_id": "req_abc123",
  "status": "created",
  "estimated_credits": 3,
  "remaining_balance": 247,
  "created_at": "2025-11-15T10:30:00Z"
}

Status Codes

• 202 - Parse request accepted and queued for processing
• 400 - Invalid request parameters
• 401 - Invalid API key
• 402 - No active subscription or insufficient credits
• 413 - File too large (exceeds 10MB)
• 422 - Page limit exceeded for your plan
• 429 - Rate limit exceeded
• 501 - Prompt check level not implemented (advanced, professional)

Get Parse Results

GET /v1/parse/:requestId

Response (Processing)

{
  "request_id": "req_abc123",
  "status": "parsing",
  "current_stage": "ai_parsing",
  "progress_percentage": 60,
  "estimated_completion": "2025-11-15T10:30:45Z"
}

Response (Completed)

When all checks pass and parsing produces output, checks is populated, and result / ai_features are present. If matching runs, matching is also present:

{
  "request_id": "req_abc123",
  "status": "completed",
  "created_at": "2025-11-15T10:30:00Z",
  "completed_at": "2025-11-15T10:30:28Z",
  "duration_ms": 28000,

  "credits_consumed": 3,
  "remaining_balance": 247,

  "metadata": {
    "parser_version": "1.0.0",
    "model_used": "basic",
    "ocr_used": "none",
    "source_format": "pdf",
    "page_count": 2,
    "file_size_bytes": 245760,
    "confidence_score": 0.94
  },

  "checks": {
    "text_validation": {
      "passed": true,
      "reasons": []
    },
    "prompt_check": {
      "passed": true,
      "level": "basic",
      "detections": []
    }
  },

  "ai_features": {
    "summary": "Experienced software engineer with 8+ years in full-stack development, specializing in microservices architecture and cloud technologies. Proven track record of leading engineering teams and delivering scalable solutions.",
    "skills_aggregation": {
      "total_skills": 15,
      "by_proficiency": {
        "expert": 5,
        "advanced": 6,
        "intermediate": 3,
        "basic": 1
      },
      "by_type": {
        "hard": 12,
        "soft": 3
      }
    },
    "experience_summary": {
      "total_years": 8,
      "total_positions": 4,
      "companies": 3,
      "current_title": "Senior Engineer"
    }
  },

  "matching": {
    "score": 72,
    "summary": "Strong backend fit with a few critical gaps.",
    "matched_skills": [
      { "skill": "Python", "requirement": "5+ years Python", "reason": "10 years professional use" }
    ],
    "missing_skills": [
      { "requirement": "Kubernetes", "criticality": 0.8, "transferable_skills": ["Docker", "AWS"] }
    ]
  },
  "result": {
    "personal_info": {
      "name": "John Doe",
      "label": "Senior Software Engineer",
      "email": "[email protected]",
      "phone": "+1234567890",
      "location": {
        "city": "San Francisco",
        "region": "CA",
        "country": "United States",
        "country_code": "US"
      }
    },
    "experience": [
      {
        "type": "full-time",
        "company": "Tech Corp",
        "title": "Senior Engineer",
        "start_date": "2020-01",
        "end_date": "2024-12",
        "current": false,
        "description": "Led development of microservices architecture...",
        "highlights": [
          "Reduced API latency by 40%",
          "Mentored 5 junior engineers"
        ]
      }
    ],
    "education": [
      {
        "institution": "University of California",
        "degree": "B.S.",
        "field_of_study": "Computer Science",
        "graduation_date": "2016-05"
      }
    ],
    "skills": [
      {
        "skill": "JavaScript",
        "skill_id": "javascript",
        "synonyms": ["javascript", "js", "ecmascript"],
        "proficiency": "expert",
        "proficiency_score": 0.9,
        "category": "Programming Languages",
        "skill_type": "hard",
        "years_experience": 8,
        "confidence": 1.0,
        "match_method": "exact",
        "implied_by": null
      }
    ],
    "certifications": [],
    "languages": [
      {
        "language": "English",
        "proficiency": "native"
      },
      {
        "language": "Spanish",
        "proficiency": "professional-working"
      }
    ]
  }
}

If text validation or prompt check fails, the response can still be completed with credits charged; result, ai_features, and matching are null, and checks reflects the failure:

{
  "request_id": "req_abc123",
  "status": "completed",
  "created_at": "2025-11-15T10:30:00Z",
  "completed_at": "2025-11-15T10:30:15Z",
  "duration_ms": 15000,
  "credits_consumed": 1,
  "remaining_balance": 249,
  "metadata": {
    "parser_version": "1.0.0",
    "model_used": "basic",
    "ocr_used": "none",
    "source_format": "pdf",
    "page_count": 1,
    "file_size_bytes": 120000,
    "confidence_score": null
  },
  "checks": {
    "text_validation": {
      "passed": false,
      "reasons": ["insufficient_text"]
    },
    "prompt_check": {
      "passed": false,
      "level": "basic",
      "detections": [
        {
          "phrase": "example phrase",
          "position": 42,
          "line": 3,
          "context": "...surrounding text..."
        }
      ]
    }
  },
  "ai_features": null,
  "matching": null,
  "result": null
}

Response Fields

Request Information:

• request_id: Unique identifier for this parse request
• status: Current status (created, parsing, completed, failed)
• created_at: When the request was created (ISO 8601)
• completed_at: When parsing finished (ISO 8601)
• duration_ms: Processing time in milliseconds

Billing Information:

• credits_consumed: Credits used for this parse
• remaining_balance: Your current credit balance after this request

Metadata Object:

• parser_version: Version of The Resume Parser used
• model_used: AI model used (basic, standard, premium)
• ocr_used: OCR method used when OCR ran (e.g. standard, premium); reflects no OCR when skipped
• source_format: Original file format (pdf, docx, txt, etc.)
• page_count: Number of pages in source document
• file_size_bytes: Size of uploaded file
• confidence_score: Overall parsing confidence (0-1), may be null when no parse output

Checks Object (checks, optional — may be null on some responses):

• text_validation: { "passed": boolean, "reasons": string[] }
• prompt_check (when prompt check ran): { "passed": boolean, "level": string, "detections": [{ "phrase", "position", "line", "context" }] }

AI-Generated Features Object (ai_features, optional — null when checks block output):

• summary: Candidate profile overview (2-5 sentences). Distinct from result.summary which is the candidate's own summary text from their resume.
• skills_aggregation: Aggregated skills statistics
  • total_skills: Total number of skills identified
  • by_proficiency: Breakdown by proficiency level
  • by_type: Breakdown by hard/soft skills
• experience_summary: Career overview
  • total_years: Total years of experience
  • total_positions: Number of positions held
  • companies: Number of different companies
  • current_title: Most recent job title

Resume Data:

• result: Structured resume data following The Resume Parser Schema, or null when checks fail

Matching Object (matching, optional — null when not requested or checks block output):

• score: Integer 0-100
• summary: AI fit summary
• matched_skills: Top matched skills (ranked, capped by top_skills)
• missing_skills: Top missing skills with criticality and transferable_skills

Response (Failed)

{
  "request_id": "req_abc123",
  "status": "failed",
  "created_at": "2025-11-15T10:30:00Z",
  "duration_ms": 15000,
  "credits_consumed": 0,
  "remaining_balance": 250,
  "error": "Unable to extract text from file",
  "error_code": "EXTRACTION_FAILED",
  "error_stage": "extraction"
}

Error codes: EXTRACTION_FAILED, OCR_FAILED, PARSE_FAILED, LLM_ERROR, TIMEOUT

Prompt check feature

Prompt check is an optional pipeline step for customer-defined content screening (not a security control). It is off by default (skip: true).

Enable in options.steps.prompt_check:

{
  "input": { "type": "text", "data": "..." },
  "options": {
    "steps": {
      "prompt_check": { "skip": false, "level": "basic" }
    }
  }
}

Only level: "basic" is implemented today. Requesting advanced or professional on create returns 501.

When enabled and violations are detected, the parse may complete with result and ai_features set to null while checks.prompt_check lists detections.

Input Methods

URL Input

{
  "input": {
    "type": "url",
    "data": "https://example.com/resume.pdf"
  },
  "options": {
    "model": "standard",
    "steps": {
      "ocr": { "skip": false, "tier": "standard" }
    }
  }
}

File Upload (multipart)

Send file (required). Optional options: a JSON string of the same options object used in the JSON body (not separate model, ocr, or output_format fields).

curl -X POST https://api.theresumeparser.com/v1/parse \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F 'options={"model":"basic","steps":{"ocr":{"skip":false,"tier":"standard"}}}'

Minimal upload (defaults: model basic, OCR skipped, no prompt check):

curl -X POST https://api.theresumeparser.com/v1/parse \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]"

Text Input

{
  "input": {
    "type": "text",
    "data": "John Doe\nSoftware Engineer\n..."
  },
  "options": {
    "output_format": "json",
    "steps": {
      "normalisation": { "skip": false },
      "enrichment": { "skip": false }
    }
  }
}

Supported Formats

• PDF - up to 4 pages (Beginner) / 8 pages (Professional)
• DOCX - same page limits apply
• Markdown (.md)
• TXT
• Images (JPG, PNG) - enable OCR via options.steps.ocr with "skip": false, same page limits apply
• Web page URLs

Resume Data Schema

The API response is structured in main parts:

1. Metadata - Parsing information (model used, credits, timestamps, source details)
2. Checks - Text validation and optional prompt-check results (null if not applicable)
3. AI Features - Candidate summary, skills aggregation, and experience overview (null when checks block output)
4. Result - Structured resume data following The Resume Parser Schema (null when checks block output)

The result field, when non-null, contains the parsed resume data conforming to our standardized schema:

Schema Highlights

Unified Experience Type Instead of separate "work" and "volunteer" fields, we use a single experience array with a type field:

{
  "experience": [
    {
      "type": "full-time",
      "company": "Tech Corp",
      "title": "Senior Engineer",
      "start_date": "2020-01",
      "end_date": "2024-12"
    },
    {
      "type": "volunteer",
      "company": "Local Charity",
      "title": "Technical Advisor",
      "start_date": "2022-06",
      "end_date": null,
      "current": true
    }
  ]
}

Normalized Skills Skills include normalization against our 32,000+ skill taxonomy:

{
  "skills": [
    {
      "skill": "React",
      "skill_id": "react",
      "synonyms": ["react", "reactjs", "react js"],
      "proficiency": "expert",
      "category": "Web Frameworks",
      "skill_type": "hard",
      "confidence": 1.0,
      "match_method": "alias",
      "implied_by": null
    }
  ]
}

Complete Field Reference See the full schema specification for all available fields and their types.