Riferimento API di Live ID

Tre superfici: la gestione delle chiavi (autenticata con la dashboard, riservata agli amministratori), il ciclo di vita della sessione (autenticato con chiave e token di sessione, pubblico) e il webhook. L'URL di base qui sotto è l'host del Suo tenant.

Emetta una chiave di identificazione

POST /api/kyc/live-id/:orgSlug/keys    Autenticazione: sessione della dashboard (amministratore / proprietario)

Emette una chiave per profilo. Il token in chiaro viene restituito una sola volta — lo conservi in modo sicuro sul Suo backend; viene conservato solo il suo hash.

Corpo della richiesta

{ "applicantId": "app_…", "label": "mobile-app", "expiresInDays": 365 }

Risposta 201

{
  "id": "lik_…",
  "token": "livid_…",          // shown ONCE
  "keyVersion": 1,
  "label": "mobile-app",
  "expiresAt": null,
  "createdAt": "2026-06-18T12:00:00.000Z"
}

Endpoint complementari: GET /api/kyc/live-id/:orgSlug/keys (elenco, solo metadati), DELETE /api/kyc/live-id/:orgSlug/keys/:id (revoca), GET /api/kyc/live-id/:orgSlug/enrollments (elenco dei profili registrati).

Crei una sessione

POST /api/kyc/public/live-id/sessions    Autenticazione: chiave di identificazione (nel corpo)

Chiami questo endpoint lato server. Verifica la chiave, applica il controllo di fatturazione e crea un token di sessione monouso.

Corpo della richiesta

{ "key": "livid_…", "deviceFingerprint": "optional", "captureMethod": "live_camera" }

Risposta 201

{
  "sessionId": "lis_…",
  "sessionToken": "…",
  "expiresAt": "2026-06-18T12:02:00.000Z",
  "captureUrl": "https://app.certivant.com/live-id/…",
  "nonce": "…"
}

Consegni captureUrl al dispositivo. Viene restituito anche il sessionToken, così può interrogare lo stato lato server. nonce è il valore monouso della sessione — serve solo se costruisce una Sua interfaccia di acquisizione (vedi Invii un selfie).

La creazione viene rifiutata con 429 enrollment_locked mentre il profilo è bloccato dopo ripetute validazioni fallite (5 errori entro 15 minuti bloccano il profilo per 30 minuti e attivano live_id.enrollment.locked).

Apra la pagina di acquisizione

GET /live-id/:sessionToken    Autenticazione: token di sessione (nel percorso)

La pagina di acquisizione ospitata, pensata per il mobile — la apra a livello principale: in un popup, tramite un reindirizzamento oppure in una WebView nativa. È servita con frame-ancestors 'none', quindi non è incorporabile in un iframe. Mostra l'interfaccia di fotocamera e selfie quando la sessione è attiva, e un avviso chiaro quando è scaduta, non valida o già completata.

Al caricamento, la pagina ospitata chiama POST /api/kyc/public/live-id/sessions/:sessionToken/open. Questo registra l'indirizzo IP del dispositivo e restituisce il valore monouso della sessione, che la pagina rimanda insieme al selfie. Da quel momento in poi, un selfie inviato senza il valore corretto viene rifiutato.

Apra un'acquisizione (solo con un'interfaccia di acquisizione propria)

POST /api/kyc/public/live-id/sessions/:sessionToken/open    Autenticazione: token di sessione (nel percorso)

Lo chiami dal dispositivo quando si apre la Sua schermata di acquisizione. Risposta 200:

{ "nonce": "…", "expiresAt": "2026-06-18T12:02:00.000Z" }

Invii un selfie

POST /api/kyc/public/live-id/validate    Autenticazione: token di sessione (nel corpo)

La pagina ospitata lo chiama per Lei. Lo documenti solo se costruisce una Sua interfaccia di acquisizione nativa al posto della pagina ospitata.

Corpo della richiesta

{ "sessionToken": "…", "selfieImage": "data:image/jpeg;base64,/9j/4AAQ…", "nonce": "…" }

selfieImage accetta una stringa base64 oppure un URL data:. Minimo circa 1 KB, massimo 8 MB.

nonce è il valore monouso della sessione (dalla risposta della creazione oppure da /open):

• Un valore errato viene sempre rifiutato (reason: "nonce_mismatch", matched: false).
• Un valore mancante viene rifiutato solo quando l'acquisizione è stata aperta con /open (la pagina ospitata lo fa sempre). Le integrazioni server-to-server che non chiamano mai /open continuano a funzionare anche senza di esso, ma è consigliato inviarlo.

Lo stesso selfie non può mai essere usato due volte: una copia esatta della foto di riferimento registrata o del selfie di una sessione precedente viene rifiutata (reason: "replayed_image"). Le copie quasi identiche vengono segnalate nel campo riskSignals del webhook.

Risposta 200

{
  "matched": true,
  "faceMatchScore": 0.94,
  "livenessScore": 0.98,
  "livePassed": true,
  "reason": "matched",
  "sessionId": "lis_…"
}

reason è uno tra matched, face_below_threshold, liveness_failed, face_and_liveness_failed, no_reference_image, nonce_mismatch, replayed_image, near_duplicate_image.

Interroghi una sessione

GET /api/kyc/public/live-id/sessions/:sessionToken    Autenticazione: token di sessione (nel percorso)

Risposta 200

{
  "sessionId": "lis_…",
  "status": "completed",
  "matched": true,
  "faceMatchScore": 0.94,
  "livenessScore": 0.98,
  "reason": "matched",
  "expiresAt": "2026-06-18T12:02:00.000Z"
}

status: pending → processing → completed (oppure expired). Quando è completed, matched è il verdetto. Interroghi circa ogni 2 secondi; si fermi a completed o expired.

Webhook — live_id.validation.completed

Si attiva una volta per ogni validazione completata verso l'URL webhook del Suo tenant, firmato esattamente come ogni altro webhook di Certivant (X-Certivant-Signature-V2: t=…,v1=…; il vecchio X-KYC-Signature: sha256=… viene ancora inviato).

{
  "event": "live_id.validation.completed",
  "organizationId": "org_…",
  "validationId": "liv_…",
  "sessionId": "lis_…",
  "enrollmentId": "lie_…",
  "applicantId": "app_…",
  "matched": true,
  "faceMatchScore": 0.94,
  "livenessScore": 0.98,
  "decisionReason": "matched",
  "riskSignals": {
    "nearDuplicateImage": false,
    "nearestImageDistance": 0.21,
    "nearestImageSource": "previous_session",
    "nonceVerified": true,
    "deviceIpChanged": false
  },
  "timestamp": "2026-06-18T12:02:00.000Z"
}

riskSignals servono alla Sua decisione sul rischio — non modificano mai da soli matched. nonceVerified è true quando il selfie conteneva il valore monouso della sessione; deviceIpChanged è true quando l'IP del dispositivo è cambiato tra /open e il selfie (null quando non può essere confrontato).

Webhook — live_id.enrollment.locked

Si attiva quando un profilo viene bloccato dopo ripetute validazioni fallite.

{
  "event": "live_id.enrollment.locked",
  "organizationId": "org_…",
  "enrollmentId": "lie_…",
  "applicantId": "app_…",
  "failures": 5,
  "lockedUntil": "2026-06-18T12:32:00.000Z",
  "timestamp": "2026-06-18T12:02:00.000Z"
}

Vedi Webhook → Verifica della firma.

Errori