> ## 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: report e corrispondenze JSON

> Report di Ricerca facciale 1:N di Didit: ID sessione, percentuali di somiglianza, flag blocklist e dettagli utente per indagini sulle frodi.

## Panoramica

La Ricerca facciale è una ricerca biometrica **1:N**: Didit prende il volto più grande rilevato nella tua `user_image` e lo cerca all'interno dell'indice di ricerca facciale della tua applicazione — volti registrati da sessioni di verifica, chiamate API autonome salvate, caricamenti diretti di volti nel profilo utente e le tue blocklist e allowlist. È diversa dal Confronto facciale, che è **1:1** — il Confronto facciale confronta un selfie con la foto presente su un documento specifico, mentre la Ricerca facciale si chiede: "abbiamo già visto questa persona da qualche parte in precedenza?".

È importante comprendere due comportamenti prima di analizzare il report:

* **Solo le corrispondenze con la blocklist comportano un rifiuto.** `face_search.status` è `Declined` solo quando scatta un avviso `FACE_IN_BLOCKLIST` o `POSSIBLE_FACE_IN_BLOCKLIST`. Le sole corrispondenze duplicate restituiscono `Approved` — esamina `matches` e `warnings`, non solo `status`.
* **Persistenza e registrazione facoltative.** Quando `save_api_request=true` (impostazione predefinita), la chiamata viene salvata come sessione di tipo API e il volto cercato viene registrato nel tuo indice di ricerca facciale. I volti registrati dalle chiamate di Ricerca facciale sono **esclusi dai risultati futuri della Ricerca facciale**, in modo che ricerche ripetute non corrispondano mai tra loro. Passa `save_api_request=false` per una query una tantum: non viene memorizzato nulla e il volto non viene registrato.

## Dove compaiono i risultati

La Ricerca facciale è un'API autonoma. I risultati della ricerca vengono restituiti **in modo sincrono, unicamente nella risposta `POST /v3/face-search/`**, come singolo oggetto `face_search` a livello principale:

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

Non esiste alcun array al plurale `face_searches[]` — la convenzione degli array al plurale usata da `id_verifications[]`, `aml_screenings[]` e `liveness_checks[]` sull'endpoint di decisione della sessione non si applica qui.

Quando `save_api_request=true` (impostazione predefinita), la chiamata viene salvata anche come sessione di tipo API:

* **Business Console** — la sessione compare nell'elenco delle tue sessioni con l'immagine di ricerca, le corrispondenze e gli avvisi.
* **`GET /v3/session/{sessionId}/decision/`** — recuperabile utilizzando il `request_id` restituito come id di sessione. I dati salvati emergono come voce `FACE_SEARCH` in `features[]` e come elemento di `liveness_checks[]` che contiene i `matches` salvati (con valori `match_image_url` appena firmati) e i `warnings` — **non** come oggetto `face_search`.

Quando `save_api_request=false`, `request_id` è un UUID di correlazione temporaneo: la sessione non viene mai salvata, quindi non può essere recuperata dalla Console o dall'endpoint di decisione.

## Schema

