API di gestione v3: workflow e fatturazione

Autenticazione

Tutti gli endpoint dell’API di gestione usano la tua chiave API dell’applicazione. Negli URL non servono UUID di organizzazione o applicazione: l’applicazione viene identificata dalla tua chiave.

curl -H "x-api-key: YOUR_API_KEY" https://verification.didit.me/v3/...

Non hai ancora una chiave API? Registrati in modo programmatico con 2 chiamate API.

Workflow

Un workflow definisce quali passaggi di verifica devono completare i tuoi utenti (scansione del documento d’identità, rilevamento della vitalità, confronto facciale, screening AML, ecc.). Ogni workflow è una configurazione riutilizzabile che colleghi alle sessioni.

GET

Elenca tutti i workflow della tua applicazione. Restituisce le funzionalità e le soglie di ciascun workflow e indica se è quello predefinito.

POST

Crea un nuovo workflow. Definisci quali funzionalità di verifica attivare, imposta le soglie, configura i tipi di documento accettati e altro.

GET

Recupera tutti i dettagli di un workflow specifico, incluse le configurazioni di tutte le funzionalità e le soglie.

PATCH

Aggiorna la configurazione di un workflow. Puoi modificare qualsiasi impostazione delle funzionalità, le soglie o i documenti accettati.

DELETE

Elimina un workflow. Le sessioni che usano già questo workflow non sono interessate.

Consigliamo vivamente di usare la Business Console per creare e configurare i workflow. Il builder visivo dei workflow offre modelli, configurazione delle funzionalità tramite trascinamento, impostazioni dei documenti, regolazione delle soglie e anteprima, senza scrivere codice. Usa l’API solo per l’automazione o la gestione programmatica dei workflow.

Esempio rapido: creare un workflow

Il workflow_type determina l’insieme di funzionalità di base. Le singole funzionalità vengono poi attivate o disattivate con i flag is_*_enabled.

curl -X POST https://verification.didit.me/v3/workflows/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_label": "Standard KYC",
    "workflow_type": "kyc",
    "is_default": true,
    "is_face_match_enabled": true,
    "is_liveness_enabled": true,
    "is_aml_enabled": false
  }'

I valori disponibili per workflow_type sono: kyc, kyb, adaptive_age_verification, biometric_authentication, address_verification, questionnaire_verification, email_verification, phone_verification. Per i workflow kyc, la verifica dell’identità è inclusa automaticamente: non serve un flag separato. Usa i flag is_*_enabled per aggiungere o rimuovere funzionalità facoltative come confronto facciale, rilevamento della vitalità, AML, NFC, telefono, email, prova di residenza, Analisi dispositivo e IP e altre. Quindi usa il workflow quando crei le sessioni:

curl -X POST https://verification.didit.me/v3/session/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "callback_url": "https://myapp.com/callback",
    "workflow_id": "WORKFLOW_UUID_FROM_ABOVE"
  }'

Questionari

Moduli personalizzati da aggiungere ai workflow di verifica per raccogliere ulteriori informazioni dagli utenti.

GET

Elenca tutti i questionari.

POST

Crea un nuovo questionario con domande personalizzate, logica di ramificazione e traduzioni.

GET

Recupera i dettagli di un questionario, incluse tutte le domande e la struttura del modulo.

PATCH

Aggiorna un questionario.

DELETE

Elimina un questionario.

Utenti

Gestisci le persone verificate (utenti) nella tua applicazione. Ogni utente è identificato da una stringa vendor_data che fornisci quando crei le sessioni.

GET

Elenca tutti gli utenti della tua applicazione, inclusi lo stato di verifica e la cronologia delle sessioni.

GET

Recupera i dettagli di un utente tramite il tuo identificatore vendor_data.

PATCH

Aggiorna i metadati di un utente.

POST

Elimina in blocco gli utenti. Corpo: {"vendor_data_list": ["user-1", "user-2"]} oppure {"delete_all": true}. Elimina definitivamente inoltre tutti i modelli biometrici conservati per quegli utenti.

Modelli biometrici

Modelli biometrici facciali privi di immagini che un’applicazione che ha scelto di aderire conserva dopo aver eliminato le sessioni. Vedi Modelli biometrici.

GET

Elenco paginato con filtri (vendor_data, vendor_user_uuid, status, source_type, retained_from, retained_to, ordering).

GET

Conteggio con gli stessi filtri.

GET

