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

# Pesquisa facial e lista de bloqueio de utilizadores

> A Didit associa biometria facial a entidades User de fornecedores: pesquisa 1:N, deteção de duplicados, lista de bloqueio 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) 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>



      
      

Colar em

A biometria facial é essencial para cada entidade User. A Didit captura um rosto durante a [prova de vida](https://docs.didit.me/pt/core-technology/liveness/overview.md), gera um embedding vetorial e armazena-o para quatro funcionalidades subsequentes: **pesquisa facial 1:N**, **deteção de duplicados**, **aplicação da lista de bloqueio** e **reautenticação biométrica**.> [!NOTE]
>
> Os rostos armazenados servem também de referência para a [Autenticação biométrica](https://docs.didit.me/pt/core-technology/biometric-auth/overview.md): crie uma sessão de autenticação biométrica com o `vendor_data` do utilizador e omita `portrait_image`, e a Didit reutiliza automaticamente o rosto armazenado (primeiro o rosto da prova de vida aprovado, depois a fotografia do chip do ePassport, depois o retrato do documento de identidade e, por último, um rosto de perfil inscrito manualmente).## Como os rostos ficam associados a um utilizador**1. Capturado durante a prova de vida**Quando um utilizador passa por uma sessão com a prova de vida ativada, a Didit captura uma selfie, executa a deteção passiva de prova de vida, extrai o rosto de maior dimensão e gera um embedding vetorial para pesquisa.**2. Armazenado no perfil do utilizador**O rosto fica associado à sessão e à entidade User principal. O URL do retrato surge no perfil do utilizador como `portrait_image`.**3. Indexado para pesquisa**O embedding é adicionado ao índice de pesquisa. As sessões seguintes podem executar pesquisas 1:N neste índice.## Pesquisa facial (1:N)A pesquisa facial permite encontrar um utilizador carregando uma imagem e comparando-a com todos os rostos inscritos na sua aplicação.Casos de utilização:- **Deteção de duplicados** no onboarding: impedir que a mesma pessoa crie duas contas.
- **Pesquisa inversa**: identificar o utilizador por detrás de uma imagem de CCTV ou de uma imagem numa investigação de fraude.
- **Reconhecimento de cliente recorrente**: dispensar o KYC para um cliente que regressa.A pesquisa facial é executada automaticamente durante as novas sessões quando o seu fluxo tem a deteção de duplicados ativada. Também está exposta como API autónoma:- `POST /v3/face-search/`: [pesquisa facial autónoma](https://docs.didit.me/pt/standalone-apis/face-search.md)## Deteção de duplicadosCada novo rosto pode ser comparado com os rostos inscritos existentes para identificar duplicados. A Didit atribui a cada rosto um `approved_duplicate_status`:| Estado | Significado |
| - | - |
| `NOT_DUPLICATED` | Não foram encontradas correspondências acima do limiar de semelhança |
| `DUPLICATED` | O rosto corresponde a um ou mais rostos de uma sessão já aprovada |Os fluxos de verificação podem ser configurados para:- **Recusar** automaticamente as sessões marcadas como duplicadas.
- **Sinalizar para revisão**: encaminhar para um analista humano.
- **Apenas aviso**: permitir a sessão, mas adicionar uma etiqueta de risco.Configure isto na consola em *Workflows → \[o seu fluxo] → Face Match / Liveness → Duplicate detection*.## Lista de bloqueio facialRecusar uma sessão não adiciona o rosto a nenhuma lista de bloqueio. Para rejeitar futuras sessões com o mesmo rosto, bloqueie-o você mesmo: adicione-o a partir da [página da lista de bloqueio](https://docs.didit.me/pt/console/blocklist-users.md) ou com a [API de listas](https://docs.didit.me/pt/management-api/lists/overview.md). Uma nova sessão cuja selfie de prova de vida corresponda a essa entrada é recusada automaticamente.## Carregar um rosto importado para o perfil de um utilizadorSe estiver a migrar de outro fornecedor de KYC, pode criar primeiro o utilizador e depois associar a esse perfil uma imagem de rosto fidedigna. O utilizador continua identificado pelo seu `vendor_data`, mas o endpoint de carregamento de rostos usa o ID interno do utilizador na Didit (`didit_internal_id`), para que o alvo seja inequívoco.**1. Criar ou obter o utilizador**Chame [`POST /v3/users/create/`](https://docs.didit.me/pt/management-api/users/create) com o seu `vendor_data` estável, ou chame `GET /v3/users/{vendor_data}/` se o utilizador já existir.**2. Ler o didit\_internal\_id**A resposta do utilizador inclui `didit_internal_id`. Continue a usar o `vendor_data` no seu próprio sistema; use o `didit_internal_id` apenas nos endpoints de associação ao perfil.**3. Carregar 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/management-api/users/upload-face) com uma imagem de rosto 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 inscritos no mesmo índice facial usado para a deteção de duplicados e a pesquisa facial. Não são colocados automaticamente numa lista de bloqueio. Para bloquear um agente mal-intencionado conhecido, carregue o rosto para uma lista de rostos.> [!WARNING]
>
> Carregue apenas rostos que tem autorização para tratar ao abrigo do seu próprio aviso de privacidade e do seu acordo de migração. Mantenha os identificadores do fornecedor de origem em `metadata` ou `comment` apenas quando for seguro expô-los aos seus responsáveis de conformidade.### Como o bloqueio acontece| Acionador | Ação |
| - | - |
| Sessão `DECLINED` | Nada é adicionado a uma lista de bloqueio; o utilizador mantém-se `ACTIVE` |
| O analista bloqueia manualmente um rosto na consola | O rosto é adicionado e o estado do utilizador é atualizado de acordo com a política |
| Adição programática através da API de listas | Carregar a imagem do rosto para uma lista de bloqueio do tipo facial |### Carregar um rosto para a lista de bloqueioPara bloquear um utilizador por rosto de forma programática, carregue a imagem do rosto para uma lista de bloqueio do tipo facial através do endpoint dedicado [Carregar rosto para a lista](https://docs.didit.me/pt/management-api/lists/upload-face.md). A Didit extrai o embedding biométrico e insere-o no índice de correspondência: qualquer sessão futura cuja selfie de prova de vida corresponda é recusada automaticamente.> [!NOTE]
>
> O carregamento de um rosto de perfil e o carregamento de um rosto para a lista de bloqueio são operações diferentes. Use o carregamento de perfil para associar um rosto importado de confiança a um utilizador, para fins de evidência, deteção de duplicados e pesquisa facial. Use a [API de listas](https://docs.didit.me/pt/management-api/lists/overview.md) para bloquear um rosto, para que as sessões futuras em que haja correspondência sejam rejeitadas.### Remover um rosto da lista de bloqueioRemova a entrada na consola em *Blocklist → Faces → row actions → Remove*, ou use o endpoint [Eliminar entrada](https://docs.didit.me/pt/management-api/lists/delete-entry.md).## Templates biométricos conservados após a eliminação da sessãoAo eliminar uma sessão, elimina-se a imagem do rosto e, por predefinição, o embedding facial, pelo que a pessoa deixa de ser considerada na deteção de duplicados e na Pesquisa facial. Se eliminar sessões logo após a aprovação, mas ainda precisar de detetar novos registos da mesma pessoa, ative a [conservação de templates biométricos](https://docs.didit.me/pt/console/data-retention.md#retenção-de-modelo-biométrico) na aplicação ou envie `retain_face_embeddings: true` no pedido de eliminação.A Didit elimina a sessão e todos os seus dados, como habitualmente, e mantém um template biométrico facial separado, gerido à parte, sem imagem, associado ao utilizador:- Contém apenas o template facial numérico e os metadados de conservação. 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 eliminada.
- Participa na deteção de duplicados, na Pesquisa facial, na autenticação biométrica e nas suas listas faciais exatamente como um rosto de uma sessão ativa. Os resultados são reportados com `source: "retained_template"`, o `vendor_user_id` e o `vendor_data` do utilizador, e um `biometric_template_id`.
- É um dado biométrico com um `expires_at` finito. É eliminado quando o utilizador é eliminado, quando qualquer sessão desse utilizador é eliminada com `deletion_instruction: "privacy_erasure"`, quando expira, ou quando o purga em **Lists → Templates biométricos** ou através da [API de Templates biométricos](https://docs.didit.me/pt/management-api/biometric-templates/overview.md).
- Uma sessão criada sem `vendor_data` não tem um utilizador ao qual associar um template; ao eliminá-la, é reportado `ineligible_no_vendor_user` e o embedding é eliminado juntamente com a sessão.
- Os templates conservados nunca são incluídos na lista de bloqueio. Uma entrada na lista de bloqueio criada a partir da sessão eliminada mantém a sua própria entrada biométrica independente e o seu próprio ciclo de vida.Os templates associados a um utilizador aparecem no perfil do utilizador, em **Templates biométricos**, com uma ação de purga.## Resumo do ciclo de vida facial```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
```## Carregar um rosto a partir da consolaOs operadores de conformidade podem carregar rostos manualmente:1) Aceda a *Users → \[user] → Actions → Upload face*.
2) Selecione uma imagem; a Didit extrai o maior rosto e guarda um novo registo de Face associado ao utilizador.
3) O rosto fica registado para as provas do perfil, a deteção de duplicados e a pesquisa facial. Use a área de Blocklist quando o objetivo for rejeitar futuras sessões que correspondam.Isto é útil quando:- Tem uma fotografia conhecida de um cliente verificado por um canal offline.
- Pretende carregar previamente uma lista de bloqueio com autores de fraude conhecidos da sua base de dados de fraude.## Privacidade e conservação- Os embeddings faciais são vetores numéricos, não imagens. As próprias imagens são guardadas em armazenamento de objetos cifrado, com acesso por URL assinado. Um embedding facial é um dado biométrico.
- A conservação segue a política de [conservação de dados](https://docs.didit.me/pt/console/data-retention.md) da sua aplicação. Os templates biométricos conservados seguem o período de [conservação de templates biométricos](https://docs.didit.me/pt/console/data-retention.md#retenção-de-modelo-biométrico), mais restrito e finito.
- Ao eliminar uma sessão, elimina-se a imagem e, por predefinição, o embedding. Se a sua aplicação tiver ativado a conservação de templates biométricos, a eliminação de uma sessão mantém um template sem imagem até expirar ou ser purgado.
- Para um pedido de direito ao esquecimento ao abrigo do RGPD ou do CCPA, elimine as sessões da pessoa com `deletion_instruction: "privacy_erasure"` ou elimine o utilizador: em ambos os casos, todos os templates conservados são também purgados. As entradas da lista de bloqueio que gere mantêm-se até as remover.## Próximos passos> [card] [Pesquisa facial](https://docs.didit.me/pt/core-technology/face-search/overview.md)
>
> Como funciona a pesquisa facial 1:N.> [card] [Prova de vida](https://docs.didit.me/pt/core-technology/liveness/overview.md)
>
> A deteção de prova de vida que capta o rosto.> [card] [API de lista de bloqueio](https://docs.didit.me/pt/management-api/lists/upload-face.md)
>
> Carregue um rosto para uma lista de bloqueio.> [card] [Templates biométricos](https://docs.didit.me/pt/management-api/biometric-templates/overview.md)
>
> Templates conservados após a eliminação da sessão.> [card] [Lista de bloqueio de utilizadores](https://docs.didit.me/pt/entities/users/blocklist.md)
>
> Como funciona o bloqueio de um utilizador.


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