> ## 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. # API elenco sessioni: filtri per sessioni KYC e KYB > Elenca le sessioni di verifica con GET /v3/sessions/ e filtra per tipo, stato, workflow e dati vendor. API KYC e KYB unificata di Didit a consumo. Prompt per elencare le sessioni Copia il prompt negli appunti \

\`List Didit verification sessions for your application with filters and pagination.

Endpoint:
GET https://verification.didit.me/v3/sessions

Authentication:
Use the x-api-key header with your Didit API key. The key must hold read:sessions.

Query parameters:
\- session_kind ("user" | "business" | "all", default "user") — chooses which kind to list. "user" returns only KYC sessions (backward-compatible default). "business" returns only KYB. "all" concatenates both (KYB rows are appended; not interleaved by timestamp).
\- vendor_data (string) — exact match on your stable identifier.
\- didit_internal_id (UUID) — matches vendor_user_id.
\- status (one or more, comma-separated) — Approved, Declined, In Review, In Progress, Not Started, Expired, Abandoned, Kyc Expired, Resubmitted, Awaiting User.
\- workflow_id (one or more UUIDs, comma-separated).
\- country (one or more ISO-3 codes, comma-separated) — issuing-state for KYC, country_code for KYB.
\- region (one or more, comma-separated).
\- document_type (one or more, comma-separated).
\- date_from, date_to (ISO 8601 date) — inclusive on created_at.
\- search (string) - a complete displayed reference such as S-0001 (user) or B-0001 (business) matches only that session number and kind, ignoring leading zeros and letter case.
Other input searches the existing name, contact, document, registration-number and vendor_data fields.
\- tags (comma-separated tag ids) — sessions that carry any of them.
\- decided_from, decided_to (ISO 8601 datetimes) — sessions whose status last changed at or after / before the value.
\- limit (int, default 50), offset (int, default 0) — limit/offset pagination. Both accept values up to 1000000; larger values return 400.

Per-kind filters (silently ignored on the other kind): is_kyc_to_be_reviewed, status_initialized_as_in_review, session_type, api_service, screened_full_name, document_name, warning.

curl example:
curl -G https://verification.didit.me/v3/sessions/ \
-H "x-api-key: " \
\--data-urlencode "session_kind=all" \
\--data-urlencode "status=Approved,In Review" \
\--data-urlencode "date_from=2026-01-01" \
\--data-urlencode "limit=50"

Response envelope:
\{
"count": ,   // exact up to 100, capped at 100 beyond that: paginate with next
"next": "",
"previous": "",
"results": [ ...rows ]
}

Every row has:
\- session_id (UUID), session_kind ("user" | "business"), session_number, status, vendor_data, created_at.

KYC row extras: portrait_image, document_type, full_name, country (issuing state), phone_number, email_address, features, didit_internal_id, assignee, waiting_since, sla_due_at, top_warnings, warnings_count.

KYB row extras: workflow_type, workflow_label, company_name, registration_number, country (incorporation).

Each row is a LIGHT projection. For the full feature payload of a row, call GET /v3/session/{session_id}/decision/ — see /sessions-api/retrieve-session.

Failure modes:
\- 401 — invalid API key.
\- 403 — { "detail": "You do not have permission to perform this action." } when the key lacks read:sessions.
\- 400 — malformed UUIDs in filters are silently dropped (no error); malformed ISO dates return { "date_from": ["..."] }.

Common patterns:
\- Build a dashboard: paginate with limit + offset, sort newest-first (server orders by -session_number within each kind).
\- Find pending review queue: status=In Review.
\- Find a specific entity's sessions: vendor_data=.
\- Refresh ongoing AML hits: filter by workflow_id of your AML workflow.

For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.`

