Busca Facial 1:N: Encontrando Todas as Contas de Uma Pessoa (PT-BR)

Um operador gerenciando quarenta contas em sua plataforma possui quarenta endereços de e-mail, provavelmente quarenta instrumentos de pagamento e, possivelmente, quarenta dispositivos. O que eles não têm são quarenta rostos.

Se qualquer parte do seu fluxo de acesso captura uma selfie, você já possui o único identificador que é genuinamente caro de multiplicar. A Busca Facial 1:N é a chamada que o utiliza — uma solicitação, um rosto, e retorna cada conta em seu próprio sistema que a mesma pessoa verificou.

É gratuito com a verificação de identidade Didit, retorna em menos de dois segundos e é executado automaticamente durante a prova de vida em uma sessão de verificação.

Principais pontos

• POST /v3/face-search/ busca um rosto em relação aos rostos que sua própria aplicação cadastrou — sessões executadas com save_api_request=true — e não em um índice global compartilhado.
• As correspondências retornam com seu próprio vendor_data em cada uma, para que os resultados sejam mapeados diretamente para seus IDs de conta.
• Dois modos: most_similar para deduplicação e usuários recorrentes, blocklisted_or_approved para triagem de lista negra.
• O status é "Declined" apenas em caso de correspondência com a lista negra. Duplicatas retornam "Approved" com um aviso DUPLICATED_FACE — informativo por design, pois a política de deduplicação é sua.
• A resposta é um objeto face_search singular, não um array. Isso confunde as pessoas.
• Gratuito com a verificação Didit. Resposta em menos de dois segundos. Executado automaticamente durante a prova de vida.

O que 1:N significa e por que é a ferramenta certa

Uma correspondência facial 1:1 responde "esta é a pessoa neste documento?". Essa é uma pergunta de verificação, e é o que acontece durante o onboarding.

Uma busca 1:N responde a uma pergunta diferente: "de todas as pessoas que já verifiquei, esta é uma delas?". Uma imagem entra, e cada correspondência em seu índice sai.

Para o abuso coordenado de contas, a segunda pergunta é a que importa. O relatório da Anthropic sobre campanhas de destilação descreveu a atribuição construída a partir de sinais relacionais — métodos de pagamento compartilhados, tempo coordenado, infraestrutura compartilhada. Uma busca biométrica 1:N é a mesma classe de sinal, obtida do identificador mais caro que um operador tem para multiplicar.

O índice é seu. A Busca Facial é executada contra os rostos que sua própria aplicação cadastrou através de verificações anteriores — sessões com save_api_request=true, ou Prova de Vida Passiva com save_api_request=true. Não é uma busca entre usuários de outros clientes Didit. Se você não cadastrou rostos, não há nada para buscar.

A API

Requisição

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=acct_8842'

multipart/form-data, autenticado com x-api-key.

Obrigatório: user_image — jpg, jpeg, png, tiff ou webp, máximo 5 MB. PDFs não são aceitos. A imagem deve conter pelo menos um rosto detectável; quando vários estão presentes, o maior bounding box vence.

Opcional:

• search_type — most_similar (padrão) para deduplicação e detecção de usuários recorrentes, ou blocklisted_or_approved para triagem de lista negra.
• save_api_request — cadastra esta imagem em seu índice.
• vendor_data — seu próprio identificador para o assunto.

Resposta

A resposta contém um objeto face_search singular. A maioria dos recursos Didit retorna arrays plurais, então esta é a única forma que vale a pena ler cuidadosamente antes de escrever o parser.

{
  "request_id": "...",
  "face_search": {
    "status": "Approved",
    "total_matches": 12,
    "matches": [
      {
        "session_id": "...",
        "session_number": 4471,
        "similarity_percentage": 97.4,
        "vendor_data": "acct_3310",
        "verification_date": "2026-06-02T09:14:00Z",
        "user_details": { },
        "match_image_url": "...",
        "status": "Approved",
        "is_blocklisted": false
      }
    ],
    "user_image": { "entities": [] },
    "warnings": []
  }
}

