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

# Informe de cerca facial 1:N: coincidències en JSON

> Referència de l'informe de cerca facial 1:N de Didit: ID de sessions, similitud, alertes de llista de bloqueig i detalls per investigar fraus.

## Visió general

La Cerca facial és una cerca biomètrica **1:N**: Didit agafa la cara detectada més gran de la teva `user_image` i la cerca a l'índex de cerca facial de la teva aplicació — cares registrades a partir de sessions de verificació, crides d'API independents desades, càrregues directes de cares al perfil d'usuari i les teves llistes de bloqueig i d'autorització. És diferent de la Coincidència facial, que és **1:1** — la Coincidència facial compara una selfie amb el retrat d'un document específic, mentre que la Cerca facial planteja la pregunta: «hem vist abans aquesta persona en algun lloc?».

Hi ha dos comportaments que convé entendre abans d'analitzar l'informe:

* **Només les coincidències amb la llista de bloqueig provoquen un rebuig.** `face_search.status` és `Declined` només quan s'activa una advertència `FACE_IN_BLOCKLIST` o `POSSIBLE_FACE_IN_BLOCKLIST`. Les coincidències duplicades per si soles retornen `Approved` — inspecciona `matches` i `warnings`, no només `status`.
* **Persistència i registre opcionals.** Quan `save_api_request=true` (per defecte), la crida es desa com una sessió de tipus API i la cara cercada es registra a l'índex de cerca facial. Les cares registrades mitjançant crides de Cerca facial s'**exclouen dels futurs resultats de la Cerca facial**, de manera que les cerques repetides mai no coincideixen entre si. Passa `save_api_request=false` per a una consulta d'un sol ús: no s'emmagatzema res i la cara no es registra.

## On apareixen els resultats

La Cerca facial és una API independent. Els resultats de la cerca es retornen **de manera síncrona, únicament a la resposta de `POST /v3/face-search/`**, com un objecte singular `face_search` al nivell superior:

```text theme={null}
POST /v3/face-search/  ──▶  { "request_id": …, "face_search": { … }, "vendor_data": …, "metadata": …, "created_at": … }
```

No hi ha cap matriu en plural `face_searches[]` enlloc — la convenció de matrius en plural emprada per `id_verifications[]`, `aml_screenings[]` i `liveness_checks[]` a l'endpoint de decisió de sessió no s'aplica aquí.

Quan `save_api_request=true` (per defecte), la crida també es desa com una sessió de tipus API:

* **Consola empresarial** — la sessió apareix a la teva llista de sessions amb la imatge de cerca, les coincidències i les advertències.
* **`GET /v3/session/{sessionId}/decision/`** — recuperable mitjançant el `request_id` retornat com a ID de sessió. Les dades persistides es mostren com una entrada `FACE_SEARCH` a `features[]` i com un element de `liveness_checks[]` que conté les `matches` emmagatzemades (amb valors de `match_image_url` signats recentment) i `warnings` — **no** pas com un objecte `face_search`.

Quan `save_api_request=false`, `request_id` és un UUID de correlació transitori: la sessió no s'emmagatzema mai, de manera que no es pot obtenir des de la Consola ni des de l'endpoint de decisió.

## Esquema

