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

# Cerca facial 1:N amb API: detecció de duplicats

> Didit cerca cares entre usuaris verificats per detectar duplicats i defraudadors en menys de 2 segons. Gratuït amb la verificació d'identitat.

La Cerca facial és una potent funcionalitat que et permet cercar una cara específica entre totes les teves sessions de verificació d'identitat aprovades. Aquesta capacitat ajuda a identificar comptes duplicats, prevenir el frau i millorar les teves mesures de seguretat.

Prompt d'integració de la Cerca facial
        Copia el prompt al porta-retalls



      
      

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



      
      

Enganxa a

La lliçó de l'Academy sobre com interpretar el resultat d'una verificació arriba a la cerca facial i a les llistes de bloqueig al minut 6:53.[Cerca facial i llistes de bloqueig — Didit Academy](https://www.youtube.com/embed/7htTWCWsl60?start=413\&rel=0\&playsinline=1)![Flux 1:N de cerca facial de Didit integrat amb prova de vida per a la detecció de duplicats i llistes de bloqueig](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)## Integració automàtica de Cerca facial> La Cerca facial s'executa automàticament durant les comprovacions de prova de vida en les sessions de verificació per detectar usuaris duplicats i comparar els seus rostres amb els rostres de la llista de bloqueig.### Detecció automàtica de duplicatsQuan un usuari completa una comprovació de prova de vida durant la verificació d'identitat:- La seva biometria facial es compara automàticament amb la de tots els usuaris verificats anteriorment
- El sistema identifica possibles comptes duplicats basant-se en la similitud facial
- Les coincidències es marquen segons els llindars de similitud que hagis configurat
- Pots revisar els possibles usuaris duplicats i prendre mesures sobre ells### Integració amb la llista de bloqueigLa Cerca facial s'integra de manera nativa amb la [funcionalitat de llista de bloqueig](https://docs.didit.me/ca/management-api/lists/overview.md):- Durant la verificació, els rostres es comparen automàticament amb la teva llista de bloqueig
- Si es troba una coincidència amb un rostre de la llista de bloqueig, la verificació es rebutja automàticament
- Això impedeix que usuaris problemàtics identificats anteriorment creïn comptes nous
- Ajuda a mantenir la integritat del teu procés de verificació### La selfie presa durant la captura del documentMentre l'usuari fotografia el seu document, la càmera frontal li fa una selfie (captura silenciosa). Cada vegada que s'avalua el document, aquesta selfie passa per la mateixa cerca 1:N que la selfie de la prova de vida:- Es compara amb la teva llista de bloqueig de rostres i amb els usuaris ja aprovats a la teva aplicació, amb els mateixos llindars de similitud i la mateixa precedència que la cerca de prova de vida.
- Una coincidència amb la llista de bloqueig genera `FRONT_CAMERA_FACE_IN_BLOCKLIST` (sempre Declined) o `POSSIBLE_FRONT_CAMERA_FACE_IN_BLOCKLIST` (sempre Review). Una coincidència amb un usuari aprovat genera `FRONT_CAMERA_DUPLICATED_FACE` o `POSSIBLE_FRONT_CAMERA_DUPLICATED_FACE`, a més de `FRONT_CAMERA_DUPLICATED_FACE_NAME_MISMATCH` quan aquest usuari aprovat es va verificar amb un nom diferent, i `FRONT_CAMERA_DUPLICATED_FACE_DOCUMENT_MISMATCH` quan el document d'identitat d'aquest usuari mostra una data de naixement diferent. Consulta les [advertències de verificació d'identitat](https://docs.didit.me/ca/core-technology/id-verification/warnings-id-verification.md).
- Les coincidències es mostren als detalls de la sessió, a la targeta de verificació d'identitat, i es retornen a `id_verifications[].document_selfie_face_matches` de la [decisió de la sessió](https://docs.didit.me/ca/sessions-api/retrieve-session.md). Utilitza el mateix format d'entrada que `liveness_checks[].matches`. El camp és `null` per a sessions més antigues o quan la cerca no s'ha executat, i una matriu buida quan s'ha executat i no ha trobat res. `match_image_url` és una URL signada prèviament que caduca.
- Només s'utilitza el rostre més gran de la selfie, i només quan el detector té la certesa que es tracta d'un rostre. Se cerca una selfie per document: la de la part frontal, o la del dors quan la selfie de la part frontal no conté cap rostre clar.
- La selfie només es compara. La seva plantilla biomètrica no s'emmagatzema mai, de manera que sessions posteriors mai no s'hi contrastaran. Per bloquejar una persona a partir de la selfie d'una sessió, afegeix-la a la teva llista de bloqueig de rostres des de la pàgina de la sessió.La cerca té el seu propi commutador i les seves pròpies accions al pas **Verificació d'identitat**, a la pestanya **Rules** del pas (**Silent Capture Face Search**), o amb `document_selfie_face_search_enabled` i les accions `document_selfie_duplicated_face_*` a la [configuració de funcionalitats del flux de treball](https://docs.didit.me/ca/management-api/workflows/feature-configs.md#ocr-/-verificació-d’identitat). Està activada per defecte; l'acció per a rostre duplicat està configurada per defecte a Approve (l'advertència s'informa igualment) i les comprovacions creuades de nom i document estan configurades per defecte a Review, igual que les seves contraparts de prova de vida. La cerca requereix la selfie, de manera que només s'executa quan la captura silenciosa està activada. Desactivar la Cerca facial al pas de Prova de vida també desactiva aquesta cerca: aquesta opció d'exclusió és una decisió sobre el rostre de la persona, per la qual cosa cobreix totes les selfies de la sessió.### La regla de discrepància de documentLa regla de **discrepància de document** (`DUPLICATED_FACE_DOCUMENT_MISMATCH` per a la selfie de prova de vida, `FRONT_CAMERA_DUPLICATED_FACE_DOCUMENT_MISMATCH` per a la captura silenciosa) només marca un rostre duplicat quan el document d'identitat de l'usuari coincident mostra una data de naixement diferent.
La mateixa persona presentant un document diferent, per exemple un passaport després d'un document d'identitat, no es marca.
Un document renovat tampoc no es marca.
Dues sessions que comparteixen el mateix número de document del mateix país mai no es marquen.### Desactivar la Cerca facial automàticaLa Cerca facial automàtica està activada per defecte per a cada pas de Prova de vida. Si el teu enfocament de privacitat ho requereix, pots desactivar-lo per flux de treball des de la pestanya **Rules** del pas **Liveness** a la Business Console (Mode simple i avançat), o amb `face_search_enabled: false` al node `LIVENESS` o `AGE_ESTIMATION` a la [configuració de funcionalitats del flux de treball](https://docs.didit.me/ca/management-api/workflows/feature-configs.md#prova-de-vida).Amb el commutador desactivat, la puntuació de la selfie de prova de vida es continua calculant i la selfie es continua comparant 1:1 amb el retrat del document a Coincidència facial, però mai no arriba a l'índex de rostres:- No s'executa cap cerca, de manera que la sessió no obté cap veredicte de duplicat, de llista de bloqueig ni de llista permesa i el seu `liveness_checks[].matches` roman buit. Les regles de **Rostre duplicat**, **discrepància de nom**, **discrepància de document** i de rostres entre organitzacions no tenen res sobre el que actuar i s'amaguen a la consola.
- No s'emmagatzema cap plantilla biomètrica per a la selfie, de manera que sessions posteriors no es poden contrastar amb aquesta i no hi ha res que la [conservació de plantilles biomètriques](https://docs.didit.me/ca/console/data-retention.md#conservació-de-plantilles-biomètriques) hagi de mantenir un cop eliminada la sessió.
- La selfie no s'utilitza per resoldre una persona biomètrica compartida per a comprovacions entre organitzacions.
- La selfie presa durant la captura del document tampoc no se cerca (cap risc de llista de bloqueig o de duplicat `FRONT_CAMERA_*`): l'opció d'exclusió cobreix totes les selfies de la sessió. El commutador propi del pas de Verificació d'identitat (vegeu més amunt) també pot desactivar aquesta cerca pel seu compte.**A quin pas pertany el commutador.** El commutador es troba al pas que captura la selfie, de manera que un pas de **Liveness** o d'**Estimació d'edat** determina la configuració que li correspon. Un pas de **Coincidència facial** no en té cap de propi: quan un usuari torna a fer-se la selfie allà (després que li demanis que torni a enviar aquest pas, per exemple), la nova captura segueix la configuració del pas de Prova de vida, de manera que una exclusió manté la nova selfie fora de l'índex també. Si el teu flux de treball es ramifica en més d'un pas de Prova de vida, la configuració que s'aplica és la de la branca per la qual la sessió ha passat realment, i la lectura de rostres entre organitzacions segueix aquest mateix pas.Els fluxos de treball existents mantenen el comportament actual fins que hi renunciïs. El canvi s'aplica a les sessions iniciades després de desar el flux de treball; les plantilles emmagatzemades per sessions anteriors es mantenen a l'índex fins que aquestes sessions se suprimeixin o es purguin. Aquest canvi no afecta l'[API de Cerca facial](https://docs.didit.me/ca/standalone-apis/face-search.md) independent, que es crida explícitament.> [!WARNING]
>
> La teva llista de bloqueig facial s'aplica durant la verificació mitjançant la mateixa cerca 1:N. Amb Cerca facial desactivada al pas de Prova de vida, una persona a la llista de bloqueig no es detecta ni en aquest pas ni mitjançant la selfie presa durant la captura del document; amb la Cerca facial de captura silenciosa desactivada al pas de Verificació d'identitat, tampoc mitjançant aquesta selfie.### Accés a l'APILa funcionalitat de Cerca facial també està disponible mitjançant la nostra [API](https://docs.didit.me/ca/standalone-apis/face-search.md), cosa que et permet:- Enviar cerques facials programàticament
- Integrar capacitats de coincidència facial a les teves pròpies aplicacions
- Crear fluxos de treball personalitzats de detecció de frau
- Crear sistemes automatitzats per a la detecció de duplicats## Funcionalitats clau- **Alta precisió**: Algorismes biomètrics avançats que ofereixen resultats de coincidència fiables
- **Llindars configurables**: Personalitza la sensibilitat de la coincidència segons la teva tolerància al risc
- **Escaneig exhaustiu**: Cerca entre tots els teus usuaris verificats
- **Resultats ràpids**: Processa cerques ràpidament fins i tot amb bases de dades d'usuaris extenses
- **Centrat en la privadesa**: La comparació utilitza plantilles facials numèriques associades a la teva aplicació; l'índex mai surt de la teva organització### Llindars configurablesPots personalitzar la sensibilitat de la cerca definint diferents llindars per a les puntuacions de similitud:> [!NOTE]
>
> Aquests llindars es poden ajustar en funció de la teva tolerància al risc i dels teus requisits de seguretat.## Com funciona**1. Extracció facial**Quan s'inicia una cerca, el sistema processa la imatge de referència:| Procés | Descripció |
| - | - |
| **Extracció de característiques** | Aïlla les característiques facials de la imatge de referència |
| **Normalització** | Estandarditza les dades facials per a una comparació coherent |
| **Validació de qualitat** | Comprova la qualitat de la imatge i la claredat facial |
| **Codificació vectorial** | Crea una representació vectorial matemàtica de la cara |**2. Algorisme de comparació**El sistema cerca a tota la teva base de dades de sessions verificades:- Compara el vector facial de referència amb **cada cara registrada a la teva aplicació**: cares de sessions, cares pujades a perfils d'Usuari, les teves llistes facials i qualsevol plantilla biomètrica conservada
- Utilitza una arquitectura avançada de xarxes neuronals optimitzada per a la velocitat i la precisió
- Admet dos modes de cerca: **més similar** (llista ordenada) i **a la llista de bloqueig o aprovades** (filtrat per estat)
- Processa bases de dades extenses ràpidament mitjançant una indexació optimitzada**3. Puntuació de similitud**Per a cada comparació, es genera un percentatge de similitud:| Rang de puntuació | Interpretació |
| :-: | - |
| **90%+** | Coincidència forta — molt probablement la mateixa persona |
| **70–89%** | Possible coincidència — pot requerir revisió manual |
| **Menys del 70%** | Probablement persones diferents |Els llindars de coincidència configurats determinen quins resultats es marquen.**4. Lliurament de resultats**El sistema retorna un conjunt complet de resultats:- **Llista ordenada** de possibles coincidències ordenades per puntuació de similitud
- **Detalls de la coincidència** incloent l'ID de sessió, la data de verificació i les dades del proveïdor
- **Percentatge de similitud** per a cada coincidència
- **Imatges de la coincidència** disponibles per a la revisió visual
- **Estat a la llista de bloqueig** que indica si la cara coincident està a la llista de bloqueig## Sessions suprimides i plantilles biomètriques conservadesEn suprimir una sessió, se suprimeix el seu embedding facial per defecte, de manera que la persona desapareix de l'índex i pot tornar-se a verificar sense cap alerta de duplicat. Les aplicacions que suprimeixen sessions poc després de l'aprovació però que encara necessiten detectar altes repetides poden activar la [conservació de plantilles biomètriques](https://docs.didit.me/ca/console/data-retention.md#conservació-de-plantilles-biomètriques). Didit conserva llavors una plantilla biomètrica sense imatge vinculada a l'Usuari després que la sessió s'hagi suprimit, i aquesta plantilla participa en la Cerca facial i a la detecció automàtica de duplicats exactament com la cara d'una sessió activa.Una coincidència amb una plantilla conservada es notifica amb `source: "retained_template"`, el `vendor_user_id` i les `vendor_data` de l'Usuari propietari, i un `biometric_template_id`. No conté cap ID de sessió, imatge de coincidència, dades d'identitat ni estat de la sessió, perquè la sessió que va generar la cara ja no existeix. Les plantilles conservades mai s'afegeixen a la llista de bloqueig; les entrades de la llista de bloqueig facial mantenen el seu propi registre biomètric independent.La plantilla es manté fins a la seva caducitat programada, la supressió de l'Usuari, una sol·licitud d'eliminació per privadesa o una purga explícita mitjançant l'[API de plantilles biomètriques](https://docs.didit.me/ca/management-api/biometric-templates/overview.md) o a **Llistes → Plantilles biomètriques** a la Console.## Percentatge de similitudEl percentatge de similitud és la mètrica principal utilitzada per determinar possibles coincidències:- **Percentatge alt (típicament del 90% o superior)**: Indica una probabilitat alta que les cares pertanyin a la mateixa persona.
- **Percentatge mitjà (70-89%)**: Suggereix possibles coincidències que poden requerir una revisió addicional.
- **Percentatge baix (per sota del 70%)**: Probablement indica persones diferents.El llindar exacte del que constitueix una "coincidència" es pot configurar en funció dels teus requisits de seguretat. Augmentar el llindar redueix els falsos positius, però pot incrementar els falsos negatius.## Casos d'ús- **Prevenció de frau**: Identifica usuaris que intenten crear diversos comptes
- **KYC millorat**: Afegeix una capa addicional de verificació al teu procés de KYC
- **Compliment normatiu**: Compleix els requisits per detectar comptes duplicats
- **Control d'accés**: Verifica l'autenticitat dels usuaris en àrees d'alta seguretat
- **Cossos de seguretat**: Ajuda els organismes autoritzats a identificar persones d'interès


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