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

> A API da Didit gerencia templates biométricos faciais sem imagem retidos após a exclusão da sessão: liste, conte, filtre, inspecione e exclua.



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 padrão, excluir uma sessão de verificação também exclui o embedding facial que alimentava a [Busca facial 1:N](https://docs.didit.me/pt-br/core-technology/face-search/overview.md) e a detecção de duplicidades dessa sessão. Aplicações que precisam manter a detecção de duplicidades funcionando depois da exclusão da sessão podem ativar a **retenção de templates biométricos**. Nesse caso, a Didit exclui a sessão e todos os seus dados normalmente e mantém um único template biométrico facial, sem imagens e gerenciado separadamente, vinculado ao [Usuário](https://docs.didit.me/pt-br/entities/users/overview.md) da sessão.A API de templates biométricos permite ver exatamente quais templates sua aplicação mantém, por que motivo e até quando, além de expurgá-los a qualquer momento. Cada template também aparece no Business Console em **Lists → Biometric templates** e no perfil do Usuário ao qual pertence.> [!WARNING]
>
> Um template biométrico retido é um dado biométrico. Ele não é anônimo, não é temporário e não é excluído junto com a sessão. Ele permanece até a data de validade programada, até um prazo anterior exigido pela legislação aplicável, até a exclusão do Usuário, até uma solicitação de eliminação por motivos de privacidade ou até um expurgo explícito. Ative a retenção somente quando sua instrução como controlador e seu aviso de privacidade a contemplarem.## Como um template é criado| Gatilho | `source_type` | Origem da instrução |
| - | - | - |
| Você exclui uma sessão em uma aplicação com a retenção ativada, ou envia `retain_face_embeddings: true` em [Excluir sessão](https://docs.didit.me/pt-br/sessions-api/delete-session.md) ou [Excluir sessões em lote](https://docs.didit.me/pt-br/management-api/sessions/batch-delete.md) | `session_delete` | `instruction_source: api` ou `console` |
| A [janela geral de retenção de dados](https://docs.didit.me/pt-br/console/data-retention.md) da sua aplicação faz uma sessão expirar em uma aplicação com a retenção ativada | `automatic_retention` | `instruction_source: automatic_retention` |
| Um backfill operado pela Didit, solicitado por você, para sessões excluídas antes de você ativar a retenção | `backfill` | `instruction_source: backfill` |A retenção exige um vínculo com um Usuário. Uma sessão criada sem `vendor_data` não tem Usuário e, portanto, não pode reter um template; a exclusão informa `ineligible_no_vendor_user` e o embedding é excluído junto com a sessão.## O que um template contém| Retido | Nunca retido |
| - | - |
| O template facial numérico usado na correspondência | A imagem do rosto, o vídeo de prova de vida, as imagens de documentos, os recortes de retrato e qualquer outra mídia |
| Um novo `uuid` aleatório do template e um `provenance_reference` opaco | O id, o número, a decisão, os campos de identidade extraídos ou os payloads de recursos da sessão excluída |
| O Usuário proprietário (`vendor_user_uuid`); o `vendor_data` é obtido do Usuário quando você lê o template, nunca copiado | Status na 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 de quem executou a ação |Os templates são específicos de cada tenant e usados somente sob sua instrução, dentro da sua aplicação: detecção de rostos duplicados e de múltiplas contas, [Autenticação biométrica](https://docs.didit.me/pt-br/core-technology/biometric-auth/overview.md) e suas próprias listas de rostos. Eles nunca são usados para treinamento de modelos, análises, correspondência entre organizações, sinais compartilhados de [Redes](https://docs.didit.me/pt-br/console/networks.md) ou o processamento independente de fraudes 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 excluída nem do rosto dela. |
| `vendor_user_uuid` | UUID | O Usuário proprietário. |
| `vendor_data` | string ou null | O `vendor_data` atual do Usuário, obtido quando você lê o template. |
| `source_type` | enum | `session_delete`, `automatic_retention` ou `backfill`. |
| `provenance_reference` | UUID | Referência opaca que vincula o template ao seu registro de auditoria. Não é o id da sessão excluída e não pode ser vinculada a ela pela API. |
| `retention_policy` | enum | A política da aplicação no momento da retenção: `delete_with_session` ou `retain_until_user_deleted`. |
| `retention_override` | boolean ou null | O valor de `retain_face_embeddings` enviado na exclusão, ou `null` quando a política foi aplicada. |
| `retained_at` | datetime | Quando o template foi criado. |
| `expires_at` | datetime | Quando o template expira e é expurgado automaticamente. Sempre definido. |
| `retained_by` | string | Principal que deu a instrução: o id da aplicação para chaves de API, o id do membro do Console para ações no 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 você enviou na exclusão, ou um id gerado pela Didit quando você o omitiu. |
| `held_out_of_use` | boolean | `true` somente enquanto um bloqueio legal estiver em vigor. Um template bloqueado é excluído de toda correspondência. Consulte [Bloqueios legais](#preservações-legais). |
| `status` | enum | Status do ciclo de vida, veja abaixo. |
| `purged_at` | datetime ou null | Quando o template foi expurgado. |### Status| `status` | Significado | Participa da correspondência? |
| - | - | - |
| `pending` | O template está sendo criado. Se a exclusão que o criou retornou `503`, repita a exclusão para concluí-la. | Não |
| `active` | O template participa da correspondência até `expires_at`. | Sim, a menos que `held_out_of_use` seja `true` ou que `expires_at` já tenha passado |
| `expired` | `expires_at` já passou e o expurgo automático está em andamento. | Não |
| `held_out_of_use` | Um bloqueio legal está em vigor. | Não |
| `purge_pending` | Um expurgo está em andamento. | Não |
| `purge_failed` | Um expurgo não pôde ser concluído porque um armazenamento biométrico estava indisponível. Repita o expurgo; enquanto isso, o template continua excluído da correspondência. | Não |
| `purged` | O template foi excluído. Visível apenas na resposta do expurgo como `already_purged`; templates expurgados não são listados e retornam `404` na consulta de detalhes. | Não |## Como os templates são usados na correspondênciaUm template `active` participa exatamente da mesma correspondência que o rosto de uma sessão em andamento: detecção automática de duplicatas durante novas sessões, a [API de Busca facial](https://docs.didit.me/pt-br/standalone-apis/face-search.md) independente, a [Autenticação biométrica](https://docs.didit.me/pt-br/core-technology/biometric-auth/overview.md) e as suas listas de rostos. Uma correspondência com um template retido é informada com `source: "retained_template"`, o `vendor_user_id` e os `vendor_data` do Usuário ao qual ele pertence e o `biometric_template_id`. Ela nunca traz um ID de sessão, uma imagem de correspondência, dados de identidade ou um status, porque a sessão que gerou o rosto não existe mais. Consulte o [relatório de Busca facial](https://docs.didit.me/pt-br/core-technology/face-search/report-face-search.md).Um template retido nunca entra em uma lista de bloqueio. Se o rosto da sessão excluída estava em uma lista de bloqueio de rostos, essa entrada da lista de bloqueio mantém a sua própria entrada biométrica independente e o seu próprio ciclo de vida: remover a entrada da lista exclui a entrada da lista de bloqueio, e expurgar o template não afeta a lista.## Pontos de expurgoTodos os casos a seguir removem o template da correspondência e excluem o template armazenado:| Ponto de expurgo | Como |
| - | - |
| Expurgo explícito | [`DELETE /v3/biometric-templates/{uuid}/`](https://docs.didit.me/pt-br/management-api/biometric-templates/purge) ou [`POST /v3/biometric-templates/delete/`](https://docs.didit.me/pt-br/management-api/biometric-templates/batch-purge), ou **Lists → Biometric templates** no Console |
| Exclusão do usuário | [`POST /v3/users/delete/`](https://docs.didit.me/pt-br/management-api/users/delete) expurga todos os templates vinculados ao Usuário antes de o Usuário ser excluído |
| Apagamento por privacidade | Qualquer exclusão de uma sessão desse Usuário enviada com `deletion_instruction: "privacy_erasure"` expurga todos os templates vinculados ao Usuário, independentemente da política da aplicação |
| Expiração | A Didit expurga o template automaticamente assim que a data em `expires_at` passa |Alterar novamente a política da aplicação para `delete_with_session` impede a criação de novos templates, mas **não** expurga os existentes. Expurgue-os explicitamente.Os expurgos excluem primeiro o template armazenado e só depois marcam o template como expurgado. Por isso, um expurgo que retorna `503` deixa o template em `purge_failed`, já excluído da correspondência, e pode ser repetido com segurança. Um novo expurgo de um template já expurgado retorna `already_purged`.## Trilha de auditoriaToda tentativa de retenção e de expurgo, incluindo falhas e resultados de inelegibilidade, é registrada com a entidade responsável pela ação (`retained_by` / responsável pelo expurgo e seu tipo), `instruction_class`, `instruction_source`, `instruction_id`, `provenance_reference` e o resultado. Envie o seu próprio `instruction_id` nas exclusões para poder correlacionar a trilha de auditoria da Didit com o seu registro de apagamentos. As entradas de auditoria nunca contêm imagens, vetores, campos de identidade ou endereços de e-mail.## Preservações legaisUma preservação legal (legal hold) é uma exceção, nunca um modo de retenção. A Didit não aplica preservações por iniciativa própria; uma preservação só pode decorrer de uma instrução documentada nos termos do seu Acordo de Processamento de Dados ou de uma ordem vinculante de uma autoridade competente. Enquanto uma preservação estiver em vigor, o template fica marcado como `held_out_of_use`: ele é excluído de todo tipo de correspondência e da recuperação rotineira, e nunca pode ser pesquisado. Não existe API para criar ou remover preservações. Entre em contato com o seu representante da Didit se receber uma ordem que afete templates retidos.## Permissões e autenticaçãoOs endpoints de templates biométricos aceitam apenas chaves de API da aplicação (`x-api-key`). Tokens de usuário do Business Console são rejeitados com `403`. Os usuários do Console gerenciam os templates em **Lists → Biometric templates** de acordo com suas permissões de `lists`.## Endpoints| Endpoint | Método | Finalidade |
| - | - | - |
| [`/v3/biometric-templates/`](https://docs.didit.me/pt-br/management-api/biometric-templates/list) | GET | Lista paginada com filtros |
| [`/v3/biometric-templates/count/`](https://docs.didit.me/pt-br/management-api/biometric-templates/count) | GET | Contagem com os mesmos filtros |
| [`/v3/biometric-templates/{template_uuid}/`](https://docs.didit.me/pt-br/management-api/biometric-templates/get) | GET | Um template |
| [`/v3/biometric-templates/{template_uuid}/`](https://docs.didit.me/pt-br/management-api/biometric-templates/purge) | DELETE | Excluir permanentemente um template |
| [`/v3/biometric-templates/delete/`](https://docs.didit.me/pt-br/management-api/biometric-templates/batch-purge) | POST | Excluir permanentemente por lista de IDs ou por filtro |## Conteúdo relacionado- [Excluir sessão](https://docs.didit.me/pt-br/sessions-api/delete-session.md)
- [Excluir sessões em lote](https://docs.didit.me/pt-br/management-api/sessions/batch-delete.md)
- [Retenção de dados](https://docs.didit.me/pt-br/console/data-retention.md#retenção-de-template-biométrico)
- [Rostos e biometria](https://docs.didit.me/pt-br/entities/users/faces-and-biometrics.md)


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