List users with KYC status
Returns a paginated list of end users for the authenticated client.
Deactivated users (is_active=False) are excluded by default; pass
include_inactive=true to include them. Supports optional filtering
by KYC status, verification mode, external verification status, and a
case-insensitive substring search matched against full_name and email.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Returns a paginated list of the end users (individual customers) registered under the authenticated client, together with each user's verification status. Deactivated users are excluded by default. The list supports filtering by KYC status, verification mode, and external attestation status, plus a free-text search over name and email.
Authentication & access
- Requires a client API token:
Authorization: Bearer <token>. - The caller must hold the
kyc.users.readpermission. - Allowed roles: OWNER, DEVELOPER, OPERATIONS.
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
page | integer (>= 1) | 1 | Page number (1-based). |
page_size | integer (1-200) | 20 | Items per page. |
kyc_status | enum | - | Filter by KYC status: none, pending, approved, rejected, on_hold. |
verification_mode | enum | - | Filter by verification mode: urbanpayx_kyc, urbanpayx_kyb, external_attestation. |
external_verification_status | enum | - | Filter by external attestation status: pending, verified, rejected. |
q | string (<= 255 chars) | - | Case-insensitive substring search matched against full_name and email. |
include_inactive | boolean | false | When false, deactivated users (is_active=false) are omitted. Set true to include them. |
All filters are optional and combine with logical AND. A blank or whitespace-only q is ignored.
Verification modes
A user's verification_mode indicates how their verified status is obtained:
- UrbanpayX-managed (
urbanpayx_kyc): the user is verified through UrbanpayX-managed KYC.kyc_statusreflects the verification outcome. - External attestation (
external_attestation): the user's verified status is attested outside UrbanpayX. In this modeexternal_verification_statusis the relevant field, andexternal_verification_provider,external_verification_ref, andexternal_verified_atcarry the attestation details when present.
verification_source records what granted the user's verified status: none, urbanpayx, or external.
Response
200 returns a UserListResponse:
users- an array of users on the current page, ordered bycreated_atdescending. Each entry includesid,email,full_name,kyc_status,verification_mode,external_verification_status,verification_source,external_verification_provider,external_verification_ref,external_verified_at,is_active, andcreated_at.pagination-total(items matching the query),page,page_size, andtotal_pages.
Error responses
| Status | When |
|---|---|
422 | A query parameter failed validation (e.g. page < 1, page_size outside 1-200, q longer than 255 characters, or an invalid enum value). |
Standard 401 (authentication), 403 (insufficient permission or role), and 429 (rate limit) responses apply to every endpoint and are documented in the Error reference.