Consulta [Ricerca facciale nel riferimento ai modelli di dati](https://docs.didit.me/it/reference/data-models.md#ricerca-facciale) per le tabelle canoniche dei campi. La struttura riportata di seguito riflette ciò che l'endpoint restituisce effettivamente in fase di esecuzione.

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

Note sui campi:

* **`matches[]` è limitato a 5** voci al di sopra della soglia minima di somiglianza, ordinate per somiglianza decrescente (`search_type=blocklisted_or_approved` posiziona per prime le voci in blocklist, poi quelle in allowlist, quindi per somiglianza).
* **`source`** indica l'origine di registrazione del volto corrispondente: `session` — una sessione di verifica o una chiamata API autonoma salvata; `imported` — un volto caricato direttamente su un profilo utente; `list_entry` — un volto associato a una delle tue liste; `retained_template` — un [modello biometrico](https://docs.didit.me/it/management-api/biometric-templates/overview.md) senza immagini che l'applicazione ha conservato dopo l'eliminazione della sessione di origine. `session_id`, `session_number`, `status` e `api_service` sono `null` per le corrispondenze di tipo `imported`, `list_entry` e `retained_template`.
* Le corrispondenze **`retained_template`** includono `vendor_user_id`, `vendor_data` e `biometric_template_id`, e sono sempre `null` per `match_image_url`, `user_details` e qualsiasi dato relativo alla sessione: la sessione che ha generato il volto non esiste più e il modello non contiene immagini né dati identificativi. `is_blocklisted` è sempre `false` per un modello biometrico conservato; un volto in blocklist viene segnalato separatamente come corrispondenza `list_entry`. Rimuovi il modello con `DELETE /v3/biometric-templates/{biometric_template_id}/`.
* **`api_service`** è il tipo di API autonoma della sessione corrispondente (in maiuscolo, ad es. `PASSIVE_LIVENESS`) e `null` quando il volto corrispondente proviene da una normale sessione di verifica del workflow.
* **`user_details`** proviene dalla verifica del documento della sessione corrispondente. Per le corrispondenze con `source: imported` viene invece compilato a partire dal profilo utente (`full_name` impostato, `document_type`/`document_number` null); è `null` quando non esistono dati identificativi (ad esempio nelle sessioni con il solo Rilevamento della vitalità).
* **Gli avvisi utilizzano una struttura ridotta** rispetto agli avvisi del workflow: non è presente alcun `node_id`. Il contratto di risposta documentato (`FaceSearchResponseSerializer`) dichiara i cinque campi `risk`, `additional_data`, `log_type`, `short_description`, `long_description`; il payload di runtime include inoltre `feature`, che qui è sempre `"LIVENESS"`. Consulta [Avvisi di Ricerca facciale](https://docs.didit.me/it/core-technology/face-search/warnings-face-search.md).
* **Le corrispondenze con lo stesso utente non sono escluse** — a differenza del rilevamento dei duplicati nei workflow, l'endpoint autonomo non esclude le sessioni precedenti con lo stesso `vendor_data`, quindi un utente legittimo che ritorna trova corrispondenze nelle proprie sessioni precedenti.

## Valori di stato

Il valore di `face_search.status` a livello principale è derivato da `warnings[]`. Lo `status` a livello di corrispondenza riflette l'esito della verifica della **sessione corrispondente** ed è indipendente.

| Valore | Quando compare |
| - | - |
| `Approved` | Non è scattato alcun avviso relativo alla blocklist. Include il caso in cui siano state trovate corrispondenze duplicate — i duplicati sono segnali informativi, non rifiuti. |
| `Declined` | È scattato un avviso `FACE_IN_BLOCKLIST` o `POSSIBLE_FACE_IN_BLOCKLIST` — l'immagine cercata corrisponde a un volto presente nella tua blocklist di volti. |

Nota: quando l'immagine cercata non contiene alcun volto rilevabile, l'API restituisce HTTP `400` con `{"error": "No face detected in the image"}` **prima** che venga creato un oggetto `face_search` — non esiste alcuno stato `Declined` per questo caso. Crediti insufficienti restituiscono HTTP `403` prima di qualsiasi elaborazione delle immagini.

## Esempi

### Approvata — corrispondenza duplicata, nessuna blocklist

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

### Rifiutata — corrispondenza con blocklist

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

## Correlati

* [Avvisi di Ricerca facciale](https://docs.didit.me/it/core-technology/face-search/warnings-face-search.md) — ogni codice di avviso che la ricerca può emettere
* [Riferimento API di Ricerca facciale](https://docs.didit.me/it/standalone-apis/face-search.md) — parametri di richiesta e modalità `search_type`
* [Modelli di dati — Ricerca facciale](https://docs.didit.me/it/reference/data-models.md#ricerca-facciale) — schema canonico
* [Webhook](https://docs.didit.me/it/integration/webhooks.md) — payload `status.updated` per le sessioni persistenti

> [!NOTE]
>
> Quando `save_api_request=true`, i valori di `match_image_url` sono URL firmati e di breve durata — effettua nuovamente una richiesta all'endpoint di decisione della sessione con il `request_id` restituito per ottenerne di nuovi. Quando `save_api_request=false`, sono percorsi di archiviazione interni e non sono scaricabili direttamente. Memorizza solo l'id della sessione corrispondente, lo stato e `similarity_percentage` sul tuo sistema — non conservare l'immagine biometrica sottostante.


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