Vai al contenuto principale
POST
curl
Carica un’immagine del volto codificata in base64 in una blocklist o allowlist di volti. Didit rileva i volti nell’immagine, conserva quello più grande, memorizza l’immagine e un ritaglio di quel volto e calcola il modello biometrico facciale rispetto al quale vengono confrontate le nuove sessioni. Il value della nuova voce è l’UUID di quel volto. Disponibile solo per le liste con entry_type: face e list_type: blocklist oppure list_type: allowlist.
Se vuoi inserire un volto in una blocklist o allowlist a partire da una sessione esistente, usa Crea voce con reference_session_id: la voce viene collegata alla sessione.
L’immagine deve contenere un volto chiaramente visibile e avere una dimensione massima di 2 MB una volta decodificata. Se non viene rilevato alcun volto, la richiesta restituisce 400 e non viene creata alcuna voce. Se l’analisi facciale è temporaneamente non disponibile, restituisce 503: riprova più tardi.
Per rimuovere il volto dalla lista, elimina la relativa voce: non verrà più confrontato con le nuove sessioni.

Autorizzazioni

x-api-key
string
header
obbligatorio

La chiave API della tua applicazione, da Developers -> API keys nella Business Console. La chiave primaria ha accesso completo. Una chiave con nome può avere un ambito definito: nessuno, lettura o scrittura per risorsa, limitata ad alcuni workflow o a sessioni approvate, a un elenco di indirizzi IP e a una data di scadenza. 401 indica che la chiave è errata, revocata o scaduta; 403 indica che non è stata inviata alcuna chiave, che la chiave non ha accesso a questa risorsa o azione, oppure che la richiesta proviene da un indirizzo non incluso nel suo elenco IP; 404 su una route di sessione indica che la sessione non rientra nei workflow o negli stati previsti dalla chiave. Una chiave senza accesso ai media riceve gli URL di immagini, video e PDF come null, e una chiave senza permessi di scrittura sulle sessioni riceve link e token di sessione come null. Consulta https://docs.didit.me/console/api-keys.

Parametri del percorso

list_uuid
string<uuid>
obbligatorio

UUID di una lista con entry_type: face e list_type: blocklist o allowlist.

Corpo

application/json
image
string<byte>
obbligatorio

JPEG o PNG codificato in Base64, di massimo 2 MB una volta decodificato, che mostra un volto chiaramente visibile. Invia la stringa base64 pura, senza il prefisso data:image/...;base64,.

comment
string
predefinito:""

Nota opzionale a testo libero, ad esempio il motivo dell'inserimento in elenco.

Risposta

La voce del volto è stata creata.

Un singolo valore in una lista.

uuid
string<uuid>
obbligatorio

Identificatore della voce. Utilizzalo come entry_uuid in Elimina una voce dell'elenco.

value
string
obbligatorio

Il valore inserito in lista: un numero di telefono in formato E.164, un indirizzo email, un numero di documento, un indirizzo IP o un intervallo CIDR, un'impronta digitale del dispositivo, un indirizzo del wallet, un conto bancario, un codice paese ISO 3166-1 alpha-3, un vendor_data, qualsiasi stringa su una lista key, oppure l'UUID del volto memorizzato su una lista di volti. I valori inviati vengono memorizzati in minuscolo, ad eccezione dei numeri di telefono e dei codici paese. La corrispondenza non fa distinzione tra maiuscole e minuscole.

display_label
string | null
obbligatorio

Etichetta di facile lettura. Didit la compila per le voci estratte da una sessione (ad esempio il nome del titolare e il numero del documento) quando non ne invii nessuna.

Maximum string length: 512
comment
string
obbligatorio

Nota in formato testo libero. Stringa vuota se non impostata.

added_by
string | null
obbligatorio

Chi ha aggiunto la voce: api (una chiave API), l'indirizzo email di un utente della console o console, system o migration (voci create da Didit), oppure rule (un'azione di una regola di transazione o monitoraggio).

reference_session_id
string<uuid> | null
obbligatorio

Sessione di verifica da cui è stata estratta la voce. null quando la voce è stata aggiunta per valore.

reference_session_number
integer | null
obbligatorio

Numero della sessione con ambito limitato all'applicazione, come mostrato nella console.

reference_session_type
enum<string> | null
obbligatorio

kyc per una sessione di verifica di una persona fisica, kyb per una sessione di verifica aziendale, null quando non è presente alcuna sessione.

Opzioni disponibili:
kyc,
kyb,
null
reference_object_uuid
string<uuid> | null
obbligatorio

Il record rappresentato dalla voce: il record del volto, del documento, del telefono o dell'email letto da una sessione, il volto creato tramite Upload a face to a list, o l'UUID inviato (ad esempio l'UUID di una transazione o il didit_internal_id di un utente).

metadata
object | null
obbligatorio

Contesto aggiuntivo. Contiene le chiavi impostate da Didit (elencate qui) unite a qualsiasi metadata inviato durante la creazione della voce, restituite così come memorizzate. null se non è presente alcuno.

created_at
string<date-time>
obbligatorio

Data e ora di aggiunta della voce.

Ultima modifica il 7 novembre 2026