CVReader API

CVReaderPro API Documentation

Automate CV analysis, matching and generation for efficient, GDPR-compliant recruitment.

V2 endpoint reference

Every request uses Authorization: ApiKey YOUR_API_KEY. The success contract is listed first in green; validation and authorization failures use application/problem+json.

Quick start: parse a CV with V2

These examples upload a CV file as multipart/form-data. Replace the API key and file path before use.

const formData = new FormData();
formData.append('file', fileInput.files[0]);

const response = await fetch('https://cvreaderpro.com/api/v2/parser', {
  method: 'POST',
  headers: { Authorization: 'ApiKey YOUR_API_KEY' },
  body: formData,
});

if (!response.ok) throw new Error(await response.text());
const resume = await response.json();

import requests

with open('/path/to/cv.pdf', 'rb') as cv_file:
    response = requests.post(
        'https://cvreaderpro.com/api/v2/parser',
        headers={'Authorization': 'ApiKey YOUR_API_KEY'},
        files={'file': cv_file},
    )

response.raise_for_status()
resume = response.json()

SuccessCommon success envelope example

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "status": "COMPLETED"
}

RFC 9457 error response

{
  "type": "about:blank",
  "title": "Validation failed",
  "status": 400,
  "detail": "One or more fields are invalid"
}

Key Features

Webhooks

Register one HTTPS endpoint and subscribe it to any supported event. The endpoint uses one signing secret for every delivery.

Configure this endpoint from Settings → Webhooks. The configuration API uses the authenticated recruiter session, while event-producing API operations continue to use your API key.

Read the registration

{
  "webhookUrl": "https://example.com/webhooks/cvreader",
  "events": [
    "resume.parsed",
    "resume.matched",
    "pdf.generated"
  ],
  "signatureSecret": "<base64-secret>",
  "signatureHeader": "X-CVReader-Signature",
  "signatureTimestampHeader": "X-CVReader-Timestamp",
  "signatureAlgorithm": "HMAC-SHA256",
  "signaturePayload": "<timestamp>.<raw-json-body>"
}

Create or update the registration

{
  "webhookUrl": "https://example.com/webhooks/cvreader",
  "events": [
    "resume.parsed",
    "resume.matched",
    "pdf.generated"
  ]
}

The events array is a subscription set: include one, several, or all supported events. Sending an empty array pauses new deliveries without deleting the endpoint.

Rotate the signing secret

Rotation affects newly created deliveries. Keep the previous secret available until older pending deliveries finish, because each delivery retains the secret captured when its event was created.

Configuration API errors

Delivery headers

Content-Type: application/json
X-CVReader-Event: resume.parsed | resume.matched | pdf.generated
X-CVReader-Delivery-Id: <uuid>
X-CVReader-Timestamp: <unix-seconds>
X-CVReader-Signature: v1=<hmac-sha256>

Verify the signature against the exact raw request body using<timestamp>.<raw-json-body>and return any 2xx response to acknowledge delivery. Use the delivery ID for idempotency because retries can deliver the same event more than once.

import crypto from "node:crypto";

const signedPayload = `${timestamp}.${rawBody}`;
const expected = "v1=" + crypto
  .createHmac("sha256", Buffer.from(secret, "base64"))
  .update(signedPayload, "utf8")
  .digest("hex");

const received = Buffer.from(receivedSignature);
const calculated = Buffer.from(expected);
const valid = received.length === calculated.length
  && crypto.timingSafeEqual(received, calculated);

Payloads and retries

• resume.parsed sends the asynchronous parser result as its raw JSON body.
• resume.matched and pdf.generated use the existing delivery envelope with a public event name, delivery ID, creation time, and payload.
• Failed deliveries retry after approximately 1 minute, 5 minutes, 30 minutes, 2 hours, and 24 hours.
• Every retry reuses the same delivery ID, endpoint URL, signing secret, and exact raw JSON body.
• After the final failed attempt, the delivery is retained as failed and is no longer counted as pending.

