KYC (Know Your Customer) verification is not mandatory to use UrbanpayX — it's an optional service available to clients who need identity verification for their users.

If you don't require KYC or already use an external verification provider, set the verification mode to external_attestation and manage verification status on your own terms. If you'd like UrbanpayX to handle identity verification for you, use the urbanpayx_kyc mode to access our built-in verification flow.

All endpoints use the /api/v1/kyc base path.

Endpoints

Method	Endpoint	Description
`POST`	`/api/v1/kyc/users`	Create a new user record for KYC verification
`PATCH`	`/api/v1/kyc/users/{user_id}/verification-mode`	Switch a user's verification mode between `urbanpayx_kyc` and `external_attestation`
`POST`	`/api/v1/kyc/verify`	Initiate the KYC verification process for a user (UrbanpayX KYC mode)
`POST`	`/api/v1/kyc/external/status/{user_id}`	Submit or update external verification status for a user (external attestation mode)
`GET`	`/api/v1/kyc/lists`	List all users and their current KYC verification status
`GET`	`/api/v1/kyc/status/{user_id}`	Retrieve the KYC verification status for a specific user

Verification Modes

Mode	Description
`urbanpayx_kyc`	UrbanpayX handles identity verification. Call `POST /verify` to initiate the flow and receive a verification URL for the user.
`external_attestation`	The client performs identity verification externally. Call `POST /external/status/{user_id}` to report the verification result back to UrbanpayX.

Verification Flow

Create user — Register a user via POST /users with their basic information (email, name, etc.).
Choose mode — The default verification mode is set at the project level. Use PATCH /users/{user_id}/verification-mode to override it for a specific user if needed.
Verify — Depending on the mode:
- UrbanpayX KYC: Call POST /verify to get a Sumsub verification link. The user completes verification through the link. Results are delivered asynchronously via the kyc.status_changed webhook.
- External attestation: Submit the verification result via POST /external/status/{user_id}.
Check status — Query GET /status/{user_id} or GET /lists at any time to check verification status.

Related guides

KYC Verification Guide — Detailed flows for both verification modes, bulk operations, and status transitions
Core Concepts — How users and verification fit in the domain model
Error Reference — KYC-related errors
Pagination — User list pagination (default: 20, max: 200)