API Documentation

Everything you need to integrate ExtractCV into your application.

Base URL: https://extractcv.com/api

Authentication

All API requests require a Bearer token in the Authorization header.

Authorization: Bearer excv_live_xxxxxxxxxxxxxxxx

Key types:

excv_live_* — Production keys. Extractions consume credits.
excv_test_* — Sandbox keys. No credits consumed, useful for testing.
Generate keys from your Dashboard.

POST /api/v1/extract

Extract structured data from a CV.

Request:

curl -X POST https://extractcv.com/api/v1/extract \
  -H "Authorization: Bearer excv_live_your_key" \
  -F "file=@resume.pdf"

Parameters (multipart/form-data):

file — The CV file (PDF, JPG, PNG, WEBP, TIFF). Max 10MB.
base64 — Alternative: base64-encoded file content.
content_type — Required with base64 (e.g. application/pdf).
Response (200):

{
  "success": true,
  "data": {
    "full_name": "Jean-Pierre Dupont",
    "email": "jp.dupont@gmail.com",
    "phone": "+33612345678",
    "location": { "city": "Paris", "country": "FR", "raw": "Paris, France" },
    "linkedin_url": "https://linkedin.com/in/jpdupont",
    "summary": "Fullstack engineer with 8 years of experience...",
    "experience": [...],
    "education": [...],
    "skills": [{ "name": "React", "category": "frontend", "level": "expert" }],
    "languages": [{ "language": "French", "proficiency": "native" }],
    "certifications": [...],
    "projects": [...],
    "total_experience_years": 8,
    "seniority_level": "senior",
    "detected_language": "fr",
    "confidence_score": 0.97
  }
}

Response headers:

X-Job-Id — Unique job identifier
X-Processing-Time-Ms — Processing time in milliseconds
X-Model-Used — AI model used for extraction

GET /api/v1/usage

Get current credit usage for your account.

Request:

curl https://extractcv.com/api/v1/usage \
  -H "Authorization: Bearer excv_live_your_key"

Response:

{
  "success": true,
  "data": {
    "plan": "starter",
    "credits_used": 234,
    "credits_limit": 1000,
    "credits_remaining": 766,
    "current_period_start": "2026-03-01T00:00:00.000Z",
    "current_period_end": "2026-04-01T00:00:00.000Z",
    "overage_rate": 0.025
  }
}

GET /api/v1/job/:id

Get the status and result of a specific extraction job.

Request:

curl https://extractcv.com/api/v1/job/abc123 \
  -H "Authorization: Bearer excv_live_your_key"

Response:

{
  "success": true,
  "data": {
    "id": "abc123",
    "status": "done",
    "result": { ... },
    "confidence_score": 0.97,
    "processing_time_ms": 4523,
    "model_used": "gpt-4o",
    "created_at": "2026-03-12T10:30:00.000Z",
    "completed_at": "2026-03-12T10:30:04.523Z"
  }
}

Statuses: pending, processing, done, failed

GET /api/v1/health

Public healthcheck endpoint. No authentication required.

Response:

{
  "status": "healthy",
  "checks": {
    "api": "ok",
    "database": "ok",
    "timestamp": "2026-03-12T10:30:00.000Z"
  }
}

Error Codes

Status	Code	Description
400	`UNSUPPORTED_FORMAT`	File format not supported
400	`FILE_TOO_LARGE`	File exceeds 10MB limit
400	`NO_FILE`	No file or base64 data provided
401	`UNAUTHORIZED`	Missing Authorization header
401	`INVALID_KEY`	API key not found or revoked
402	`QUOTA_EXCEEDED`	Monthly credit quota exceeded
429	`RATE_LIMITED`	Too many requests (see Retry-After header)
422	`UNPROCESSABLE`	File corrupted or unreadable
500	`INTERNAL_ERROR`	Unexpected error (retryable: true)

| 503 | SERVICE_UNAVAILABLE | Service temporarily unavailable |

Error response format:

{
  "success": false,
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Monthly credit quota exceeded. Please upgrade your plan.",
    "retryable": false
  }
}