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

# Ricerca facciale 1:N: API per il rilevamento duplicati

> Cerca volti tra gli utenti verificati per rilevare duplicati con Didit. Gratuito con la verifica dell'identità, risposta in meno di 2 secondi.

La ricerca facciale è una potente funzionalità che ti consente di cercare un volto specifico all'interno di tutte le tue sessioni di verifica dell'identità approvate. Questa funzionalità aiuta a identificare gli account duplicati, prevenire le frodi e rafforzare le tue misure di sicurezza.

Prompt di integrazione per Ricerca facciale
        Copia il prompt negli appunti



      
      

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



      
      

Incolla in

La lezione dell'Academy sulla lettura dell'esito di una verifica tratta la ricerca facciale e le blocklist al minuto 6:53.[Ricerca facciale e blocklist — Didit Academy](https://www.youtube.com/embed/7htTWCWsl60?start=413\&rel=0\&playsinline=1)![Flusso 1:N di ricerca facciale di Didit integrato con rilevamento della vitalità per l'individuazione di duplicati e blocklist](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)## Integrazione automatica della Ricerca facciale> La Ricerca facciale viene eseguita automaticamente durante i controlli del rilevamento della vitalità nelle sessioni di verifica per rilevare utenti duplicati ed effettuare controlli rispetto ai volti presenti nella blocklist.### Rilevamento automatico dei duplicatiQuando un utente completa un controllo del rilevamento della vitalità durante la verifica dell'identità:- I suoi dati biometrici facciali vengono confrontati automaticamente con tutti gli utenti verificati in precedenza
- Il sistema identifica potenziali account duplicati in base alla somiglianza facciale
- Le corrispondenze vengono segnalate in base alle soglie di somiglianza configurate
- Puoi esaminare i potenziali utenti duplicati e intraprendere azioni al riguardo### Integrazione con la blocklistLa Ricerca facciale si integra perfettamente con la [funzionalità di blocklist](https://docs.didit.me/it/management-api/lists/overview.md):- Durante la verifica, i volti vengono controllati automaticamente rispetto alla tua blocklist
- Se viene rilevata una corrispondenza con un volto presente nella blocklist, la verifica viene automaticamente rifiutata
- Ciò impedisce agli utenti problematici precedentemente identificati di creare nuovi account
- Aiuta a mantenere l'integrità del tuo processo di verifica### Il selfie scattato durante l'acquisizione del documentoMentre l'utente fotografa il proprio documento, la fotocamera frontale scatta un selfie (acquisizione silenziosa o Silent Capture). Ogni volta che il documento viene valutato, quel selfie viene sottoposto alla stessa ricerca 1:N del selfie del rilevamento della vitalità:- Viene confrontato con la tua blocklist dei volti e con gli utenti già approvati nella tua applicazione, con le stesse soglie di somiglianza e la stessa precedenza della ricerca del rilevamento della vitalità.
- Una corrispondenza nella blocklist genera `FRONT_CAMERA_FACE_IN_BLOCKLIST` (sempre Rifiutata) o `POSSIBLE_FRONT_CAMERA_FACE_IN_BLOCKLIST` (sempre In revisione). Una corrispondenza con un utente approvato genera `FRONT_CAMERA_DUPLICATED_FACE` o `POSSIBLE_FRONT_CAMERA_DUPLICATED_FACE`, oltre a `FRONT_CAMERA_DUPLICATED_FACE_NAME_MISMATCH` quando tale utente approvato è stato verificato con un nome diverso, e `FRONT_CAMERA_DUPLICATED_FACE_DOCUMENT_MISMATCH` quando il documento d'identità di quell'utente riporta una data di nascita diversa. Consulta gli [avvisi della verifica dell'identità](https://docs.didit.me/it/core-technology/id-verification/warnings-id-verification.md).
- Le corrispondenze sono elencate nei dettagli della sessione, nella scheda Verifica dell'identità, e restituite in `id_verifications[].document_selfie_face_matches` della [decisione della sessione](https://docs.didit.me/it/sessions-api/retrieve-session.md). Utilizza lo stesso formato delle voci di `liveness_checks[].matches`. Il campo è `null` per le sessioni meno recenti o quando la ricerca non è stata eseguita, e un array vuoto quando è stata eseguita senza trovare corrispondenze. `match_image_url` è un URL prefirmato soggetto a scadenza.
- Viene utilizzato solo il volto più grande nel selfie, e solo quando il rilevatore è certo che si tratti di un volto. Viene sottoposto a ricerca un solo selfie per documento: quello del lato frontale, o quello del retro se il selfie frontale non contiene un volto chiaro.
- Il selfie viene solo confrontato. Il suo modello biometrico non viene mai memorizzato, quindi le sessioni successive non verranno mai confrontate con esso. Per bloccare una persona a partire dal selfie di una sessione, aggiungilo alla tua blocklist dei volti dalla pagina della sessione.La Ricerca facciale dispone di un interruttore dedicato e delle proprie azioni nel passaggio **Verifica dell'identità**, nella scheda **Regole** del passaggio (**Ricerca facciale con acquisizione silenziosa**), oppure con `document_selfie_face_search_enabled` e le azioni `document_selfie_duplicated_face_*` nella [configurazione delle funzionalità del workflow](https://docs.didit.me/it/management-api/workflows/feature-configs.md#ocr-/-verifica-dell’identità). È attiva per impostazione predefinita; l'azione per il volto duplicato è impostata di default su Approva (l'avviso viene comunque segnalato) e i controlli incrociati su nome e documento sono impostati di default su In revisione, come le rispettive controparti del rilevamento della vitalità. La ricerca necessita del selfie, pertanto viene eseguita solo quando Silent Capture è attiva. Disattivare la Ricerca facciale nel passaggio Rilevamento della vitalità disattiva anche questa ricerca: tale rinuncia è una scelta riguardante il volto della persona, pertanto copre ogni selfie della sessione.### La regola di mancata corrispondenza del documentoLa regola di **mancata corrispondenza del documento** (`DUPLICATED_FACE_DOCUMENT_MISMATCH` per il selfie del rilevamento della vitalità, `FRONT_CAMERA_DUPLICATED_FACE_DOCUMENT_MISMATCH` per Silent Capture) segnala un volto duplicato solo quando il documento d'identità dell'utente corrispondente riporta una data di nascita diversa.
La stessa persona che presenta un documento diverso, ad esempio un passaporto dopo una carta d'identità, non viene segnalata.
Neanche un documento rinnovato viene segnalato.
Due sessioni che condividono lo stesso numero di documento dello stesso paese non vengono mai segnalate.### Disattivazione della Ricerca facciale automaticaLa Ricerca facciale automatica è attiva per impostazione predefinita per ogni passaggio Rilevamento della vitalità. Se le tue esigenze di privacy lo richiedono, puoi disattivarla per ciascun workflow dalla scheda **Regole** del passaggio **Rilevamento della vitalità** nella Business Console (modalità Semplice e Avanzata), oppure con `face_search_enabled: false` sul nodo `LIVENESS` o `AGE_ESTIMATION` nella [configurazione delle funzionalità del workflow](https://docs.didit.me/it/management-api/workflows/feature-configs.md#rilevamento-della-vitalità).Con l'interruttore disattivato, al selfie del rilevamento della vitalità viene comunque assegnato un punteggio di vitalità e viene confrontato 1:1 con la foto del documento nel Confronto facciale, ma non raggiunge mai l'indice dei volti:- Non viene eseguita alcuna ricerca, quindi la sessione non riceve alcun verdetto di duplicato, blocklist o allowlist e il suo campo `liveness_checks[].matches` rimane vuoto. Le regole **Volto duplicato**, **mancata corrispondenza del nome**, **mancata corrispondenza del documento** e quelle relative ai volti tra organizzazioni non hanno dati su cui agire e vengono nascoste nella Console.
- Nessun modello biometrico viene memorizzato per il selfie, quindi le sessioni successive non possono essere confrontate con questa e non c'è nulla da mantenere per la [conservazione del modello biometrico](https://docs.didit.me/it/console/data-retention.md#conservazione-del-modello-biometrico) dopo la cancellazione della sessione.
- Il selfie non viene utilizzato per identificare una persona biometrica condivisa per i controlli tra diverse organizzazioni.
- Anche il selfie scattato durante l'acquisizione del documento non viene sottoposto a ricerca (nessun rischio di blocklist o duplicati con `FRONT_CAMERA_*`): la rinuncia copre ogni selfie della sessione. L'interruttore specifico del passaggio Verifica dell'identità (vedi sopra) può anche disattivare tale ricerca autonomamente.**A quale passaggio appartiene l'interruttore.** L'interruttore si trova sul passaggio che acquisisce il selfie, quindi un passaggio **Rilevamento della vitalità** o **Stima dell'età** applica l'impostazione a se stesso. Un passaggio **Confronto facciale** non ne ha uno proprio: quando un utente ripete il selfie lì (ad esempio dopo avergli richiesto di inviare nuovamente quel passaggio), la ripetizione segue l'impostazione del passaggio Rilevamento della vitalità, pertanto una rinuncia mantiene anche il nuovo selfie fuori dall'indice. Se il tuo workflow si suddivide in più rami verso più passaggi Rilevamento della vitalità, l'impostazione applicata è quella presente sul ramo effettivamente percorso dalla sessione, e l'analisi facciale tra organizzazioni segue lo stesso passaggio.I workflow esistenti mantengono il comportamento attuale finché non decidi di disattivarlo. La modifica si applica alle sessioni avviate dopo il salvataggio del workflow; i modelli memorizzati dalle sessioni precedenti rimangono nell'indice finché tali sessioni non vengono eliminate o rimosse definitivamente. L'opzione non influisce sulla [Face Search API](https://docs.didit.me/it/standalone-apis/face-search.md) autonoma, che viene chiamata esplicitamente.> [!WARNING]
>
> La tua blocklist facciale viene applicata durante la verifica mediante la stessa ricerca 1:N. Con la Ricerca facciale disattivata nel passaggio Liveness, una persona inclusa nella blocklist non viene rilevata né in quel passaggio né tramite il selfie scattato durante l'acquisizione del documento; con la Ricerca facciale di Silent Capture disattivata nel passaggio ID Verification, non viene rilevata tramite tale selfie.### Accesso APILa funzionalità di Ricerca facciale è disponibile anche tramite la nostra [API](https://docs.didit.me/it/standalone-apis/face-search.md), consentendoti di:- Inviare ricerche facciali programmaticamente
- Integrare funzionalità di confronto facciale nelle tue applicazioni
- Creare workflow personalizzati di rilevamento delle frodi
- Realizzare sistemi automatizzati per il rilevamento dei duplicati## Funzionalità principali- **Elevata accuratezza**: algoritmi biometrici avanzati forniscono risultati di corrispondenza affidabili
- **Soglie configurabili**: personalizza la sensibilità di corrispondenza in base alla tua tolleranza al rischio
- **Scansione completa**: esegui ricerche su tutti i tuoi utenti verificati
- **Risultati rapidi**: elabora le ricerche velocemente anche con database di utenti di grandi dimensioni
- **Attenzione alla privacy**: il confronto utilizza modelli facciali numerici limitati alla tua applicazione; l'indice non lascia mai il tuo tenant### Soglie configurabiliPuoi personalizzare la sensibilità di ricerca impostando soglie diverse per i punteggi di somiglianza:> [!NOTE]
>
> Queste soglie possono essere regolate in base alla tua tolleranza al rischio e ai tuoi requisiti di sicurezza.## Come funziona**1. Estrazione facciale**Quando viene avviata una ricerca, il sistema elabora l'immagine di riferimento:| Processo | Descrizione |
| - | - |
| **Estrazione delle caratteristiche** | Isola le caratteristiche facciali dall'immagine di riferimento |
| **Normalizzazione** | Standardizza i dati facciali per un confronto coerente |
| **Validazione della qualità** | Verifica la qualità dell'immagine e la nitidezza del volto |
| **Codifica vettoriale** | Crea una rappresentazione vettoriale matematica del volto |**2. Algoritmo di confronto**Il sistema esegue la ricerca nell'intero database delle sessioni verificate:- Confronta il vettore facciale di riferimento con **ogni volto registrato nella tua applicazione**: volti delle sessioni, volti caricati nei profili utente, le tue liste di volti e qualsiasi modello biometrico conservato
- Impiega un'architettura di rete neurale avanzata ottimizzata per velocità e precisione
- Supporta due modalità di ricerca: **più simili** (elenco ordinato) e **in blocklist o approvati** (filtrati per stato)
- Elabora rapidamente database di grandi dimensioni utilizzando un'indicizzazione ottimizzata**3. Punteggio di somiglianza**Per ciascun confronto, viene generata una percentuale di somiglianza:| Intervallo di punteggio | Interpretazione |
| :-: | - |
| **90%+** | Corrispondenza forte — molto probabilmente la stessa persona |
| **70–89%** | Possibile corrispondenza — potrebbe richiedere una revisione manuale |
| **Inferiore al 70%** | Probabilmente individui diversi |Le soglie di corrispondenza configurate determinano quali risultati vengono segnalati.**4. Consegna dei risultati**Il sistema restituisce una serie completa di risultati:- **Elenco ordinato** delle potenziali corrispondenze disposte in base al punteggio di somiglianza
- **Dettagli della corrispondenza** inclusi ID sessione, data di verifica e dati del vendor
- **Percentuale di somiglianza** per ciascuna corrispondenza
- **Immagini di corrispondenza** disponibili per la revisione visiva
- **Stato della blocklist** che indica se il volto corrispondente è presente nella blocklist## Sessioni eliminate e modelli biometrici conservatiL'eliminazione di una sessione elimina per impostazione predefinita il relativo embedding facciale, quindi la persona viene rimossa dall'indice e può eseguire nuovamente la verifica senza che venga segnalato un duplicato. Le applicazioni che eliminano le sessioni subito dopo l'approvazione ma hanno comunque la necessità di intercettare registrazioni ripetute possono abilitare la [conservazione dei modelli biometrici](https://docs.didit.me/it/console/data-retention.md#conservazione-del-modello-biometrico). Didit conserva quindi un modello biometrico privo di immagini collegato all'utente dopo l'eliminazione della sessione, e tale modello partecipa a Ricerca facciale e al rilevamento automatico dei duplicati esattamente come il volto di una sessione attiva.Una corrispondenza su un modello conservato viene segnalata con `source: "retained_template"`, il `vendor_user_id` e i `vendor_data` dell'utente proprietario e un `biometric_template_id`. Non include alcun ID sessione, immagine di corrispondenza, dettagli sull'identità o stato della sessione, poiché la sessione che ha generato il volto non esiste più. I modelli conservati non vengono mai inseriti in blocklist; le voci della blocklist facciale mantengono una propria voce biometrica indipendente.Il modello rimane fino alla scadenza programmata, all'eliminazione dell'utente, a una richiesta di cancellazione per la privacy o a un'eliminazione definitiva esplicita tramite la [Biometric Templates API](https://docs.didit.me/it/management-api/biometric-templates/overview.md) o **Lists → Biometric templates** nella Console.## Percentuale di somiglianzaLa percentuale di somiglianza è la metrica principale utilizzata per determinare le potenziali corrispondenze:- **Percentuale elevata (in genere dal 90% in su)**: indica un'alta probabilità che i volti appartengano alla stessa persona.
- **Percentuale media (70-89%)**: suggerisce possibili corrispondenze che potrebbero richiedere un'ulteriore revisione.
- **Percentuale bassa (inferiore al 70%)**: indica probabilmente individui diversi.La soglia esatta per ciò che costituisce una "corrispondenza" può essere configurata in base ai tuoi requisiti di sicurezza. L'aumento della soglia riduce i falsi positivi ma può aumentare i falsi negativi.## Casi d'uso- **Prevenzione delle frodi**: identifica gli utenti che tentano di creare più account
- **KYC avanzato**: aggiungi un ulteriore livello di verifica al tuo processo KYC
- **Conformità normativa**: rispetta i requisiti per il rilevamento di account duplicati
- **Controllo degli accessi**: verifica l'autenticità degli utenti per le aree ad alta sicurezza
- **Forze dell'ordine**: assisti le agenzie autorizzate nell'identificazione di persone di interesse


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