> ## 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 busca facial 1:N: detecção de duplicidade

> A busca facial da Didit encontra duplicidades e fraudadores em listas de bloqueio entre todos os usuários verificados. Grátis, em menos de 2 segundos.

A Busca facial da Didit é um recurso poderoso que permite procurar um rosto específico em todas as suas sessões de verificação de identidade aprovadas. Essa capacidade ajuda a identificar contas duplicadas, prevenir fraudes e reforçar as suas medidas de segurança.

Prompt de integração da Busca facial
        Copy prompt to clipboard



      
      

\<pre>

\````# Goal
Integrate Didit Face Search (1:N — search a face across your enrolled users + blocklist) into your app.

\# Delivery mode
Face Search is a **standalone API**. It runs against the face index your application has enrolled through prior verifications (sessions with save_api_request=true or Passive Liveness with save_api_request=true), faces uploaded to User profiles, your face lists, and any image-free biometric templates the application retained after deleting sessions (opt-in, see /management-api/biometric-templates/overview). There is no separate Face Search workflow feature.

POST https://verification.didit.me/v3/face-search/
multipart/form-data — x-api-key: YOUR_API_KEY

Required: `user_image` (jpg/jpeg/png/tiff/webp, max 5 MB; PDFs not accepted). The image must contain at least one detectable face (largest bbox wins when multiple).

Optional: `search_type` = "most_similar" (default — dedupe / returning-user) | "blocklisted_or_approved" (blocklist screening).

curl example:
\```bash
curl -X POST 'https://verification.didit.me/v3/face-search/' \
-H 'x-api-key: YOUR_API_KEY' \
-F 'user_image=@./selfie.jpg' \
-F 'search_type=most_similar' \
-F 'save_api_request=true' \
-F 'vendor_data=user-123'
\```

\# Response shape (singular)
Unlike most features, Face Search returns a **singular** `face_search` object — not a plural array:
\{ request_id, face_search: { status, total_matches, matches: [{ session_id, session_number, similarity_percentage, source, vendor_data, vendor_user_id, biometric_template_id, verification_date, user_details, match_image_url, status, is_blocklisted, is_allowlisted, api_service }], user_image: {entities}, warnings: [...] } }

match.source is "session", "imported", "list_entry", or "retained_template". A retained_template hit comes from an image-free biometric template kept after the source session was deleted: session_id, session_number, status, api_service, match_image_url, and user_details are null; vendor_data and vendor_user_id identify the User; biometric_template_id is the template you can inspect or purge via /v3/biometric-templates/{id}/.

\`status` is "Declined" only when at least one blocklist match is found. Pure duplicate matches return "Approved" (informational) — apply your own dedupe policy in app logic.

\# Warnings
Face Search emits risk codes from the LogWarningChoices.FACEMATCH bucket plus blocklist/duplicate semantics:
FACE_IN_BLOCKLIST, POSSIBLE_FACE_IN_BLOCKLIST, DUPLICATED_FACE, POSSIBLE_DUPLICATED_FACE, MULTIPLE_FACES_DETECTED.
Full catalogue: /core-technology/face-search/warnings-face-search.

\# Failure modes to handle
\- HTTP 400 — no face detected in user_image. Ask the user to retake.
\- HTTP 403 — out of credits.
\- status="Declined" with FACE_IN_BLOCKLIST — definitive blocklist hit; reject.
\- POSSIBLE_FACE_IN_BLOCKLIST — borderline match below the hard threshold; route to manual review.
\- DUPLICATED_FACE — user already verified under a different vendor_data; merge or block according to policy.

\# See also
\- Canonical schema: /reference/data-models#face-search
\- Per-feature report: /core-technology/face-search/report-face-search
\- Risk catalogue: /core-technology/face-search/warnings-face-search
\- Full integration playbook: /integration/integration-prompt````

\</pre>



      
      

Paste into

