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

# Correspondência facial 1:1 API: comparação selfie vs ID

> Compare uma selfie com o documento com a Didit. IA facial a $0.05 por chamada, $10 grátis/mês e pontuação sub-2s para KYC e onboarding.

A Correspondência facial da Didit compara dois rostos 1:1, normalmente a selfie de uma verificação de prova de vida com o retrato no documento de identificação do utilizador, e devolve uma pontuação de semelhança de 0 a 100. Os limiares definidos por si decidem se a verificação é aprovada; a API autónoma `POST /v3/face-match/` recusa uma pontuação de 30 ou inferior por predefinição.Na aula da Academy sobre a leitura do resultado de uma verificação, o capítulo aos 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 de correspondência facial
        Copiar o prompt para a área de transferência



      
      

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



      
      

Colar em

![Visão geral dos passos de 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ávelNuma sessão da Didit, uma correspondência facial que falhe por um **motivo de captura corrigível** (a selfie está demasiado escura, desfocada, descentrada ou a semelhança está no limite) não é imediatamente recusada. O utilizador é convidado a **tentar novamente com orientações**, até um número configurável de tentativas — o mesmo modelo utilizado para a [Prova de vida](https://docs.didit.me/pt/core-technology/liveness/overview.md).* **Orçamento de tentativas** — `face_match_max_attempts` controla o número total de envios de correspondência facial por sessão. Predefinição **3** (uma tentativa inicial mais duas novas tentativas), configurável por nó de fluxo (intervalo 1–3).

* **Feedback de nova tentativa** — enquanto restarem tentativas, uma falha que permita nova tentativa mantém o utilizador no passo e devolve `feedback_codes` (os SDKs Web e Mobile apresentam-nos 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** — assim que o orçamento se esgota, o estado calculado é aplicado (`Declined` ou `In Review`).> [!NOTE]
>
> As novas tentativas aplicam-se apenas ao **fluxo de sessão**. O endpoint autónomo `POST /v3/face-match/` não mantém estado e é de execução única — devolve a pontuação de semelhança diretamente, sem qualquer orçamento de novas tentativas.## Como funciona**1. Captura inteligente**Inicie o processo de verificação sem esforço com o nosso sistema de captura intuitivo e baseado em IA.Os utilizadores carregam ou fotografam os seus documentos de identificação com assistência em tempo real:| Funcionalidade | Descrição |
| - | - |
| **Deteção automática** | Identifica o tipo de documento e o país emissor automaticamente |
| **Orientação em tempo real** | Indicações visuais para um posicionamento, iluminação e foco ideais |
| **Captura inteligente** | Captura automática quando as condições são ideais — sem necessidade de novas tentativas manuais |
| **Amplo suporte** | Passaportes, cartas de condução, cartões de cidadão/identidade e autorizações de residência |> [!NOTE]
>
> *Por que motivo é importante*: A nossa captura inteligente reduz o atrito do utilizador e assegura envios de alta qualidade logo 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 uma precisão inigualável.**Extração de dados** — Tecnologia de ponta que processa todos os campos essenciais:| Capacidade | Detalhes |
| - | - |
| **Extração de campos** | Nome completo, data de nascimento, número do documento, datas de emissão/validade, nacionalidade e muito mais |
| **OCR** | Reconhecimento ótico de caracteres de alta precisão para texto |
| **Análise de MRZ** | Análise de Zona de Leitura Ótica (MRZ) e descodificação de códigos de barras |**Validação de dados**:* Cruzamento de dados entre zonas visuais, MRZ e códigos de barras para garantir a consistência
* Correspondência de formatos e padrões para detetar anomalias
* Consultas em tempo real a bases de dados governamentais (onde permitido) para verificação fidedigna> [!NOTE]
>
> *Por que motivo é importante*: O processamento abrangente de dados assegura a exatidão e elimina erros, proporcionando-lhe confiança em cada verificação.**3. Análise avançada**O nosso sistema baseado em IA realiza verificações abrangentes:- Verificação de autenticidade do documento
- Deteção de adulterações e análise de integridade da imagem
- Validação de elementos de segurança (hologramas, marcas de água, etc.)
- Correspondência de modelos com uma base de dados certificadaA **prova de vida do documento** previne fraudes de:| Tipo de ataque | Descrição |
| - | - |
| **Capturas de ecrã** | Documentos digitais fotografados a partir de um ecrã |
| **Reprodução em ecrã** | Fotografias de documentos exibidos em ecrãs |
| **Cópias impressas** | Reproduções físicas de documentos originais |
| **Retratos alterados** | Documentos manipulados com fotografias substituídas ou editadas |**4. Resultados e integração simplificados**Obtenha informações acionáveis instantaneamente com opções flexíveis de entrega.**Resultados em tempo real**:| Canal | Descrição |
| - | - |
| **Painel** | Atualizações imediatas através de um painel intuitivo |
| **Webhooks** | Notificações instantâneas por webhook para fluxos automatizados |
| **API REST** | Integração perfeita nos seus sistemas existentes |**Relatórios abrangentes**:* Relatórios detalhados em PDF com os resultados da verificação e provas
* Registos de auditoria para conformidade e conservação de registos
* Opções personalizáveis para se alinharem com as suas necessidades operacionais> [!NOTE]
>
> *Por que motivo é importante*: Resultados rápidos e acessíveis capacitam a sua equipa a agir prontamente, mantendo um processo seguro e auditável.***## Requisitos do documentoPara um sucesso ideal na verificação, os documentos devem cumprir estes padrões:#### Requisitos gerais- Emitidos pelo governo e válidos dentro do período de validade configurado
- Fisicamente intacto (sem danos, riscos ou manchas a ocultar detalhes)
- Todas as informações críticas (nome completo, data de nascimento, MRZ, etc.) claramente legíveis
- Dados consistentes em todos os documentos submetidos#### Requisitos da imagem- Fotografia original em tempo real (sem capturas de ecrã, digitalizações ou cópias digitais)
- Formatos suportados: JPG, JPEG, PNG, PDF
- Tamanho máximo do ficheiro: 5MB
- Imagem a cores com todos os cantos do documento visíveis
- Sem reflexos, sombras, edições digitais ou manipulações
- Documentos físicos obrigatórios (IDs digitais suportados apenas em regiões selecionadas onde sejam oficialmente reconhecidos)## Definições adicionais por país e tipo de documentoConfigure regras detalhadas por país e tipo de documento diretamente a partir da consola. Estes controlos permitem adaptar os critérios de aceitação e as preferências de transcrição às suas necessidades de conformidade.![Painel de definições avançadas de correspondência facial da Didit para limiares 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 expiração**: Escolha como tratar documentos cuja data de validade já passou.
  * **Rejeitar expirados**: Se a data de validade do documento for anterior ao dia de hoje, marcar como expirado e recusar.
  * **Permitir expirados**: Não sinalizar nem bloquear documentos com uma data de validade expirada.
* **Formato de carateres preferido**: Selecione como os nomes e campos extraídos devem ser normalizados.
  * **Preferir carateres latinos (A–Z)**: Exemplo: "Mohammed"
  * **Preferir sistema de escrita original (não latino)**: Exemplo: "محمد"
* **Suporte regional e subtipos**: Ative documentos por região e especifique subtipos aceitáveis quando um tipo de documento contiver várias variações.
  * Exemplo: Para cartas de condução dos Estados Unidos, selecione os subtipos exatos que aceita (por exemplo, Arizona Commercial Driver License, Indiana Operator License (REAL ID), New York Enhanced Driver License, etc.).
  * Utilize o controlo "Subtipos aceites" para incluir/excluir rapidamente diversas variantes (por exemplo, "128 selecionados").> Dica: Estas definições aplicam-se por país e tipo de documento, permitindo-lhe aplicar critérios mais rigorosos em alguns mercados e ser mais permissivo noutros.


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