> ## 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.
# List Users
> List [users](/entities/users) Didit assembles from KYC sessions sharing the same `vendor_data` (free-form string, NOT a UUID), plus users created via the API. Paginated, ordered by `last_session_at` desc. This endpoint does not support filtering or search parameters — fetch pages and filter client-side.
export const AgentPromptAccordion = ({prompt, title = "AI Agent Integration Prompt"}) => {
const [copied, setCopied] = React.useState(false);
const handleCopy = e => {
e.stopPropagation();
if (!prompt) return;
navigator.clipboard.writeText(prompt.trim()).then(() => {
setCopied(true);
setTimeout(() => setCopied(false), 2000);
});
};
const agents = ["Claude Code", "Codex", "Cursor", "Devin", "Windsurf", "GitHub Copilot"];
return
{}
{title}
{}
{prompt.trim()}
{}
Paste into
{agents.map(name => {name})}
;
};
Query params (all optional):
- status: "ACTIVE" | "FLAGGED" | "BLOCKED" (VendorUserStatusChoices, NOT the session enum).
- search: free-text over vendor_data, display_name, full_name, approved_emails, approved_phones.
- country: ISO 3166-1 alpha-3 (e.g. "USA", "ESP") — filters by issuing country of approved documents.
- limit: integer, 1–200, default 50.
- offset: integer, 0+, default 0. Prefer following the "next" URL from the previous page.
curl:
curl -X GET 'https://verification.didit.me/v3/users/?limit=50&status=ACTIVE' \\
-H 'x-api-key: YOUR_API_KEY'
Response 200 (envelope):
{
"count": ,
"next": ,
"previous": ,
"results": [ UserListItem, ... ]
}
UserListItem key fields: didit_internal_id (UUID), vendor_data (string, may be null), display_name, full_name, effective_name, status, portrait_image_url, session_count, approved_count, declined_count, in_review_count, issuing_states, approved_emails, approved_phones, features (map of feature -> "Approved" | "Declined" | "In Review" | ...), features_list, last_session_at, first_session_at, tags, created_at. See /reference/data-models for the full shape.
Notes:
- Ordered by last_session_at desc (most recently active first).
- Soft-deleted users are hidden from this list.
- vendor_data is a free-form client-supplied string, NOT a UUID. It may be null when the originating session did not provide one.
Pagination loop:
url = 'https://verification.didit.me/v3/users/?limit=200&status=ACTIVE'
while url:
r = requests.get(url, headers={'x-api-key': API_KEY})
r.raise_for_status()
page = r.json()
for user in page['results']:
...handle user...
url = page['next']
Failure modes (all return {"detail": "..."} unless noted):
- 401 — missing or revoked x-api-key.
- 403 — key valid but lacks list:users permission for this app.
- 429 — rate-limited. Honour Retry-After header.
For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.`}
/>
## Overview
Returns a paginated list of [User entities](/entities/users/overview) 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 parameter | Description |
| --------------------------------------------- | ------------------------------------------------------------------------------ |
| `status` | Filter by `ACTIVE`, `FLAGGED`, or `BLOCKED`. |
| `search` | Substring match on `vendor_data`, `display_name`, `full_name`, emails, phones. |
| `country_code` | Filter by `issuing_states` (ISO 3166-1 alpha-3). |
| `created_after`, `created_before` | Creation date window (ISO 8601). |
| `last_activity_after`, `last_activity_before` | Activity window. |
| `page_size` | 1–200. Default: 50. |
| `cursor` | Pagination 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](/entities/users/data-model) for all fields on a user row.
## Permissions
Role must grant `list:users`. See [Roles & permissions](/console/roles-permissions).
## Related
* [Users overview](/entities/users/overview)
* [Get user](/management-api/users/get)
* [User operations](/entities/users/operations)
## OpenAPI
````yaml GET /v3/users/
openapi: 3.0.0
info:
version: 3.0.0
title: Didit Verification API
description: Identity verification API. Authenticate with x-api-key header.
servers:
- url: https://verification.didit.me
security: []
tags: []
paths:
/v3/users/:
get:
tags:
- Users
summary: List users
description: >-
List [users](/entities/users) Didit assembles from KYC sessions sharing
the same `vendor_data` (free-form string, NOT a UUID), plus users
created via the API. Paginated, ordered by `last_session_at` desc. This
endpoint does not support filtering or search parameters — fetch pages
and filter client-side.
operationId: list_users
parameters:
- name: limit
in: query
schema:
type: integer
default: 50
minimum: 1
description: >-
Page size. Defaults to 50 when omitted. There is no enforced
maximum, but keep pages small for latency.
- name: offset
in: query
schema:
type: integer
default: 0
minimum: 0
description: >-
Zero-based offset of the first record to return. Prefer following
the `next` URL from the previous page over computing this by hand.
responses:
'200':
description: >-
Paginated list of users with verification status, session counts,
and feature breakdown.
content:
application/json:
schema:
type: object
properties:
count:
type: integer
description: >-
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:
type: string
nullable: true
description: Absolute URL of the next page, or `null` on the last page.
previous:
type: string
nullable: true
description: >-
Absolute URL of the previous page, or `null` on the first
page.
results:
type: array
items:
$ref: '#/components/schemas/UserListItem'
examples:
Example:
value:
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:///...
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'
'401':
description: >-
No credentials supplied. Requests to `/v3/users/*` paths without an
`x-api-key` header (or `Authorization: Bearer` token) are rejected
by the authentication middleware before reaching the API.
content:
application/json:
examples:
Missing credentials:
value:
detail: >-
You must be authenticated with a valid access token to
access this endpoint.
'403':
description: >-
Invalid or revoked API key, or the key cannot list users for this
application. Note: on this endpoint an *invalid* key returns `403`
(not `401`).
content:
application/json:
examples:
Forbidden:
value:
detail: You do not have permission to perform this action.
'429':
description: >-
Rate limit exceeded; back off and retry after the interval indicated
in `Retry-After`.
content:
application/json:
examples:
Rate limited:
value:
detail: Request was throttled. Expected available in 30 seconds.
security:
- ApiKeyAuth: []
x-codeSamples:
- lang: curl
label: curl
source: |-
curl -X GET 'https://verification.didit.me/v3/users/?limit=50' \
-H 'x-api-key: YOUR_API_KEY'
- lang: python
label: Python
source: |-
import requests
resp = requests.get(
'https://verification.didit.me/v3/users/',
headers={'x-api-key': 'YOUR_API_KEY'},
params={'limit': 50},
)
resp.raise_for_status()
page = resp.json()
for user in page['results']:
print(user['vendor_data'], user['status'])
- lang: javascript
label: JavaScript
source: |-
const url = new URL('https://verification.didit.me/v3/users/');
url.searchParams.set('limit', '50');
const page = await fetch(url, {
headers: { 'x-api-key': process.env.DIDIT_API_KEY },
}).then((r) => r.json());
console.log(page.count, page.results.length);
components:
schemas:
UserListItem:
type: object
description: A verified user.
properties:
didit_internal_id:
type: string
format: uuid
description: Didit's stable internal UUID for this user.
vendor_data:
type: string
nullable: true
description: >-
Your unique identifier for this user (passed when creating
sessions). This can be null when no vendor identifier was supplied.
display_name:
type: string
nullable: true
description: Custom display name set by you
full_name:
type: string
nullable: true
description: Full name extracted from verified documents
date_of_birth:
type: string
format: date
nullable: true
effective_name:
type: string
nullable: true
description: 'Best available name: display_name if set, otherwise full_name'
status:
type: string
enum:
- ACTIVE
- FLAGGED
- BLOCKED
description: >-
Lifecycle status of the user record (NOT a session status). `ACTIVE`
is the default, `FLAGGED` marks the user for manual attention,
`BLOCKED` prevents new sessions for this `vendor_data`.
portrait_image_url:
type: string
nullable: true
description: >-
Presigned URL of the user's portrait photo (expires after a few
hours)
session_count:
type: integer
description: Total number of verification sessions for this user
approved_count:
type: integer
description: Number of approved sessions
declined_count:
type: integer
description: Number of declined sessions
in_review_count:
type: integer
description: Number of sessions in review
issuing_states:
type: array
items:
type: string
description: >-
ISO 3166-1 alpha-3 codes of issuing countries seen on this user's
approved ID documents, e.g. `["USA", "ESP"]`. Empty array when none.
approved_emails:
type: array
items:
type: string
description: >-
Verified email addresses collected from this user's approved
sessions, e.g. `["john@example.com"]`.
approved_phones:
type: array
items:
type: string
description: >-
Verified phone numbers collected from this user's approved sessions,
e.g. `["+14155551234"]`.
features:
type: object
description: >-
Aggregated per-feature status across all of this user's sessions.
Possible keys: `ID_VERIFICATION`, `NFC`, `LIVENESS`, `FACE_MATCH`,
`POA`, `QUESTIONNAIRE`, `EMAIL_VERIFICATION`, `PHONE`, `AML`,
`IP_ANALYSIS`, `AGE_ESTIMATION`, `DATABASE_VALIDATION`. Possible
values: `Approved`, `Declined`, `In Review`, `Not Finished`, `Resub
Requested`.
features_list:
type: array
items:
type: object
properties:
feature:
type: string
status:
type: string
description: >-
Same data as `features`, as an ordered array of `{feature, status}`
objects.
last_session_at:
type: string
format: date-time
nullable: true
description: Timestamp of the most recent session
first_session_at:
type: string
format: date-time
nullable: true
description: Timestamp of the first session
last_activity_at:
type: string
format: date-time
nullable: true
description: >-
Timestamp of the most recent activity on this user (session,
transaction, status change, data edit, etc.).
tags:
type: array
items:
type: object
properties:
uuid:
type: string
format: uuid
name:
type: string
color:
type: string
description: Tags assigned to this user
created_at:
type: string
format: date-time
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
````