> ## 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 de templates biométricos

> Gira na API da Didit os templates faciais biométricos sem imagem retidos após eliminar sessões: listar, contar, filtrar, inspecionar e eliminar.



Prompt da API de templates biométricos
        Copiar o prompt para a área de transferência



      
      

\<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>



      
      

Colar em

Por predefinição, eliminar uma sessão de verificação também elimina o embedding facial que alimentava a [Pesquisa facial 1:N](https://docs.didit.me/pt/core-technology/face-search/overview.md) e a deteção de duplicados dessa sessão. As aplicações que precisam de manter a deteção de duplicados a funcionar após a eliminação da sessão podem optar pela **retenção de templates biométricos**. Nesse caso, a Didit elimina a sessão e todos os seus dados, como habitualmente, e mantém um template biométrico facial, sem imagens e gerido em separado, associado ao [Utilizador](https://docs.didit.me/pt/entities/users/overview.md) da sessão.A Biometric Templates API permite-lhe ver exatamente quais os templates que a sua aplicação detém, porquê, até quando, e purgá-los a qualquer momento. Cada template fica também visível na Business Console em **Lists → Biometric templates** e no perfil do Utilizador proprietário.> [!WARNING]
>
> Um template biométrico retido é um dado biométrico. Não é anónimo, não é transitório e não é eliminado com a sessão. Mantém-se até à sua data de expiração agendada, até um prazo anterior previsto na lei aplicável, até à eliminação do Utilizador, até um pedido de apagamento por motivos de privacidade ou até uma purga explícita. Ative a retenção apenas quando a sua instrução enquanto responsável pelo tratamento e o seu aviso de privacidade a abrangerem.## Como um template é criado| Gatilho | `source_type` | De onde vem a instrução |
| - | - | - |
| Eliminar uma sessão numa aplicação com retenção ativada, ou enviar `retain_face_embeddings: true` em [Eliminar sessão](https://docs.didit.me/pt/sessions-api/delete-session.md) ou [Eliminar sessões em lote](https://docs.didit.me/pt/management-api/sessions/batch-delete.md) | `session_delete` | `instruction_source: api` ou `console` |
| Quando a janela geral de [retenção de dados](https://docs.didit.me/pt/console/data-retention.md) da sua aplicação faz expirar uma sessão numa aplicação com retenção ativada | `automatic_retention` | `instruction_source: automatic_retention` |
| Um preenchimento retroativo (backfill) executado pela Didit, por sua instrução, para sessões eliminadas antes de ativar a retenção | `backfill` | `instruction_source: backfill` |A retenção exige uma âncora de Utilizador. Uma sessão criada sem `vendor_data` não tem Utilizador e, por isso, não pode reter um template. A eliminação devolve `ineligible_no_vendor_user` e o embedding é eliminado com a sessão.## O que um template contém| Retido | Nunca retido |
| - | - |
| O template facial numérico usado na correspondência | A imagem facial, o vídeo de prova de vida, as imagens do documento, os recortes de retrato e quaisquer outros conteúdos multimédia |
| Um novo `uuid` de template, gerado aleatoriamente, e um `provenance_reference` opaco | O id, o número, a decisão, os campos de identidade extraídos ou os payloads de funcionalidades da sessão eliminada |
| O Utilizador proprietário (`vendor_user_uuid`); o `vendor_data` é obtido a partir do Utilizador quando lê o template, nunca copiado | O estado da lista de bloqueio, correspondências anteriores, rótulos de fraude ou declarações de identidade entre organizações |
| `retained_at`, `expires_at`, `retention_policy`, `retention_override`, `instruction_class`, `instruction_source`, `instruction_id`, `retained_by`, `retained_by_type` | Endereços de e-mail dos atores |Os templates têm âmbito limitado à sua organização e são utilizados apenas por instrução sua, dentro da sua aplicação: deteção de rostos duplicados e de várias contas, [Autenticação biométrica](https://docs.didit.me/pt/core-technology/biometric-auth/overview.md) e as suas próprias listas faciais. Nunca são usados para treino de modelos, análises, correspondência entre organizações, sinais partilhados das [Redes](https://docs.didit.me/pt/console/networks.md) ou para o processamento independente de fraude da Didit.## Objeto template```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 | Descrição |
| - | - | - |
| `uuid` | UUID | Id do template. Gerado aleatoriamente; não derivado da sessão eliminada nem do seu rosto. |
| `vendor_user_uuid` | UUID | O Utilizador proprietário. |
| `vendor_data` | string ou null | O `vendor_data` atual do Utilizador, obtido quando lê o template. |
| `source_type` | enum | `session_delete`, `automatic_retention` ou `backfill`. |
| `provenance_reference` | UUID | Referência opaca que liga o template ao seu registo de auditoria. Não é o id da sessão eliminada e não pode ser resolvida para essa sessão através da API. |
| `retention_policy` | enum | A política da aplicação à data da retenção: `delete_with_session` ou `retain_until_user_deleted`. |
| `retention_override` | boolean ou null | O valor de `retain_face_embeddings` enviado na eliminação, ou `null` quando se aplicou a política. |
| `retained_at` | datetime | Quando o template foi criado. |
| `expires_at` | datetime | Quando o template expira e é purgado automaticamente. Está sempre definido. |
| `retained_by` | string | Entidade que deu a instrução: o id da aplicação para chaves de API, o id do membro da Console para ações na Console, ou um identificador `service:` para a retenção automática. Nunca um endereço de e-mail. |
| `retained_by_type` | enum | `API_KEY`, `CONSOLE_USER` ou `SYSTEM`. |
| `instruction_class` | enum | `operational_session_delete` ou `privacy_erasure`. |
| `instruction_source` | enum | `api`, `console`, `automatic_retention`, `backfill`, `privacy_erasure`, `explicit_template_purge`, `vendor_user_delete`, `expiry`, `reconciliation`, `migration` ou `system`. |
| `instruction_id` | string | O `instruction_id` que enviou na eliminação, ou um id gerado pela Didit quando o omitiu. |
| `held_out_of_use` | boolean | `true` apenas enquanto se aplicar uma retenção legal. Um template sujeito a retenção legal é excluído de toda a correspondência. Consulte [Retenções legais](#retenções-legais). |
| `status` | enum | Estado do ciclo de vida, ver abaixo. |
| `purged_at` | datetime ou null | Quando o template foi purgado. |### Estado| `status` | Significado | Em correspondência? |
| - | - | - |
| `pending` | O template está a ser criado. Se a eliminação que o criou devolveu `503`, repita a eliminação para concluir. | Não |
| `active` | O template participa na correspondência até `expires_at`. | Sim, exceto se `held_out_of_use` for `true` ou se `expires_at` já tiver passado |
| `expired` | `expires_at` já passou e a purga automática está em curso. | Não |
| `held_out_of_use` | Aplica-se uma retenção legal. | Não |
| `purge_pending` | Uma purga está em curso. | Não |
| `purge_failed` | A purga não pôde terminar porque um armazenamento biométrico estava indisponível. Repita a purga; entretanto, o template continua excluído da correspondência. | Não |
| `purged` | O template foi eliminado. Só é visível na resposta da purga como `already_purged`; os templates purgados não aparecem em listagens e devolvem `404` no detalhe. | Não |## Como são utilizados os modelos na correspondênciaUm modelo `active` participa exatamente na mesma correspondência que um rosto de uma sessão em direto: deteção automática de duplicados durante novas sessões, a [API de Pesquisa facial](https://docs.didit.me/pt/standalone-apis/face-search.md) independente, [Autenticação biométrica](https://docs.didit.me/pt/core-technology/biometric-auth/overview.md) e as suas listas de rostos. Uma correspondência com um modelo retido é reportada com `source: "retained_template"`, o `vendor_user_id` e `vendor_data` do utilizador titular, e o `biometric_template_id`. Nunca inclui um ID de sessão, uma imagem de comparação, dados de identidade ou um estado, porque a sessão que produziu o rosto já não existe. Consulte [Relatório de Pesquisa facial](https://docs.didit.me/pt/core-technology/face-search/report-face-search.md).Um modelo retido nunca é colocado numa lista de bloqueio. Se o rosto da sessão eliminada estava numa lista de bloqueio de rostos, essa entrada da lista mantém a sua própria entrada biométrica independente e o seu próprio ciclo de vida: remover a entrada da lista elimina a entrada da lista de bloqueio, e eliminar o modelo não afeta a lista.## Pontos de eliminaçãoTodos os casos seguintes removem o modelo da correspondência e eliminam o modelo armazenado:| Ponto de eliminação | Como |
| - | - |
| Eliminação explícita | [`DELETE /v3/biometric-templates/{uuid}/`](https://docs.didit.me/pt/management-api/biometric-templates/purge) ou [`POST /v3/biometric-templates/delete/`](https://docs.didit.me/pt/management-api/biometric-templates/batch-purge), ou **Listas → Templates biométricos** na Consola |
| Eliminação de utilizador | [`POST /v3/users/delete/`](https://docs.didit.me/pt/management-api/users/delete) elimina todos os modelos associados ao utilizador antes de eliminar o utilizador |
| Apagamento por motivos de privacidade | Qualquer eliminação de uma sessão desse utilizador enviada com `deletion_instruction: "privacy_erasure"` elimina todos os modelos associados ao utilizador, independentemente da política da aplicação |
| Expiração | A Didit elimina o modelo automaticamente quando `expires_at` for ultrapassado |Repor a política da aplicação para `delete_with_session` impede a criação de novos modelos, mas **não** elimina os existentes. Elimine-os explicitamente.As eliminações apagam primeiro o modelo armazenado e só depois marcam o modelo como eliminado. Assim, uma eliminação que devolve `503` deixa o modelo em `purge_failed`, já excluído da correspondência, e pode ser repetida em segurança. Uma eliminação repetida de um modelo já eliminado devolve `already_purged`.## Registo de auditoriaCada tentativa de retenção e de eliminação, incluindo falhas e resultados não elegíveis, é registada com o principal que atua (`retained_by` / principal de eliminação e tipo), `instruction_class`, `instruction_source`, `instruction_id`, `provenance_reference` e o resultado. Envie o seu próprio `instruction_id` nas eliminações para poder correlacionar o registo de auditoria da Didit com o seu registo de eliminações. As entradas de auditoria nunca contêm imagens, vetores, campos de identidade nem endereços de correio eletrónico.## Retenções legaisUma retenção legal é uma exceção, nunca um modo de retenção. A Didit não aplica retenções por iniciativa própria; uma retenção só pode seguir uma instrução documentada ao abrigo do seu Acordo de Tratamento de Dados ou uma ordem vinculativa de uma autoridade competente. Enquanto uma retenção estiver em vigor, o modelo é marcado como `held_out_of_use`: fica excluído de todos os tipos de correspondência e da recuperação de rotina, e nunca é pesquisável. Não existe nenhuma API para criar ou levantar retenções. Contacte o seu representante da Didit se receber uma ordem que afete modelos retidos.## Permissões e autenticaçãoOs endpoints de templates biométricos aceitam apenas chaves de API da aplicação (`x-api-key`). Os tokens de utilizador da Business Console são rejeitados com `403`. Os utilizadores da Consola gerem os modelos em **Listas → Templates biométricos** com as suas permissões de `lists`.## Endpoints| Endpoint | Método | Finalidade |
| - | - | - |
| [`/v3/biometric-templates/`](https://docs.didit.me/pt/management-api/biometric-templates/list) | GET | Lista paginada com filtros |
| [`/v3/biometric-templates/count/`](https://docs.didit.me/pt/management-api/biometric-templates/count) | GET | Contagem com os mesmos filtros |
| [`/v3/biometric-templates/{template_uuid}/`](https://docs.didit.me/pt/management-api/biometric-templates/get) | GET | Um modelo |
| [`/v3/biometric-templates/{template_uuid}/`](https://docs.didit.me/pt/management-api/biometric-templates/purge) | DELETE | Eliminar um modelo |
| [`/v3/biometric-templates/delete/`](https://docs.didit.me/pt/management-api/biometric-templates/batch-purge) | POST | Eliminar por lista de IDs ou por filtro |## Documentação relacionada- [Eliminar sessão](https://docs.didit.me/pt/sessions-api/delete-session.md)
- [Eliminar sessões em lote](https://docs.didit.me/pt/management-api/sessions/batch-delete.md)
- [Conservação de dados](https://docs.didit.me/pt/console/data-retention.md#retenção-de-modelo-biométrico)
- [Rostos e biometria](https://docs.didit.me/pt/entities/users/faces-and-biometrics.md)


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