A aula da Academy sobre como ler o resultado de uma verificação chega à busca facial e às listas de bloqueio em 6:53.[Busca facial e listas de bloqueio — Didit Academy](https://www.youtube.com/embed/7htTWCWsl60?start=413\&rel=0\&playsinline=1)![Fluxo de busca facial 1:N da Didit integrado à prova de vida para detectar duplicidades e rostos em listas de bloqueio](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/face-search-liveness.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=0cb5738f8ceaae7891cf13631485c400)## Integração automática da Busca facial> A Busca facial é executada automaticamente durante as verificações de prova de vida nas sessões de verificação, para detectar usuários duplicados e conferir rostos em listas de bloqueio.### Detecção automática de duplicidadeQuando um usuário conclui uma verificação de prova de vida durante a verificação de identidade:- A biometria facial dele é comparada automaticamente com a de todos os usuários verificados anteriormente
- O sistema identifica possíveis contas duplicadas com base na similaridade facial
- As correspondências são sinalizadas de acordo com os limites de similaridade que você configurou
- Você pode revisar e agir sobre possíveis usuários duplicados### Integração com a lista de bloqueioA Busca facial se integra de forma transparente com o [recurso de lista de bloqueio](https://docs.didit.me/management-api/lists/overview.md):- Durante a verificação, os rostos são conferidos automaticamente com a sua lista de bloqueio
- Se for encontrada uma correspondência com um rosto da lista de bloqueio, a verificação é recusada automaticamente
- Isso impede que usuários problemáticos já identificados criem novas contas
- Ajuda a manter a integridade do seu processo de verificação### A selfie tirada durante a captura do documentoEnquanto o usuário fotografa o documento, a câmera frontal tira uma selfie dele (Silent Capture). Toda vez que o documento é avaliado, essa selfie passa pela mesma busca 1:N que a selfie da prova de vida:- Ela é comparada com a sua lista de bloqueio de rostos e com os usuários já aprovados na sua aplicação, com os mesmos limites de similaridade e a mesma precedência da busca da prova de vida.
- Uma correspondência na lista de bloqueio gera `FRONT_CAMERA_FACE_IN_BLOCKLIST` (sempre Recusada) ou `POSSIBLE_FRONT_CAMERA_FACE_IN_BLOCKLIST` (sempre Em revisão). Uma correspondência com um usuário aprovado gera `FRONT_CAMERA_DUPLICATED_FACE` ou `POSSIBLE_FRONT_CAMERA_DUPLICATED_FACE`, mais `FRONT_CAMERA_DUPLICATED_FACE_NAME_MISMATCH` quando esse usuário aprovado foi verificado com outro nome, e `FRONT_CAMERA_DUPLICATED_FACE_DOCUMENT_MISMATCH` quando o documento de identidade desse usuário mostra outra data de nascimento. Veja os [avisos da verificação de identidade](https://docs.didit.me/core-technology/id-verification/warnings-id-verification.md).
- As correspondências aparecem nos detalhes da sessão, no card de verificação de identidade, e são retornadas em `id_verifications[].document_selfie_face_matches` da [decisão da sessão](https://docs.didit.me/sessions-api/retrieve-session.md). O formato das entradas é o mesmo de `liveness_checks[].matches`. O campo é `null` em sessões antigas ou quando a busca não foi executada, e um array vazio quando ela foi executada e não encontrou nada. `match_image_url` é uma URL pré-assinada que expira.
- Só o maior rosto da selfie é usado, e apenas quando o detector tem confiança de que é um rosto. Uma selfie por documento é pesquisada: a do lado da frente, ou a do verso quando a selfie da frente não contém um rosto nítido.
- A selfie é apenas comparada. Seu template biométrico nunca é armazenado, então sessões futuras nunca são comparadas com ela. Para banir uma pessoa a partir da selfie de uma sessão, adicione-a à sua lista de bloqueio de rostos pela página da sessão.A busca tem seu próprio interruptor e suas próprias ações na etapa de **Verificação de identidade**, na aba **Regras** da etapa (**Busca facial com captura silenciosa**), ou com `document_selfie_face_search_enabled` e as ações `document_selfie_duplicated_face_*` na [configuração de recursos do fluxo](https://docs.didit.me/management-api/workflows/feature-configs.md#ocr-/-id-verification). Ela vem ativada por padrão; a ação de rosto duplicado vem como Aprovar por padrão (o aviso continua sendo informado) e as verificações cruzadas de nome e de documento vêm como Em revisão, como suas equivalentes da prova de vida. A busca precisa da selfie, então só é executada quando a Silent Capture está ativada. Desativar a Busca facial na etapa de Prova de vida também desativa esta busca: essa desativação é uma escolha sobre o rosto da pessoa, então vale para todas as selfies da sessão.### A regra de divergência de documentoA regra de **divergência de documento** (`DUPLICATED_FACE_DOCUMENT_MISMATCH` para a selfie da prova de vida, `FRONT_CAMERA_DUPLICATED_FACE_DOCUMENT_MISMATCH` para a Silent Capture) só sinaliza um rosto duplicado quando o documento de identidade do usuário correspondente mostra uma data de nascimento diferente.
A mesma pessoa apresentando outro documento, por exemplo um passaporte depois de uma carteira de identidade, não é sinalizada.
Um documento renovado também não é sinalizado.
Duas sessões que compartilham o mesmo número de documento do mesmo país nunca são sinalizadas.### Desativando a Busca facial automáticaA Busca facial automática vem ativada por padrão em toda etapa de Prova de vida. Se a sua postura de privacidade exigir, você pode desativá-la por fluxo, na aba **Regras** da etapa de **Prova de vida** no Business Console (Modo Simples e Modo Avançado), ou com `face_search_enabled: false` no nó `LIVENESS` ou `AGE_ESTIMATION` da [configuração de recursos do fluxo](https://docs.didit.me/management-api/workflows/feature-configs.md#liveness).Com o interruptor desligado, a selfie da prova de vida ainda recebe a pontuação de prova de vida e é comparada 1:1 com o retrato do documento na Correspondência facial, mas nunca chega ao índice de rostos:- Nenhuma busca é executada, então a sessão não recebe veredito de duplicidade, lista de bloqueio ou lista de permissão, e seu `liveness_checks[].matches` permanece vazio. As regras de **Rosto duplicado**, **divergência de nome**, **divergência de documento** e de rosto entre organizações não têm sobre o que agir e ficam ocultas no Console.
- Nenhum template biométrico é armazenado para a selfie, então sessões futuras não podem ser comparadas com esta e não há nada para a [retenção de templates biométricos](https://docs.didit.me/pt-br/console/data-retention.md#retenção-de-template-biométrico) manter depois que a sessão for excluída.
- A selfie não é usada para resolver uma pessoa biométrica compartilhada em verificações entre organizações.
- A selfie tirada durante a captura do documento também não é pesquisada (sem risco `FRONT_CAMERA_*` de lista de bloqueio ou duplicidade): a desativação cobre todas as selfies da sessão. O interruptor próprio da etapa de Verificação de identidade (veja acima) também pode desativar essa busca isoladamente.**A qual etapa o interruptor pertence.** O interruptor fica na etapa que captura a selfie, então uma etapa de **Prova de vida** ou de **Estimativa de idade** responde por si mesma. Uma etapa de **Correspondência facial** não tem um próprio: quando um usuário refaz a selfie ali - depois que você pede o reenvio dessa etapa, por exemplo - a nova captura segue a configuração da etapa de Prova de vida, então uma desativação mantém a nova selfie fora do índice também. Se o seu fluxo se ramifica em mais de uma etapa de Prova de vida, vale a configuração do ramo pelo qual a sessão realmente passou, e a leitura de rosto entre organizações segue essa mesma etapa.Os fluxos existentes mantêm o comportamento atual até que você desative. A mudança se aplica às sessões iniciadas depois que o fluxo é salvo; os templates armazenados por sessões anteriores permanecem no índice até que essas sessões sejam excluídas ou purgadas. O interruptor não afeta a [API de Busca facial](https://docs.didit.me/standalone-apis/face-search.md) independente, que você chama explicitamente.> [!WARNING]
>
> A sua lista de bloqueio de rostos é aplicada durante a verificação pela mesma busca 1:N. Com a Busca facial desativada na etapa de Prova de vida, uma pessoa da lista de bloqueio não é detectada nessa etapa nem pela selfie tirada durante a captura do documento; com a Busca facial com captura silenciosa desativada na etapa de Verificação de identidade, não é detectada por essa selfie.### Acesso pela APIA funcionalidade de Busca facial também está disponível pela nossa [API](https://docs.didit.me/standalone-apis/face-search.md), permitindo que você:- Envie buscas faciais de forma programática
- Integre capacidades de correspondência facial às suas próprias aplicações
- Construa fluxos personalizados de detecção de fraude
- Crie sistemas automatizados de detecção de duplicidade## Principais recursos- **Alta precisão**: algoritmos biométricos avançados fornecem resultados de correspondência confiáveis
- **Limites configuráveis**: personalize a sensibilidade da correspondência de acordo com a sua tolerância a risco
- **Varredura abrangente**: pesquise em todos os seus usuários verificados
- **Resultados rápidos**: processe buscas com agilidade mesmo em bases de usuários grandes
- **Foco em privacidade**: a correspondência usa templates faciais numéricos restritos à sua aplicação; o índice nunca sai do seu tenant### Limites configuráveisVocê pode personalizar a sensibilidade da busca definindo limites diferentes para as pontuações de similaridade:> [!NOTE]
>
> Esses limites podem ser ajustados de acordo com a sua tolerância a risco e os seus requisitos de segurança.## Como funciona**1. Extração do rosto**Quando uma busca é iniciada, o sistema processa a imagem de referência:| Processo | Descrição |
| - | - |
| **Extração de características** | Isola as características faciais da imagem de referência |
| **Normalização** | Padroniza os dados faciais para uma comparação consistente |
| **Validação de qualidade** | Verifica a qualidade da imagem e a nitidez do rosto |
| **Codificação vetorial** | Cria uma representação vetorial matemática do rosto |**2. Algoritmo de comparação**O sistema pesquisa em toda a sua base de sessões verificadas:- Compara o vetor facial de referência com **todos os rostos cadastrados na sua aplicação**: rostos de sessões, rostos enviados aos perfis de Usuários, suas listas de rostos e quaisquer templates biométricos retidos
- Emprega uma arquitetura de rede neural avançada, otimizada para velocidade e precisão
- Oferece suporte a dois modos de busca: **mais similares** (lista ordenada) e **bloqueados ou aprovados** (filtrada por status)
- Processa bases grandes com rapidez usando indexação otimizada**3. Pontuação de similaridade**Para cada comparação, é gerado um percentual de similaridade:| Faixa de pontuação | Interpretação |
| :-: | - |
| **90%+** | Correspondência forte - muito provavelmente a mesma pessoa |
| **70–89%** | Correspondência possível - pode exigir revisão manual |
| **Abaixo de 70%** | Provavelmente pessoas diferentes |Os limites de correspondência que você configurou determinam quais resultados são sinalizados.**4. Entrega dos resultados**O sistema retorna um conjunto de resultados completo:- **Lista ordenada** de possíveis correspondências por pontuação de similaridade
- **Detalhes da correspondência**, incluindo ID da sessão, data da verificação e vendor data
- **Percentual de similaridade** de cada correspondência
- **Imagens das correspondências** disponíveis para revisão visual
- **Status na lista de bloqueio** indicando se o rosto correspondente está na lista de bloqueio## Sessões excluídas e templates biométricos retidosExcluir uma sessão exclui, por padrão, o embedding facial dela, de modo que a pessoa sai do índice e pode se verificar novamente sem uma sinalização de duplicidade. Aplicações que excluem sessões logo após a aprovação, mas ainda precisam detectar cadastros repetidos, podem ativar a [retenção de templates biométricos](https://docs.didit.me/pt-br/console/data-retention.md#retenção-de-template-biométrico). A Didit então mantém um template biométrico sem imagem, vinculado ao Usuário, depois que a sessão é excluída, e esse template participa da Busca facial e da detecção automática de duplicidade exatamente como o rosto de uma sessão ativa.Uma correspondência com um template retido é informada com `source: "retained_template"`, o `vendor_user_id` e o `vendor_data` do Usuário dono do template e um `biometric_template_id`. Ela não traz ID de sessão, imagem da correspondência, dados de identidade nem status de sessão, porque a sessão que gerou o rosto não existe mais. Templates retidos nunca entram na lista de bloqueio; as entradas da lista de bloqueio de rostos mantêm sua própria entrada biométrica independente.O template permanece até a data de expiração programada, a exclusão do Usuário, uma solicitação de eliminação por privacidade ou uma purga explícita pela [API de Templates biométricos](https://docs.didit.me/management-api/biometric-templates/overview.md) ou por **Listas → Templates biométricos** no Console.## Percentual de similaridadeO percentual de similaridade é a métrica central usada para determinar possíveis correspondências:- **Percentual alto (normalmente 90% ou mais)**: indica uma forte probabilidade de que os rostos pertençam à mesma pessoa.
- **Percentual médio (70-89%)**: sugere possíveis correspondências que podem exigir mais revisão.
- **Percentual baixo (abaixo de 70%)**: provavelmente indica pessoas diferentes.O limite exato do que constitui uma "correspondência" pode ser configurado de acordo com os seus requisitos de segurança. Aumentar o limite reduz os falsos positivos, mas pode aumentar os falsos negativos.## Casos de uso- **Prevenção a fraudes**: identifique usuários que tentam criar várias contas
- **KYC reforçado**: adicione uma camada extra de verificação ao seu processo de KYC
- **Conformidade regulatória**: atenda aos requisitos de detecção de contas duplicadas
- **Controle de acesso**: verifique a autenticidade do usuário em áreas de alta segurança
- **Aplicação da lei**: auxilie órgãos autorizados na identificação de pessoas de interesse


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