\
Incolla in ## Filtro per tipo di sessioneUsa il parametro di query `session_kind` per scegliere quale tipo di sessione restituire:| Valore | Restituisce | | - | - | | `user` (predefinito) | Solo sessioni di Verifica degli utenti (KYC). **Comportamento retrocompatibile**: ometti `session_kind` per ottenere questo risultato. | | `business` | Solo sessioni di Verifica aziendale (KYB). | | `all` | Sessioni sia di Verifica degli utenti sia di Verifica aziendale, concatenate. |Ogni riga della risposta include `session_kind: "user" | "business"`, così il tuo client può gestire la struttura di ogni riga in base a questo campo.## Filtri comuniQuesti filtri si applicano a entrambi i tipi (i filtri riservati agli utenti vengono ignorati quando `session_kind=business`, e viceversa):| Parametro di query | Descrizione | | - | - | | `session_kind` | `user`, `business` o `all`. Predefinito `user`. | | `vendor_data` | Corrispondenza esatta con il tuo identificativo. | | `status` | Uno o più stati, separati da virgole, scritti esattamente come li restituisce l'API: `Approved`, `Declined`, `In Review` e così via (vedi [Stati di verifica](https://docs.didit.me/it/integration/verification-statuses.md)). | | `workflow_id` | Filtra per il workflow utilizzato. | | `country` | Filtro per codice paese (utenti: `issuing_states`, aziende: `country_code`). | | `date_from`, `date_to` | Finestra della data di creazione (ISO 8601). | | `tags` | ID dei tag separati da virgole. Restituisce le sessioni che ne contengono almeno uno. | | `decided_from`, `decided_to` | Data e ora in formato ISO 8601. Restituisce le sessioni il cui stato è cambiato per l'ultima volta in quella finestra (da incluso, a escluso). Usano l'orario dell'ultimo cambio di stato, non quello di creazione. | | `search` | Un riferimento completo visualizzato, come `S-0001` o `B-0001`, corrisponde solo a quel numero di sessione e a quel tipo, ignorando zeri iniziali e differenze tra maiuscole e minuscole. Per gli altri input, la ricerca viene eseguita nei campi esistenti relativi a nome, contatto, documento, numero di registrazione e `vendor_data`. |## Esempi> [tab] Elenca sessioni di Verifica degli utenti (KYC) (predefinito) > > ```bash theme={null} > curl -G https://verification.didit.me/v3/sessions/ \ > -H "x-api-key: YOUR_API_KEY" \ > --data-urlencode "vendor_data=user-42" > ``` > > **Risposta (troncata):** > > ```json theme={null} > { > "count": 3, > "next": null, > "previous": null, > "results": [ > { > "session_id": "...", > "session_kind": "user", > "session_number": 1024, > "session_url": "...", > "portrait_image": "...", > "document_type": "Passport", > "full_name": "John Doe", > "country": "GBR", > "status": "Approved", > "vendor_data": "user-42", > "didit_internal_id": "...", > "created_at": "2026-04-10T09:00:00Z", > "features": "ID_VERIFICATION,LIVENESS,FACE_MATCH,AML", > "phone_number": "+14155550123", > "email_address": "jane@example.com", > "additional_details": null > } > ] > } > ```> [tab] Elenca sessioni di Verifica aziendale (KYB) > > ```bash theme={null} > curl -G https://verification.didit.me/v3/sessions/ \ > -H "x-api-key: YOUR_API_KEY" \ > --data-urlencode "session_kind=business" \ > --data-urlencode "status=Approved" > ``` > > **Risposta (troncata):** > > ```json theme={null} > { > "count": 1, > "next": null, > "previous": null, > "results": [ > { > "session_id": "...", > "session_kind": "business", > "session_number": 89, > "status": "Approved", > "vendor_data": "biz-acme-001", > "created_at": "2026-04-01T09:00:00Z", > "workflow_id": "wf_kyb_standard", > "workflow_type": "business", > "workflow_label": "Standard KYB", > "company_name": "Acme Corporation Limited", > "registration_number": "12345678", > "country": "GBR" > } > ] > } > ```> [tab] Elenca entrambi i tipi > > ```bash theme={null} > curl -G https://verification.didit.me/v3/sessions/ \ > -H "x-api-key: YOUR_API_KEY" \ > --data-urlencode "session_kind=all" \ > --data-urlencode "date_from=2026-04-01T00:00:00Z" > ``` > > Restituisce righe di Verifica degli utenti e di Verifica aziendale in un unico array `results`. I consumatori devono gestire ogni riga in base a `session_kind`. > > > [!NOTE] > > > > La modalità `all` concatena i risultati invece di alternarli per timestamp. Per scansioni miste ad alto volume, richiama ciascun tipo separatamente e unisci i risultati lato client.## Le forme delle righe cambiano in base al tipoLe righe di Verifica degli utenti (KYC) includono: `portrait_image`, `document_type`, `full_name`, `country` (paese di emissione), `phone_number`, `email_address` e alcuni campi di revisione: `assignee` (il revisore della Console che detiene la sessione, o `null`), `waiting_since` e `sla_due_at` (valorizzati solo mentre la sessione è `In Review`), `top_warnings` (gli avvisi più importanti, ciascuno con `risk`, `feature`, `log_type` e `short_description`) e `warnings_count`.Le righe di Verifica aziendale (KYB) includono: `workflow_type`, `workflow_label`, `company_name`, `registration_number`, `country` (paese di costituzione).Entrambe contengono: `session_id`, `session_kind`, `session_number`, `status`, `vendor_data`, `created_at`.Vedi [Panoramica delle sessioni](https://docs.didit.me/it/sessions-api/overview.md) per la matrice completa delle funzionalità.## PaginazioneLa paginazione usa `limit` (predefinito `50`) e `offset` (predefinito `0`), con URL assoluti `next` e `previous` nella risposta. Entrambi i parametri accettano valori fino a `1000000`; un valore superiore restituisce `400`.`count` è esatto fino a `100` e resta a `100` oltre tale valore, quindi non usarlo come totale. Continua a richiedere l'URL `next` finché non è `null`. Con `session_kind=all`, `count` è la somma dei due tipi, ciascuno limitato a `100`.## Correlati- [Panoramica delle sessioni](https://docs.didit.me/it/sessions-api/overview.md) - [Recupera sessione](https://docs.didit.me/it/sessions-api/retrieve-session.md): decisione completa per una singola riga - [Panoramica delle aziende](https://docs.didit.me/it/entities/businesses/overview.md): l'entità Business aggregata tra le sessioni - [Panoramica degli utenti](https://docs.didit.me/it/entities/users/overview.md): l'entità User aggregata tra le sessioni ## OpenAPI ````yaml it/openapi-25.json GET /v3/sessions/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API di verifica dell'identità. Autenticati con l'intestazione x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/sessions/: get: tags: - Sessions summary: Elenca le sessioni di verifica (KYC e/o KYB) con filtri e paginazione description: >- Restituisce un elenco impaginato di sessioni di verifica per l'applicazione identificata dalla tua chiave API, dalla più recente alla meno recente (`session_number` decrescente). **URL canonico:** la rotta è `/v3/sessions/` (barra finale). Le richieste a `/v3/sessions` senza barra finale ricevono un reindirizzamento `301` all'URL con la barra conservando la query string; la maggior parte dei client HTTP lo segue in modo trasparente su GET. **Quando usare questo endpoint rispetto ai webhook.** Usa questo endpoint per dashboard, ricerche di back-office, riconciliazione ed esportazioni in batch. Non eseguire polling per monitorare l'avanzamento delle singole verifiche: configura invece i [webhook](/it/integration/webhooks), che inviano eventi `status.updated` non appena una sessione cambia. Per il risultato completo di una singola sessione, chiama `GET /v3/session/{sessionId}/decision/`. **Sessioni KYC e KYB.** `session_kind` seleziona quali tipi vengono elencati: - `user` (predefinito) - Solo sessioni di Verifica degli utenti (KYC). Comportamento retrocompatibile. - `business` - Solo sessioni di Verifica aziendale (KYB). Le righe hanno una struttura diversa e più ridotta (vedi lo schema della risposta). - `all` - Entrambi i tipi in un'unica risposta: la pagina KYC e la pagina KYB per gli stessi `limit`/`offset` vengono concatenate in `results` (prima le righe KYC), quindi una pagina può contenere fino a `2 x limit` righe. `count` è la somma di entrambi i tipi e `next`/`previous` riflettono l'impaginazione del lato KYC. Per un'impaginazione rigorosa dei dati misti, chiama `user` e `business` separatamente. Ogni riga contiene un discriminatore `session_kind` (`"user"` o `"business"`). **Impaginazione.** Standard limit/offset: `limit` (predefinito 50) e `offset` (predefinito 0), con URL di pagina pronti all'uso in `next`/`previous`. Per le righe KYC `count` è esatto. Per le righe KYB `count` viene calcolato con una scansione limitata ed è bloccato a un massimo di 100: quando ci sono più di 100 corrispondenze rimane a 100, quindi itera usando `next` (o verificando se è stata restituita una pagina intera) anziché calcolare le pagine totali da `count`. **Semantica dei filtri.** Tutti i filtri si combinano con AND e si applicano alle righe KYC. Quando `session_kind` è `business` o `all`, il lato KYB rispetta i parametri condivisi `vendor_data`, `status`, `workflow_id`, `country` (codice paese del registro delle imprese), `date_from`, `date_to`, `search` (ragione sociale, numero di registrazione — inserisci i numeri di registrazione senza separatori, ad es. `DPC001` e non `DPC-001` — vendor_data, numero di sessione o UUID della sessione), `warning` e `organization_name`; i restanti filtri validi solo per KYC vengono ignorati per le righe KYB. I parametri separati da virgola (`status`, `country`, `document_type`, `region`, `workflow_id`, `document_name`, `warning`, `organization_name`, `session_type`) corrispondono a uno qualsiasi dei valori elencati (OR all'interno del parametro). `vendor_data` prevede una corrispondenza esatta: usa `search` per una corrispondenza parziale. I valori sconosciuti nei filtri di tipo elenco non restituiscono alcuna riga (nessun errore); i valori tipizzati malformati (`date_from`, `date_to`, `didit_internal_id`, `api_service`, `session_kind`) restituiscono `400` con un oggetto di errore per ciascun campo. **Ricerca.** `search` si adatta all'input: un UUID completo cerca `session_id`; le cifre (con `+ - . space` facoltativi) cercano corrispondenze per prefisso del numero di sessione, numeri di documento/personali, prefisso del numero di telefono o `vendor_data`; i valori contenenti `@` cercano corrispondenze con prefissi email; qualsiasi altro testo cerca corrispondenze con nomi (indipendentemente dagli accenti) e `vendor_data`. Non è applicato alcun limite di frequenza fisso per endpoint, ma mantieni poco frequente il polling degli elenchi e affidati ai webhook per gli aggiornamenti in tempo reale. operationId: get_v3_sessions parameters: - name: session_kind in: query required: false description: >- Quale tipo di sessioni elencare: `user` (solo KYC, predefinito), `business` (solo KYB) o `all` (entrambe, concatenate; consulta la descrizione per la semantica di paginazione unificata). La corrispondenza non fa distinzione tra maiuscole e minuscole (`BUSINESS` funziona); qualsiasi valore diverso da una variante di maiuscole/minuscole di `user`/`business`/`all` restituisce `400`. schema: type: string enum: - user - business - all default: user example: all - name: limit in: query required: false description: >- Numero massimo di righe per pagina (per tipologia quando `session_kind=all`). Il valore predefinito è 50. schema: type: integer default: 50 minimum: 1 maximum: 1000000 example: 20 - name: offset in: query required: false description: >- Numero di righe da saltare prima della prima riga restituita. Il valore predefinito è 0. È preferibile seguire gli URL `next`/`previous` della risposta. schema: type: integer maximum: 1000000 minimum: 0 default: 0 example: 20 - name: status in: query required: false description: >- Elenco separato da virgole degli stati della sessione da includere, ad es. `Approved,In Review`. I valori fanno distinzione tra maiuscole e minuscole; consulta [Stati di verifica](/it/integration/verification-statuses). I valori sconosciuti non corrispondono a nulla. schema: type: string example: Approved,In Review - name: vendor_data in: query required: false description: >- Filtro per corrispondenza esatta sul `vendor_data` inviato alla creazione della sessione (il tuo identificatore per l'utente/azienda). Per corrispondenze parziali, usa invece `search`. schema: type: string example: your-user-id-123 - name: search in: query required: false description: >- Un riferimento visualizzato completo come `S-0001` (utente) o `B-0001` (azienda) corrisponde unicamente a quel numero e tipo di sessione; gli zeri iniziali e le maiuscole/minuscole non influiscono sulla corrispondenza. Ricerca intelligente a testo libero. Un UUID completo corrisponde a `session_id`; un input numerico corrisponde al prefisso del numero di sessione, ai numeri di documento/personali, al prefisso telefonico o a `vendor_data`; un input contenente `@` corrisponde ai prefissi email; altro testo corrisponde ai nomi (senza distinzione di accenti) e a `vendor_data`. Il testo libero contenente cifre corrisponde inoltre ai campi di ricerca del numero di documento/personale e ai prefissi del numero di sessione. schema: type: string example: jane doe - name: workflow_id in: query required: false description: >- UUID dei workflow separati da virgola (disponibili nella pagina Workflow della Console). Gli UUID non validi nell'elenco vengono ignorati; se nessuno è valido, il risultato è vuoto. schema: type: string example: 9f9b1234-aaaa-bbbb-cccc-1234567890ab - name: date_from in: query required: false description: >- Solo le sessioni create in questa data o successivamente (UTC), formato `YYYY-MM-DD`. Le date con formato non valido restituiscono `400`. schema: type: string format: date example: '2026-06-01' - name: date_to in: query required: false description: >- Solo le sessioni create fino a questa data (UTC), formato `YYYY-MM-DD`. Per le righe KYC viene inclusa l'intera giornata; per le righe KYB il confronto è `created_at <= date_to` (mezzanotte), quindi usa la data del giorno successivo per includere un'intera giornata di sessioni KYB. schema: type: string format: date example: '2026-06-30' - name: tags in: query required: false schema: type: string description: >- ID di tag separati da virgole (`tags` della tua applicazione). Restituisce le sessioni che contengono uno qualsiasi di essi. Gli ID che non sono UUID validi vengono ignorati e, se nessuno è valido, l'elenco è vuoto. - name: decided_from in: query required: false schema: type: string format: date-time description: >- Data e ora ISO 8601. Restituisce le sessioni il cui stato è cambiato l'ultima volta a partire da tale momento. Filtra in base all'orario dell'ultimo cambio di stato, non all'orario di creazione. - name: decided_to in: query required: false schema: type: string format: date-time description: >- Data e ora ISO 8601. Restituisce le sessioni il cui stato è cambiato l'ultima volta prima di tale momento. Combina con `decided_from` per un intervallo semiaperto. - name: country in: query required: false description: >- Filtro per paese separato da virgole. Per le righe KYC: codici ISO 3166-1 alpha-3 dello stato di emissione del documento d'identità (ad es. `ESP,USA`), che possono differire dalla nazionalità. Per le righe KYB: il codice del paese dell'azienda nel registro. schema: type: string example: ESP,USA - name: document_type in: query required: false description: >- Codici dei tipi di documento di identità verificati nella sessione, separati da virgole (solo righe KYC): `P` (passaporto), `ID` (carta d'identità), `DL` (patente di guida), `RP` (permesso di soggiorno), `SSC` (tessera di sicurezza sociale), `HIC` (tessera sanitaria), `WP` (permesso di lavoro), `TC` (tesserino del codice fiscale), `VISA`, `PSC` (carta dei servizi pubblici), `BC` (certificato di nascita), `OTHER`. Nota che il campo di risposta `document_type` contiene il nome visualizzato, non il codice. schema: type: string example: P,ID - name: document_name in: query required: false description: >- Nomi esatti dei documenti; è possibile passare più nomi separati da virgola, ma il valore viene suddiviso in corrispondenza delle virgole solo se contiene più di un separatore ` - ` (un singolo nome contenente una virgola interna viene confrontato per intero). I nomi corrispondono a quelli riconosciuti dalla verifica del documento (fronte o retro), ad es. `Spain - Id Card (2021)`. Solo righe KYC. schema: type: string example: Spain - Id Card (2021) - name: region in: query required: false description: >- Valori di regione/stato del documento separati da virgole (per documenti emessi su base regionale, come le patenti di guida statunitensi). Solo righe KYC. schema: type: string example: CA,TX - name: didit_internal_id in: query required: false description: >- Filtra per identificatore interno dell'utente di Didit (il campo di risposta `didit_internal_id`) per elencare tutte le sessioni di un utente verificato. Deve essere un UUID valido; i valori non validi restituiscono `400`. Solo righe KYC. schema: type: string format: uuid example: d9e78474-6c8d-4f2a-bb90-6f5c2f3a1147 - name: session_type in: query required: false description: >- Canali di creazione della sessione separati da virgole: `API`, `HOSTED`, `MIGRATED`. Il valore speciale `ALL` (o l'omissione del parametro) disabilita il filtro. Solo righe KYC. schema: type: string example: HOSTED - name: api_service in: query required: false description: >- Filtra le sessioni API standalone per servizio. I valori non validi restituiscono `400`. Solo righe KYC. schema: type: string enum: - ID_VERIFICATION - FACE_MATCH - AGE_ESTIMATION - FACE_SEARCH - POA - AML - KYB_REGISTRY - PASSIVE_LIVENESS - DATABASE_VALIDATION - PHONE_VERIFICATION - EMAIL_VERIFICATION example: AML - name: screened_full_name in: query required: false description: >- Ricerca del nome senza distinzione di accenti all'interno dei dati sottoposti a screening AML e validazione su database. Se combinata con `api_service=AML` o `api_service=DATABASE_VALIDATION`, la ricerca è limitata ai dati sottoposti a screening di tale funzionalità. Solo righe KYC. schema: type: string example: Jane Doe - name: warning in: query required: false description: >- Codici di rischio degli avvisi separati da virgole; restituisce le sessioni che ne hanno generato alcuno (ad es. `POSSIBLE_FRAUD`). I codici di rischio sono elencati per funzionalità nella [documentazione sugli avvisi](/it/integration/webhooks). Si applica alle righe KYC e, con i codici di avviso aziendali, alle righe KYB. schema: type: string example: POSSIBLE_FRAUD - name: status_initialized_as_in_review in: query required: false description: >- Quando è `true`, include solo le sessioni la cui decisione è stata inizialmente impostata su `In Review` (utile per verificare il volume della revisione manuale). Solo righe KYC. schema: type: boolean example: true - name: is_kyc_to_be_reviewed in: query required: false description: >- `true` restituisce le sessioni la cui verifica del documento è contrassegnata per la revisione manuale; `false` restituisce le sessioni la cui verifica del documento non è esplicitamente contrassegnata. Ometti per disattivare. Solo righe KYC. schema: type: boolean example: true - name: euuid in: query required: false description: >- Filtra in base all'euuid dell'utente finale (UUID assegnato all'utente in fase di verifica, utilizzato per i deep link della Console). Deve essere un UUID valido; valori non corretti restituiscono un errore di campo 400. Solo righe KYC. schema: type: string format: uuid example: 0f8fad5b-d9cb-469f-a165-70867728950e - name: organization_name in: query required: false description: >- Nomi delle organizzazioni separati da virgole. Destinato alla Console; con una chiave API (già limitata a una singola applicazione) corrisponde solo al nome della tua organizzazione. schema: type: string example: Acme Inc responses: '200': description: >- Elenco sessioni impaginato. Gli elementi di `results` sono righe KYC, righe KYB o entrambe a seconda di `session_kind`; distingui con il campo `session_kind` di ciascuna riga. content: application/json: schema: type: object required: - count - next - previous - results properties: count: type: integer description: >- Numero di sessioni corrispondenti ai filtri: esatto fino a 100 e limitato a 100 oltre tale soglia, pertanto non utilizzarlo come totale complessivo. Usa `next` per sapere se esistono altre pagine. Per `session_kind=all` corrisponde alla somma di entrambi i tipi, ciascuno limitato a 100. example: 2 next: type: string format: uri nullable: true description: >- URL assoluto della pagina successiva, o `null` sull'ultima pagina. example: >- https://verification.didit.me/v3/sessions/?limit=20&offset=20 previous: type: string format: uri nullable: true description: >- URL assoluto della pagina precedente, o `null` sulla prima pagina. example: null results: type: array description: >- Righe delle sessioni, dalla più recente. Con `session_kind=all`, vengono prima le righe KYC, poi quelle KYB. items: oneOf: - $ref: '#/components/schemas/UserSessionListItem' - $ref: '#/components/schemas/BusinessSessionListItem' discriminator: propertyName: session_kind mapping: user: '#/components/schemas/UserSessionListItem' business: '#/components/schemas/BusinessSessionListItem' examples: KYC sessions (default): summary: >- session_kind=user - una sessione completata e una non avviata value: count: 2 next: null previous: null results: - session_id: 5b3720ed-d429-42ef-b67f-37ea805f48ee session_kind: user session_number: 720 session_url: https://verify.didit.me/session/CuXoBYCYVO5Y portrait_image: >- https:///portraits/5b3720ed.jpg?X-Amz-Expires=3600&X-Amz-Signature=... document_type: Passport full_name: Jane Marie Doe country: ESP status: Approved vendor_data: your-user-id-123 didit_internal_id: d9e78474-6c8d-4f2a-bb90-6f5c2f3a1147 created_at: '2026-06-09T12:26:54.328364Z' features: - feature: ID_VERIFICATION status: Approved - feature: LIVENESS status: Approved - feature: FACE_MATCH status: Approved - feature: AML status: Approved - feature: IP_ANALYSIS status: Approved phone_number: number: '+14155552671' is_verified: true email_address: email: jane@example.com is_verified: true additional_details: aml: total_hits: 0 entity_type: person is_adverse_media_fetched: false liveness: method: PASSIVE score: 0.98 face_match: score: 0.95 - session_id: 038ad62f-5ebd-46c2-afe9-4b2956bf687f session_kind: user session_number: 719 session_url: https://verify.didit.me/session/7RGKiO6ioGH6 portrait_image: null document_type: null full_name: null country: null status: Not Started vendor_data: your-user-id-124 didit_internal_id: eb4e679d-ca4b-461f-9685-687bac29ebdb created_at: '2026-06-09T08:02:23.343053Z' features: - feature: ID_VERIFICATION status: Not Finished - feature: LIVENESS status: Not Finished - feature: FACE_MATCH status: Not Finished - feature: AML status: Not Finished - feature: IP_ANALYSIS status: Not Finished phone_number: null email_address: null additional_details: null Mixed KYC + KYB (session_kind=all): summary: session_kind=all - riga KYC seguita da una riga KYB value: count: 2 next: null previous: null results: - session_id: 5b3720ed-d429-42ef-b67f-37ea805f48ee session_kind: user session_number: 720 session_url: https://verify.didit.me/session/CuXoBYCYVO5Y portrait_image: null document_type: Identity Card full_name: Jane Marie Doe country: ESP status: In Review vendor_data: your-user-id-123 didit_internal_id: d9e78474-6c8d-4f2a-bb90-6f5c2f3a1147 created_at: '2026-06-09T12:26:54.328364Z' features: - feature: ID_VERIFICATION status: In Review - feature: LIVENESS status: Approved phone_number: null email_address: null additional_details: liveness: method: PASSIVE score: 0.98 - session_id: 8a1f63c2-1b9e-4f3a-9c41-2f6a1f0b7d52 session_kind: business session_number: 42 status: Approved vendor_data: your-company-id-77 created_at: '2026-06-08T09:14:02.118450Z' workflow_id: 9f9b1234-aaaa-bbbb-cccc-1234567890ab workflow_type: kyb workflow_label: Standard KYB company_name: Acme Holdings S.L. registration_number: B12345678 country: ES '301': description: >- Reindirizzamento all'URL canonico con barra finale. Restituito quando il percorso della richiesta è `/v3/sessions` (senza barra finale); l'intestazione `Location` punta a `/v3/sessions/` preservando la query string. I client GET in genere lo seguono automaticamente. '400': description: >- Parametro di query non valido. Il corpo è un oggetto indicizzato per il parametro errato. content: application/json: examples: Invalid session_kind: summary: session_kind non è uno dei valori user/business/all value: session_kind: Must be "user", "business", or "all". Invalid date: summary: date_from/date_to non validi value: date_from: - Enter a valid date. Invalid didit_internal_id: summary: didit_internal_id non è un UUID value: didit_internal_id: - Enter a valid UUID. Invalid api_service: summary: api_service non rientra tra le opzioni consentite value: api_service: - >- Select a valid choice. FOO is not one of the available choices. '403': description: >- Chiave API mancante, malformata o revocata. Una chiave mancante restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`. **Applicazione eliminata:** per alcuni minuti dopo l'eliminazione di un'applicazione, una richiesta effettuata con una delle sue chiavi API può restituire `{"detail": "This application was deleted.", "code": "application_deleted"}`. Non riprovare: l'applicazione e le sue chiavi API non esistono più. Trascorsi questi pochi minuti, la chiave viene rifiutata come qualsiasi altra chiave non valida. content: application/json: schema: type: object properties: detail: type: string example: You do not have permission to perform this action. code: type: string description: >- Motivo leggibile dalla macchina, presente solo per alcuni errori. `application_deleted`: la chiave API appartiene a un'applicazione che è stata eliminata. example: application_deleted required: - detail examples: Forbidden: summary: x-api-key mancante o non valida value: detail: You do not have permission to perform this action. ApplicationDeleted: summary: Chiave API di un'applicazione eliminata value: detail: This application was deleted. code: application_deleted security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: >- curl -s 'https://verification.didit.me/v3/sessions/?status=Approved,In%20Review&date_from=2026-06-01&limit=20' \ -H 'x-api-key: YOUR_API_KEY' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() for item in client.sessions.list(): print(item) - lang: javascript label: Node.js source: |- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); for await (const item of didit.sessions.list()) { console.log(item); } - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Sessions.ListAutoPaging(ctx, didit.SessionsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" - lang: java label: Java source: |- import me.didit.Didit; // Reads DIDIT_API_KEY. Didit client = new Didit(); for (var item : client.sessions().list()) { System.out.println(item); } - lang: php label: PHP source: |- sessions->list() as $item) { print_r($item); } - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new didit.sessions.list.auto_paging_each do |item| puts item.to_h end - lang: csharp label: .NET source: |- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); await foreach (var item in await client.Sessions.ListAsync()) { Console.WriteLine(JsonSerializer.Serialize(item)); } components: schemas: UserSessionListItem: title: 'KYC session row (session_kind: user)' type: object description: >- Riga di riepilogo per una sessione di Verifica degli utenti (KYC). I campi di identità (`full_name`, `country`, `document_type`, `portrait_image`, campi di contatto) vengono popolati progressivamente man mano che l'utente completa i passaggi di verifica, e sono `null` fino al termine del passaggio pertinente. Anche i campi soggetti a restrizioni dalla configurazione degli attributi di risposta del workflow vengono restituiti come `null`. required: - session_id - session_kind - session_number - session_url - portrait_image - document_type - full_name - country - status - vendor_data - didit_internal_id - created_at - features - phone_number - email_address - additional_details properties: session_id: type: string format: uuid description: >- Identificativo univoco della sessione di verifica. Usalo con `GET /v3/session/{sessionId}/decision/` per recuperare il payload completo della decisione. example: 5b3720ed-d429-42ef-b67f-37ea805f48ee session_kind: type: string enum: - user description: >- Discriminatore di riga. Sempre `"user"` per le righe KYC; le righe di Verifica aziendale (KYB) hanno `"business"` e una struttura diversa. example: user session_number: type: integer description: >- Numero progressivo intuitivo della sessione all'interno della tua applicazione. Utilizzato anche dal parametro `search` per trovare la sessione. example: 720 session_url: type: string nullable: true description: >- URL di verifica ospitato che l'utente finale apre per completare il flusso. `null` quando la sessione non ha un URL ospitato. example: https://verify.didit.me/session/CuXoBYCYVO5Y portrait_image: type: string nullable: true description: >- URL con scadenza (pre-firmato) del miglior ritratto disponibile: la foto del chip NFC quando disponibile, altrimenti il ritratto del documento d'identità, altrimenti l'immagine di riferimento del rilevamento della vitalità. `null` finché non ne esiste uno. Scarica tempestivamente; il link scade. example: >- https:///portraits/5b3720ed.jpg?X-Amz-Expires=3600&X-Amz-Signature=... document_type: type: string nullable: true enum: - Passport - Identity Card - Driver's License - Residence Permit - Health Insurance Card - Tax Card description: >- Tipo leggibile dall'utente del documento d'identità verificato. `null` prima del completamento della verifica del documento, e anche `null` dopo il completamento quando il codice verificato non ha una mappatura di visualizzazione (`SSC`, `WP`, `VISA`, `PSC`, `BC`, `OTHER`). Nota: il parametro di query `document_type` filtra in base ai codici brevi (`P`, `ID`, `DL`, `RP`, ...), non in base a questi valori visualizzati. example: Passport full_name: type: string nullable: true description: >- Miglior nome completo disponibile per la sessione, risolto nell'ordine: OCR del documento d'identità, dati sottoposti a screening AML, dati sottoposti a validazione su database, documento di prova di residenza, quindi i dati previsti forniti alla creazione della sessione. `null` se nessuno è ancora disponibile. example: Jane Marie Doe country: type: string nullable: true description: >- Paese ISO 3166-1 alpha-3 associato alla sessione, risolto nell'ordine: stato di emissione del documento d'identità, stato di emissione della validazione su database, stato di emissione della prova di residenza, dati previsti, quindi paese del telefono verificato. Può differire dalla nazionalità. example: ESP status: type: string enum: - Not Started - In Progress - Approved - Declined - In Review - Expired - Abandoned - Kyc Expired - Resubmitted - Awaiting User description: >- Stato complessivo della sessione. Consulta la pagina [Stati di verifica](/it/integration/verification-statuses) per il ciclo di vita. example: Approved vendor_data: type: string nullable: true description: >- Il tuo identificatore per l'utente finale, restituito esattamente come inviato alla creazione della sessione. example: your-user-id-123 didit_internal_id: type: string format: uuid nullable: true description: >- Identificatore interno Didit del profilo utente verificato associato a questa sessione. Stabile tra più sessioni dello stesso utente; filtrabile tramite il parametro di query `didit_internal_id`. example: d9e78474-6c8d-4f2a-bb90-6f5c2f3a1147 created_at: type: string format: date-time description: Timestamp UTC di creazione della sessione. example: '2026-06-09T12:26:54.328364Z' features: type: array description: >- Stato per funzionalità di ogni passaggio di verifica configurato nel workflow della sessione, nell'ordine del workflow. items: type: object required: - feature - status properties: feature: type: string enum: - ID_VERIFICATION - NFC - LIVENESS - FACE_MATCH - POA - QUESTIONNAIRE - EMAIL_VERIFICATION - PHONE - AML - IP_ANALYSIS - AGE_ESTIMATION - DATABASE_VALIDATION - GEOLOCATION description: Identificatore della funzionalità di verifica. example: ID_VERIFICATION status: type: string enum: - Not Finished - Approved - Declined - In Review - Resub Requested description: >- Stato di questa funzionalità. `Not Finished` finché il passaggio non viene completato. example: Approved phone_number: type: object nullable: true description: >- Telefono associato alla sessione: il telefono verificato se la verifica telefonica è stata eseguita, altrimenti il telefono di contatto fornito alla creazione della sessione. `null` se nessuno dei due è presente. required: - number - is_verified properties: number: type: string description: Numero di telefono in formato E.164. example: '+14155552671' is_verified: type: boolean description: >- `true` solo quando la funzionalità di verifica telefonica ha approvato questo numero. example: true email_address: type: object nullable: true description: >- Email associata alla sessione: l'email verificata se la verifica email è stata eseguita, altrimenti l'email di contatto fornita al momento della creazione della sessione. `null` se nessuna delle due è presente. required: - email - is_verified properties: email: type: string format: email example: jane@example.com is_verified: type: boolean description: >- `true` solo quando la funzionalità di verifica email ha approvato questo indirizzo. example: true additional_details: type: object nullable: true description: >- Dati extra compatti per funzionalità. Solo le funzionalità che hanno generato dati compaiono come chiavi; `null` se nessuna funzionalità ha generato dati extra. I campi esclusi dalla configurazione degli attributi della risposta del workflow vengono omessi. properties: aml: type: object description: Presente quando è stato eseguito lo screening AML. properties: total_hits: type: integer description: Numero di corrispondenze dello screening AML. example: 0 entity_type: type: string description: Tipo di entità sottoposta a screening. example: person is_adverse_media_fetched: type: boolean example: false screened_data: type: object description: >- Sottoinsieme dei dati sottoposti a screening. Vengono incluse solo le chiavi non vuote. properties: nationality: type: string example: ESP document_number: type: string example: XX1234567 date_of_birth: type: string example: '1990-05-21' database_validation: type: object description: Presente quando è stata eseguita la validazione su database. properties: validation_type: type: string example: DOCUMENT_VALIDATION match_type: type: string example: FULL_MATCH identification_number: type: string description: >- Numero fiscale, personale o del documento che è stato convalidato (il primo disponibile). example: 12345678Z poa: type: object description: Presente quando è stata eseguita la prova di residenza. properties: document_type: type: string example: UTILITY_BILL issuer: type: string example: Energy Co address: type: string example: Calle Mayor 1, 28013 Madrid name_on_document: type: string example: Jane Marie Doe liveness: type: object description: Presente quando è stato eseguito il rilevamento della vitalità. properties: method: type: string example: PASSIVE score: type: number description: >- Punteggio di affidabilità del rilevamento della vitalità, arrotondato a 2 decimali. example: 0.98 face_match: type: object description: Presente quando è stato eseguito il confronto facciale. properties: score: type: number description: >- Punteggio di somiglianza del confronto facciale, arrotondato a 2 decimali. example: 0.95 source_image: type: string description: >- URL con scadenza (pre-firmato) dell'immagine del volto sorgente. example: https:///faces/source.jpg?X-Amz-Expires=3600&... target_image: type: string description: >- URL con scadenza (pre-firmato) dell'immagine del volto target. example: https:///faces/target.jpg?X-Amz-Expires=3600&... phone_verification: type: object description: Presente quando è stata eseguita la verifica telefonica. properties: country_code: type: string description: Paese ISO 3166-1 alpha-2 del numero di telefono. example: US is_temporary: type: boolean example: false is_ported: type: boolean example: false is_blocked: type: boolean example: false email_verification: type: object description: Presente quando è stata eseguita la verifica email. properties: is_breached: type: boolean example: false is_disposable: type: boolean example: false is_undeliverable: type: boolean example: false is_blocklisted: type: boolean example: false assignee: type: object nullable: true description: >- Il revisore della Console a cui è assegnata la sessione, oppure `null` se non è assegnata a nessuno. properties: email: type: string format: email assigned_at: type: string format: date-time nullable: true waiting_since: type: string format: date-time nullable: true description: >- Quando la sessione ha iniziato l'attesa per la revisione. `null` a meno che la sessione non sia `In Review`. sla_due_at: type: string format: date-time nullable: true description: >- Termine entro cui la revisione deve essere completata, in base alla scadenza di revisione impostata per la tua applicazione nella Console. `null` a meno che la sessione non sia `In Review` e sia impostata una scadenza. top_warnings: type: array description: >- Al massimo alcuni degli avvisi più importanti della sessione, per una rapida valutazione iniziale. L'elenco completo si trova nella decisione. items: type: object properties: risk: type: string description: Codice dell'avviso, ad esempio `FACE_MATCH_LOW_SIMILARITY`. feature: type: string description: La funzionalità che lo ha generato. log_type: type: string nullable: true description: '`error` o `warning`; `null` per una voce legacy.' short_description: type: string warnings_count: type: integer description: Numero di avvisi presenti nella sessione. BusinessSessionListItem: title: 'KYB session row (session_kind: business)' type: object description: >- Riga di riepilogo per una sessione di Verifica aziendale (KYB). Restituita solo quando `session_kind` è `business` o `all`. required: - session_id - session_kind - session_number - status - vendor_data - created_at - workflow_id - workflow_type - workflow_label - company_name - registration_number - country properties: session_id: type: string format: uuid description: Identificativo univoco della sessione di verifica aziendale. example: 8a1f63c2-1b9e-4f3a-9c41-2f6a1f0b7d52 session_kind: type: string enum: - business description: Discriminatore di riga. Sempre `"business"` per le righe KYB. example: business session_number: type: integer description: >- Numero progressivo di facile lettura della sessione aziendale all'interno della tua applicazione. Numerato indipendentemente dalle sessioni KYC. example: 42 status: type: string enum: - Not Started - In Progress - Approved - Declined - In Review - Expired - Abandoned - Kyc Expired - Resubmitted - Awaiting User description: >- Stato complessivo della sessione. Consulta la pagina [Stati di verifica](/it/integration/verification-statuses). example: Approved vendor_data: type: string nullable: true description: >- Il tuo identificatore per l'azienda, restituito esattamente come inviato alla creazione della sessione. example: your-company-id-77 created_at: type: string format: date-time description: Timestamp UTC di creazione della sessione. example: '2026-06-08T09:14:02.118450Z' workflow_id: type: string format: uuid nullable: true description: Identificatore del workflow con cui è stata creata questa sessione. example: 9f9b1234-aaaa-bbbb-cccc-1234567890ab workflow_type: type: string nullable: true description: Tipo di workflow. `kyb` per i workflow aziendali. example: kyb workflow_label: type: string nullable: true description: Nome visualizzato del workflow. example: Standard KYB company_name: type: string nullable: true description: >- Nome dell'azienda sottoposta a verifica, ricavato dall'azienda del registro delle imprese collegata alla sessione. `null` finché non viene selezionata un'azienda. example: Acme Holdings S.L. registration_number: type: string nullable: true description: >- Numero di registrazione aziendale proveniente dall'azienda del registro collegata alla sessione. example: B12345678 country: type: string nullable: true description: Codice del paese dell'azienda nel registro collegata alla sessione. example: ES securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- La chiave API della tua applicazione, da Developers -> API keys nella Business Console. La chiave primaria ha accesso completo. Una chiave con nome può avere un ambito definito: nessuno, lettura o scrittura per risorsa, limitata ad alcuni workflow o a sessioni approvate, a un elenco di indirizzi IP e a una data di scadenza. 401 indica che la chiave è errata, revocata o scaduta; 403 indica che non è stata inviata alcuna chiave, che la chiave non ha accesso a questa risorsa o azione, oppure che la richiesta proviene da un indirizzo non incluso nel suo elenco IP; 404 su una route di sessione indica che la sessione non rientra nei workflow o negli stati previsti dalla chiave. Una chiave senza accesso ai media riceve gli URL di immagini, video e PDF come null, e una chiave senza permessi di scrittura sulle sessioni riceve link e token di sessione come null. Consulta https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.