Os campos que conduzem a investigação:

• total_matches — quantas contas compartilham este rosto.
• vendor_data em cada correspondência — seu identificador, então uma lista de correspondências é imediatamente uma lista de contas.
• similarity_percentage — a força de cada correspondência individual.
• verification_date — a linha do tempo. Doze contas verificadas em onze meses são lidas de forma diferente de doze verificadas em uma tarde.
• is_blocklisted — se esta correspondência já está em sua lista negra.
• session_id — o pivô para todo o resto que a sessão capturou, incluindo seu dispositivo e avisos de rede.

Semântica de status

Este é o comportamento mais importante em todo o endpoint:

O status é "Declined" apenas quando pelo menos uma correspondência de lista negra é encontrada. Correspondências puramente duplicadas retornam "Approved".

Uma duplicata não é uma recusa. É informação. A Didit recusa deliberadamente tomar a decisão de deduplicação por você, porque as duplicatas têm explicações legítimas e só você conhece as regras do seu produto.

Avisos

Aviso	Significado
FACE_IN_BLOCKLIST	Correspondência definitiva na lista negra — rejeitar
POSSIBLE_FACE_IN_BLOCKLIST	Correspondência limítrofe abaixo do limite rígido — encaminhar para revisão manual
DUPLICATED_FACE	Este rosto já está verificado sob um vendor_data diferente
POSSIBLE_DUPLICATED_FACE	Duplicata limítrofe
MULTIPLE_FACES_DETECTED	Mais de um rosto na imagem enviada

Modos de falha

• HTTP 400 — nenhum rosto detectado em user_image. Peça uma nova tentativa.
• HTTP 403 — sem créditos.
• status: "Declined" com FACE_IN_BLOCKLIST — acerto definitivo. Rejeitar.
• POSSIBLE_FACE_IN_BLOCKLIST — abaixo do limite rígido. Revisão manual.
• DUPLICATED_FACE — já verificado sob um vendor_data diferente. Mesclar, bloquear ou permitir de acordo com sua política.

O caminho automático

Muitas vezes, você não precisa chamar o endpoint. A Busca Facial é executada automaticamente durante a prova de vida dentro de uma sessão de verificação:

• A biometria facial é comparada com todos os usuários previamente verificados.
• Potenciais contas duplicadas são identificadas pela similaridade facial.
• As correspondências são sinalizadas de acordo com seus limites de similaridade configurados.
• Os rostos são verificados em sua lista negra, e uma correspondência na lista negra automaticamente recusa a verificação.

Assim, para qualquer nível onde você já executa a verificação completa, a detecção de duplicatas está incluída sem custo adicional e sem chamada extra. O endpoint autônomo é para os casos que o fluxo da sessão não cobre — investigando uma conta após o fato, triando uma imagem que você obteve de outra forma, ou trocando search_type para executar uma busca focada na lista negra sobre uma imagem que você já possui.

Transformando correspondências em um mapa de atores

O fluxo de trabalho prático, começando por uma conta suspeita:

1. Busque o rosto. total_matches: 12 — doze contas, uma pessoa.
2. Leia o vendor_data. Doze dos seus próprios IDs de conta, sem necessidade de junção.
3. Leia a linha do tempo. Agrupe os valores de verification_date. Contas criadas em picos são operacionalmente diferentes de contas criadas ao longo de anos.
4. Pivote em session_id. Puxe os avisos de dispositivo e rede de cada sessão. Rostos que compartilham DUPLICATED_DEVICE_FINGERPRINT estreitam o cluster; contas em dispositivos não relacionados podem ser um arranjo diferente.
5. Expanda. Dispositivos e faixas de IP surgidos na etapa 4 puxarão contas que a busca facial perdeu — porque uma pessoa diferente concluiu essas verificações.
6. Decida uma vez, aplique em todos os identificadores. Se o cluster for confirmado como abuso, publique o reference_session_id confirmado em cada lista negra de tipo de entrada que você se importa — rosto, dispositivo, IP, e-mail, telefone, documento. É uma chamada por lista, e cada chamada extrai automaticamente o valor correto daquela sessão, para que nada seja digitado manualmente.

