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'

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

User and Business Verifications

List Sessions

Returns a paginated list of verification sessions for the application identified by your API key, newest first (descending session_number).

Canonical URL: the route is /v3/sessions/ (trailing slash). Requests to /v3/sessions without the slash receive a 301 redirect to the slashed URL with the query string preserved; most HTTP clients follow it transparently on GET.

When to use this endpoint vs webhooks. Use this endpoint for dashboards, back-office search, reconciliation, and batch exports. Do not poll it to track the progress of individual verifications - configure webhooks instead, which push status.updated events the moment a session changes. For one session’s full result, call GET /v3/session/{sessionId}/decision/.

KYC and KYB rows. session_kind selects which tables are listed:

user (default) - User Verification (KYC) sessions only. Backward-compatible behavior.
business - Business Verification (KYB) sessions only. Rows have a different, smaller shape (see the response schema).
all - both kinds in one response: the KYC page and the KYB page for the same limit/offset are concatenated in results (KYC rows first), so a page can contain up to 2 x limit rows. count is the sum of both kinds and next/previous reflect the KYC-side pagination. For strict pagination of mixed data, call user and business separately.

Every row carries a session_kind discriminator ("user" or "business").

Pagination. Standard limit/offset: limit (default 50) and offset (default 0), with next/previous ready-made page URLs. For KYC rows count is exact. For KYB rows count is computed with a bounded scan and is capped at 100 - when there are more than 100 matches it stays at 100, so iterate using next (or by checking whether a full page came back) rather than computing total pages from count.

Filter semantics. All filters combine with AND and apply to KYC rows. When session_kind is business or all, the KYB side honors the shared parameters vendor_data, status, workflow_id, country (registry-company country code), date_from, date_to, search (company name, registration number — type registration numbers without separators, e.g. DPC001 not DPC-001 — vendor_data, session number, or session UUID), warning, and organization_name; the remaining KYC-only filters are ignored for KYB rows. Comma-separated parameters (status, country, document_type, region, workflow_id, document_name, warning, organization_name, session_type) match any of the listed values (OR within the parameter). vendor_data is an exact match - use search for partial matching. Unknown values in list filters simply return no rows (no error); malformed typed values (date_from, date_to, didit_internal_id, api_service, session_kind) return 400 with a per-field error object.

Search. search adapts to the input: a full UUID looks up session_id; digits (with optional + - . space) match session-number prefix, document/personal numbers, phone-number prefix, or vendor_data; values containing @ match email prefixes; any other text matches names (accent-insensitive) and vendor_data.

No fixed per-endpoint rate limit is enforced, but keep list polling infrequent and rely on webhooks for real-time updates.

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'

{
  "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`	`APPROVED`, `DECLINED`, `IN_REVIEW`, etc.
`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).
`search`	Substring match. For user: vendor_data, full name, document number, phone, email. For business: vendor_data, company name, registration number.

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

Cursor-based via page_size and the next / previous pointers in the response. Default page_size=25, max 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

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: x >= 1

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: x >= 0

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

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.

country

string

Comma-separated country filter. For KYC rows: ISO 3166-1 alpha-3 codes of the ID document's issuing state (e.g. ESP,USA), which may differ from nationality. For KYB rows: the registry company's country code.

document_type

string

Comma-separated ID-document type codes verified in the session (KYC rows only): P (Passport), ID (Identity Card), DL (Driver's License), RP (Residence Permit), SSC (Social Security Card), HIC (Health Insurance Card), WP (Work Permit), TC (Tax Card), VISA, PSC (Public Service Card), BC (Birth Certificate), OTHER. Note the response field document_type contains the display name, not the code.

document_name

string

Exact document names; multiple names can be passed comma-separated, but the value is only split on commas when it contains more than one - separator (a lone name with an embedded comma is matched whole). Names are as recognized by document verification (front or back side), e.g. Spain - Id Card (2021). KYC rows only.

region

string

Comma-separated document region/state values (for documents issued per region, such as US driver's licenses). KYC rows only.

didit_internal_id

string<uuid>

Filter by Didit's internal user identifier (the didit_internal_id response field) to list all sessions of one verified user. Must be a valid UUID; malformed values return 400. KYC rows only.

session_type

string

Comma-separated session creation channels: API, HOSTED, MIGRATED. The special value ALL (or omitting the parameter) disables the filter. KYC rows only.

api_service

enum<string>

Filter standalone API sessions by service. Invalid values return 400. KYC rows only.

Available options:

ID_VERIFICATION,

FACE_MATCH,

AGE_ESTIMATION,

FACE_SEARCH,

POA,

AML,

KYB_REGISTRY,

PASSIVE_LIVENESS,

DATABASE_VALIDATION,

PHONE_VERIFICATION,

EMAIL_VERIFICATION

screened_full_name

string

Accent-insensitive name search inside AML and database-validation screened data. When combined with api_service=AML or api_service=DATABASE_VALIDATION, the search is restricted to that feature's screened data. KYC rows only.

warning

string

Comma-separated warning risk codes; returns sessions that raised any of them (e.g. POSSIBLE_FRAUD). Risk codes are listed per feature in the warnings documentation. Applies to KYC rows and, with business warning codes, to KYB rows.

status_initialized_as_in_review

boolean

When true, only sessions whose decision initially landed in In Review (useful to audit manual-review volume). KYC rows only.

is_kyc_to_be_reviewed

boolean

true returns sessions whose document verification is flagged for manual review; false returns sessions with document verification explicitly not flagged. Omit to disable. KYC rows only.

euuid

string<uuid>

Filter by the end user's euuid (UUID assigned to the verifying user, used by Console deep links). Must be a valid UUID; malformed values return a 400 field error. KYC rows only.

organization_name

string

Comma-separated organization names. Console-oriented; with an API key (already scoped to one application) it only matches your own organization's name.

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 for KYC rows; for KYB rows it is capped at 100 (use next to know whether more pages exist). For session_kind=all it is the sum of both kinds.

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

Retrieve Session Update Session Status

⌘I

​Session kind filter

​Common filters

​Examples

​Row shapes differ by kind

​Pagination

​Related

Authorizations

Query Parameters

Response

Session kind filter

Common filters

Examples

Row shapes differ by kind

Pagination

Related