1. CV Parsing

Extract structured data from CV files (PDF, DOCX, etc.).

Headers

Authorization: ApiKey YOUR_API_KEY
Accept: application/json  (default) | application/xml

Body (multipart/form-data)

• file: CV file (PDF, DOCX, TXT, etc.)
• parserType: "ADVANCED" (56 fields) or "PREMIUM" (96 fields, recommended)

cURL Example

curl -X POST https://cvreaderpro.com/api/v1/parser \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -F "file=@/path/to/cv.pdf" \
  -F "parserType=PREMIUM"

SuccessResponse (excerpt)

{
  "resumeId": "c8cd44a0-d765-4d47-ba04-67903ef650e5",
  "documentType": "CV",
  "documentLanguage": "FR",
  "candidate": { "firstName": "Jean", "lastName": "Dupont" },
  "experiences": [],
  "educations": [],
  "skills": [],
  ...
}

Error responses

{
  "candidate": {
    "firstName": "Jean",
    "lastName": "Dupont",
    "jobTitle": "Senior Java Developer"
  },
  "profile": "Backend engineer specialising in Spring services.",
  "experienceLevel": "Senior",
  "experiences": [],
  "educations": [],
  "languages": [],
  "skills": [],
  "softSkills": ["Communication"],
  "references": [],
  "hobbies": "Cycling"
}

Async Parser

Submit a CV for asynchronous processing. Results are sent to your webhook.

PrerequisiteConfigure one webhook endpoint subscribed to resume.parsed in Settings → Webhooks.

Example

curl -X POST https://cvreaderpro.com/api/v1/parser/async \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -F "file=@cv.pdf" \
  -F "parserType=PREMIUM"

SuccessImmediate response:

{ "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08" }

A successful request returns 202 Accepted. Processing continues in the background and the result is delivered to the subscribed webhook.

Webhook (client implementation)

Your endpoint must receive a POST request with the result. Verify the HMAC-SHA256 signature with your secret.

POST /your-configured-webhook
X-CVReader-Event: resume.parsed
X-CVReader-Delivery-Id: <uuid>
X-CVReader-Timestamp: <unix-seconds>
X-CVReader-Signature: v1=<hmac-sha256>

Body: { "id": "...", "status": "SUCCESS", "resumeData": { ... } }

2. Jobs API

Provide an API that returns your job listings in JobItem format.

(implemented by client)

Must return an array of objects:

[
  {
    "title": "Senior Software Engineer",
    "reference": "JOB-2023-456",
    "description": "...",
    "company": "TechCorp",
    "country": "FR",
    "city": "Paris"
  }
]

Register your endpoint URL in CVReaderPro (Settings → API Integrations).

Authorization: ApiKey YOUR_API_KEY
Content-Type: multipart/form-data

curl -X POST "https://cvreaderpro.com/api/job/parse/api-key" \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -F "file=@/path/to/job_description.pdf"

{
  "id": "d4c7a1e2-0f3b-4c8d-9e1f-000000000001",
  "title": "Senior Software Engineer",
  "description": "We are looking for...",
  "profile": "Experienced developer with leadership skills",
  "experience": "5+ years",
  "education": "Bachelor's degree",
  "skills": "[\"Java\",\"Spring Boot\",\"Docker\"]",
  "company": "TechCorp",
  "country": "FR",
  "city": "Paris"
}

Authorization: ApiKey YOUR_API_KEY
Content-Type: application/json

// Option A — plain JSON string
"We are looking for a Senior React Developer with 5+ years..."

// Option B — object with recognized field
{ "description": "We are looking for a Senior React Developer..." }

curl -X POST "https://cvreaderpro.com/api/job/parse/text/api-key" \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '"We are looking for a Senior React Developer with 5+ years of experience..."'

