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

# Biometria d'usuaris: cerca facial i llista de bloqueig

> Didit associa la biometria facial a les entitats d'usuari del proveïdor: cerca 1:N, detecció de duplicats, llista de bloqueig i pujada manual.



Prompt de biometria facial
        Copia el prompt al porta-retalls



      
      

\<pre>

\````# Goal — search, blocklist, and act on User face biometrics

Faces are captured automatically during liveness inside a verification session, and can also be uploaded to an existing User profile when you are migrating users from another provider. You interact with biometrics through three action surfaces: **profile face upload** (attach an imported face to a User), **face search** (find a user by face), and the **Lists API** (blocklist a face so future sessions are auto-declined).

\## 1) Upload a face to an imported User profile

Use this when you already created or imported a User with `vendor_data` and have a trusted face image from your previous provider.

\```bash
\# 1. Get the Didit internal User id from vendor_data
curl https://verification.didit.me/v3/users/user-42/ \
-H "x-api-key: $DIDIT_API_KEY"

\# 2. Upload a base64-encoded face to that profile
curl -X POST https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/$DIDIT_INTERNAL_ID/faces/upload/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"image": "<base64-encoded-jpg-or-png>", "comment": "Imported from previous KYC provider"}'
\```

Limits: max 5 faces per User, max 2 MB per image, and the image must contain a detectable face. This enrolls the face for profile evidence and future duplicate/face-search matching. It does not blocklist the face.

\## 2) Face search — 1:N

Use to detect duplicate accounts, identify a face from a CCTV frame, or recognise a returning customer before running new KYC.

\```bash
curl -X POST https://verification.didit.me/v3/face-search/ \
-H "x-api-key: $DIDIT_API_KEY" \
-F "user_image=@./selfie.jpg"
\```

Response includes match candidates with similarity scores. Wire your workflow (in the console) to auto-decline / flag / warn on duplicate hits, or call this endpoint directly from your backend before creating a session.

\## 3) Face blocklist — block a user by face

To block a known bad actor going forward, upload their face to a **face-type list** in your application. Any future session whose liveness selfie matches the embedding is auto-declined.

\```bash
\# Upload a face directly to a face-type list (no session needed)
curl -X POST https://verification.didit.me/v3/lists/$LIST_UUID/entries/face-upload/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"image": "<base64-encoded-jpg-or-png>", "reason": "confirmed_fraud"}'
\```

If the face you want to block came from an existing session, use `POST /v3/lists/{list_uuid}/entries/` with `reference_session_id` instead — the backend extracts the biometric and links the entry back to the session.

Remove a face from the list with the Delete entry endpoint:

\```bash
curl -X DELETE https://verification.didit.me/v3/lists/$LIST_UUID/entries/$ENTRY_UUID/ \
-H "x-api-key: $DIDIT_API_KEY"
\```

The Lists API supports face, document, email, phone, and IBAN list types. See /management-api/lists/overview for the full catalog.

\## 4) Blocklisting after a decline

Declining a session adds the face to no blocklist: the User stays `ACTIVE` and no list entry is written, so a later session with the same face is decided by the workflow's own rules, not by a list match. To block a declined subject, upload the face to a face-type list yourself with the Lists API call above — a decline never does it for you.

\## 5) Where the face lives on the User

\- `portrait_image` on the User entity is a signed URL to the latest approved selfie.
\- Manually uploaded profile faces are listed under the User profile face collection and returned by the profile face list endpoint.
\- `approved_duplicate_status` on each face is one of `NOT_DUPLICATED` / `DUPLICATED`.
\- Embeddings (numeric vectors) are stored separately from the image. Deleting a session deletes the image and, by default, the embedding. An application that opted in to biometric-template retention keeps one image-free template anchored to the User after the session is deleted; it has a finite expiry and is purged on User deletion, a privacy-erasure deletion (deletion_instruction: "privacy_erasure"), or an explicit purge via /v3/biometric-templates/ (see /management-api/biometric-templates/overview).

\## Failure modes

\- `400` from face-search / upload-face — image has no detectable face, multiple faces, or is too low-quality. Re-capture and retry.
\- `404` on Lists API — wrong `list_id` or list deleted.
\- `403` — your role lacks permission on the `lists` resource.
\- `429` — rate-limited.

\## Response shape

See /standalone-apis/face-search and /management-api/lists/upload-face for full schemas. Match objects use `similarity` (0–1) and reference the linked User `vendor_data` when known.

\## Sources of truth

\- /management-api/users/upload-face — attach an imported face to a User profile
\- /standalone-apis/face-search — face search request / response
\- /management-api/lists/upload-face — face blocklist upload
\- /management-api/lists/delete-entry — remove from list
\- /management-api/biometric-templates/overview — templates retained after session deletion
\- /core-technology/face-search/overview — search behaviour
\- /core-technology/liveness/overview — face capture during sessions
\- /integration/integration-prompt — canonical end-to-end prompt````

\</pre>



      
      

Enganxa a

La biometria facial és fonamental per a cada entitat User. Didit captura una cara durant la [prova de vida](https://docs.didit.me/ca/core-technology/liveness/overview.md), genera un embedding vectorial i l'emmagatzema per a quatre funcionalitats posteriors: **cerca facial 1:N**, **detecció de duplicats**, **aplicació de la llista de bloqueig** i **reautenticació biomètrica**.> [!NOTE]
>
> Les cares emmagatzemades també serveixen de referència per a l'[Autenticació biomètrica](https://docs.didit.me/ca/core-technology/biometric-auth/overview.md): crea una sessió d'autenticació biomètrica amb el `vendor_data` de l'usuari i omet `portrait_image`, i Didit reutilitza automàticament la cara emmagatzemada (primer la cara de la prova de vida aprovada, després la foto del xip del passaport electrònic, després el retrat del document d'identitat i, finalment, una cara de perfil inscrita manualment).## Com s'associen les cares a un usuari**1. Capturada durant la prova de vida**Quan un User fa una sessió amb la prova de vida activada, Didit captura un selfie, executa la prova de vida passiva, extreu la cara més gran i genera un embedding vectorial per a la cerca.**2. Emmagatzemada al perfil d'usuari**La cara s'enllaça a la sessió i a l'entitat User pare. La URL del retrat apareix al perfil d'usuari com a `portrait_image`.**3. Indexada per a la cerca**L'embedding s'afegeix a l'índex de cerca. Les sessions posteriors poden fer cerques 1:N en aquest índex.## Cerca facial (1:N)La cerca facial et permet trobar un usuari pujant una imatge i comparant-la amb totes les cares inscrites a la teva aplicació.Casos d'ús:- **Detecció de duplicats** durant l'alta: evita que la mateixa persona creï dos comptes.
- **Cerca inversa**: identifica l'usuari que hi ha darrere d'un fotograma de CCTV o d'una imatge en una investigació de frau.
- **Reconeixement de clients habituals**: omet el KYC per a un client que torna.La cerca facial s'executa automàticament durant les sessions noves quan el teu flux de treball té la detecció de duplicats activada. També s'ofereix com a API independent:- `POST /v3/face-search/`: [cerca facial independent](https://docs.didit.me/ca/standalone-apis/face-search.md)## Detecció de duplicatsCada cara nova es pot comparar amb les cares inscrites existents per detectar duplicats. Didit assigna a cada cara un `approved_duplicate_status`:| Estat | Significat |
| - | - |
| `NOT_DUPLICATED` | No s'han trobat coincidències per sobre del llindar de similitud |
| `DUPLICATED` | La cara coincideix amb una o més cares d'una sessió ja aprovada |Els fluxos de treball es poden configurar per:- **Rebutjar** automàticament les sessions marcades com a duplicades.
- **Marcar per revisar**: enviar la sessió a un analista humà.
- **Només advertir**: permetre la sessió però afegir una etiqueta de risc.Configura-ho a la consola a *Workflows → \[el teu flux de treball] → Face Match / Liveness → Duplicate detection*.## Llista de bloqueig facialRebutjar una sessió no afegeix la cara a cap llista de bloqueig. Per rebutjar sessions futures amb la mateixa cara, bloqueja-la tu mateix: afegeix-la des de la [pàgina de la llista de bloqueig](https://docs.didit.me/ca/console/blocklist-users.md) o amb l'[API de llistes](https://docs.didit.me/ca/management-api/lists/overview.md). Una sessió nova amb un selfie de prova de vida que coincideixi amb aquesta entrada es rebutja automàticament.## Pujar una cara importada a un perfil d'usuariSi estàs migrant des d'un altre proveïdor de KYC, pots crear primer el User i després adjuntar-li a aquest perfil una imatge facial fiable. El User continua identificat pel teu `vendor_data`, però l'endpoint de pujada de cares utilitza l'identificador intern del User de Didit (`didit_internal_id`) perquè el destí no sigui ambigu.**1. Crea o recupera el User**Crida [`POST /v3/users/create/`](https://docs.didit.me/ca/management-api/users/create) amb el teu `vendor_data` estable, o crida `GET /v3/users/{vendor_data}/` si el User ja existeix.**2. Llegeix didit\_internal\_id**La resposta del User inclou `didit_internal_id`. Continua utilitzant `vendor_data` al teu propi sistema; utilitza `didit_internal_id` només per als endpoints d'adjunció de perfils.**3. Puja la cara**Crida [`POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`](https://docs.didit.me/ca/management-api/users/upload-face) amb una imatge facial codificada en base64.```bash theme={null}
# 1. Create or retrieve the User keyed by your vendor_data
curl -X POST https://verification.didit.me/v3/users/create/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data": "user-42",
    "display_name": "Jane Doe",
    "metadata": { "previous_provider": "legacy-kyc-vendor" }
  }'