Seis passos, um ponto de partida, e nenhuma inspeção imediata em lugar algum. A camada de tráfego informa que algo está errado com esta conta. Isso informa quantas contas realmente são.

Vale a pena afirmar claramente: uma busca facial 1:N não impede a extração de modelo e não a detecta. A Busca Facial não tem visibilidade do seu tráfego de API. Ela resolve contas para pessoas, o que permite que você aja em um alerta em um cluster inteiro em vez de uma única linha. Controles de saída em nível de modelo e detecção de tráfego semântico são camadas separadas, e permanecem responsabilidade do provedor do modelo.

Casos de uso

Plataformas de API de IA resolvendo um alerta comportamental no conjunto completo de contas que um operador controla.

Abuso de nível gratuito e crédito — uma pessoa, muitas contas de teste, é o mesmo problema de detecção com riscos menores.

Marketplaces e plataformas de gig pegando vendedores, motoristas ou entregadores banidos que se recadastram.

iGaming aplicando regras de conta única e autoexclusão, onde um jogador excluído que retorna é uma falha regulatória, não apenas um caso de abuso.

Serviços financeiros identificando redes de identidade sintética onde um rosto real é espalhado por muitas identidades fabricadas.

Perguntas frequentes

Meu índice facial é compartilhado com outros clientes Didit?

Não. A Busca Facial é executada contra o índice que sua própria aplicação construiu através de suas próprias verificações. Não é uma busca entre clientes.

O que controla se um rosto entra no índice?

save_api_request=true em uma sessão de verificação ou uma chamada de Prova de Vida Passiva. Você decide o que é cadastrado e controla a retenção, consistente com seu próprio aviso de privacidade e base legal para o processamento de dados biométricos.

Qual limite de similaridade devo usar?

Esteja ciente de onde o ajuste se aplica. No endpoint autônomo, as faixas de similaridade que separam acertos confirmados (FACE_IN_BLOCKLIST, DUPLICATED_FACE) de possíveis acertos (POSSIBLE_FACE_IN_BLOCKLIST, POSSIBLE_DUPLICATED_FACE) são fixas internamente — o ajuste de limite por aplicação se aplica à verificação de prova de vida do fluxo de trabalho, não a POST /v3/face-search/. Portanto, no caminho autônomo, leia similarity_percentage por correspondência e aplique seu próprio critério na lógica da aplicação, e trate os avisos POSSIBLE_* como sua fila de revisão, e não sua fila de recusa.

Quão rápido é em escala?

Resposta em menos de dois segundos.

Posso buscar um rosto que nunca passou pela verificação Didit?

Sim. Qualquer user_image em um formato aceito funciona. Se nenhum rosto for detectado, a chamada retorna HTTP 400.

É realmente gratuito?

Sim — a Busca Facial 1:N é gratuita com a verificação de identidade Didit. Não há cobrança por busca. Você está pagando pelas verificações que constroem o índice, a US$ 0,33 pelo pacote completo, com as primeiras 500 gratuitas por mês.

E se a mesma pessoa tiver legitimamente duas contas?

Então DUPLICATED_FACE é exatamente o sinal informativo para o qual foi projetado — é por isso que não recusa. Mescle-as, permita-as ou pergunte ao usuário, de acordo com as regras do seu produto.

Pronto para começar?

A Busca Facial está disponível em todas as contas Didit, sem necessidade de comprar um produto separado.

• Leia a documentação — Visão geral da Busca Facial 1:N e a API de Listas para listas negras faciais.
• Veja o produto — Verificação de Usuário.
• Verifique os preços — A Busca Facial 1:N é gratuita; o pacote de verificação que constrói o índice custa US$ 0,33.
• Comece gratuitamente — business.didit.me, 500 verificações KYC por mês sem custo.