{
  "jobTitle": "Senior React Developer",
  "jobDescription": "We are looking for a Senior React Developer...",
  "profileRecherche": "Experienced frontend engineer",
  "experienceRequired": "5+ years",
  "educationLevel": "Bachelor's degree",
  "skills": ["React", "TypeScript", "Node.js", "GraphQL"]
}

curl -X POST "https://cvreaderpro.com/api/jobs/api-key" \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Senior Java Developer",
    "reference": "JOB-2026-001",
    "description": "We are looking for a Senior Java Developer...",
    "profile": "Experienced backend engineer",
    "experience": "5+ years",
    "education": "Bachelor'"'"'s degree",
    "skills": "[\"Java\",\"Spring Boot\",\"Docker\"]",
    "company": "TechCorp",
    "country": "FR",
    "city": "Paris",
    "status": "ACTIVE"
  }'

{
  "id": "d4c7a1e2-0f3b-4c8d-9e1f-000000000001",
  "title": "Senior Java Developer",
  "reference": "JOB-2026-001",
  "status": "ACTIVE",
  "company": "TechCorp",
  "country": "FR",
  "city": "Paris"
}

# All active jobs, page 0, 10 per page
curl "https://cvreaderpro.com/api/jobs/api-key/my?page=0&size=10&status=ACTIVE" \
  -H "Authorization: ApiKey YOUR_API_KEY"

{
  "content": [
    { "id": "d4c7a1e2-...", "title": "Senior Java Developer", "status": "ACTIVE", ... }
  ],
  "totalElements": 42,
  "totalPages": 5,
  "number": 0,
  "size": 10
}

JOB_ID="d4c7a1e2-0f3b-4c8d-9e1f-000000000001"
curl "https://cvreaderpro.com/api/jobs/api-key/my/${JOB_ID}" \
  -H "Authorization: ApiKey YOUR_API_KEY"

JOB_ID="d4c7a1e2-0f3b-4c8d-9e1f-000000000001"
curl -X PUT "https://cvreaderpro.com/api/jobs/api-key/my/${JOB_ID}" \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Lead Java Developer",
    "status": "ACTIVE",
    "city": "Lyon"
  }'

3. Scoring API (Matching)

Get scores for a CV against jobs

Returns a list of scores for a given CV.

[
  {
    "jobReference": "JOB-2026-001",
    "candidateId": "e918ab2f-d2f8-4890-b2d6-b049a76207a9",
    "distance": 0.1121,
    "totalScore": 88.79,
    "profileScore": 91.5,
    "experienceScore": 85.0,
    "educationScore": 90.0,
    "languageScore": 82.0
  }
]

Returns [] when the owned resume has no stored job scores. Score fields are numeric matching components; higher values indicate a stronger match, while distance is the underlying vector distance.

Get CVs matching a job

Returns the same score objects shown above, or [] when the API key owner has no stored resume scores for the reference.

Direct match (job vs CV)

JSON body with job details.

Request body

{
  "jobTitle": "Senior Java Developer",
  "jobDescription": "Build and maintain Spring services...",
  "candidateProfile": "Backend engineer",
  "requiredExperience": "5 years",
  "requiredEducationLevel": "Bachelor",
  "skills": ["Java", "Spring", "SQL"]
}

SuccessResponse 200 OK

{ "score": 88.79 }

Async queue

Submit a list of job references for processing. Results sent via webhook.

Request body

["offre-123", "offre-456"]

SuccessResponse 200 OK

{
  "message": "Resume matching queue created successfully",
  "queue_id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "job_count": 2,
  "job_references": ["offre-123", "offre-456"]
}

4. Resume Generation (standard or anonymized)

Generate CVs in PDF format with optional anonymization.

curl -X PUT "https://cvreaderpro.com/api/resume-settings/api-key/update-with-canvas" \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "layout": "modern",
    "fontStyle": "Calibri",
    "fontSize": 11,
    "lineHeight": 1.35,
    "marginTop": 20,
    "marginBottom": 18,
    "marginX": 18,
    "sectionSpacing": 10,
    "agencyName": "Acme Recruiting",
    "agencyWebsite": "https://acme.example"
  }'

