> ## 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.

# API dei modelli biometrici

> Con Didit gestisci via API i modelli biometrici facciali senza immagini conservati dopo l'eliminazione: elenca, conta, filtra, ispeziona ed elimina.



Prompt per l'API dei modelli biometrici
        Copia il prompt negli appunti



      
      

\<pre>

\`Manage the biometric templates my Didit application retains after deleting verification sessions.

What a biometric template is:
When an application opts in (face_retention_policy: "retain_until_user_deleted", or retain_face_embeddings: true on a delete call), deleting a KYC session deletes the session and all of its data but keeps ONE image-free face biometric template anchored to the session's User. The template keeps duplicate-face, multi-account, biometric-authentication, and list matching working for that person. It contains the numeric face template plus retention metadata only — never the face image, liveness video, document data, extracted identity fields, the decision, or the deleted session's id. It is biometric data: not anonymous, not transient, and not deleted with the session. It has a finite expires_at.

Endpoints (base https://verification.didit.me, header x-api-key: YOUR_API_KEY; API keys only — Console user tokens get 403):
\- GET  /v3/biometric-templates/            — paginated list (limit/offset). Filters: vendor_data (substring, case-insensitive), vendor_user_uuid, status, source_type, retained_from, retained_to (ISO 8601), ordering (retained_at | -retained_at | expires_at | -expires_at; default -retained_at). Purged templates are not listed.
\- GET  /v3/biometric-templates/count/      — {"count": n} with the same filters.
\- GET  /v3/biometric-templates/{uuid}/     — one template.
\- DELETE /v3/biometric-templates/{uuid}/   — purge one template. 200 {"uuid": "...", "outcome": "purged" | "already_purged"}.
\- POST /v3/biometric-templates/delete/     — bulk purge. Body: {"template_uuids": ["..."]} OR {"delete_all": true} plus optional filters (vendor_data, vendor_user_uuid, status, source_type, retained_from, retained_to) that narrow delete_all. 200 {"results": [{"uuid": "...", "outcome": "purged" | "already_purged"}]}.

Template object:
\{
"uuid": "<template id>",
"vendor_user_uuid": "<User id>",
"vendor_data": "<the User's current vendor_data, resolved live>",
"source_type": "session_delete" | "automatic_retention" | "backfill",
"provenance_reference": "<opaque UUID, not the deleted session id>",
"retention_policy": "delete_with_session" | "retain_until_user_deleted",
"retention_override": true | false | null,
"retained_at": "<ISO 8601>",
"expires_at": "<ISO 8601>",
"retained_by": "<principal id: application UUID for API keys, Console member id, or service:...>",
"retained_by_type": "API_KEY" | "CONSOLE_USER" | "SYSTEM",
"instruction_class": "operational_session_delete" | "privacy_erasure",
"instruction_source": "api" | "console" | "automatic_retention" | "backfill" | "privacy_erasure" | "explicit_template_purge" | "vendor_user_delete" | "expiry" | "reconciliation" | "migration" | "system",
"instruction_id": "<your instruction_id or a Didit-generated one>",
"held_out_of_use": false,
"status": "pending" | "active" | "expired" | "held_out_of_use" | "purge_pending" | "purge_failed" | "purged",
"purged_at": null | "<ISO 8601>"
}
Only status "active" templates that are not held_out_of_use, not past expires_at, and whose User still exists take part in matching.

Purge points (all remove the template from matching and delete the stored template):
\- DELETE /v3/biometric-templates/{uuid}/ or POST /v3/biometric-templates/delete/
\- POST /v3/users/delete/ for the owning User
\- any session deletion for that User sent with deletion_instruction: "privacy_erasure"
\- automatic expiry at expires_at
Switching the application policy back to delete_with_session does NOT purge existing templates — purge them explicitly.

Failure modes:
\- 400 — {"template_uuids": ["This field is required unless delete_all is true."]} on bulk purge without a selector; invalid filter values.
\- 403 — {"detail": "You do not have permission to perform this action."} (Console user token, or key not allowed).
\- 404 — {"detail": "Biometric template not found."} on GET of an unknown or purged template.
\- 503 — {"detail": "The biometric-template operation could not finish because an external store is unavailable. The operation is retryable."} The template moves to status purge_failed and is already excluded from matching; repeat the purge.

Every retain and purge attempt, including failures, is recorded on Didit's audit trail with the acting principal, instruction class, instruction_source, instruction_id, and outcome.

For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.`

\</pre>



      
      

Incolla in

