La Sua prima richiesta

Procedura completa — crei una richiesta, carichi i documenti lato server, la invii e gestisca il webhook.

La pagina Avvio rapido usava una sessione ospitata perché è il percorso più semplice. Questa pagina illustra l'alternativa: raccogliere i documenti nella propria interfaccia e caricarli lato server. Scelga questo approccio quando vuole il pieno controllo dell'esperienza del richiedente, o quando dispone già delle immagini dei documenti.

Il ciclo di vita

stateDiagram-v2
  [*] --> PENDING_UPLOAD: POST /requests
  PENDING_UPLOAD --> PENDING_UPLOAD: POST /documents (each upload)
  PENDING_UPLOAD --> PROCESSING: POST /submit
  PROCESSING --> APPROVED: auto-decision: approve
  PROCESSING --> REJECTED: auto-decision: reject
  PROCESSING --> ESCALATED: auto-decision: escalate
  ESCALATED --> APPROVED: POST /decision (human)
  ESCALATED --> REJECTED: POST /decision (human)
  REJECTED --> PENDING_UPLOAD: POST /resubmit
  APPROVED --> [*]

Ogni transizione di stato genera un webhook. Nella maggior parte delle integrazioni è necessario reagire solo agli stati PROCESSING, APPROVED, REJECTED ed ESCALATED.

Passo 1 — Crei la richiesta

curl -X POST https://app.certivant.com/api/v1/kyc/requests \
  -H "Authorization: Bearer ck_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "INDIVIDUAL",
    "externalRef": "user-9281",
    "applicant": {
      "fullName": "Alex Singh",
      "dateOfBirth": "1988-11-03",
      "nationality": "GB",
      "email": "alex@example.com",
      "phone": "+447700900100",
      "emailVerified": true,
      "phoneVerified": false
    }
  }'

Risposta (201):

{
  "id": "req_01J0...",
  "status": "PENDING_UPLOAD",
  "pendingDocTypes": ["GOVERNMENT_ID", "SELFIE"],
  "applicant": { "fullName": "Alex Singh", ... },
  "createdAt": "..."
}

pendingDocTypes indica quali documenti questa verifica richiede ancora. Si aggiorna a ogni caricamento: quando è vuoto, la richiesta è pronta per essere inviata.

Passo 2 — Carichi i documenti

Ogni caricamento di documento è una richiesta POST multipart/form-data separata. Passi documentType (e side per i documenti a due facciate, come le patenti di guida) come parametri di query, e il file in un campo chiamato file.

# Front of an ID card
curl -X POST "https://app.certivant.com/api/v1/kyc/requests/req_01J0.../documents?documentType=GOVERNMENT_ID&side=front" \
  -H "Authorization: Bearer ck_live_..." \
  -F "file=@/path/to/id-front.jpg"

# Back of the same ID card
curl -X POST "https://app.certivant.com/api/v1/kyc/requests/req_01J0.../documents?documentType=GOVERNMENT_ID&side=back" \
  -H "Authorization: Bearer ck_live_..." \
  -F "file=@/path/to/id-back.jpg"

# Selfie
curl -X POST "https://app.certivant.com/api/v1/kyc/requests/req_01J0.../documents?documentType=SELFIE" \
  -H "Authorization: Bearer ck_live_..." \
  -F "file=@/path/to/selfie.jpg"

Vincoli:

Dimensione del file: 10 MB al massimo per file.
Tipi MIME: image/jpeg, image/png, image/webp, application/pdf.
side è obbligatorio per GOVERNMENT_ID ed è accettato per qualsiasi documento a due facciate; va omesso per SELFIE, PROOF_OF_ADDRESS, ecc.

Ogni caricamento restituisce lo stato aggiornato della richiesta:

{
  "id": "doc_01J1...",
  "documentType": "GOVERNMENT_ID",
  "side": "front",
  "status": "pending",
  "requestStatus": "PENDING_UPLOAD",
  "pendingDocTypes": ["SELFIE"],
  "fileSize": 412938,
  "mimeType": "image/jpeg"
}

Quando pendingDocTypes è vuoto, la richiesta può essere inviata.

Passo 3 — Invii per l'elaborazione

