Ricerca facciale e blocklist: biometria degli utenti

La biometria facciale è al centro di ogni entità User. Didit acquisisce un volto durante il rilevamento della vitalità, genera un embedding facciale e lo conserva per quattro funzionalità a valle: ricerca facciale 1:N, rilevamento dei duplicati, applicazione della blocklist e ri-autenticazione biometrica.

I volti memorizzati fungono anche da riferimento per l’Autenticazione biometrica: crea una sessione di autenticazione biometrica con il vendor_data dell’utente e ometti portrait_image, e Didit riutilizza automaticamente il volto memorizzato (prima il volto del rilevamento della vitalità approvato, poi la foto del chip del passaporto elettronico, poi il ritratto del documento d’identità e infine un volto del profilo registrato manualmente).

Come i volti vengono associati a un utente

Acquisito durante il rilevamento della vitalità

Quando un User completa una sessione con il rilevamento della vitalità attivo, Didit acquisisce un selfie, esegue il rilevamento passivo della vitalità, estrae il volto più grande e genera un embedding facciale per la ricerca.

Memorizzato nel profilo utente

Il volto viene collegato alla sessione e all’entità User principale. L’URL del ritratto compare nel profilo utente come portrait_image.

Indicizzato per la ricerca

L’embedding viene aggiunto all’indice di ricerca. Le sessioni successive possono eseguire ricerche 1:N su questo indice.

Ricerca facciale (1:N)

La ricerca facciale consente di trovare un utente caricando un’immagine e confrontandola con ogni volto registrato nella tua applicazione. Casi d’uso:

Rilevamento dei duplicati durante l’onboarding: impedisce alla stessa persona di creare due account.
Ricerca inversa: identifica l’utente che compare in un fotogramma di una videocamera a circuito chiuso o in un’immagine utilizzata in un’indagine antifrode.
Riconoscimento dei clienti abituali: salta il KYC per un cliente che torna.

La ricerca facciale viene eseguita automaticamente durante le nuove sessioni quando il tuo workflow ha il rilevamento dei duplicati abilitato. È disponibile anche come API autonoma:

POST /v3/face-search/: ricerca facciale autonoma

Rilevamento dei duplicati

Ogni nuovo volto può essere confrontato con i volti registrati esistenti per individuare i duplicati. Didit assegna a ogni volto un approved_duplicate_status:

Stato	Significato
`NOT_DUPLICATED`	Nessuna corrispondenza trovata sopra la soglia di somiglianza
`DUPLICATED`	Il volto corrisponde a uno o più volti di una sessione già approvata

I workflow possono essere configurati per:

Rifiutare automaticamente le sessioni contrassegnate come duplicate.
Segnalare per revisione: invia la sessione a un analista umano.
Solo avviso: consentire la sessione ma aggiungere un tag di rischio.

Configura questa opzione nella console in Workflows → [your workflow] → Face Match / Liveness → Duplicate detection.

Blocklist dei volti

Rifiutare una sessione non aggiunge il volto a nessuna blocklist. Per rifiutare in futuro le sessioni con lo stesso volto, aggiungilo tu alla blocklist: dalla pagina Blocklist oppure con la Lists API. Una nuova sessione il cui selfie del rilevamento della vitalità corrisponde a quella voce viene rifiutata automaticamente.

Caricare un volto importato in un profilo utente

Se stai migrando da un altro provider KYC, puoi creare prima lo User e poi associare a quel profilo un’immagine del volto attendibile. Lo User è ancora identificato dal tuo vendor_data, ma l’endpoint di caricamento del volto usa l’ID interno dello User di Didit (didit_internal_id), così che il destinatario sia inequivocabile.

Crea o recupera lo User

Chiama POST /v3/users/create/ con il tuo vendor_data stabile, oppure chiama GET /v3/users/{vendor_data}/ se lo User esiste già.

Leggi didit_internal_id

La risposta dello User include didit_internal_id. Continua a usare vendor_data nel tuo sistema; usa didit_internal_id solo per gli endpoint di associazione del profilo.

Carica il volto

Chiama

POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/

con un’immagine del volto codificata in base64.

# 1. Create or retrieve the User keyed by your vendor_data
curl -X POST https://verification.didit.me/v3/users/create/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data": "user-42",
    "display_name": "Jane Doe",
    "metadata": { "previous_provider": "legacy-kyc-vendor" }
  }'

# Response includes:
# { "didit_internal_id": "11111111-2222-3333-4444-555555555555", ... }

# 2. Upload the imported face to the User profile
curl -X POST https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/11111111-2222-3333-4444-555555555555/faces/upload/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "<base64-encoded-jpg-or-png>",
    "comment": "Imported from previous KYC provider"
  }'

I volti dei profili importati vengono registrati nello stesso indice facciale usato per il rilevamento dei duplicati e la ricerca facciale. Non vengono aggiunti automaticamente alla blocklist. Per bloccare un soggetto problematico noto, carica il volto in una lista per i volti.

Carica solo volti che sei autorizzato a trattare in base alla tua informativa sulla privacy e al tuo accordo di migrazione. Inserisci gli identificativi del provider di origine in metadata o comment solo se possono essere esposti ai tuoi operatori di compliance.