Un modello: utente titolare, riferimento di provenienza, scadenza, istruzione e stato.

DELETE

Elimina definitivamente un modello. Restituisce {"uuid": "...", "outcome": "purged" | "already_purged"}.

POST

Eliminazione definitiva in blocco. Corpo: {"template_uuids": [...]} oppure {"delete_all": true}, con eventuali filtri facoltativi.

Operazioni sulle sessioni

POST

Elimina in blocco le sessioni. Richiede delete:sessions. Corpo: {"session_numbers": ["1", "2", "3"]} oppure {"delete_all": true} (restringi delete_all con i filtri di List Sessions preceduti da filter_, come filter_status), più eventuali retain_face_embeddings, face_retention_days, face_retention_deadline, deletion_instruction e instruction_id. Fino a 20 sessioni corrispondenti restituiscono 200 con un face_retention_outcome per ogni sessione; per un numero maggiore viene restituito 202 con un job di eliminazione.

GET

Avanzamento e conteggi degli esiti di un’eliminazione in blocco delle sessioni che ha restituito 202.

GET

Elenca le revisioni e il registro delle attività di una sessione.

POST

Aggiungi una nota di revisione o un cambio di stato a una sessione.

Fatturazione

GET

Recupera il saldo attuale dei crediti e le impostazioni di ricarica automatica.

{
  "balance": "142.5000",
  "auto_refill_enabled": true,
  "auto_refill_amount": "100.0000",
  "auto_refill_threshold": "10.0000"
}

POST

Crea una sessione di checkout Stripe per ricaricare i crediti. Ogni ricarica va da $50 a $20,000 e viene accreditata al valore nominale.

{
  "amount_in_dollars": 100,
  "success_url": "https://myapp.com/billing/success",
  "cancel_url": "https://myapp.com/billing/cancel"
}

Liste (Blocklist, Allowlist e personalizzate)

Gestisci liste tipizzate per il blocklisting, l’allowlisting e le condizioni personalizzate dei workflow. Consulta la documentazione completa dell’API delle liste.

GET

Elenca tutte le liste dell’applicazione (blocklist, allowlist, personalizzate).

POST

Aggiunge una voce a una lista. Supporta reference_session_id per estrarre automaticamente i dati da una sessione e reference_object_uuid per la tracciabilità verso transazioni, utenti o aziende.

DELETE

Rimuove una voce da una lista.

POST

Carica un’immagine del volto in una blocklist facciale (base64).

Configurazione webhook

GET

Recupera la configurazione webhook attuale, inclusi l’URL, la versione, la chiave segreta per verificare le firme dei webhook e la politica di conservazione dei dati e dei modelli biometrici dell’applicazione. La risposta contiene anche allowed_domains, descritto più avanti in PATCH /v3/webhook/.

{
  "webhook_url": "https://myapp.com/webhooks/didit",
  "webhook_version": "v3",
  "secret_shared_key": "whsec_a1b2c3d4e5f6...",
  "capture_method": "both",
  "data_retention_months": null,
  "face_retention_policy": "delete_with_session",
  "face_retention_days": null,
  "allowed_return_hosts": ["app.example.com"],
  "allowed_domains": ["https://app.example.com"]
}

PATCH