Verifichi prima email e telefono. La verifica di email e telefono fa parte dei controlli. Se la Sua organizzazione lo richiede (Impostazioni KYC/B), assicuri che ogni canale richiesto sia verificato prima dell'invio — impostando emailVerified / phoneVerified: true alla creazione (come nel passo 1, quando li ha già validati Lei stesso), oppure facendo completare al richiedente il passaggio del codice via email o telefono in una sessione ospitata. Un canale obbligatorio non verificato fa fallire il controllo di verifica dei contatti durante l'elaborazione.

curl -X POST https://app.certivant.com/api/v1/kyc/requests/req_01J0.../submit \
  -H "Authorization: Bearer ck_live_..."

Risposta:

{ "id": "req_01J0...", "status": "PROCESSING", "message": "..." }

La richiesta passa in PROCESSING. Il motore di rischio di Certivant esegue i controlli di autenticità del documento, OCR, confronto del volto (se è stato caricato un selfie), controllo di vivacità, screening delle sanzioni e le eventuali regole personalizzate configurate dalla Sua organizzazione. Di norma il completamento avviene in pochi secondi.

Non interroghi il servizio per ottenere il risultato. Configuri un webhook (vedi il passo 4) — è così che Certivant comunica che la richiesta è completata. Il polling consuma il limite di frequenza e aggiunge latenza.

Passo 4 — Riceva il webhook

Configuri un endpoint webhook in KYC → Impostazioni → Webhook nella dashboard. Ogni volta che la richiesta cambia stato, Certivant invia una POST al Suo URL:

{
  "event": "kyc.request.approved",
  "requestId": "req_01J0...",
  "organizationId": "org_01H...",
  "externalRef": "user-9281",
  "status": "APPROVED",
  "timestamp": "2026-05-27T10:04:21.000Z",
  "data": {
    "score": 94,
    "decision": "approve",
    "extracted": {
      "fullName": "Alex Singh",
      "dateOfBirth": "1988-11-03",
      "documentNumber": "GBR-1234567"
    },
    "liveness": { "isLive": true, "confidence": 0.98 },
    "faceMatch": { "isMatch": true, "confidence": 0.91 }
  }
}

Verifichi l'intestazione X-Certivant-Signature-V2 (vedi Verifica della firma), cerchi la riga nel Suo database tramite externalRef e proceda.

Passo 5 — Gestisca l'inoltro e il rifiuto

Non tutte le richieste vengono approvate senza problemi. I due esiti da prevedere sono:

`kyc.request.escalated`

Il motore automatico non ha raggiunto un livello di certezza sufficiente — di solito perché il documento era di bassa qualità, il confronto del volto ha dato un punteggio al limite, oppure un riscontro nelle sanzioni richiede una verifica umana. Un revisore della Sua organizzazione apre la richiesta nella dashboard e decide. Lei non deve fare nulla; la decisione finale genera un altro webhook (kyc.request.approved o kyc.request.rejected).

Può anche emettere la decisione in modo programmatico con l'ambito kyc:manage:

curl -X POST https://app.certivant.com/api/v1/kyc/requests/req_01J0.../decision \
  -H "Authorization: Bearer ck_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "decision": "APPROVED", "note": "Confirmed against internal CRM record" }'

`kyc.request.rejected`

Il richiedente non ha superato i controlli — documento scaduto, riscontro nelle sanzioni, controllo di vivacità non superato, ecc. Consulti data.factors e data.disqualifiers nel payload del webhook per capire il motivo. Può consentire al richiedente di riprovare reinviando la richiesta:

curl -X POST https://app.certivant.com/api/v1/kyc/requests/req_01J0.../resubmit \
  -H "Authorization: Bearer ck_live_..."

Questa operazione riporta la richiesta allo stato PENDING_UPLOAD e cancella i documenti precedenti. Il richiedente può quindi caricare di nuovo i documenti (oppure usare un nuovo URL di sessione ospitata), e Lei può inviare di nuovo la richiesta.

Cosa costruire dopo

Colleghi il gestore del webhook alla Sua coda di lavoro in background, così da poter ritentare le operazioni a valle se falliscono.
Salvi i campi data.extracted nel Suo record utente — nome, data di nascita, numero del documento — ed eviti di richiederli di nuovo all'utente.
Aggiunga nella Sua app una vista amministrativa con un link alla dashboard di Certivant per ogni richiesta che il Suo team deve esaminare.

Per il riferimento completo degli endpoint e i casi limite, consulti Richieste KYC.

La Sua prima richiesta

On this page