# Response includes:
# { "didit_internal_id": "11111111-2222-3333-4444-555555555555", ... }

# 2. Upload the imported face to the User profile
curl -X POST https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/11111111-2222-3333-4444-555555555555/faces/upload/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "<base64-encoded-jpg-or-png>",
    "comment": "Imported from previous KYC provider"
  }'
```Les cares importades al perfil s'inscriuen al mateix índex facial que s'utilitza per a la detecció de duplicats i la cerca facial. No s'afegeixen automàticament a cap llista de bloqueig. Per bloquejar un mal actor conegut, puja la cara a una llista de cares.> [!WARNING]
>
> Puja només cares que tinguis permís per tractar d'acord amb el teu propi avís de privacitat i el teu acord de migració. Conserva els identificadors del proveïdor d'origen a `metadata` o `comment` només quan es puguin exposar de manera segura als teus operadors de compliment.### Com es produeix el bloqueig| Activador | Acció |
| - | - |
| Sessió `DECLINED` | No s'afegeix res a cap llista de bloqueig; el User continua `ACTIVE` |
| L'analista bloqueja manualment una cara des de la consola | La cara s'afegeix i l'estat de l'usuari s'actualitza segons la política |
| Addició programàtica mitjançant l'API de llistes | Puja la imatge de la cara a una llista de bloqueig de tipus facial |### Pujar una cara a la llista de bloqueigPer bloquejar un usuari per la seva cara de manera programàtica, puja la imatge de la cara a una llista de bloqueig de tipus facial mitjançant l'endpoint dedicat [Pujar cara a la llista](https://docs.didit.me/ca/management-api/lists/upload-face.md). Didit extreu l'embedding biomètric i l'insereix a l'índex de coincidències: qualsevol sessió futura amb un selfie de prova de vida que coincideixi es rebutja automàticament.> [!NOTE]
>
> Pujar una cara al perfil i pujar una cara a la llista de bloqueig són operacions diferents. Utilitza la pujada al perfil per adjuntar a un User una cara importada fiable com a evidència, per a la detecció de duplicats i per a la cerca facial. Utilitza l'[API de llistes](https://docs.didit.me/ca/management-api/lists/overview.md) per bloquejar una cara perquè les sessions coincidents futures es rebutgin.### Eliminar una cara de la llista de bloqueigElimina l'entrada des de la consola a *Blocklist → Faces → row actions → Remove*, o utilitza l'endpoint [Eliminar entrada](https://docs.didit.me/ca/management-api/lists/delete-entry.md).## Plantilles biomètriques retingudes després de la supressió de sessionsSi elimines una sessió, se suprimeixen la imatge de la cara i, per defecte, l'embedding facial, de manera que la persona deixa d'aparèixer en la detecció de duplicats i en la Cerca facial. Si elimines sessions poc després de l'aprovació però encara necessites detectar registres repetits, activa la [retenció de plantilles biomètriques](https://docs.didit.me/ca/console/data-retention.md#conservació-de-plantilles-biomètriques) a l'aplicació o envia `retain_face_embeddings: true` en la crida de supressió.Aleshores, Didit elimina la sessió i totes les seves dades com de costum, i conserva una única plantilla biomètrica facial gestionada per separat i sense imatge, vinculada a l'Usuari:- Conté només la plantilla facial numèrica i les metadades de retenció. Mai no conté la imatge de la cara, el vídeo de prova de vida, les dades del document, els camps d'identitat extrets, la decisió ni l'id de la sessió suprimida.
- Participa en la detecció de duplicats, la Cerca facial, l'autenticació biomètrica i les teves llistes facials exactament igual que una cara d'una sessió activa. Les coincidències s'informen amb `source: "retained_template"`, el `vendor_user_id` i el `vendor_data` de l'Usuari, i un `biometric_template_id`.
- És una dada biomètrica amb un `expires_at` finit. Es purga quan se suprimeix l'Usuari, quan se suprimeix qualsevol sessió d'aquest Usuari amb `deletion_instruction: "privacy_erasure"`, quan caduca, o quan la purgues a **Llistes → Plantilles biomètriques** o mitjançant l'[API de plantilles biomètriques](https://docs.didit.me/ca/management-api/biometric-templates/overview.md).
- Una sessió creada sense `vendor_data` no té cap Usuari al qual vincular una plantilla; en suprimir-la s'informa `ineligible_no_vendor_user` i l'embedding se suprimeix amb la sessió.
- Les plantilles retingudes mai no s'inclouen a la llista de bloqueig. Una entrada de la llista de bloqueig creada a partir de la sessió suprimida conserva la seva pròpia entrada biomètrica independent i el seu propi cicle de vida.Les plantilles vinculades a un Usuari apareixen al perfil de l'Usuari, a **Plantilles biomètriques**, amb una acció de purga.## Resum del cicle de vida facial```mermaid theme={null}
stateDiagram-v2
    [*] --> Enrolled: Face captured during liveness
    Enrolled --> Approved: Session approved
    Enrolled --> Declined: Session declined
    Enrolled --> Duplicated: 1:N search finds match
    Duplicated --> Approved: Allowed by workflow
    Duplicated --> Declined: Rejected by workflow
    Enrolled --> Blocklisted: Face uploaded to a face-type list
    Declined --> [*]: Nothing blocklisted
    Blocklisted --> [*]: Manually removed
    Approved --> [*]: Session deleted (default)
    Approved --> RetainedTemplate: Session deleted with retention enabled
    RetainedTemplate --> [*]: Expiry, User deletion, privacy erasure, or purge
