Skip to main content
GET
/
v3
/
sessions
List User Verification (KYC) and Business Verification (KYB) sessions
curl --request GET \
  --url https://verification.didit.me/v3/sessions \
  --header 'x-api-key: <api-key>'
{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "session_id": "5b3720ed-d429-42ef-b67f-37ea805f48ee",
      "session_number": 720,
      "session_url": "https://verify.didit.me/example",
      "portrait_image": "https://example.com/portrait",
      "document_type": "ID",
      "full_name": "Alejandro Rosas",
      "country": "ESP",
      "status": "Approved",
      "vendor_data": "user-1",
      "didit_internal_id": "d9e78474-6c8d-4f2a-bb90-6f5c2f3a1147",
      "created_at": "2025-06-09T12:26:54.328364Z",
      "features": [
        {
          "feature": "ID_VERIFICATION",
          "status": "Approved"
        },
        {
          "feature": "LIVENESS",
          "status": "Approved"
        },
        {
          "feature": "FACE_MATCH",
          "status": "Approved"
        },
        {
          "feature": "IP_ANALYSIS",
          "status": "Approved"
        }
      ],
      "workflow_label": "Standard KYC",
      "phone_number": {
        "number": "+14155552671",
        "is_verified": true
      },
      "email_address": {
        "email": "test@example.com",
        "is_verified": true
      }
    },
    {
      "session_id": "6c8f0c7a-e872-4a6d-9703-489b6a7e17ec",
      "session_number": 19,
      "session_url": "https://verify.didit.me/example",
      "portrait_image": "https://example.com/portrait",
      "document_type": "P",
      "full_name": "John Doe",
      "country": "USA",
      "status": "Declined",
      "vendor_data": null,
      "didit_internal_id": "4e3a91d1-8d4e-4d34-8d6f-c3f1fe4a4d28",
      "created_at": "2025-06-09T08:02:23.343053Z",
      "features": [
        {
          "feature": "ID_VERIFICATION",
          "status": "Declined"
        },
        {
          "feature": "LIVENESS",
          "status": "Approved"
        },
        {
          "feature": "FACE_MATCH",
          "status": "Approved"
        },
        {
          "feature": "IP_ANALYSIS",
          "status": "Approved"
        }
      ],
      "workflow_label": "Full Verification + AML",
      "phone_number": {
        "number": "+14155552671",
        "is_verified": true
      },
      "email_address": {
        "email": "test@example.com",
        "is_verified": true
      }
    }
  ]
}

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.

​
Session kind filter

Use the session_kind query parameter to choose which kind of sessions to return:
ValueReturns
user (default)Only User Verification (KYC) sessions. Backward-compatible behavior — omit session_kind to get this.
businessOnly Business Verification (KYB) sessions.
allBoth 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 parameterDescription
session_kinduser, business, or all. Default user.
vendor_dataExact match on your identifier.
statusAPPROVED, DECLINED, IN_REVIEW, etc.
workflow_idFilter by the workflow used.
countryCountry code filter (user: issuing_states, business: country_code).
date_from, date_toCreated-date window (ISO 8601).
searchSubstring match. For user: vendor_data, full name, document number, phone, email. For business: vendor_data, company name, registration number.

​
Examples

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

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

Authorizations

​
x-api-key
string
header
required

Query Parameters

​
vendor_data
string
default:""

A unique identifier for the vendor or user, such as a UUID or email. This field enables proper session tracking and user data aggregation across multiple verification sessions.

​
country
string
default:""

ISO 3166-1 alpha-3 country code representing the country of the country of the applicant's ID document, which may differ from nationality. For example, GBR.

​
status
string
default:""

The status of the verification session. For a complete list of possible verification statuses, refer to the Verification Statuses page.

​
workflow_id
string
default:""

The identifier of the verification workflow to filter sessions by. You can find this ID on the Workflows page in the Console.

​
offset
string
default:0

The number of items to skip before starting to return results.

​
limit
string
default:20

The maximum number of items to return in the response.

​
session_kind
enum<string>
default:user

Filter by session kind. Default user preserves backward compatibility.

Available options:
user,
business,
all

Response

200 - application/json
​
count
integer
Example:

2

​
next
string
Example:

null

​
previous
string
Example:

null

​
results
object[]