Developer Guide

Integrate CVParse into your application in minutes. Parse CVs, extract structured data, and convert between formats using our REST API.

REST API API Key Auth PDF & DOCX Async Processing

Quick Start

Parse your first CV in 3 steps. All you need is an API key.

Step 1 — Get your API key

Create an account, then go to Dashboard → API Keys and generate a key.

Step 2 — Submit a CV for parsing

curl -X POST https://cvapi.zenithpulseconsulting.co.za/api/v1/parse \
  -H "X-API-Key: your_api_key_here" \
  -F "file=@resume.pdf"

Returns a job_id — parsing happens asynchronously.

Step 3 — Get the results

curl https://cvapi.zenithpulseconsulting.co.za/api/v1/jobs/{job_id}/result \
  -H "X-API-Key: your_api_key_here"

{
  "job_id": "a1b2c3d4-...",
  "data": {
    "full_name": "Jane Smith",
    "email": "jane@example.com",
    "phone": "+44 7700 900123",
    "location": "London, UK",
    "summary": "Senior software engineer with 8 years...",
    "experience": [
      {
        "title": "Senior Engineer",
        "company": "Acme Corp",
        "start_date": "2020-01",
        "end_date": "present",
        "description": "Led a team of 5 engineers..."
      }
    ],
    "education": [
      {
        "degree": "BSc Computer Science",
        "institution": "University of London",
        "year": "2015"
      }
    ],
    "skills": ["Python", "TypeScript", "AWS", "Docker"],
    "languages": ["English", "French"]
  },
  "metadata": {
    "filename": "resume.pdf",
    "file_type": "pdf",
    "processing_time_seconds": 2.3,
    "confidence_score": 0.92,
    "extraction_warnings": []
  }
}

Authentication

CVParse supports two authentication methods. Use API keys for server-to-server integration.

API Key

Recommended

For programmatic access from your backend.

X-API-Key: cvp_abc123...

JWT Bearer Token

For frontend/dashboard access.

Authorization: Bearer eyJhbG...

Parse CVs

Submit PDF or DOCX files for parsing. Processing is asynchronous — you receive a job ID immediately.

Single file

curl -X POST https://cvapi.zenithpulseconsulting.co.za/api/v1/parse \
  -H "X-API-Key: your_api_key" \
  -F "file=@candidate_resume.pdf"

Accepted formats: PDF, DOCX

Max file size: 10 MB

Response: { job_id, status, filename }

Batch upload (up to 50 files)

curl -X POST https://cvapi.zenithpulseconsulting.co.za/api/v1/parse/batch \
  -H "X-API-Key: your_api_key" \
  -F "files=@resume1.pdf" \
  -F "files=@resume2.docx" \
  -F "files=@resume3.pdf"

Get Results

Poll the job status endpoint, then fetch results when complete.

Check job status

curl https://cvapi.zenithpulseconsulting.co.za/api/v1/jobs/{job_id} \
  -H "X-API-Key: your_api_key"

pendingprocessingcompletedfailed

Fetch parsed data

curl https://cvapi.zenithpulseconsulting.co.za/api/v1/jobs/{job_id}/result \
  -H "X-API-Key: your_api_key"

Delete job data

curl -X DELETE https://cvapi.zenithpulseconsulting.co.za/api/v1/jobs/{job_id} \
  -H "X-API-Key: your_api_key"

Job data is automatically deleted after 1 hour. Use this to delete immediately for GDPR compliance.

Format Conversion

Convert CV files between PDF, DOCX, and JSON. Apply templates to re-style documents.

Convert a file

curl -X POST https://cvapi.zenithpulseconsulting.co.za/api/v1/convert \
  -H "X-API-Key: your_api_key" \
  -F "file=@resume.pdf" \
  -F "target_format=docx" \
  -F "template=professional" \
  --output resume_converted.docx

Available templates

Professional

Modern

Minimal

Convert from parsed JSON

curl -X POST https://cvapi.zenithpulseconsulting.co.za/api/v1/convert/from-json \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "cv_data": { "full_name": "Jane Smith", ... },
    "target_format": "pdf",
    "template": "modern"
  }' --output resume.pdf

Convert a completed job result

curl -X POST "https://cvapi.zenithpulseconsulting.co.za/api/v1/convert/job/{job_id}?target_format=pdf&template=professional" \
  -H "X-API-Key: your_api_key" \
  --output formatted_resume.pdf

Webhooks

Instead of polling, configure a webhook URL to receive parse results automatically.

Configure webhook

curl -X PUT https://cvapi.zenithpulseconsulting.co.za/api/v1/auth/webhook \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://your-app.com/webhooks/cvparse",
    "webhook_secret": "whsec_your_secret"
  }'

Error Handling

All errors return a consistent JSON structure with an error code and human-readable message.

{
  "error": "invalid_file_type",
  "message": "Invalid file type: .txt. Allowed: pdf, docx"
}

HTTP Status	Error Code	Description
400	invalid_file_type	File is not PDF or DOCX
400	file_too_large	File exceeds 10 MB limit
400	validation_error	Request body validation failed
401	unauthorized	Missing or invalid API key
401	expired	API key has expired
404	not_found	Job or resource not found
429	quota_exceeded	Monthly parse limit reached
429	rate_limit_exceeded	Per-minute rate limit hit
500	internal_error	Unexpected server error

Rate Limits

Rate limits are enforced per API key. When exceeded, requests return 429 Too Many Requests with a Retry-After header.

Plan	Requests / minute	Monthly parses
Starter (Free)	5	10
Professional	60	5,000
Enterprise	500	Unlimited

SDKs & Libraries

Official client libraries for popular languages.

Python SDK

Coming Soon

pip install cvparse

from cvparse import CVParse

client = CVParse(api_key="cvp_...")
result = client.parse("resume.pdf")
print(result.full_name)

JavaScript SDK

Coming Soon

npm install @cvparse/sdk

import { CVParse } from "@cvparse/sdk";

const client = new CVParse({ apiKey: "cvp_..." });
const result = await client.parse("resume.pdf");
console.log(result.fullName);

API Endpoints

Full reference available at https://cvapi.zenithpulseconsulting.co.za/docs ↗

Method	Endpoint	Description
POST	/api/v1/parse	Parse a single CV
POST	/api/v1/parse/batch	Parse multiple CVs (up to 50)
GET	/api/v1/jobs/{job_id}	Check job status
GET	/api/v1/jobs/{job_id}/result	Get parsed results
DELETE	/api/v1/jobs/{job_id}	Delete job data
POST	/api/v1/convert	Convert a CV file
POST	/api/v1/convert/batch	Batch convert files
POST	/api/v1/convert/from-json	Convert JSON to PDF/DOCX
POST	/api/v1/convert/job/{job_id}	Convert job result
POST	/api/v1/auth/register	Register account
POST	/api/v1/auth/login	Login (get JWT)
POST	/api/v1/auth/api-keys	Create API key
GET	/api/v1/health	Health check

Ready to integrate?

Create a free account and start parsing CVs in minutes.

Get Started API Docs