> ## 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 Confronto facciale 1:1: selfie e documento

> Didit confronta selfie e documento con l'IA. $0.05 a chiamata, $10 gratis/mese e punteggio di corrispondenza in meno di 2s per KYC.

Il confronto facciale di Didit confronta due volti 1:1, di solito il selfie ottenuto durante un controllo di vitalità con la foto sul documento d'identità dell'utente, e restituisce un punteggio di somiglianza da 0 a 100. Le soglie impostate determinano il superamento del controllo; l'API autonoma `POST /v3/face-match/` rifiuta per impostazione predefinita un punteggio pari o inferiore a 30.Nella lezione dell'Academy su come interpretare l'esito di una verifica, il capitolo al minuto 6:16 tratta il controllo del confronto facciale all'interno di una sessione reale.[Face match — Didit Academy](https://www.youtube.com/embed/7htTWCWsl60?start=376\&rel=0\&playsinline=1)

Prompt per l'integrazione del confronto facciale
        Copia il prompt negli appunti



      
      

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



      
      

Incolla in

![Panoramica dei passaggi della verifica dell'identità](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)## Nuovi tentativi e feedback praticoIn una sessione Didit, un confronto facciale che fallisce per un **motivo di acquisizione risolvibile** (il selfie è troppo scuro, sfocato, non centrato, oppure la somiglianza è al limite) non viene rifiutato immediatamente. All'utente viene chiesto di **riprovare con indicazioni guidate**, fino a un numero configurabile di tentativi — lo stesso modello utilizzato per [Rilevamento della vitalità](https://docs.didit.me/it/core-technology/liveness/overview.md).* **Budget dei tentativi** — `face_match_max_attempts` controlla il numero totale di invii del confronto facciale per sessione. Predefinito **3** (un tentativo iniziale più due nuovi tentativi), configurabile per nodo del workflow (intervallo 1–3).

* **Feedback sui nuovi tentativi** — finché rimangono tentativi, un errore che ammette un nuovo tentativo mantiene l'utente sul passaggio e restituisce `feedback_codes` (gli SDK Web e Mobile li mostrano automaticamente come messaggi di guida):

  ```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
  }
  ```

* **Esaurimento** — una volta esaurito il budget viene applicato lo stato calcolato (`Declined` o `In Review`).> [!NOTE]
>
> I nuovi tentativi si applicano esclusivamente al **flusso di sessione**. L'endpoint autonomo `POST /v3/face-match/` è senza stato e a esecuzione singola: restituisce direttamente il punteggio di somiglianza senza alcun budget di nuovi tentativi.## Come funziona**1. Acquisizione intelligente**Inizia il processo di verifica senza difficoltà grazie al nostro intuitivo sistema di acquisizione guidato dall'IA.Gli utenti caricano o fotografano i loro documenti d'identità con assistenza in tempo reale:| Funzionalità | Descrizione |
| - | - |
| **Rilevamento automatico** | Identifica automaticamente il tipo di documento e il paese di emissione |
| **Guida in tempo reale** | Indicazioni visive per posizionamento, illuminazione e messa a fuoco ottimali |
| **Acquisizione intelligente** | Scatto automatico quando le condizioni sono ideali — nessun nuovo tentativo manuale necessario |
| **Ampio supporto** | Passaporti, patenti di guida, carte d'identità nazionali e permessi di soggiorno |> [!NOTE]
>
> *Perché è importante*: la nostra acquisizione intelligente riduce gli ostacoli per l'utente e garantisce invii di alta qualità al primo tentativo, aumentando i tassi di conversione e la fiducia.**2. Elaborazione avanzata dei dati**Estrai e valida i dati di identità con una precisione senza pari.**Estrazione dei dati** — Una tecnologia all'avanguardia elabora tutti i campi chiave:| Funzionalità | Dettagli |
| - | - |
| **Estrazione dei campi** | Nome completo, data di nascita, numero del documento, date di emissione/scadenza, nazionalità e altro |
| **OCR** | Riconoscimento ottico dei caratteri ad alta precisione per il testo |
| **Analisi MRZ** | Analisi della zona a lettura ottica e decodifica dei codici a barre |**Validazione dei dati**:* Confronta i dati tra zone visive, MRZ e codici a barre per verificarne la coerenza
* Corrispondenza di formati e pattern per rilevare anomalie
* Interrogazioni in tempo reale sui database governativi (dove consentito) per una verifica basata su una fonte ufficiale> [!NOTE]
>
> *Perché è importante*: un'elaborazione completa dei dati garantisce accuratezza ed elimina gli errori, dandoti sicurezza in ogni verifica.**3. Analisi avanzata**Il nostro sistema basato sull'IA esegue controlli approfonditi:- Verifica dell'autenticità del documento
- Rilevamento delle manomissioni e analisi dell'integrità dell'immagine
- Validazione degli elementi di sicurezza (ologrammi, filigrane, ecc.)
- Corrispondenza del modello con un database certificato**Il rilevamento della vitalità del documento** previene le frodi derivanti da:| Tipo di attacco | Descrizione |
| - | - |
| **Catture dello schermo** | Documenti digitali fotografati da uno schermo |
| **Riproduzione su schermo** | Foto di documenti visualizzati su schermi |
| **Copie stampate** | Riproduzioni fisiche di documenti originali |
| **Ritratti alterati** | Documenti manipolati con foto sostituite o modificate |**4. Risultati e integrazione senza interruzioni**Ottieni subito informazioni operative grazie a opzioni di consegna flessibili.**Esiti in tempo reale**:| Canale | Descrizione |
| - | - |
| **Dashboard** | Aggiornamenti immediati tramite una dashboard intuitiva |
| **Webhook** | Notifiche webhook istantanee per flussi di lavoro automatizzati |
| **API REST** | Perfetta integrazione nei tuoi sistemi esistenti |**Reportistica completa**:* Report PDF dettagliati con gli esiti della verifica e gli elementi probatori
* Registri di audit per la compliance e l'archiviazione
* Opzioni personalizzabili per allinearsi alle tue esigenze operative> [!NOTE]
>
> *Perché è importante*: esiti rapidi e accessibili consentono al tuo team di agire tempestivamente, mantenendo un processo sicuro e sottoponibile ad audit.***## Requisiti dei documentiPer un esito ottimale della verifica, i documenti devono rispettare questi standard:#### Requisiti generali- Emessi dal governo e in corso di validità entro il periodo configurato
- Integri fisicamente (senza danni, graffi o macchie che oscurino i dettagli)
- Tutte le informazioni critiche (nome completo, data di nascita, MRZ, ecc.) chiaramente leggibili
- Dati coerenti su tutti i documenti inviati#### Requisiti dell'immagine- Foto originale scattata in tempo reale (niente screenshot, scansioni o copie digitali)
- Formati supportati: JPG, JPEG, PNG, PDF
- Dimensione massima del file: 5MB
- Immagine a colori con tutti gli angoli del documento visibili
- Priva di riflessi, ombre, modifiche digitali o manomissioni
- Documenti fisici obbligatori (i documenti d'identità digitali sono supportati solo in aree geografiche selezionate in cui sono ufficialmente riconosciuti)## Impostazioni aggiuntive per paese e tipo di documentoConfigura regole dettagliate per paese e tipo di documento direttamente dalla console. Questi controlli ti consentono di adattare i criteri di accettazione e le preferenze di trascrizione alle tue esigenze di compliance.![Pannello delle impostazioni avanzate di confronto facciale Didit per le soglie di somiglianza e le regole di accettazione](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)* **Modalità di scadenza**: scegli come gestire i documenti la cui data di scadenza è trascorsa.
  * **Rifiuta i documenti scaduti**: se la data di scadenza del documento è antecedente a quella odierna, contrassegnalo come scaduto e rifiutalo.
  * **Consenti i documenti scaduti**: non contrassegnare né bloccare i documenti con una data di scadenza trascorsa.
* **Formato dei caratteri preferito**: seleziona come devono essere normalizzati i nomi e i campi estratti.
  * **Preferisci i caratteri latini (A–Z)**: esempio: "Mohammed"
  * **Preferisci il sistema di scrittura originale (non latino)**: esempio: "محمد"
* **Supporto regionale e sottotipi**: abilita i documenti per regione e specifica i sottotipi accettabili quando un tipo di documento contiene molte varianti.
  * Esempio: per le patenti di guida degli Stati Uniti, seleziona i sottotipi esatti che accetti (ad es. Arizona Commercial Driver License, Indiana Operator License (REAL ID), New York Enhanced Driver License, ecc.).
  * Usa il controllo "Sottotipi accettati" per includere o escludere rapidamente molte varianti (ad es. "128 selezionati").> Suggerimento: queste impostazioni si applicano per paese e tipo di documento, consentendoti di applicare criteri rigorosi in alcuni mercati e più permissivi in altri.


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