> ## 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 1:N: API de deteção de duplicados

> Detete duplicados e fraudadores na lista de bloqueio com a Didit. Grátis com a verificação de identidade e resposta sub-2 segundos.

A pesquisa facial é uma funcionalidade poderosa que permite pesquisar um rosto específico em todas as suas sessões de verificação de identidade aprovadas. Esta capacidade ajuda a identificar contas duplicadas, prevenir a fraude e reforçar as suas medidas de segurança.

Prompt de integração da pesquisa facial
        Copiar o prompt para a área de transferência



      
      

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



      
      

Colar em

A aula da Didit Academy sobre a leitura de um resultado de verificação aborda a pesquisa facial e as listas de bloqueio aos 6:53.[Pesquisa facial e listas de bloqueio — Didit Academy](https://www.youtube.com/embed/7htTWCWsl60?start=413\&rel=0\&playsinline=1)![Fluxo 1:N de pesquisa facial da Didit integrado com prova de vida para deteção de duplicados e de correspondências com 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 de Pesquisa facial> A Pesquisa facial é realizada automaticamente durante as verificações de prova de vida em sessões de verificação para detetar utilizadores duplicados e verificar contra rostos na lista de bloqueio.### Deteção automática de duplicadosQuando um utilizador conclui uma verificação de prova de vida durante a verificação de identidade:- A sua biometria facial é comparada automaticamente com a de todos os utilizadores previamente verificados
- O sistema identifica potenciais contas duplicadas com base na semelhança facial
- As correspondências são sinalizadas de acordo com os limiares de semelhança configurados
- Pode rever e tomar medidas em relação a potenciais utilizadores duplicados### Integração com a lista de bloqueioA Pesquisa facial integra-se perfeitamente com a [funcionalidade de lista de bloqueio](https://docs.didit.me/pt/management-api/lists/overview.md):- Durante a verificação, os rostos são verificados automaticamente contra a sua lista de bloqueio
- Se for encontrada uma correspondência com um rosto na lista de bloqueio, a verificação é recusada automaticamente
- Isto impede que utilizadores problemáticos identificados anteriormente criem novas contas
- Ajuda a manter a integridade do seu processo de verificação### A selfie tirada durante a captura do documentoEnquanto o utilizador fotografa o seu documento, a câmara frontal tira uma selfie dele (Captura Silenciosa). Cada vez que o documento é avaliado, essa selfie passa pela mesma pesquisa 1:N que a selfie da prova de vida:- É comparada com a sua lista de bloqueio de rostos e com os utilizadores já aprovados na sua aplicação, com os mesmos limiares de semelhança e a mesma precedência da pesquisa de 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 análise). Uma correspondência com um utilizador aprovado gera `FRONT_CAMERA_DUPLICATED_FACE` ou `POSSIBLE_FRONT_CAMERA_DUPLICATED_FACE`, além de `FRONT_CAMERA_DUPLICATED_FACE_NAME_MISMATCH` quando esse utilizador aprovado foi verificado com um nome diferente, e `FRONT_CAMERA_DUPLICATED_FACE_DOCUMENT_MISMATCH` quando o documento de identidade desse utilizador apresenta uma data de nascimento diferente. Consulte os [avisos de verificação de identidade](https://docs.didit.me/pt/core-technology/id-verification/warnings-id-verification.md).
- As correspondências são listadas nos detalhes da sessão, no cartão de verificação de identidade, e devolvidas em `id_verifications[].document_selfie_face_matches` da [decisão da sessão](https://docs.didit.me/pt/sessions-api/retrieve-session.md). Utiliza o mesmo formato de entrada que `liveness_checks[].matches`. O campo fica como `null` para sessões mais antigas ou quando a pesquisa não foi executada, e um array vazio quando foi executada e não encontrou nada. `match_image_url` é um URL pré-assinado que expira.
- Apenas o maior rosto na selfie é utilizado, e apenas quando o detetor tem confiança de que se trata de um rosto. É pesquisada uma selfie por documento: a da frente, ou a do verso quando a selfie da frente não contém um rosto nítido.
- A selfie é apenas comparada. O seu template biométrico nunca é armazenado, pelo que sessões posteriores nunca serão comparadas com ela. Para banir uma pessoa com base na selfie de uma sessão, adicione-a à sua lista de bloqueio de rostos a partir da página da sessão.A pesquisa tem o seu próprio comutador e as suas próprias ações no passo **Verificação de identidade**, no separador **Regras** do passo (**Pesquisa facial com captura silenciosa**), ou com `document_selfie_face_search_enabled` e as ações `document_selfie_duplicated_face_*` na [configuração de funcionalidades do fluxo](https://docs.didit.me/pt/management-api/workflows/feature-configs.md#ocr-/-verificação-de-identidade). Está ativada por predefinição; a ação para rosto duplicado tem como predefinição Aprovar (o aviso continua a ser comunicado) e as verificações cruzadas do nome e do documento têm como predefinição Em análise, tal como as suas contrapartes da prova de vida. A pesquisa necessita da selfie, pelo que apenas é executada quando a Captura Silenciosa está ativada. Desativar a Pesquisa facial no passo de Prova de vida desativa também esta pesquisa: essa opção de exclusão diz respeito ao rosto da pessoa, abrangendo todas as selfies da sessão.### A regra de discrepância de documentoA regra de **discrepância de documento** (`DUPLICATED_FACE_DOCUMENT_MISMATCH` para a selfie de prova de vida, `FRONT_CAMERA_DUPLICATED_FACE_DOCUMENT_MISMATCH` para a Captura Silenciosa) sinaliza um rosto duplicado apenas quando o documento de identidade do utilizador correspondente apresenta uma data de nascimento diferente.
A mesma pessoa a apresentar um documento diferente, por exemplo um passaporte depois de um cartão de cidadão, não é sinalizada.
Um documento renovado também não é sinalizado.
Duas sessões que partilhem o mesmo número de documento do mesmo país nunca são sinalizadas.### Desativar a Pesquisa facial automáticaA Pesquisa facial automática está ativada por predefinição para cada passo de Prova de vida. Se a sua postura de privacidade o exigir, pode desativá-la por fluxo a partir do separador **Regras** do passo **Prova de vida** na Business Console (Modo Simples e Avançado), ou com `face_search_enabled: false` no nó `LIVENESS` ou `AGE_ESTIMATION` na [configuração de funcionalidades do fluxo](https://docs.didit.me/pt/management-api/workflows/feature-configs.md#prova-de-vida).Com o comutador desativado, a selfie de prova de vida continua a ser pontuada quanto à prova de vida e comparada 1:1 com o retrato do documento em Correspondência facial, mas nunca chega ao índice de rostos:- Nenhuma pesquisa é executada, pelo que a sessão não obtém qualquer veredito relativo a duplicados, à lista de bloqueio ou à lista de permissões e o seu `liveness_checks[].matches` permanece vazio. As regras de **Rosto duplicado**, **discrepância de nome**, **discrepância de documento** e de rostos entre organizações não têm nada sobre que atuar e ficam ocultas na Consola.
- Nenhum template biométrico é armazenado para a selfie, pelo que sessões posteriores não podem ser comparadas com esta e não há nada para a [conservação de templates biométricos](https://docs.didit.me/pt/console/data-retention.md#retenção-de-modelo-biométrico) manter após a eliminação da sessão.
- A selfie não é utilizada para resolver uma pessoa biométrica partilhada para verificações entre organizações.
- A selfie tirada durante a captura do documento também não é pesquisada (sem risco de lista de bloqueio ou de duplicado `FRONT_CAMERA_*`): a opção de exclusão abrange todas as selfies da sessão. O próprio comutador do passo de Verificação de identidade (ver acima) também pode desativar essa pesquisa de forma independente.**A que passo pertence o comutador.** O comutador situa-se no passo que captura a selfie, pelo que um passo de **Prova de vida** ou de **Estimativa de idade** aplica a definição a si próprio. Um passo de **Correspondência facial** não tem um comutador próprio: quando um utilizador repete a selfie aí - depois de lhe pedir para voltar a submeter esse passo, por exemplo -, a nova captura segue a definição do passo de Prova de vida, pelo que uma exclusão mantém a nova selfie também fora do índice. Se o seu fluxo se ramificar em mais do que um passo de Prova de vida, a definição que se aplica é a da ramificação pela qual a sessão realmente passou, e a leitura facial entre organizações segue esse mesmo passo.Os fluxos existentes mantêm o comportamento atual até que opte por desativá-lo. A alteração aplica-se às sessões iniciadas após guardar o fluxo; os modelos armazenados por sessões anteriores permanecem no índice até que essas sessões sejam eliminadas ou removidas definitivamente. A alteração não afeta a [API de pesquisa facial](https://docs.didit.me/pt/standalone-apis/face-search.md) autónoma, que chama explicitamente.> [!WARNING]
>
> A sua lista de bloqueio facial é aplicada durante a verificação através da mesma pesquisa 1:N. Com a Pesquisa facial desativada no passo de Prova de vida, uma pessoa que conste da lista de bloqueio não é detetada nem nesse passo nem pela selfie tirada durante a captura do documento; com a Pesquisa facial por Captura Silenciosa desativada no passo de Verificação de identidade, não é detetada por essa selfie.### Acesso à APIA funcionalidade de Pesquisa facial também está disponível através da nossa [API](https://docs.didit.me/pt/standalone-apis/face-search.md), permitindo-lhe:- Submeter pesquisas faciais programaticamente
- Integrar capacidades de correspondência facial nas suas próprias aplicações
- Desenvolver fluxos de deteção de fraude personalizados
- Criar sistemas automatizados para deteção de duplicados## Funcionalidades principais- **Elevada precisão**: Os algoritmos biométricos avançados fornecem resultados de correspondência fiáveis
- **Limiares configuráveis**: Personalize a sensibilidade da correspondência com base na sua tolerância ao risco
- **Análise abrangente**: Pesquise em todos os seus utilizadores verificados
- **Resultados rápidos**: Processe pesquisas rapidamente, mesmo com grandes bases de dados de utilizadores
- **Foco na privacidade**: A correspondência utiliza modelos faciais numéricos restritos à sua aplicação; o índice nunca sai do seu tenant### Limiares configuráveisPode personalizar a sensibilidade da pesquisa definindo diferentes limiares para as pontuações de similaridade:> [!NOTE]
>
> Estes limiares podem ser ajustados com base na sua tolerância ao risco e nos seus requisitos de segurança.## Como funciona**1. Extração facial**Quando uma pesquisa é 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** | Uniformiza os dados faciais para uma comparação consistente |
| **Validação de qualidade** | Verifica a qualidade da imagem e a nitidez facial |
| **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 dados de sessões verificadas:- Compara o vetor facial de referência com **cada rosto registado na sua aplicação**: rostos de sessões, rostos carregados para perfis de Utilizadores, as suas listas de rostos e quaisquer modelos biométricos retidos
- Utiliza uma arquitetura avançada de redes neuronais otimizada para velocidade e precisão
- Suporta dois modos de pesquisa: **mais semelhante** (lista ordenada) e **na lista de bloqueio ou aprovado** (filtrado por estado)
- Processa grandes bases de dados rapidamente utilizando indexação otimizada**3. Pontuação de similaridade**Para cada comparação, é gerada uma percentagem de similaridade:| Intervalo 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 indivíduos diferentes |Os limiares de correspondência configurados por si determinam quais os resultados sinalizados.**4. Entrega de resultados**O sistema devolve um conjunto abrangente de resultados:- **Lista ordenada** de potenciais correspondências ordenadas por pontuação de similaridade
- **Detalhes da correspondência**, incluindo o ID da sessão, a data de verificação e os dados do fornecedor
- **Percentagem de similaridade** para cada correspondência
- **Imagens da correspondência** disponíveis para revisão visual
- **Estado na lista de bloqueio** a indicar se o rosto correspondente está na lista de bloqueio## Sessões eliminadas e modelos biométricos retidosA eliminação de uma sessão elimina o respetivo embedding facial por predefinição, pelo que a pessoa sai do índice e pode verificar-se novamente sem um sinalizador de duplicado. As aplicações que eliminam sessões logo após a aprovação, mas que ainda precisam de detetar novas inscrições duplicadas, podem ativar a [retenção de modelos biométricos](https://docs.didit.me/pt/console/data-retention.md#retenção-de-modelo-biométrico). A Didit mantém então um modelo biométrico sem imagem associado ao Utilizador após a eliminação da sessão, e esse modelo participa na Pesquisa facial e na deteção automática de duplicados exatamente como o rosto de uma sessão ativa.Uma correspondência num modelo retido é comunicada com `source: "retained_template"`, o `vendor_user_id` e os `vendor_data` do Utilizador proprietário e um `biometric_template_id`. Não inclui ID de sessão, imagem de correspondência, dados de identidade nem estado da sessão, uma vez que a sessão que gerou o rosto já não existe. Os modelos retidos nunca são colocados na lista de bloqueio; as entradas da lista de bloqueio facial mantêm a sua própria entrada biométrica independente.O modelo permanece até à respetiva expiração programada, à eliminação do Utilizador, a um pedido de eliminação por privacidade ou a uma remoção definitiva explícita através da [Biometric Templates API](https://docs.didit.me/pt/management-api/biometric-templates/overview.md) ou em **Lists → Biometric templates** na Consola.## Percentagem de similaridadeA percentagem de similaridade é a métrica principal utilizada para determinar potenciais correspondências:- **Percentagem elevada (normalmente 90% ou superior)**: Indica uma forte probabilidade de os rostos pertencerem à mesma pessoa.
- **Percentagem média (70-89%)**: Sugere possíveis correspondências que podem exigir uma revisão adicional.
- **Percentagem baixa (inferior a 70%)**: Indica provavelmente indivíduos diferentes.O limiar exato para o que constitui uma «correspondência» pode ser configurado com base nos seus requisitos de segurança. Aumentar o limiar reduz os falsos positivos, mas pode aumentar os falsos negativos.## Casos de utilização- **Prevenção de Fraude**: Identifique utilizadores que tentam criar múltiplas contas
- **KYC avançado**: Adicione uma camada adicional de verificação ao seu processo de KYC
- **Conformidade regulamentar**: Cumpra os requisitos para a deteção de contas duplicadas
- **Controlo de acessos**: Verifique a autenticidade dos utilizadores para áreas de alta segurança
- **Aplicação da lei**: Ajude agências autorizadas a identificar pessoas de interesse


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