Consulta [Cerca facial a la referència de models de dades](https://docs.didit.me/ca/reference/data-models.md#cerca-facial) per a les taules de camps canòniques. L'estructura següent reflecteix el que l'endpoint retorna realment en temps d'execució.

```typescript theme={null}
interface FaceSearchResponse {
  request_id: string;            // UUID — the persisted session id when save_api_request=true
  face_search: {
    status: 'Approved' | 'Declined';
    total_matches: number;       // 0-5, length of matches[]
    matches: FaceSearchMatch[];  // capped at 5, ordered by similarity
    user_image: {                // always present
      entities: {
        bbox: [number, number, number, number];
        confidence: number;      // 0-1, one entry per detected face
      }[];
      best_angle: 0 | 90 | 180 | 270;
    };
    warnings: Warning[];
  };
  vendor_data: string | null;    // echoed from the request
  metadata: object | null;       // echoed from the request
  created_at: string;            // ISO 8601, e.g. "2026-06-12T01:04:42.763237+00:00"
}

interface FaceSearchMatch {
  session_id: string | null;     // UUID of the matched session; null for non-session matches
  session_number: number | null; // Console-friendly number; null for non-session matches
  similarity_percentage: number; // 0-100
  source: 'session' | 'imported' | 'list_entry' | 'retained_template';
  vendor_data: string | null;    // the matched session's, imported profile's, or retained template's User vendor_data
  vendor_user_id: string | null; // UUID of the linked User; null for list_entry matches and sessions without a User
  biometric_template_id: string | null; // set only for retained_template matches
  verification_date: string | null;  // "YYYY-MM-DDThh:mm:ssZ"; null for list_entry matches; the retention date for retained_template matches
  user_details: {
    full_name: string | null;
    document_type: string | null;
    document_number: string | null;
  } | null;                      // null when the matched session has no document data
  match_image_url: string | null; // signed URL when save_api_request=true; raw storage path otherwise; null for retained_template matches
  status: 'Approved' | 'Declined' | 'In Review' | null;  // the matched session's status
  is_blocklisted: boolean;
  is_allowlisted: boolean;
  api_service: 'ID_VERIFICATION' | 'FACE_MATCH' | 'AGE_ESTIMATION' | 'POA' | 'AML'
             | 'PASSIVE_LIVENESS' | 'DATABASE_VALIDATION' | 'PHONE_VERIFICATION'
             | 'EMAIL_VERIFICATION' | null;  // null when the match comes from a workflow session
}

interface Warning {
  risk: string;
  feature: 'LIVENESS';           // always LIVENESS on this endpoint
  additional_data: object | null;
  log_type: 'error' | 'warning' | 'information';
  short_description: string;
  long_description: string;
}
```

Notes sobre els camps:

* **`matches[]` té un límit de 5** entrades per sobre del llindar mínim de similitud, ordenades per similitud descendent (`search_type=blocklisted_or_approved` classifica primer les entrades a la llista de bloqueig, després les de la llista d'autorització i finalment per similitud).
* **`source`** indica d'on s'ha registrat la cara coincident: `session` — una sessió de verificació o una crida d'API independent desada; `imported` — una cara carregada directament a un perfil d'usuari; `list_entry` — una cara associada a una de les teves llistes; `retained_template` — una [plantilla biomètrica](https://docs.didit.me/ca/management-api/biometric-templates/overview.md) sense imatge que l'aplicació ha conservat després d'eliminar la sessió d'origen. `session_id`, `session_number`, `status` i `api_service` són `null` per a coincidències de tipus `imported`, `list_entry` i `retained_template`.
* **Les coincidències de tipus `retained_template`** contenen `vendor_user_id`, `vendor_data` i `biometric_template_id`, i sempre són `null` per a `match_image_url`, `user_details` i tot el que estigui relacionat amb la sessió: la sessió que va generar la cara ja no existeix i la plantilla no conté cap imatge ni dada d'identitat. `is_blocklisted` sempre és `false` per a una plantilla retinguda; una cara a la llista de bloqueig es notifica per separat com una coincidència de tipus `list_entry`. Purga la plantilla amb `DELETE /v3/biometric-templates/{biometric_template_id}/`.
* **`api_service`** és el tipus d'API independent de la sessió coincident (en majúscules, p. ex. `PASSIVE_LIVENESS`) i `null` quan la cara coincident prové d'una sessió de verificació estàndard de flux de treball.
* **`user_details`** prové de la verificació documental de la sessió coincident. Per a coincidències amb `source: imported`, s'obté del perfil d'usuari (`full_name` definit, `document_type`/`document_number` com a null); és `null` quan no hi ha dades d'identitat (per exemple, sessions de només prova de vida).
* **Les advertències utilitzen una estructura reduïda** en comparació amb les advertències dels fluxos de treball: no hi ha cap `node_id`. El contracte de resposta documentat (`FaceSearchResponseSerializer`) declara els cinc camps `risk`, `additional_data`, `log_type`, `short_description` i `long_description`; el payload en temps d'execució inclou addicionalment `feature`, que aquí sempre és `"LIVENESS"`. Consulta [Advertències de Cerca facial](https://docs.didit.me/ca/core-technology/face-search/warnings-face-search.md).
* **No s'exclouen les coincidències del mateix usuari** — a diferència de la detecció de duplicats dels fluxos de treball, l'endpoint independent no filtra sessions anteriors amb el mateix `vendor_data`, de manera que un usuari legítim que torna coincideix amb les seves pròpies sessions anteriors.

## Valors d'estat

El camp `face_search.status` de nivell superior es deriva de `warnings[]`. L'estat `status` de la coincidència reflecteix el resultat de la verificació de la **sessió coincident** i és independent.

| Valor | Quan apareix |
| - | - |
| `Approved` | No s'ha activat cap advertència de llista de bloqueig. Inclou el cas en què s'han trobat coincidències duplicades — els duplicats són senyals informatius, no rebutjos. |
| `Declined` | S'ha activat una advertència `FACE_IN_BLOCKLIST` o `POSSIBLE_FACE_IN_BLOCKLIST` — la imatge de cerca ha coincidit amb una cara de la teva llista de bloqueig de cares. |

Nota: quan la imatge de cerca no conté cap cara detectable, l'API retorna HTTP `400` amb `{"error": "No face detected in the image"}` **abans** que es construeixi un objecte `face_search` — no hi ha cap estat `Declined` per a aquest cas. Un saldo de crèdits insuficient retorna HTTP `403` abans de qualsevol processament de la imatge.

## Exemples

### Aprovada — coincidència duplicada, sense llista de bloqueig

```json theme={null}
{
  "request_id": "5e0c3a1f-7b2d-4c8e-9f10-2a3b4c5d6e7f",
  "face_search": {
    "status": "Approved",
    "total_matches": 1,
    "matches": [
      {
        "session_id": "1f2e3d4c-5b6a-7980-1122-334455667788",
        "session_number": 1024,
        "similarity_percentage": 87.42,
        "source": "session",
        "vendor_data": "user-9",
        "verification_date": "2025-11-20T09:15:00Z",
        "user_details": {
          "full_name": "Jane Marie Doe",
          "document_type": "Passport",
          "document_number": "X1234567"
        },
        "match_image_url": "https://<media-host>/face/9c8b7a6d/reference.jpg?signature=...",
        "status": "Approved",
        "is_blocklisted": false,
        "is_allowlisted": false,
        "api_service": null
      }
    ],
    "user_image": {
      "entities": [
        {
          "bbox": [40, 40, 120, 120],
          "confidence": 0.732973
        }
      ],
      "best_angle": 0
    },
    "warnings": [
      {
        "risk": "DUPLICATED_FACE",
        "feature": "LIVENESS",
        "additional_data": {
          "duplicated_session_id": "1f2e3d4c-5b6a-7980-1122-334455667788",
          "duplicated_session_number": 1024,
          "api_service": null
        },
        "log_type": "information",
        "short_description": "Duplicated face from other approved session",
        "long_description": "The system identified a duplicated face from another approved session, requiring further investigation."
      }
    ]
  },
  "vendor_data": "user-123",
  "metadata": null,
  "created_at": "2026-06-12T01:04:42.763237+00:00"
}
```

### Rebutjada — coincidència amb la llista de bloqueig

```json theme={null}
{
  "request_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "face_search": {
    "status": "Declined",
    "total_matches": 1,
    "matches": [
      {
        "session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86",
        "session_number": 323442,
        "similarity_percentage": 99.99,
        "source": "session",
        "vendor_data": "user-1",
        "verification_date": "2025-01-01T00:00:00Z",
        "user_details": {
          "full_name": "Jane Marie Doe",
          "document_type": "ID",
          "document_number": "X1234567"
        },
        "match_image_url": "https://<media-host>/face/3f6a1c2e/reference.jpg?signature=...",
        "status": "Approved",
        "is_blocklisted": true,
        "is_allowlisted": false,
        "api_service": "PASSIVE_LIVENESS"
      }
    ],
    "user_image": {
      "entities": [
        {
          "bbox": [40, 40, 120, 120],
          "confidence": 0.732973
        }
      ],
      "best_angle": 0
    },
    "warnings": [
      {
        "risk": "FACE_IN_BLOCKLIST",
        "feature": "LIVENESS",
        "additional_data": {
          "blocklisted_session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86",
          "blocklisted_session_number": 323442,
          "api_service": "PASSIVE_LIVENESS"
        },
        "log_type": "error",
        "short_description": "Face in blocklist",
        "long_description": "The system identified a face in the blocklist, which means the face is not allowed to be verified."
      }
    ]
  },
  "vendor_data": "user-123",
  "metadata": null,
  "created_at": "2026-06-12T01:04:42.763237+00:00"
}
```

## Relacionat

* [Advertències de Cerca facial](https://docs.didit.me/ca/core-technology/face-search/warnings-face-search.md) — tots els codis d'advertència que pot emetre la cerca
* [Referència de l'API de Cerca facial](https://docs.didit.me/ca/standalone-apis/face-search.md) — paràmetres de la sol·licitud i modes de `search_type`
* [Models de dades — Cerca facial](https://docs.didit.me/ca/reference/data-models.md#cerca-facial) — esquema canònic
* [Webhooks](https://docs.didit.me/ca/integration/webhooks.md) — payloads de `status.updated` per a sessions persistides

> [!NOTE]
>
> Quan `save_api_request=true`, els valors de `match_image_url` són URL signades i de curta durada — torna a cridar l'endpoint de decisió de la sessió amb el `request_id` retornat per obtenir-ne de noves. Quan `save_api_request=false`, són rutes d'emmagatzematge intern i no es poden descarregar directament. Emmagatzema només l'id de la sessió coincident, l'estat i `similarity_percentage` al teu costat — no conservis la imatge biomètrica subjacent.


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