List Sessions API: Filter KYC & KYB Sessions

curl

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'

ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()

iter := client.Sessions.ListAutoPaging(ctx, didit.SessionsListParams{})
for iter.Next() {
	fmt.Printf("%+v\n", iter.Current())
}
if err := iter.Err(); err != nil {
	log.Fatal(err)
}

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

{
  "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://<media-host>/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
    }
  ]
}

GET

sessions

curl

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'

ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()

iter := client.Sessions.ListAutoPaging(ctx, didit.SessionsListParams{})
for iter.Next() {
	fmt.Printf("%+v\n", iter.Current())
}
if err := iter.Err(); err != nil {
	log.Fatal(err)
}

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

{
  "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://<media-host>/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
    }
  ]
}

Session kind filter

Use the session_kind query parameter to choose which kind of sessions to return:

Value	Returns
`user` (default)	Only User Verification (KYC) sessions. Backward-compatible behavior — omit `session_kind` to get this.
`business`	Only Business Verification (KYB) sessions.
`all`	Both User Verification and Business Verification sessions, concatenated.

Every row in the response includes session_kind: "user" | "business" so your client can switch on shape per row.

Common filters

These filters apply to both kinds (the user-only filters are ignored when session_kind=business, and vice versa):

Query parameter	Description
`session_kind`	`user`, `business`, or `all`. Default `user`.
`vendor_data`	Exact match on your identifier.
`status`	One or more statuses, comma-separated, written exactly as the API returns them: `Approved`, `Declined`, `In Review`, and so on (see Verification statuses).
`workflow_id`	Filter by the workflow used.
`country`	Country code filter (user: `issuing_states`, business: `country_code`).
`date_from`, `date_to`	Created-date window (ISO 8601).
`tags`	Comma-separated tag ids. Returns the sessions that carry any of them.
`decided_from`, `decided_to`	ISO 8601 datetimes. Returns the sessions whose status last changed in that window (from inclusive, to exclusive). They use the time of the last status change, not the creation time.
`search`	A complete displayed reference such as `S-0001` or `B-0001` 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.

Examples

List User Verification (KYC) sessions (default)
List Business Verification (KYB) sessions
List both kinds

curl -G https://verification.didit.me/v3/sessions/ \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "vendor_data=user-42"

Response (truncated):

{
  "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
    }
  ]
}

curl -G https://verification.didit.me/v3/sessions/ \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "session_kind=business" \
  --data-urlencode "status=Approved"

Response (truncated):

{
  "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"
    }
  ]
}

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"

Returns User Verification and Business Verification rows in a single results array. Consumers should switch per row on session_kind.

The all mode concatenates results rather than interleaving them by timestamp. For high-volume mixed traversals, call each kind separately and merge client-side.

Row shapes differ by kind

User Verification (KYC) rows include: portrait_image, document_type, full_name, country (issuing state), phone_number, email_address, and a few review fields: assignee (the Console reviewer holding the session, or null), waiting_since and sla_due_at (set only while the session is In Review), top_warnings (the most important warnings, each with risk, feature, log_type and short_description) and warnings_count. Business Verification (KYB) rows include: workflow_type, workflow_label, company_name, registration_number, country (country of incorporation). Both carry: session_id, session_kind, session_number, status, vendor_data, created_at. See sessions overview for the complete feature matrix.

Pagination

Pagination uses limit (default 50) and offset (default 0), with absolute next and previous URLs in the response. Both parameters accept values up to 1000000; a larger value returns 400. count is exact up to 100 and stays at 100 beyond that, so do not use it as a total. Keep requesting the next URL until it is null. With session_kind=all, count is the sum of both kinds, each capped at 100.

Sessions overview
Retrieve session — full decision for a single row
Businesses overview — the Business entity aggregated across sessions
Users overview — the User entity aggregated across sessions

Authorizations

x-api-key

string

header

required

Your application's API key, from Developers -> API keys in the Business Console. The primary key has full access. A named key can be scoped: none, read or write per resource, limited to some workflows or to approved sessions, to a list of IP addresses, and to an expiry date. 401 means the key is wrong, revoked or expired; 403 means no key was sent, the key has no access to this resource or action, or the request came from an address outside its IP list; 404 on a session route means the session is outside the key's workflows or statuses. A key without media access receives image, video and PDF URLs as null, and a key without sessions write receives session links and tokens as null. See https://docs.didit.me/console/api-keys.

Query Parameters

session_kind

enum<string>

default:user

Which kind of sessions to list: user (KYC only, default), business (KYB only), or all (both, concatenated - see the description for merged-pagination semantics). Matching is case-insensitive (BUSINESS works); any value other than a case variant of user/business/all returns 400.

Available options:

user,

business,

all

limit

integer

default:50

Maximum number of rows per page (per kind when session_kind=all). Defaults to 50.

Required range: 1 <= x <= 1000000

offset

integer

default:0

Number of rows to skip before the first returned row. Defaults to 0. Prefer following the next/previous URLs from the response.

Required range: 0 <= x <= 1000000

status

string

Comma-separated list of session statuses to include, e.g. Approved,In Review. Values are case-sensitive; see Verification Statuses. Unknown values match nothing.

vendor_data

string

Exact-match filter on the vendor_data you sent at session creation (your own user/business identifier). For partial matches use search instead.

string

A complete displayed reference such as S-0001 (user) or B-0001 (business) matches only that session number and kind; leading zeros and letter case do not affect matching. Smart free-text search. A full UUID matches session_id; numeric input matches session-number prefix, document/personal numbers, phone prefix, or vendor_data; input containing @ matches email prefixes; other text matches names (accent-insensitive) and vendor_data. Free text containing digits additionally matches document/personal-number search fields and session-number prefixes.

workflow_id

string

Comma-separated workflow UUIDs (find them on the Workflows page in the Console). Malformed UUIDs in the list are ignored; if none are valid the result is empty.

date_from

string<date>

Only sessions created on or after this date (UTC), format YYYY-MM-DD. Malformed dates return 400.

date_to

string<date>

Only sessions created up to this date (UTC), format YYYY-MM-DD. For KYC rows the entire day is included; for KYB rows the comparison is created_at <= date_to (midnight), so use the next day's date to include a full day of KYB sessions.

Response

Paginated session list. results items are KYC rows, KYB rows, or both depending on session_kind; discriminate with each row's session_kind field.

count

integer

required

Number of sessions matching the filters: exact up to 100 and capped at 100 beyond that, so do not use it as a total. Use next to know whether more pages exist. For session_kind=all it is the sum of both kinds, each capped at 100.

Example:

2

string<uri> | null

required

Absolute URL of the next page, or null on the last page.

Example:

"https://verification.didit.me/v3/sessions/?limit=20&offset=20"

string<uri> | null

required

Absolute URL of the previous page, or null on the first page.

Example:

null

results

(KYC session row (session_kind: user) · object | KYB session row (session_kind: business) · object)[]

required

Session rows, newest first. With session_kind=all, KYC rows come first, then KYB rows.

Summary row for a User Verification (KYC) session. Identity fields (full_name, country, document_type, portrait_image, contact fields) are populated progressively as the user completes verification steps, and are null until the relevant step finishes. Fields restricted by the workflow's response-attributes configuration are also returned as null.

KYC session row (session_kind: user)
KYB session row (session_kind: business)

Show child attributes

Last modified on November 1, 2026

Session kind filter

Common filters

Examples

Row shapes differ by kind

Pagination

Related

Authorizations

Query Parameters

Response