Aggiorna l’URL del webhook, la versione o ruota la chiave segreta. Imposta rotate_secret_key: true per generare un nuovo segreto del webhook (quello precedente viene invalidato immediatamente). Imposta anche la politica di conservazione dell’applicazione: data_retention_months e face_retention_policy (delete_with_session come valore predefinito, oppure retain_until_user_deleted), insieme a face_retention_days obbligatorio, un valore finito da 1 a 3650, quando la conservazione è attiva. Consulta Conservazione dei modelli biometrici. Registra inoltre allowed_return_hosts: fino a 20 nomi host semplici (ad esempio app.example.com, senza schema, porta, percorso o wildcard) verso cui una verifica tramite API del wallet di identità digitale può riportare la persona su HTTPS. Una nuova lista sostituisce quella registrata, e il dominio White label della tua applicazione è sempre consentito.Imposta anche allowed_domains: fino a 50 origini web (ad esempio https://app.example.com) in cui il flusso di verifica ospitato può essere incorporato e verso cui può riportare l’utente tramite un callback della sessione. Ogni voce è composta da uno schema, un host e una porta facoltativa, senza percorso, query o wildcard. Usa https; http è accettato solo per localhost, 127.0.0.1 e ::1. Didit memorizza ogni origine in minuscolo senza la porta predefinita e restituisce la lista in allowed_domains. Una voce non valida genera un errore 400 per allowed_domains. Una nuova lista sostituisce quella registrata, e una lista vuota rimuove la restrizione. Finché la lista non è vuota, POST /v3/session/ rifiuta con 400 un callback web che non vi appartiene, e il flusso ospitato non reindirizza l’utente a un callback memorizzato o predefinito del workflow che non vi appartiene. Gli schemi URL personalizzati (deep link delle app) e le chiamate API server-to-server non sono soggetti a questa limitazione.Se invii endpoints, ogni destinazione webhook non inclusa nella lista viene eliminata in modo permanente, insieme al suo segreto di firma e all’intero registro delle consegne, esattamente come DELETE /v3/webhook/destinations/{destination_uuid}/. Questa operazione non può essere annullata. Per gestire le destinazioni una alla volta, usa invece gli endpoint delle destinazioni webhook.

{
  "webhook_url": "https://myapp.com/webhooks/didit",
  "webhook_version": "v3",
  "allowed_domains": ["https://app.example.com"]
}

Riepilogo completo degli endpoint API

Endpoint	Metodo	Descrizione
`/v3/session/`	POST	Crea una sessione di verifica
`/v3/sessions/`	GET	Elenca tutte le sessioni
`/v3/session/{id}/decision/`	GET	Recupera il risultato di verifica della sessione
`/v3/session/{id}/update-status/`	PATCH	Approva o rifiuta una sessione
`/v3/session/{id}/delete/`	DELETE	Elimina una singola sessione
`/v3/sessions/delete/`	POST	Eliminazione in blocco delle sessioni
`/v3/sessions/delete/{job_id}/`	GET	Stato del processo di eliminazione in blocco delle sessioni
`/v3/sessions/{id}/reviews/`	GET, POST	Attività e revisioni della sessione
`/v3/workflows/`	GET, POST	Elenca/crea workflow
`/v3/workflows/{id}/`	GET, PATCH, DELETE	Dettaglio/aggiornamento/eliminazione del workflow
`/v3/questionnaires/`	GET, POST	Elenca/crea questionari
`/v3/questionnaires/{id}/`	GET, PATCH, DELETE	Dettaglio del questionario
`/v3/users/`	GET	Elenca gli utenti verificati
`/v3/users/{vendor_data}/`	GET, PATCH	Dettaglio/aggiornamento dell’utente
`/v3/users/delete/`	POST	Eliminazione in blocco degli utenti (elimina anche i relativi modelli biometrici conservati)
`/v3/biometric-templates/`	GET	Elenca i modelli biometrici conservati
`/v3/biometric-templates/count/`	GET	Conta i modelli biometrici conservati
`/v3/biometric-templates/{id}/`	GET, DELETE	Dettaglio del modello / eliminazione
`/v3/biometric-templates/delete/`	POST	Eliminazione in blocco dei modelli
`/v3/lists/`	GET, POST	Elenca tutte le liste / crea una lista
`/v3/lists/{id}/`	GET, PATCH, DELETE	Dettaglio / aggiornamento / eliminazione della lista
`/v3/lists/{id}/entries/`	GET, POST	Elenca le voci / aggiungi una voce
`/v3/lists/{id}/entries/{eid}/`	DELETE	Rimuovi una voce
`/v3/lists/{id}/entries/face-upload/`	POST	Carica un volto nella blocklist
`/v3/webhook/`	GET, PATCH	Configurazione webhook (URL, segreto, versione), politica di conservazione e host di ritorno del wallet
`/v3/billing/balance/`	GET	Verifica il saldo dei crediti
`/v3/billing/top-up/`	POST	Ricarica i crediti

Ultima modifica il 7 novembre 2026

​Autenticazione

​Workflow

​Esempio rapido: creare un workflow

​Questionari

​Utenti

​Modelli biometrici

​Operazioni sulle sessioni

​Fatturazione

​Liste (Blocklist, Allowlist e personalizzate)

​Configurazione webhook

​Riepilogo completo degli endpoint API

Autenticazione

Workflow

Esempio rapido: creare un workflow

Questionari

Utenti

Modelli biometrici

Operazioni sulle sessioni

Fatturazione

Liste (Blocklist, Allowlist e personalizzate)

Configurazione webhook

Riepilogo completo degli endpoint API