List business customers with KYB status.
Returns a paginated list of business customers for the authenticated
client. Deactivated businesses (is_active=False) are excluded by
default; pass include_inactive=true to include them. Supports
optional filtering by raw kyb_status, effective_status (resolves
external_attestation businesses to their external_verification_status),
verification mode, external verification status, and a case-insensitive
substring search matched against company_name and registration_number.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Returns a paginated list of business customers belonging to the authenticated client, each with its current KYB status and verification metadata. Results are ordered by creation time, newest first. Deactivated businesses are excluded by default. This is a read-only endpoint with no side effects.
Authentication & access
- Requires a client API token:
Authorization: Bearer <token>. - The caller must hold the
kyb.businesses.readpermission and have one of the OWNER, DEVELOPER, or OPERATIONS roles.
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
page | integer (>= 1) | 1 | Page number (1-based). |
page_size | integer (1-200) | 20 | Items per page. |
kyb_status | enum | none | Filter by KYB status: none, pending, approved, rejected, on_hold. |
verification_mode | enum | none | Filter by verification mode: urbanpayx_kyc, urbanpayx_kyb, external_attestation. |
external_verification_status | enum | none | Filter by external verification status: pending, verified, rejected. |
q | string (max 255) | none | Case-insensitive substring search matched against company_name and registration_number. A blank or whitespace-only value is ignored. |
include_inactive | boolean | false | When false, deactivated businesses (is_active=false) are excluded. Set true to include them. |
All filters are optional and combine with AND semantics.
Response
Returns 200 with a BusinessCustomerListResponse object:
business_customers— an array of business customer objects for the current page. Each entry includesid,company_name,registration_number,country,legal_address,tax_id,contact_email,kyb_status,verification_mode,kyb_level,external_verification_status,verification_source,external_verification_provider,external_verification_ref,external_verified_at,is_active, andcreated_at.pagination— an object withtotal(items matching the query),page,page_size, andtotal_pages.
verification_mode indicates how a business is verified: urbanpayx_kyb for UrbanpayX-managed KYB, or external_attestation when verification is attested externally and recorded through UrbanpayX. The external_verification_* fields and verification_source are populated for businesses verified outside UrbanpayX-managed flows.
Error responses
| Status | When |
|---|---|
422 | A query parameter failed validation (e.g. page below 1, page_size outside 1-200, q longer than 255 characters, or an unrecognized 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.