> ## 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 correspondência facial 1:1: selfie x documento

> A correspondência facial da Didit compara uma selfie ao vivo com o retrato do documento usando IA. $0.05 por chamada e $10 grátis por mês.

A Correspondência facial da Didit compara dois rostos 1:1, geralmente a selfie de uma prova de vida com o retrato do documento de identidade do usuário, e retorna uma pontuação de similaridade de 0 a 100. Os limites que você define decidem se a verificação é aprovada; a API independente `POST /v3/face-match/` recusa por padrão uma pontuação igual ou inferior a 30.Na lição da Academy sobre como ler o resultado de uma verificação, o capítulo de 6:16 aborda a verificação de correspondência facial dentro de uma sessão real.[Correspondência facial — Didit Academy](https://www.youtube.com/embed/7htTWCWsl60?start=376\&rel=0\&playsinline=1)

Prompt de integração da Correspondência facial
        Copy prompt to clipboard



      
      

\<pre>

\````# Goal
Integrate Didit Face Match (1:1 — compare two faces) into your app. Pick ONE mode.

\# Mode A — Session-based
Use this when the user goes through a hosted Didit flow. Face Match runs alongside ID Verification (uses the document portrait as ref) and Liveness (uses the live selfie as user_image).

1\. Add the FACE_MATCH feature to a workflow that also runs ID_VERIFICATION + LIVENESS (Business Console or POST /v3/workflows/).
2\. Create a session — POST /v3/session/ with { workflow_id, vendor_data, callback }. See /sessions-api/create-session.
3\. Open session.url for the user (or mount the Web/Mobile SDK).
4\. Fetch the decision — GET /v3/session/{sessionId}/decision/ or subscribe to session.status.updated.

Decision surface: `face_matches[]` array on the decision payload.

\# Mode B — Standalone API (server-to-server)
Use when you already have two images and want a one-shot 1:1 similarity score.

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

Required: `user_image` (live capture) and `ref_image` (reference portrait). JPEG/PNG/WebP/TIFF, max 5 MB each.

curl example:
\```bash
curl -X POST 'https://verification.didit.me/v3/face-match/' \
-H 'x-api-key: YOUR_API_KEY' \
-F 'user_image=@./selfie.jpg' \
-F 'ref_image=@./id_portrait.jpg' \
-F 'save_api_request=true' \
-F 'vendor_data=user-123'
\```
Returns: { request_id, face_match: { status, score (0-100), user_image: {entities}, ref_image: {entities}, warnings: [...] } }. `status` is "Approved" when score > face_match_score_decline_threshold (default 30), else "Declined".

\# Status enum (per face_matches[].status / face_match.status)
"Not Started" | "In Progress" | "Approved" | "In Review" | "Declined" | "Abandoned" | "Kyc Expired"

\# Warnings (LogWarningChoices.FACEMATCH)
warnings[] risk codes include:
LOW_FACE_MATCH_SIMILARITY, NO_REFERENCE_IMAGE, NO_FACE_DETECTED, MULTIPLE_FACES_DETECTED.
Full catalogue: /core-technology/face-match/warnings-face-match.

\# Failure modes to handle
\- HTTP 403 — out of credits.
\- HTTP 400 — missing user_image or ref_image, file too large, unsupported extension.
\- status="Declined" with LOW_FACE_MATCH_SIMILARITY — the two faces do not match; do not approve.
\- NO_REFERENCE_IMAGE / NO_FACE_DETECTED — capture problems; ask the user to retry.

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

\</pre>



      
      

Paste into

![Visão geral das etapas da verificação de identidade](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/id-verification-steps.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=42c64546f3495000d7ea3b10c4b5fa50)## Novas tentativas e feedback acionávelEm uma sessão da Didit, uma correspondência facial que falha por um **motivo de captura corrigível** (a selfie está escura demais, desfocada, descentralizada ou a similaridade está no limite) não é recusada de imediato. O usuário é convidado a **tentar novamente com orientação**, até um número configurável de tentativas - o mesmo modelo usado na [Prova de vida](https://docs.didit.me/pt-br/core-technology/liveness/overview.md).* **Limite de tentativas** - `face_match_max_attempts` controla o número total de envios de correspondência facial por sessão. O padrão é **3** (uma tentativa inicial mais duas novas tentativas), configurável por nó do fluxo (workflow) (intervalo de 1 a 3).

* **Feedback de nova tentativa** - enquanto restarem tentativas, uma falha que permite nova tentativa mantém o usuário na etapa e retorna `feedback_codes` (os SDKs Web e Mobile exibem esses códigos automaticamente como mensagens de orientação):

  ```json theme={null}
  {
    "detail": "Make sure your face matches your document photo, improve lighting and try again.",
    "error": "LOW_FACE_MATCH_SIMILARITY",
    "feedback_codes": ["LOW_FACE_MATCH_SIMILARITY"],
    "attempts_used": 1,
    "max_attempts": 3
  }
  ```

* **Esgotamento** - quando o limite se esgota, o status calculado é aplicado (`Declined` ou `In Review`).> [!NOTE]
>
> As novas tentativas se aplicam apenas ao **fluxo de sessão**. O endpoint independente `POST /v3/face-match/` não guarda estado e é de tentativa única - ele retorna a pontuação de similaridade diretamente, sem limite de novas tentativas.## Como funciona**1. Captura inteligente**Comece o processo de verificação sem esforço com nosso sistema de captura intuitivo, baseado em IA.Os usuários enviam ou fotografam seus documentos de identidade com assistência em tempo real:| Recurso | Descrição |
| - | - |
| **Detecção automática** | Identifica automaticamente o tipo de documento e o país emissor |
| **Orientação em tempo real** | Indicações visuais para posicionamento, iluminação e foco ideais |
| **Captura inteligente** | Captura automática quando as condições são ideais - sem tentativas manuais repetidas |
| **Ampla compatibilidade** | Passaportes, carteiras de motorista, documentos nacionais de identidade e autorizações de residência |> [!NOTE]
>
> *Por que isso importa*: nossa captura inteligente reduz o atrito para o usuário e garante envios de alta qualidade já na primeira tentativa, aumentando as taxas de conversão e a confiança.**2. Processamento avançado de dados**Extraia e valide dados de identidade com precisão incomparável.**Extração de dados** - tecnologia de ponta processa todos os campos principais:| Capacidade | Detalhes |
| - | - |
| **Extração de campos** | Nome completo, data de nascimento, número do documento, datas de emissão e validade, nacionalidade e mais |
| **OCR** | Reconhecimento óptico de caracteres de alta precisão para texto |
| **Análise de MRZ** | Análise da zona de leitura óptica (MRZ) e decodificação de códigos de barras |**Validação de dados**:* Cruza os dados entre as zonas visuais, a MRZ e os códigos de barras para verificar a consistência
* Correspondência de formato e de padrões para detectar anomalias
* Consultas em tempo real a bases de dados governamentais (onde permitido) para uma verificação com fonte oficial> [!NOTE]
>
> *Por que isso importa*: o processamento abrangente de dados garante precisão e elimina erros, dando confiança em cada verificação.**3. Análise avançada**Nosso sistema baseado em IA realiza verificações abrangentes:- Verificação de autenticidade do documento
- Detecção de adulteração e análise de integridade da imagem
- Validação de elementos de segurança (hologramas, marcas d'água etc.)
- Correspondência de modelos com uma base certificadaA **prova de vida do documento** evita fraudes como:| Tipo de ataque | Descrição |
| - | - |
| **Capturas de tela** | Documentos digitais fotografados a partir de uma tela |
| **Reprodução em tela** | Fotos de documentos exibidos em telas |
| **Cópias impressas** | Reproduções físicas de documentos originais |
| **Retratos alterados** | Documentos manipulados com fotos trocadas ou editadas |**4. Resultados e integração sem atritos**Receba informações acionáveis na hora, com opções flexíveis de entrega.**Resultados em tempo real**:| Canal | Descrição |
| - | - |
| **Painel** | Atualizações imediatas em um painel intuitivo |
| **Webhooks** | Notificações instantâneas por webhook para fluxos automatizados |
| **API REST** | Integração sem atritos aos seus sistemas existentes |**Relatórios completos**:* Relatórios detalhados em PDF com os resultados da verificação e as evidências
* Trilhas de auditoria para conformidade e manutenção de registros
* Opções personalizáveis para se adequar às suas necessidades operacionais> [!NOTE]
>
> *Por que isso importa*: resultados rápidos e acessíveis permitem que sua equipe aja com agilidade, mantendo um processo seguro e auditável.***## Requisitos do documentoPara o melhor êxito na verificação, os documentos devem atender a estes padrões:#### Requisitos gerais- Emitido por um governo e válido dentro do período de validade configurado
- Fisicamente íntegro (sem danos, riscos ou manchas que escondam detalhes)
- Todas as informações críticas (nome completo, data de nascimento, MRZ etc.) claramente legíveis
- Dados consistentes em todos os documentos enviados#### Requisitos da imagem- Foto original e em tempo real (sem capturas de tela, digitalizações ou cópias digitais)
- Formatos compatíveis: JPG, JPEG, PNG, PDF
- Tamanho máximo do arquivo: 5MB
- Imagem colorida, com todos os cantos do documento visíveis
- Sem reflexos, sombras, edição digital ou manipulação
- Documentos físicos são obrigatórios (documentos digitais só são aceitos em regiões selecionadas onde são oficialmente reconhecidos)## Configurações adicionais por país e tipo de documentoConfigure regras detalhadas por país e tipo de documento diretamente no console. Esses controles permitem adaptar os critérios de aceitação e as preferências de transcrição às suas necessidades de conformidade.![Painel de configurações avançadas da correspondência facial da Didit para limites de similaridade e regras de aceitação](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/id-additional-settings.jpeg?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=4238b10a404795a61926fbdf1a3adc20)* **Modo de validade**: escolha como tratar documentos com data de validade vencida.
  * **Rejeitar documentos expirados**: se a data de validade do documento for anterior a hoje, marque-o como expirado e rejeite.
  * **Permitir documentos expirados**: não sinalize nem bloqueie documentos com data de validade vencida.
* **Formato de caracteres preferido**: selecione como os nomes e campos extraídos devem ser normalizados.
  * **Prefira caracteres latinos (A–Z)**: exemplo: "Mohammed"
  * **Prefira script original (não latino)**: exemplo: "محمد"
* **Suporte regional e subtipos**: ative documentos por região e especifique os subtipos aceitáveis quando um tipo de documento tiver muitas variações.
  * Exemplo: para carteiras de motorista dos Estados Unidos, selecione os subtipos exatos que você aceita (por exemplo, Arizona Commercial Driver License, Indiana Operator License (REAL ID), New York Enhanced Driver License etc.).
  * Use o controle "Subtipos aceitos" para incluir/excluir rapidamente muitas variantes (por exemplo, "128 selecionados").> Dica: essas configurações se aplicam por país e tipo de documento, então você pode ser rigoroso em alguns mercados e mais flexível em outros.


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