Parse Endpoint

Create parse requests and retrieve results

Parse resumes into structured JSON data.

Response Structure

The API returns comprehensive data including:

Resume Data - The result field 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 - Intelligent summaries and aggregations

Professional summary
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

{
  "input": {
    "type": "url|upload|text",
    "data": "https://example.com/resume.pdf"
  },
  "model": "basic|standard|premium",
  "ocr": "basic|standard|premium",
  "output_format": "json"
}

Parameters

input (required)

type: Input method - url, upload, or text
data: URL string, file upload, or text content

model (optional, default: basic)

basic: Fast processing, included in base credit
standard: Higher accuracy, +2 credits
premium: Highest accuracy, +3 credits

ocr (optional, default: basic)

basic: Algorithmic OCR, included in base credit
standard: Enhanced OCR, +2 credits per page
premium: Premium OCR with best accuracy, +4 credits per page

output_format (optional, default: json)

Currently only json supported

Response

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

Status Codes

201 - Request created successfully
400 - Invalid request parameters
401 - Invalid API key
402 - Insufficient credits
413 - File too large
429 - Rate limit exceeded

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)

{
  "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": "basic",
    "source_format": "pdf",
    "page_count": 2,
    "file_size_bytes": 245760,
    "confidence_score": 0.94
  },

  "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"
    }
  },

  "result": {
    "personal_info": {
      "name": "John Doe",
      "label": "Senior Software Engineer",
      "email": "john@example.com",
      "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",
        "normalized": "JavaScript",
        "proficiency": "expert",
        "proficiency_score": 0.9,
        "category": "Programming Languages",
        "skill_type": "hard",
        "years_experience": 8,
        "confidence": 0.95,
        "match_method": "exact"
      }
    ],
    "certifications": [],
    "languages": [
      {
        "language": "English",
        "proficiency": "native"
      },
      {
        "language": "Spanish",
        "proficiency": "professional-working"
      }
    ]
  }
}

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 (basic, standard, premium)
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)

AI-Generated Features Object:

summary: Professional summary of the candidate (2-3 sentences)
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

Response (Failed)

{
  "request_id": "req_abc123",
  "status": "failed",
  "error": "Unable to extract text from file",
  "error_code": "OCR_FAILED",
  "failed_at": "2025-11-15T10:30:15Z"
}

Input Methods

URL Input

{
  "input": {
    "type": "url",
    "data": "https://example.com/resume.pdf"
  }
}

File Upload

curl -X POST https://api.theresumeparser.com/v1/parse \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@resume.pdf" \
  -F "model=nano"

Text Input

{
  "input": {
    "type": "text",
    "data": "John Doe\nSoftware Engineer\n..."
  }
}

Supported Formats

PDF (up to 8 pages)
DOCX
TXT
Images (JPG, PNG) - requires OCR
Web page URLs

Resume Data Schema

The API response is structured in three main parts:

Metadata - Parsing information (model used, credits, timestamps, source details)
AI Summary - Professional summary of the candidate
Result - Structured resume data following The Resume Parser Schema

The result field 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 JS",
      "normalized": "React",
      "proficiency": "expert",
      "category": "Web Frameworks",
      "skill_type": "hard",
      "confidence": 0.95
    }
  ]
}

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