Per impostazione predefinita, eliminare una sessione di verifica elimina anche l'embedding facciale che alimentava la [Ricerca facciale 1:N](https://docs.didit.me/it/core-technology/face-search/overview.md) e il rilevamento dei duplicati per quella sessione. Le applicazioni che hanno bisogno che il rilevamento dei duplicati continui a funzionare dopo l'eliminazione della sessione possono attivare la **conservazione del modello biometrico**. In questo caso Didit elimina la sessione e tutti i suoi dati come di consueto, e conserva un unico modello biometrico facciale, gestito separatamente e privo di immagini, collegato all'[Utente](https://docs.didit.me/it/entities/users/overview.md) della sessione.L'API dei modelli biometrici ti permette di vedere esattamente quali modelli la tua applicazione conserva, per quale motivo, fino a quando, e di eliminarli in qualsiasi momento. Ogni modello è inoltre visibile nella Business Console, in **Lists → Biometric templates**, e nel profilo dell'Utente a cui appartiene.> [!WARNING]
>
> Un modello biometrico conservato è un dato biometrico. Non è anonimo, non è temporaneo e non viene eliminato insieme alla sessione. Resta disponibile fino alla sua scadenza programmata, fino a una scadenza anteriore prevista dalla legge applicabile, fino all'eliminazione dell'Utente, fino a una richiesta di cancellazione per motivi di privacy o fino a un'eliminazione esplicita. Attiva la conservazione solo se le istruzioni del titolare del trattamento e l'informativa sulla privacy la coprono.## Come viene creato un modello| Trigger | `source_type` | Origine dell'istruzione |
| - | - | - |
| Elimini una sessione su un'applicazione che ha attivato l'opzione, oppure invii `retain_face_embeddings: true` su [Delete Session](https://docs.didit.me/it/sessions-api/delete-session.md) o [Batch Delete Sessions](https://docs.didit.me/it/management-api/sessions/batch-delete.md) | `session_delete` | `instruction_source: api` oppure `console` |
| La [finestra generale di conservazione dei dati](https://docs.didit.me/it/console/data-retention.md) della tua applicazione fa scadere una sessione su un'applicazione che ha attivato l'opzione | `automatic_retention` | `instruction_source: automatic_retention` |
| Un backfill eseguito da Didit su tua istruzione, per le sessioni eliminate prima che tu attivassi l'opzione | `backfill` | `instruction_source: backfill` |La conservazione richiede un ancoraggio a un Utente. Una sessione creata senza `vendor_data` non ha un Utente, quindi non può conservare un modello; l'eliminazione restituisce `ineligible_no_vendor_user` e l'embedding viene eliminato insieme alla sessione.## Cosa contiene un modello| Conservato | Mai conservato |
| - | - |
| Il modello facciale numerico usato per il confronto | L'immagine del volto, il video di prova di vita, le immagini dei documenti, i ritagli del ritratto e qualsiasi altro contenuto multimediale |
| Un nuovo `uuid` del modello, casuale, e un `provenance_reference` opaco | L'id della sessione eliminata, il suo numero, la decisione, i campi di identità estratti o i payload delle funzionalità |
| L'Utente proprietario (`vendor_user_uuid`); `vendor_data` viene recuperato dall'Utente quando leggi il modello, e non viene mai copiato | Stato della blocklist, corrispondenze precedenti, etichette antifrode o affermazioni di identità tra organizzazioni diverse |
| `retained_at`, `expires_at`, `retention_policy`, `retention_override`, `instruction_class`, `instruction_source`, `instruction_id`, `retained_by`, `retained_by_type` | Indirizzi email degli attori |I modelli sono limitati al tuo tenant e vengono usati solo su tua istruzione all'interno della tua applicazione: rilevamento di volti duplicati e di account multipli, [Autenticazione biometrica](https://docs.didit.me/it/core-technology/biometric-auth/overview.md) e le tue liste facciali. Non vengono mai usati per l'addestramento di modelli, per analisi, per il confronto tra organizzazioni diverse, per i segnali condivisi di [Networks](https://docs.didit.me/it/console/networks.md) né per l'elaborazione antifrode indipendente di Didit.## Oggetto modello```json theme={null}
{
  "uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b",
  "vendor_user_uuid": "2f7c1a9e-8b4d-4c6a-9e1f-3d5b7a9c1e2f",
  "vendor_data": "user-42",
  "source_type": "session_delete",
  "provenance_reference": "6b1e8d2f-4a3c-4f9e-8c7d-1a2b3c4d5e6f",
  "retention_policy": "retain_until_user_deleted",
  "retention_override": null,
  "retained_at": "2026-08-28T10:15:42.318402Z",
  "expires_at": "2027-08-28T10:15:42.318402Z",
  "retained_by": "3c9e2b1f-7d4a-4e8b-9c1d-5f6a7b8c9d0e",
  "retained_by_type": "API_KEY",
  "instruction_class": "operational_session_delete",
  "instruction_source": "api",
  "instruction_id": "post-approval-cleanup-2026-08",
  "held_out_of_use": false,
  "status": "active",
  "purged_at": null
}
```| Campo | Tipo | Descrizione |
| - | - | - |
| `uuid` | UUID | Id del modello. Generato casualmente; non deriva dalla sessione eliminata né dal suo volto. |
| `vendor_user_uuid` | UUID | L'Utente proprietario. |
| `vendor_data` | string o null | Il `vendor_data` attuale dell'Utente, recuperato quando leggi il modello. |
| `source_type` | enum | `session_delete`, `automatic_retention` oppure `backfill`. |
| `provenance_reference` | UUID | Riferimento opaco che collega il modello alla sua traccia di audit. Non è l'id della sessione eliminata e non può essere ricondotto a essa tramite l'API. |
| `retention_policy` | enum | La politica dell'applicazione al momento della conservazione: `delete_with_session` oppure `retain_until_user_deleted`. |
| `retention_override` | boolean o null | Il valore di `retain_face_embeddings` inviato con l'eliminazione, oppure `null` quando si è applicata la politica. |
| `retained_at` | datetime | Quando il modello è stato creato. |
| `expires_at` | datetime | Quando il modello scade ed è eliminato automaticamente. È sempre impostato. |
| `retained_by` | string | Il soggetto che ha dato l'istruzione: l'id dell'applicazione per le chiavi API, l'id del membro della Console per le azioni dalla Console, oppure un identificativo `service:` per la conservazione automatica. Non è mai un indirizzo email. |
| `retained_by_type` | enum | `API_KEY`, `CONSOLE_USER` oppure `SYSTEM`. |
| `instruction_class` | enum | `operational_session_delete` oppure `privacy_erasure`. |
| `instruction_source` | enum | `api`, `console`, `automatic_retention`, `backfill`, `privacy_erasure`, `explicit_template_purge`, `vendor_user_delete`, `expiry`, `reconciliation`, `migration` oppure `system`. |
| `instruction_id` | string | Il `instruction_id` che hai inviato con l'eliminazione, oppure un id generato da Didit se lo hai omesso. |
| `held_out_of_use` | boolean | `true` solo finché è in vigore un vincolo di conservazione legale. Un modello soggetto a blocco è escluso da ogni confronto. Vedi [Vincoli di conservazione legale](#blocchi-legali). |
| `status` | enum | Stato del ciclo di vita, vedi sotto. |
| `purged_at` | datetime o null | Quando il modello è stato eliminato. |### Stato| `status` | Significato | Nel confronto? |
| - | - | - |
| `pending` | Il modello è in fase di creazione. Se l'eliminazione che lo ha creato ha restituito `503`, ripeti l'eliminazione per completarlo. | No |
| `active` | Il modello partecipa al confronto fino a `expires_at`. | Sì, a meno che `held_out_of_use` sia `true` oppure `expires_at` sia già passato |
| `expired` | `expires_at` è passato e l'eliminazione automatica è in corso. | No |
| `held_out_of_use` | Si applica un vincolo di conservazione legale. | No |
| `purge_pending` | Un'eliminazione è in corso. | No |
| `purge_failed` | Un'eliminazione non è riuscita a completarsi perché un archivio biometrico non era disponibile. Ripeti l'eliminazione; nel frattempo il modello resta escluso dal confronto. | No |
| `purged` | Il modello è stato eliminato. Visibile solo nella risposta dell'eliminazione come `already_purged`; i modelli eliminati non vengono elencati e restituiscono `404` nel dettaglio. | No |## Come vengono usati i modelli nel confrontoUn modello `active` partecipa esattamente allo stesso confronto di un volto di una sessione ancora esistente: rilevamento automatico dei duplicati durante le nuove sessioni, l'[API Ricerca facciale](https://docs.didit.me/it/standalone-apis/face-search.md) autonoma, [Autenticazione biometrica](https://docs.didit.me/it/core-technology/biometric-auth/overview.md) e le tue liste facciali. Una corrispondenza con un modello conservato viene riportata con `source: "retained_template"`, con il `vendor_user_id` e il `vendor_data` dell'utente proprietario, e con il `biometric_template_id`. Non include mai un id di sessione, un'immagine di confronto, dati identificativi o uno stato, perché la sessione che ha prodotto il volto non esiste più. Vedi [report della Ricerca facciale](https://docs.didit.me/it/core-technology/face-search/report-face-search.md).Un modello conservato non viene mai inserito in una blocklist. Se il volto della sessione eliminata era presente in una blocklist facciale, la voce della blocklist mantiene una propria voce biometrica indipendente e un proprio ciclo di vita: rimuovere la voce dalla lista elimina la voce della blocklist, mentre eliminare definitivamente il modello non interviene sulla lista.## Punti di eliminazioneTutti i seguenti punti rimuovono il modello dal confronto ed eliminano il modello memorizzato:| Punto di eliminazione | Come |
| - | - |
| Eliminazione esplicita | [`DELETE /v3/biometric-templates/{uuid}/`](https://docs.didit.me/it/management-api/biometric-templates/purge) oppure [`POST /v3/biometric-templates/delete/`](https://docs.didit.me/it/management-api/biometric-templates/batch-purge), oppure **Lists → Modelli biometrici** nella Console |
| Eliminazione dell'utente | [`POST /v3/users/delete/`](https://docs.didit.me/it/management-api/users/delete) elimina definitivamente ogni modello associato all'utente prima che l'utente venga eliminato |
| Cancellazione per privacy | Qualsiasi eliminazione di una sessione di quell'utente eseguita con `deletion_instruction: "privacy_erasure"` elimina definitivamente ogni modello associato all'utente, indipendentemente dalla policy dell'applicazione |
| Scadenza | Didit elimina automaticamente il modello una volta superato `expires_at` |Riportare la policy dell'applicazione a `delete_with_session` impedisce la creazione di nuovi modelli, ma **non** elimina quelli esistenti. Eliminali esplicitamente.Le eliminazioni rimuovono prima il modello memorizzato e solo dopo contrassegnano il modello come eliminato. Quindi, se un'eliminazione restituisce `503`, il modello passa a `purge_failed`, risulta già escluso dal confronto e può essere ripetuta in sicurezza. Ripetere un'eliminazione di un modello già eliminato restituisce `already_purged`.## Traccia di auditOgni tentativo di conservazione e di eliminazione, compresi i fallimenti e gli esiti di non idoneità, viene registrato con il soggetto che esegue l'operazione (`retained_by` / soggetto che elimina e relativo tipo), `instruction_class`, `instruction_source`, `instruction_id`, `provenance_reference` e l'esito. Invia un tuo `instruction_id` nelle eliminazioni, così puoi correlare la traccia di audit di Didit con il tuo registro delle cancellazioni. Le voci di audit non contengono mai immagini, vettori, campi identificativi o indirizzi email.## Blocchi legaliUn blocco legale è un'eccezione, mai una modalità di conservazione. Didit non applica blocchi di propria iniziativa: un blocco può derivare solo da un'istruzione documentata ai sensi del tuo accordo sul trattamento dei dati o da un ordine vincolante di un'autorità competente. Mentre un blocco è attivo, il modello viene contrassegnato come `held_out_of_use`: è escluso da ogni tipo di confronto e dal recupero ordinario, e non è mai ricercabile. Non esistono API per creare o rimuovere i blocchi. Se ricevi un ordine che riguarda i modelli conservati, contatta il tuo referente Didit.## Autorizzazioni e autenticazioneGli endpoint dei modelli biometrici accettano solo chiavi API dell'applicazione (`x-api-key`). I token utente della Business Console vengono rifiutati con `403`. Gli utenti della Console gestiscono i modelli tramite **Lists → Modelli biometrici** con le loro autorizzazioni `lists`.## Endpoint| Endpoint | Metodo | Scopo |
| - | - | - |
| [`/v3/biometric-templates/`](https://docs.didit.me/it/management-api/biometric-templates/list) | GET | Elenco paginato con filtri |
| [`/v3/biometric-templates/count/`](https://docs.didit.me/it/management-api/biometric-templates/count) | GET | Conteggio con gli stessi filtri |
| [`/v3/biometric-templates/{template_uuid}/`](https://docs.didit.me/it/management-api/biometric-templates/get) | GET | Un singolo modello |
| [`/v3/biometric-templates/{template_uuid}/`](https://docs.didit.me/it/management-api/biometric-templates/purge) | DELETE | Elimina definitivamente un modello |
| [`/v3/biometric-templates/delete/`](https://docs.didit.me/it/management-api/biometric-templates/batch-purge) | POST | Elimina definitivamente per elenco di id o per filtro |## Correlati- [Eliminazione della sessione](https://docs.didit.me/it/sessions-api/delete-session.md)
- [Eliminazione in batch delle sessioni](https://docs.didit.me/it/management-api/sessions/batch-delete.md)
- [Conservazione dei dati](https://docs.didit.me/it/console/data-retention.md#conservazione-del-modello-biometrico)
- [Volti e dati biometrici](https://docs.didit.me/it/entities/users/faces-and-biometrics.md)


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