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

# Biometria de usuários: busca facial e lista de bloqueio

> O Didit vincula biometria facial às entidades User: busca 1:N, detecção de duplicados, lista de bloqueio facial e upload manual.



Prompt de biometria facial
        Copiar o prompt para a área de transferência



      
      

\<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) Auto-blocklist from declines

When a session is `DECLINED` and your workflow has auto-blocklist enabled, the associated face is added to the system face list automatically and the User entity transitions to `BLOCKED` per policy. No manual call needed.

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



      
      

Colar em

A biometria facial é fundamental para todas as entidades User. A Didit captura um rosto durante a [prova de vida](https://docs.didit.me/pt-br/core-technology/liveness/overview.md), gera um embedding vetorial e o armazena para uso em quatro recursos: **busca facial 1:N**, **detecção de duplicados**, **aplicação da lista de bloqueio** e **reautenticação biométrica**.> [!NOTE]
>
> Os rostos armazenados também servem como referência para a [Autenticação biométrica](https://docs.didit.me/pt-br/core-technology/biometric-auth/overview.md): crie uma sessão de autenticação biométrica com o `vendor_data` do usuário e omita `portrait_image`, e a Didit reutiliza automaticamente o rosto armazenado (primeiro o rosto da prova de vida aprovada, depois a foto do chip do passaporte eletrônico, depois o retrato do documento de identidade e, por fim, um rosto de perfil cadastrado manualmente).## Como os rostos são vinculados a um usuário**1. Captura durante a prova de vida**Quando um User passa por uma sessão com prova de vida ativada, a Didit captura uma selfie, executa a detecção passiva de prova de vida, extrai o maior rosto e gera um embedding vetorial para a busca.**2. Armazenamento no perfil do usuário**O rosto é vinculado à sessão e à entidade User pai. A URL do retrato aparece no perfil do usuário como `portrait_image`.**3. Indexação para a busca**O embedding é adicionado ao índice de busca. As sessões seguintes podem executar buscas 1:N nesse índice.## Busca facial (1:N)A busca facial permite encontrar um usuário enviando uma imagem e comparando-a com todos os rostos cadastrados na sua aplicação.Casos de uso:- **Detecção de duplicados** no onboarding — impede que a mesma pessoa crie duas contas.
- **Busca reversa** — identifica o usuário por trás de um quadro de CFTV ou de uma imagem em uma investigação de fraude.
- **Reconhecimento de clientes recorrentes** — dispensa o KYC para um cliente que retorna.A busca facial é executada automaticamente em novas sessões quando o seu fluxo de verificação (workflow) tem a detecção de duplicados ativada. Ela também está disponível como uma API independente:- `POST /v3/face-search/` — [busca facial independente](https://docs.didit.me/pt-br/standalone-apis/face-search.md)## Detecção de duplicadosCada novo rosto pode ser comparado com os rostos já cadastrados para identificar duplicados. A Didit atribui a cada rosto um `approved_duplicate_status`:| Status | Significado |
| - | - |
| `NOT_DUPLICATED` | Nenhuma correspondência encontrada acima do limiar de similaridade |
| `DUPLICATED` | O rosto corresponde a um ou mais rostos de uma sessão já aprovada |Os fluxos podem ser configurados para:- **Recusar** automaticamente as sessões sinalizadas como duplicadas.
- **Sinalizar para revisão** — encaminhar para um analista humano.
- **Apenas avisar** — permitir, mas adicionar uma tag de risco.Configure isso no console em *Workflows → \[seu fluxo] → Face Match / Liveness → Duplicate detection*.## Lista de bloqueio facialQuando uma sessão é recusada (por regra, por um analista ou pela configuração do fluxo), o rosto associado é adicionado automaticamente à **Face Blocklist** da sua aplicação. Sessões futuras com um rosto correspondente são rejeitadas.## Enviar um rosto importado para um perfil de usuárioSe você está migrando de outro provedor de KYC, pode criar o User primeiro e depois vincular uma imagem facial confiável a esse perfil. O User continua identificado pelo seu `vendor_data`, mas o endpoint de envio de rosto usa o id interno do User na Didit (`didit_internal_id`) para que o destino não seja ambíguo.**1. Crie ou recupere o User**Chame [`POST /v3/users/create/`](https://docs.didit.me/pt-br/management-api/users/create) com o seu `vendor_data` estável, ou chame `GET /v3/users/{vendor_data}/` se o User já existir.**2. Leia o didit\_internal\_id**A resposta do User inclui `didit_internal_id`. Continue usando `vendor_data` no seu próprio sistema; use `didit_internal_id` apenas nos endpoints de vinculação ao perfil.**3. Envie o rosto**Chame [`POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`](https://docs.didit.me/pt-br/management-api/users/upload-face) com uma imagem facial codificada em 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"
  }'
```Os rostos de perfil importados são cadastrados no mesmo índice facial usado na detecção de duplicados e na busca facial. Eles não são incluídos automaticamente na lista de bloqueio. Para bloquear um ator mal-intencionado conhecido, envie o rosto para uma lista do tipo facial.> [!WARNING]
>
> Envie apenas rostos que você tem permissão para processar segundo o seu próprio aviso de privacidade e o seu acordo de migração. Mantenha os identificadores do provedor de origem em `metadata` ou `comment` apenas quando for seguro expô-los aos seus operadores de conformidade.### Como ocorre a inclusão na lista de bloqueio| Gatilho | Ação |
| - | - |
| Sessão `DECLINED` com a inclusão automática na lista de bloqueio ativada | Rosto adicionado à lista facial do sistema, status do usuário → `BLOCKED` |
| Um analista inclui manualmente um rosto na lista de bloqueio pelo console | Rosto adicionado, status do usuário atualizado conforme a política |
| Inclusão programática pela Lists API | Envie a imagem facial para uma lista de bloqueio do tipo facial |### Enviar um rosto para a lista de bloqueioPara bloquear um usuário pelo rosto de forma programática, envie a imagem facial para uma lista de bloqueio do tipo facial pelo endpoint dedicado [Enviar rosto para a lista](https://docs.didit.me/pt-br/management-api/lists/upload-face.md). A Didit extrai o embedding biométrico e o insere no índice de correspondência — qualquer sessão futura cuja selfie da prova de vida corresponda é recusada automaticamente.> [!NOTE]
>
> O envio de rosto ao perfil e o envio de rosto à lista de bloqueio são operações diferentes. Use o envio ao perfil para vincular um rosto importado confiável a um User como evidência, para a detecção de duplicados e para a busca facial. Use a [Lists API](https://docs.didit.me/pt-br/management-api/lists/overview.md) para bloquear um rosto, de modo que as futuras sessões com correspondência sejam rejeitadas.### Remover um rosto da lista de bloqueioRemova a entrada pelo console em *Blocklist → Faces → ações da linha → Remove*, ou use o endpoint [Excluir entrada](https://docs.didit.me/pt-br/management-api/lists/delete-entry.md).## Templates biométricos retidos após a exclusão da sessãoExcluir uma sessão exclui a imagem do rosto e, por padrão, o embedding facial, o que remove a pessoa da detecção de duplicatas e da Busca facial. Se você exclui sessões logo após a aprovação, mas ainda precisa identificar cadastros repetidos, ative a [retenção de templates biométricos](https://docs.didit.me/pt-br/console/data-retention.md#retenção-de-template-biométrico) na aplicação ou envie `retain_face_embeddings: true` na chamada de exclusão.Nesse caso, a Didit exclui a sessão e todos os seus dados normalmente e mantém um único template biométrico facial sem imagem, gerenciado separadamente e vinculado ao User:- Ele contém apenas o template facial numérico e os metadados de retenção. Ele nunca contém a imagem do rosto, o vídeo de prova de vida, os dados do documento, os campos de identidade extraídos, a decisão nem o id da sessão excluída.
- Ele participa da detecção de duplicatas, da Busca facial, da autenticação biométrica e das suas listas de rostos exatamente como o rosto de uma sessão ativa. As correspondências são informadas com `source: "retained_template"`, o `vendor_user_id` e o `vendor_data` do User e um `biometric_template_id`.
- Ele é um dado biométrico com um `expires_at` definido. Ele é eliminado quando o User é excluído, quando qualquer sessão desse User é excluída com `deletion_instruction: "privacy_erasure"`, quando expira ou quando você o elimina em **Lists → Templates biométricos** ou pela [API de templates biométricos](https://docs.didit.me/pt-br/management-api/biometric-templates/overview.md).
- Uma sessão criada sem `vendor_data` não tem um User ao qual vincular um template; ao excluí-la, é retornado `ineligible_no_vendor_user` e o embedding é excluído junto com a sessão.
- Templates retidos nunca entram na lista de bloqueio. Uma entrada da lista de bloqueio facial criada a partir da sessão excluída mantém sua própria entrada biométrica e seu próprio ciclo de vida, de forma independente.Os templates vinculados a um User aparecem no perfil do User em **Templates biométricos**, com uma ação para eliminá-los.## Resumo do ciclo de vida dos rostos```mermaid theme={null}
stateDiagram-v2
    [*] --> Enrolled: Face captured during liveness
    Enrolled --> Approved: Session approved
    Enrolled --> Declined: Session declined
    Declined --> Blocklisted: Auto-blocklist enabled
    Enrolled --> Duplicated: 1:N search finds match
    Duplicated --> Approved: Allowed by workflow
    Duplicated --> Declined: Rejected by workflow
    Blocklisted --> [*]: Manually removed
    Approved --> [*]: Session deleted (default)
    Approved --> RetainedTemplate: Session deleted with retention enabled
    RetainedTemplate --> [*]: Expiry, User deletion, privacy erasure, or purge
```## Enviar um rosto pelo consoleOperadores de conformidade podem enviar rostos manualmente:1) Acesse *Users → \[user] → Actions → Upload face*.
2) Selecione uma imagem; a Didit extrai o maior rosto e armazena um novo registro de Face vinculado ao usuário.
3) O rosto é cadastrado para evidência de perfil, detecção de duplicatas e busca facial. Use a área Blocklist quando o objetivo for recusar futuras sessões com correspondência.Isso é útil quando:- Você tem uma foto de referência de um cliente verificado por um canal offline.
- Você quer pré-carregar uma lista de bloqueio com fraudadores conhecidos do seu banco de dados de fraudes.## Privacidade e retenção- Embeddings faciais são vetores numéricos, não imagens. As imagens em si ficam em armazenamento de objetos criptografado, com acesso por URL assinada. Um embedding facial é um dado biométrico.
- A retenção segue a política de [retenção de dados](https://docs.didit.me/pt-br/console/data-retention.md) da sua aplicação. Os templates biométricos retidos seguem o período de [retenção de templates biométricos](https://docs.didit.me/pt-br/console/data-retention.md#retenção-de-template-biométrico), que é mais rigoroso e finito.
- Excluir uma sessão exclui a imagem e, por padrão, o embedding. Se a sua aplicação tiver optado pela retenção de templates biométricos, excluir uma sessão mantém um template sem imagem até que ele expire ou seja eliminado.
- Para uma solicitação de exclusão nos termos do direito ao esquecimento da GDPR / CCPA, exclua as sessões da pessoa com `deletion_instruction: "privacy_erasure"` ou exclua o User: as duas opções também eliminam todos os templates retidos. As entradas da lista de bloqueio facial que você gerencia permanecem até que você as remova.## Próximos passos> [card] [Busca facial](https://docs.didit.me/pt-br/core-technology/face-search/overview.md)
>
> Como funciona a busca facial 1:N.> [card] [Prova de vida](https://docs.didit.me/pt-br/core-technology/liveness/overview.md)
>
> Detecção de prova de vida com captura facial.> [card] [API de lista de bloqueio](https://docs.didit.me/pt-br/management-api/lists/upload-face.md)
>
> Envie um rosto para uma lista de bloqueio.> [card] [Templates biométricos](https://docs.didit.me/pt-br/management-api/biometric-templates/overview.md)
>
> Templates retidos após a exclusão da sessão.> [card] [Lista de bloqueio de usuários](https://docs.didit.me/pt-br/entities/users/blocklist.md)
>
> Como funciona incluir um usuário na lista de bloqueio.


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