CVReader API

Documentazione API CVReaderPro

Automatizzi l'analisi, il matching e la generazione dei CV per un reclutamento efficiente e conforme al GDPR.

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.

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

Funzionalità principali

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. Parsing CV

Estragga dati strutturati da file CV (PDF, DOCX, ecc.).

Intestazioni

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

Corpo (multipart/form-data)

• file: file CV (PDF, DOCX, TXT, ecc.)
• parserType: "ADVANCED" (56 campi) o "PREMIUM" (96 campi, consigliato)

Esempio cURL

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

SuccessRisposta (estratto)

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

Parser asincrono

Invii un CV per l'elaborazione asincrona. I risultati vengono inviati al Suo webhook.

PrerequisitoConfiguri un endpoint webhook iscritto a resume.parsed in Impostazioni → Webhook.

Esempio

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

SuccessRisposta immediata:

{ "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 (implementazione client)

Il Suo endpoint deve ricevere una richiesta POST con il risultato. Verifichi la firma HMAC-SHA256 con la Sua chiave segreta.

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. API Offerte

Fornisca un'API che restituisca le Sue offerte di lavoro in formato JobItem.

(implementato dal client)

Deve restituire un array di oggetti:

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

Registri l'URL del Suo endpoint in CVReaderPro (Impostazioni → Integrazioni API).

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

curl -X POST "{{baseapiurl}}/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 "{{baseapiurl}}/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 "{{baseapiurl}}/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 "{{baseapiurl}}/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 "{{baseapiurl}}/api/jobs/api-key/my/${JOB_ID}" \
  -H "Authorization: ApiKey YOUR_API_KEY"

JOB_ID="d4c7a1e2-0f3b-4c8d-9e1f-000000000001"
curl -X PUT "{{baseapiurl}}/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. API Scoring (Matching)

Ottieni i punteggi di un CV rispetto alle offerte

Restituisce un elenco di punteggi per un dato 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.

Ottieni i CV che corrispondono a un'offerta

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

Corrispondenza diretta (offerta vs CV)

Corpo JSON con i dettagli dell'offerta.

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 }

Coda asincrona

Invii un elenco di riferimenti di offerte per l'elaborazione. I risultati vengono inviati tramite 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. Generazione curriculum (standard o anonimizzato)

Generi CV in formato PDF con anonimizzazione opzionale.

curl -X PUT "{{baseapiurl}}/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": "https://cdn.cvreader.fr/canvas/page_0.png" },
    { "index": 1, "url": "https://cdn.cvreader.fr/canvas/page_1.png" }
  ]
}

curl -X POST "{{baseapiurl}}/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": "https://cdn.cvreader.fr/pdfs/resume_9f6ad665.pdf",
      "generatedAt": "2026-05-14T10:00:00Z"
    }
  ]
}

curl -X POST "{{baseapiurl}}/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 "{{baseapiurl}}/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": "https://cdn.cvreader.fr/pdfs/...", "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"
    }
  ]
}

Casi d'uso

1. Automatizzi la pre-selezione dei candidati

Analizzi i CV → ottenga i resumeId → li invii a /api/jobs/queue → riceva i punteggi tramite webhook.

2. Reclutamento equo con CV anonimizzati

Configuri l'anonimizzazione nelle impostazioni, poi generi CV senza dati personali.

Gestione degli errori

Buone pratiche

• Esegua test nell'ambiente sandbox prima della produzione.
• Anonimizzi sistematicamente i CV per i ruoli sensibili.
• Monitori i Suoi webhook/e-mail per i risultati asincroni.
• Archivi i CV originali in modo sicuro (conforme al GDPR).

Ha bisogno di aiuto? Contattaci