```## Puja una cara des de la consolaEls operadors de compliment poden pujar cares manualment:1) Navega fins a *Usuaris → \[usuari] → Accions → Puja una cara*.
2) Selecciona una imatge; Didit extreu la cara més gran i emmagatzema un nou registre de cara vinculat a l'usuari.
3) La cara queda registrada per a l'evidència del perfil, la detecció de duplicats i la cerca facial. Utilitza l'àrea de llistes de bloqueig quan l'objectiu sigui rebutjar les sessions futures que coincideixin.Això és útil quan:- Tens un retrat conegut d'un client verificat per un canal fora de línia.
- Vols preomplir una llista de bloqueig amb actors maliciosos coneguts de la teva base de dades de frau.## Privacitat i retenció- Els embeddings facials són vectors numèrics, no imatges. Les imatges en si s'emmagatzemen en un emmagatzematge d'objectes xifrat, amb accés mitjançant URL signades. Un embedding facial és una dada biomètrica.
- La retenció segueix la política de [conservació de dades](https://docs.didit.me/ca/console/data-retention.md) de la teva aplicació. Les plantilles biomètriques retingudes segueixen el període finit i més estricte de [retenció de plantilles biomètriques](https://docs.didit.me/ca/console/data-retention.md#conservació-de-plantilles-biomètriques).
- En suprimir una sessió se suprimeixen la imatge i, per defecte, l'embedding. Si la teva aplicació ha optat per la retenció de plantilles biomètriques, en suprimir una sessió es conserva una plantilla sense imatge fins que caduqui o es purgui.
- Per a una sol·licitud de dret a l'oblit del RGPD / CCPA, suprimeix les sessions de la persona amb `deletion_instruction: "privacy_erasure"` o suprimeix l'Usuari: en tots dos casos es purguen també totes les plantilles retingudes. Les entrades de la llista de bloqueig facial que gestiones es conserven fins que les eliminis.## Següents passos> [card] [Cerca facial](https://docs.didit.me/ca/core-technology/face-search/overview.md)
>
> Com funciona la cerca facial 1:N.> [card] [Prova de vida](https://docs.didit.me/ca/core-technology/liveness/overview.md)
>
> La prova de vida que captura la cara.> [card] [API de llista de bloqueig](https://docs.didit.me/ca/management-api/lists/upload-face.md)
>
> Puja una cara a una llista de bloqueig.> [card] [Plantilles biomètriques](https://docs.didit.me/ca/management-api/biometric-templates/overview.md)
>
> Plantilles retingudes després de la supressió de sessions.> [card] [Llista de bloqueig d'usuaris](https://docs.didit.me/ca/entities/users/blocklist.md)
>
> Com funciona el bloqueig d'un usuari.


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