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 - Hierarchical stage metadata

• Top-level request metadata (parser_version, estimated_credits, file details)
• Stage-level metadata (extract, validate, parse, matching)
• Skipped stages explicitly reported as { "skipped": true }

Raw Text - Top-level raw_text field on terminal (completed and failed) responses

• Contains extracted text for file/URL/OCR inputs
• Echoes the caller text for input.type: "text"
• Is null when no source text exists (for example input.type: "result" or extraction failed before producing text)

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",
    "raw_text": "John Doe\nSoftware Engineer\n...",
    "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 for type: "url" or full prior parse result object for type: "result"
• raw_text: Text content for type: "text" (required when type: "text")
• 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: true; if job_description is provided and config.matching is omitted, matching is enabled)
• 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",
    "file_size_bytes": 245760,
    "estimated_credits": 3,
    "extract": { "source_format": "pdf", "page_count": 2 },
    "validate": { "prompt": { "level": "basic" } },
    "parse": { "model_tier": "basic", "confidence_score": 0.94 },
    "matching": { "model_tier": "basic" }
  },

  "checks": {
    "text_validation": {
      "passed": true,
      "reasons": []
    },
    "prompt": {
      "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"] }
    ]
  },
  "raw_text": "John Doe\nSenior Software Engineer\nPython FastAPI PostgreSQL\n...",
  "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",
    "file_size_bytes": 120000,
    "estimated_credits": 1,
    "extract": { "source_format": "pdf", "page_count": 1 },
    "validate": { "prompt": { "level": "basic" } },
    "parse": { "skipped": true },
    "matching": { "skipped": true }
  },
  "checks": {
    "text_validation": {
      "passed": false,
      "reasons": ["insufficient_text"]
    },
    "prompt": {
      "passed": false,
      "level": "basic",
      "detections": [
        {
          "phrase": "example phrase",
          "position": 42,
          "line": 3,
          "context": "...surrounding text..."
        }
      ]
    }
  },
  "raw_text": "John Doe\nSoftware Engineer\n...",
  "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
• file_size_bytes: Size of uploaded file
• estimated_credits: Final estimated credits stored with the request
• extract: Stage metadata (source_format, page_count) or { "skipped": true }
• validate: Stage metadata (prompt settings) or { "skipped": true }
• parse: Stage metadata (model_tier, confidence_score) or { "skipped": true }
• matching: Stage metadata (model_tier) or { "skipped": true }

Raw Text Field (raw_text, terminal responses only):

• Present on completed and failed responses
• string when extraction (or text input) produced text
• null when no source text exists (for example result input or extraction failed early)
• Empty string "" is valid and distinct from null

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

• text_validation: { "passed": boolean, "reasons": string[] }
• prompt (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",
  "raw_text": null
}

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 config.validate.prompt:

{
  "input": { "type": "text", "raw_text": "..." },
  "config": {
    "validate": {
      "prompt": { "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 fail validation before parse/matching, and checks.prompt lists detections.

Input Methods

URL Input

{
  "input": {
    "type": "url",
    "data": "https://example.com/resume.pdf"
  },
  "config": {
    "parse": { "model_tier": "standard" },
    "extract": { "type": "ocr" }
  }
}

File Upload (multipart)

Send file (required). Optional config: a JSON string of the same config object used in the JSON body.

curl -X POST https://api.theresumeparser.com/v1/parse \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F 'config={"parse":{"model_tier":"basic"},"extract":{"type":"ocr"}}'

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",
    "raw_text": "John Doe\nSoftware Engineer\n..."
  },
  "config": {
    "parse": {
      "skills": { "skip": false }
    }
  }
}

Round-Trip: re-parse from a previous response

The same field name is used both ways: take raw_text from a completed response and submit it back as input.raw_text in a new request.

# 1) Create an initial parse request (file upload shown here)
REQUEST_ID=$(curl -sS -X POST https://api.theresumeparser.com/v1/parse \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" | jq -r .request_id)

# 2) Poll until completed and capture raw_text
RAW_TEXT=$(curl -sS https://api.theresumeparser.com/v1/parse/$REQUEST_ID \
  -H "Authorization: Bearer YOUR_API_KEY" | jq -r .raw_text)

# 3) Submit raw_text directly as text input for a new parse
curl -X POST https://api.theresumeparser.com/v1/parse \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg t "$RAW_TEXT" '{input:{type:"text",raw_text:$t},config:{parse:{model_tier:"standard"}}}')"

This is useful when you want to re-run parsing with different config values without re-uploading the original file.

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 config.extract.type: "ocr", 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.