{
  "id": "a3f4e2b1-0c91-4d2e-bc57-7f3a6e9d0012",
  "layout": "modern",
  "settings": {
    "fontStyle": "Calibri",
    "fontSize": 11,
    "lineHeight": 1.35,
    "marginTop": 20,
    "marginBottom": 18,
    "marginX": 18,
    "sectionSpacing": 10,
    "agencyName": "Acme Recruiting",
    "agencyWebsite": "https://acme.example"
  },
  "privacy": {
    "hidePhoto": false,
    "hideEmail": false,
    "hidePhone": false,
    "hideName": false
  },
  "canvas_page_count": 2,
  "canvas_pages": [
    { "index": 0, "url": "<returned-canvas-url>" },
    { "index": 1, "url": "<returned-canvas-url>" }
  ]
}

curl -X POST "https://cvreaderpro.com/api/resume-settings/v1/generate-pdf" \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '["9f6ad665-25ce-4107-8ec5-b2a2fba572cc", "a1b2c3d4-5678-90ab-cdef-000000000001"]'

{
  "jobId": "b72e9a01-3f4c-4e12-9a1d-000000000001",
  "status": "COMPLETED",
  "progress": "100%",
  "results": [
    {
      "resumeId": "9f6ad665-25ce-4107-8ec5-b2a2fba572cc",
      "downloadUrl": "<returned-download-url>",
      "generatedAt": "2026-05-14T10:00:00Z"
    }
  ]
}

curl -X POST "https://cvreaderpro.com/api/webhook/generate-pdfs" \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '["<uuid-1>", "<uuid-2>", ..., "<uuid-50>"]'

{
  "jobId": "c8a12f44-0000-0000-0000-000000000002",
  "status": "QUEUED",
  "statusUrl": "/api/webhook/generate-pdfs/c8a12f44-0000-0000-0000-000000000002",
  "message": "Processing started. Results will be sent to your webhook URL.",
  "webhookSecurity": {
    "algorithm": "HMAC-SHA256",
    "signatureHeader": "X-CVReader-Signature",
    "timestampHeader": "X-CVReader-Timestamp",
    "signedPayload": "<timestamp>.<raw-json-body>"
  }
}

JOB_ID="c8a12f44-0000-0000-0000-000000000002"
curl "https://cvreaderpro.com/api/webhook/generate-pdfs/${JOB_ID}" \
  -H "Authorization: ApiKey YOUR_API_KEY"

{
  "jobId": "c8a12f44-0000-0000-0000-000000000002",
  "status": "PROCESSING",
  "total": 25,
  "processed": 12,
  "results": [
    { "resumeId": "9f6ad665-...", "processed": true,  "downloadUrl": "<returned-download-url>", "generatedAt": "2026-05-14T10:02:00Z" },
    { "resumeId": "a1b2c3d4-...", "processed": false, "downloadUrl": null, "generatedAt": null }
  ],
  "deliveries": [
    {
      "deliveryId": "d1e2f3a4-...",
      "type": "PDF_GENERATED",
      "delivered": false,
      "attemptCount": 1,
      "lastAttempt": "2026-05-14T10:01:00Z",
      "nextAttempt": "2026-05-14T10:06:00Z",
      "responseStatusCode": 500,
      "responseBody": "Internal Server Error",
      "errorMessage": "Connection refused"
    }
  ]
}

Use Cases

1. Automate candidate pre-screening

Parse CVs → get resumeIds → send to /api/jobs/queue → receive scores via webhook.

2. Fair recruitment with anonymized CVs

Configure anonymization in settings, then generate CVs without personal data.

Error Handling

Best Practices

• Test in the sandbox environment before production.
• Systematically anonymize CVs for sensitive roles.
• Monitor your webhooks/emails for async results.
• Archive original CVs securely (GDPR compliant).

Need help? Contact us