> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Ricerca facciale e blocklist: biometria degli utenti

> Come Didit associa la biometria facciale alle entità User: ricerca 1:N, rilevamento dei duplicati, blocklist facciale e caricamento manuale.



Prompt biometria facciale
        Copia il prompt negli appunti



      
      

\<pre>

\````# Goal — search, blocklist, and act on User face biometrics

Faces are captured automatically during liveness inside a verification session, and can also be uploaded to an existing User profile when you are migrating users from another provider. You interact with biometrics through three action surfaces: **profile face upload** (attach an imported face to a User), **face search** (find a user by face), and the **Lists API** (blocklist a face so future sessions are auto-declined).

\## 1) Upload a face to an imported User profile

Use this when you already created or imported a User with `vendor_data` and have a trusted face image from your previous provider.

\```bash
\# 1. Get the Didit internal User id from vendor_data
curl https://verification.didit.me/v3/users/user-42/ \
-H "x-api-key: $DIDIT_API_KEY"

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

Limits: max 5 faces per User, max 2 MB per image, and the image must contain a detectable face. This enrolls the face for profile evidence and future duplicate/face-search matching. It does not blocklist the face.

\## 2) Face search — 1:N

Use to detect duplicate accounts, identify a face from a CCTV frame, or recognise a returning customer before running new KYC.

\```bash
curl -X POST https://verification.didit.me/v3/face-search/ \
-H "x-api-key: $DIDIT_API_KEY" \
-F "user_image=@./selfie.jpg"
\```

Response includes match candidates with similarity scores. Wire your workflow (in the console) to auto-decline / flag / warn on duplicate hits, or call this endpoint directly from your backend before creating a session.

\## 3) Face blocklist — block a user by face

To block a known bad actor going forward, upload their face to a **face-type list** in your application. Any future session whose liveness selfie matches the embedding is auto-declined.

\```bash
\# Upload a face directly to a face-type list (no session needed)
curl -X POST https://verification.didit.me/v3/lists/$LIST_UUID/entries/face-upload/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"image": "<base64-encoded-jpg-or-png>", "reason": "confirmed_fraud"}'
\```

If the face you want to block came from an existing session, use `POST /v3/lists/{list_uuid}/entries/` with `reference_session_id` instead — the backend extracts the biometric and links the entry back to the session.

Remove a face from the list with the Delete entry endpoint:

\```bash
curl -X DELETE https://verification.didit.me/v3/lists/$LIST_UUID/entries/$ENTRY_UUID/ \
-H "x-api-key: $DIDIT_API_KEY"
\```

The Lists API supports face, document, email, phone, and IBAN list types. See /management-api/lists/overview for the full catalog.

\## 4) Blocklisting after a decline

Declining a session adds the face to no blocklist: the User stays `ACTIVE` and no list entry is written, so a later session with the same face is decided by the workflow's own rules, not by a list match. To block a declined subject, upload the face to a face-type list yourself with the Lists API call above — a decline never does it for you.

\## 5) Where the face lives on the User

\- `portrait_image` on the User entity is a signed URL to the latest approved selfie.
\- Manually uploaded profile faces are listed under the User profile face collection and returned by the profile face list endpoint.
\- `approved_duplicate_status` on each face is one of `NOT_DUPLICATED` / `DUPLICATED`.
\- Embeddings (numeric vectors) are stored separately from the image. Deleting a session deletes the image and, by default, the embedding. An application that opted in to biometric-template retention keeps one image-free template anchored to the User after the session is deleted; it has a finite expiry and is purged on User deletion, a privacy-erasure deletion (deletion_instruction: "privacy_erasure"), or an explicit purge via /v3/biometric-templates/ (see /management-api/biometric-templates/overview).

\## Failure modes

\- `400` from face-search / upload-face — image has no detectable face, multiple faces, or is too low-quality. Re-capture and retry.
\- `404` on Lists API — wrong `list_id` or list deleted.
\- `403` — your role lacks permission on the `lists` resource.
\- `429` — rate-limited.

\## Response shape

See /standalone-apis/face-search and /management-api/lists/upload-face for full schemas. Match objects use `similarity` (0–1) and reference the linked User `vendor_data` when known.

\## Sources of truth

\- /management-api/users/upload-face — attach an imported face to a User profile
\- /standalone-apis/face-search — face search request / response
\- /management-api/lists/upload-face — face blocklist upload
\- /management-api/lists/delete-entry — remove from list
\- /management-api/biometric-templates/overview — templates retained after session deletion
\- /core-technology/face-search/overview — search behaviour
\- /core-technology/liveness/overview — face capture during sessions
\- /integration/integration-prompt — canonical end-to-end prompt````

\</pre>



      
      

Incolla in

La biometria facciale è al centro di ogni entità User. Didit acquisisce un volto durante il [rilevamento della vitalità](https://docs.didit.me/it/core-technology/liveness/overview.md), 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**.> [!NOTE]
>
> I volti memorizzati fungono anche da riferimento per l'[Autenticazione biometrica](https://docs.didit.me/it/core-technology/biometric-auth/overview.md): 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**1. 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.**2. 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`.**3. 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](https://docs.didit.me/it/standalone-apis/face-search.md)## Rilevamento dei duplicatiOgni 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 voltiRifiutare 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](https://docs.didit.me/it/console/blocklist-users.md) oppure con la [Lists API](https://docs.didit.me/it/management-api/lists/overview.md). Una nuova sessione il cui selfie del rilevamento della vitalità corrisponde a quella voce viene rifiutata automaticamente.## Caricare un volto importato in un profilo utenteSe 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.**1. Crea o recupera lo User**Chiama [`POST /v3/users/create/`](https://docs.didit.me/it/management-api/users/create) con il tuo `vendor_data` stabile, oppure chiama `GET /v3/users/{vendor_data}/` se lo User esiste già.**2. 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.**3. Carica il volto**Chiama [`POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`](https://docs.didit.me/it/management-api/users/upload-face) con un'immagine del volto codificata in base64.```bash theme={null}
# 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.> [!WARNING]
>
> 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 blocklistPer 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](https://docs.didit.me/it/management-api/lists/upload-face.md). 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.> [!NOTE]
>
> 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](https://docs.didit.me/it/management-api/lists/overview.md) per bloccare un volto, così che le future sessioni corrispondenti vengano rifiutate.### Rimuovere un volto dalla blocklistRimuovi la voce dalla console in *Blocklist → Faces → row actions → Remove*, oppure usa l'endpoint [Elimina voce](https://docs.didit.me/it/management-api/lists/delete-entry.md).## Modelli biometrici conservati dopo l'eliminazione della sessioneLa 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](https://docs.didit.me/it/console/data-retention.md#conservazione-del-modello-biometrico) 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](https://docs.didit.me/it/management-api/biometric-templates/overview.md).
- 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```mermaid theme={null}
stateDiagram-v2
    [*] --> Enrolled: Face captured during liveness
    Enrolled --> Approved: Session approved
    Enrolled --> Declined: Session declined
    Enrolled --> Duplicated: 1:N search finds match
    Duplicated --> Approved: Allowed by workflow
    Duplicated --> Declined: Rejected by workflow
    Enrolled --> Blocklisted: Face uploaded to a face-type list
    Declined --> [*]: Nothing blocklisted
    Blocklisted --> [*]: Manually removed
    Approved --> [*]: Session deleted (default)
    Approved --> RetainedTemplate: Session deleted with retention enabled
    RetainedTemplate --> [*]: Expiry, User deletion, privacy erasure, or purge
```## Caricare un volto dalla consoleGli operatori di compliance possono caricare manualmente i volti:1) Vai a *Users → \[user] → Actions → Upload face*.
2) Seleziona un'immagine; Didit estrae il volto più grande e crea un nuovo record Face collegato all'utente.
3) 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](https://docs.didit.me/it/console/data-retention.md) della tua applicazione. I modelli biometrici conservati seguono il periodo [conservazione dei modelli biometrici](https://docs.didit.me/it/console/data-retention.md#conservazione-del-modello-biometrico), 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> [card] [Ricerca facciale](https://docs.didit.me/it/core-technology/face-search/overview.md)
>
> Come funziona la ricerca facciale 1:N.> [card] [Rilevamento della vitalità](https://docs.didit.me/it/core-technology/liveness/overview.md)
>
> Il rilevamento della vitalità che acquisisce il volto.> [card] [API della blocklist](https://docs.didit.me/it/management-api/lists/upload-face.md)
>
> Carica un volto in una blocklist.> [card] [Modelli biometrici](https://docs.didit.me/it/management-api/biometric-templates/overview.md)
>
> Modelli conservati dopo l'eliminazione della sessione.> [card] [Blocklist degli utenti](https://docs.didit.me/it/entities/users/blocklist.md)
>
> Come funziona l'inserimento di un utente nella blocklist.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.