Skip to main content
GET
/
v3
/
users
/
curl
curl -X GET 'https://verification.didit.me/v3/users/?limit=50' \
  -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://<media-host>/...",
      "session_count": 3,
      "approved_count": 2,
      "declined_count": 0,
      "in_review_count": 1,
      "issuing_states": [
        "USA"
      ],
      "approved_emails": [
        "john@example.com"
      ],
      "approved_phones": [
        "+14155551234"
      ],
      "features": {
        "ID_VERIFICATION": "Approved",
        "LIVENESS": "Approved",
        "FACE_MATCH": "Approved",
        "AML": "Approved"
      },
      "features_list": [
        {
          "feature": "ID_VERIFICATION",
          "status": "Approved"
        },
        {
          "feature": "LIVENESS",
          "status": "Approved"
        },
        {
          "feature": "FACE_MATCH",
          "status": "Approved"
        },
        {
          "feature": "AML",
          "status": "Approved"
        }
      ],
      "last_session_at": "2025-06-15T10:30:00Z",
      "last_activity_at": "2025-06-15T10:30:00Z",
      "first_session_at": "2025-06-01T08:00:00Z",
      "tags": [
        {
          "uuid": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
          "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": {
        "ID_VERIFICATION": "In Review"
      },
      "features_list": [
        {
          "feature": "ID_VERIFICATION",
          "status": "In Review"
        }
      ],
      "last_session_at": "2025-06-20T14:00:00Z",
      "last_activity_at": "2025-06-20T14:05: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

​
limit
integer
default:50

Page size. Defaults to 50 when omitted. There is no enforced maximum, but keep pages small for latency.

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

Number of matching rows — exact up to 100, capped at 100 beyond that for performance. Do not use it to detect the last page; rely on next being null instead.

​
next
string | null

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

​
previous
string | null

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

​
results
object[]