Come avviene il blocco

Evento	Azione
Sessione `DECLINED`	Nulla viene aggiunto a una blocklist; lo User resta `ACTIVE`
L’analista inserisce manualmente un volto in blocklist dalla console	Volto aggiunto, stato dello User aggiornato secondo la policy
Aggiunta programmatica tramite la Lists API	Carica l’immagine del volto in una blocklist per i volti

Caricare un volto nella blocklist

Per bloccare programmaticamente un utente tramite il volto, carica l’immagine del volto in una blocklist per i volti con l’endpoint dedicato Carica volto in lista. Didit estrae l’embedding biometrico e lo inserisce nell’indice corrispondente: ogni futura sessione il cui selfie del rilevamento della vitalità corrisponde viene rifiutata automaticamente.

Il caricamento del volto nel profilo e il caricamento del volto nella blocklist sono operazioni diverse. Usa il caricamento nel profilo per associare a uno User un volto importato e attendibile, come prova, per il rilevamento dei duplicati e la ricerca facciale. Usa la Lists API per bloccare un volto, così che le future sessioni corrispondenti vengano rifiutate.

Rimuovere un volto dalla blocklist

Rimuovi la voce dalla console in Blocklist → Faces → row actions → Remove, oppure usa l’endpoint Elimina voce.

Modelli biometrici conservati dopo l’eliminazione della sessione

La cancellazione di una sessione elimina l’immagine del volto e, per impostazione predefinita, l’embedding facciale, perciò la persona non viene più inclusa nel rilevamento dei duplicati e nella ricerca facciale. Se elimini le sessioni poco dopo l’approvazione ma devi comunque individuare nuove registrazioni ripetute, abilita la conservazione dei modelli biometrici nell’applicazione oppure invia retain_face_embeddings: true nella chiamata di eliminazione. Didit elimina quindi la sessione e tutti i relativi dati come di consueto e conserva un modello biometrico facciale privo di immagini, gestito separatamente e associato all’utente:

Contiene esclusivamente il modello facciale numerico e i metadati di conservazione. Non contiene mai l’immagine del volto, il video del rilevamento della vitalità, i dati del documento, i campi identificativi estratti, la decisione né l’ID della sessione eliminata.
Partecipa al rilevamento dei duplicati, alla ricerca facciale, all’autenticazione biometrica e alle liste di volti esattamente come il volto di una sessione attiva. Le corrispondenze vengono segnalate con source: "retained_template", vendor_user_id e vendor_data dell’utente e un biometric_template_id.
È un dato biometrico con un campo expires_at e una durata limitata. Viene eliminato quando l’utente viene eliminato, quando una sessione di quell’utente viene eliminata con deletion_instruction: "privacy_erasure", alla scadenza oppure quando lo elimini in Lists → Biometric templates o tramite la Biometric Templates API.
Una sessione creata senza vendor_data non ha un utente a cui associare un modello; eliminandola viene segnalato ineligible_no_vendor_user e l’embedding viene eliminato insieme alla sessione.
I modelli conservati non vengono mai inseriti in blocklist. Una voce della blocklist facciale creata dalla sessione eliminata mantiene la propria voce biometrica indipendente e il proprio ciclo di vita.

I modelli associati a un utente compaiono nel profilo utente, sotto Biometric templates, con un’azione di eliminazione.

Riepilogo del ciclo di vita dei volti

Caricare un volto dalla console

Gli operatori di compliance possono caricare manualmente i volti:

Vai a Users → [user] → Actions → Upload face.
Seleziona un’immagine; Didit estrae il volto più grande e crea un nuovo record Face collegato all’utente.
Il volto viene registrato per le prove del profilo, il rilevamento dei duplicati e la ricerca facciale. Usa l’area Blocklist quando l’obiettivo è rifiutare le sessioni future corrispondenti.

Questo è utile quando:

Hai una foto nota di un cliente verificato tramite un canale offline.
Vuoi precaricare una blocklist con soggetti malintenzionati noti del tuo database antifrode.

Privacy e conservazione

Gli embedding facciali sono vettori numerici, non immagini. Le immagini stesse sono archiviate in uno storage a oggetti cifrato, con accesso tramite URL firmati. Un embedding facciale è un dato biometrico.
La conservazione segue la politica di conservazione dei dati della tua applicazione. I modelli biometrici conservati seguono il periodo conservazione dei modelli biometrici, più rigoroso e a scadenza fissa.
Eliminare una sessione elimina l’immagine e, per impostazione predefinita, l’embedding. Se la tua applicazione ha attivato la conservazione dei modelli biometrici, eliminare una sessione mantiene un modello senza immagine fino alla scadenza o alla cancellazione.
Per una richiesta di diritto all’oblio ai sensi del GDPR o del CCPA, elimina le sessioni della persona con deletion_instruction: "privacy_erasure" oppure elimina l’utente: in entrambi i casi vengono cancellati anche tutti i modelli conservati. Le voci della blocklist facciale che gestisci restano finché non le rimuovi.

Prossimi passi