Skip to main content
GET
/
v3
/
users
curl
curl -X GET 'https://verification.didit.me/v3/users/?limit=50&status=ACTIVE' \
  -H 'x-api-key: YOUR_API_KEY'
{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "didit_internal_id": "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418",
      "vendor_data": "user-abc-123",
      "display_name": null,
      "full_name": "John Michael Doe",
      "date_of_birth": "1990-05-15",
      "effective_name": "John Michael Doe",
      "status": "ACTIVE",
      "portrait_image_url": "https://service-didit-verification.s3.amazonaws.com/...",
      "session_count": 3,
      "approved_count": 2,
      "declined_count": 0,
      "in_review_count": 1,
      "issuing_states": {
        "USA": 2
      },
      "approved_emails": {
        "john@example.com": true
      },
      "approved_phones": {
        "+14155551234": true
      },
      "features": {
        "OCR": "Approved",
        "LIVENESS": "Approved",
        "FACE_MATCH": "Approved",
        "AML": "Approved"
      },
      "features_list": [
        {
          "feature": "OCR",
          "status": "Approved"
        },
        {
          "feature": "LIVENESS",
          "status": "Approved"
        },
        {
          "feature": "FACE_MATCH",
          "status": "Approved"
        },
        {
          "feature": "AML",
          "status": "Approved"
        }
      ],
      "last_session_at": "2025-06-15T10:30:00Z",
      "first_session_at": "2025-06-01T08:00:00Z",
      "tags": [
        {
          "uuid": "t1111111-2222-3333-4444-555555555555",
          "name": "VIP",
          "color": "#2567FF"
        }
      ],
      "created_at": "2025-06-01T08:00:00Z"
    },
    {
      "didit_internal_id": "6ed99d53-e8f5-4cf8-9ac1-4a506cb40f6b",
      "vendor_data": null,
      "display_name": "Jane S.",
      "full_name": "Jane Elizabeth Smith",
      "date_of_birth": "1985-11-22",
      "effective_name": "Jane S.",
      "status": "FLAGGED",
      "portrait_image_url": null,
      "session_count": 1,
      "approved_count": 0,
      "declined_count": 0,
      "in_review_count": 1,
      "issuing_states": {},
      "approved_emails": {},
      "approved_phones": {},
      "features": {
        "OCR": "In Review"
      },
      "features_list": [
        {
          "feature": "OCR",
          "status": "In Review"
        }
      ],
      "last_session_at": "2025-06-20T14:00:00Z",
      "first_session_at": "2025-06-20T14:00:00Z",
      "tags": [],
      "created_at": "2025-06-20T14:00:00Z"
    }
  ]
}

​
Overview

Returns a paginated list of User entities for the authenticated application. Use this to sync users to your warehouse, find users needing analyst attention, or search by display name.

​
When to use it

  • Periodic sync of your user table to an external BI or warehouse.
  • Analyst queues — filter by status=FLAGGED or stale last_activity_at to drive a review inbox.
  • Search users by display_name, full_name, or vendor_data.

​
Filters and pagination

Query parameterDescription
statusFilter by ACTIVE, FLAGGED, or BLOCKED.
searchSubstring match on vendor_data, display_name, full_name, emails, phones.
country_codeFilter by issuing_states (ISO 3166-1 alpha-3).
created_after, created_beforeCreation date window (ISO 8601).
last_activity_after, last_activity_beforeActivity window.
page_size1–200. Default: 50.
cursorPagination cursor returned in the previous response.

​
Notes

  • Each response item includes didit_internal_id. vendor_data may be null when the original session or transaction did not provide one.
  • This endpoint paginates via cursor — persist the next cursor between calls and stop when next is empty.
  • See the User data model for all fields on a user row.

​
Permissions

Role must grant list:users. See Roles & permissions.

Authorizations

​
x-api-key
string
header
required

Query Parameters

​
status
enum<string>

Filter by the user's lifecycle status. ACTIVE is the default for any user, FLAGGED marks the user for manual review, and BLOCKED prevents new sessions for that vendor_data (and also adds it to the system blocklist).

Available options:
ACTIVE,
FLAGGED,
BLOCKED
​
search
string

Free-text search across vendor_data, display_name, full_name, approved emails and approved phone numbers.

​
country
string

Filter by issuing country of the user's approved ID document, ISO 3166-1 alpha-3 (e.g. USA, ESP).

​
limit
integer
default:50

Page size. Maximum 200; defaults to 50.

Required range: 1 <= x <= 200
​
offset
integer
default:0

Zero-based offset of the first record to return. Prefer following the next URL from the previous page over computing this by hand.

Required range: x >= 0

Response

Paginated list of users with verification status, session counts, and feature breakdown.

​
count
integer

Total number of users matching filters

​
next
string | null

URL of next page

​
previous
string | null

URL of previous page

​
results
object[]