Initiates KYC verification for an end user under the authenticated client. The endpoint creates the user if one with the given email does not already exist, registers them for UrbanpayX-managed verification, and returns a hosted verification link to send to the user. If the user already has a terminal KYC status, the existing state is returned instead of starting a new session. This endpoint applies only to users in urbanpayx_kyc verification mode.

Authentication & access

• Requires a Bearer token in the Authorization header.
• Requires the kyc.verification.initiate permission.
• For dashboard (user) sessions, the account role must be owner or operations. The developer role is not allowed.
• API-credential callers must carry the kyc.verification.initiate permission on the credential.
• The client must have KYC link generation enabled. If it is disabled, the request is rejected with 403.

Request body

• email (required) - email address of the user. Normalized to lowercase before lookup; the user record is keyed on (client, email).
• full_name (required) - full name of the user.
• level_name (optional, default id-and-liveness) - verification level key from GET /api/v1/kyc/levels, 1-64 characters. The key must exist in the catalog, be active, and be accessible to your client; otherwise the request is rejected with 400.
• callback_url (optional, HTTPS only, max 1024 characters) - URL the user is redirected to after completing verification. When omitted, it falls back to your client's default verification callback URL. A non-HTTPS or malformed URL is rejected with 422.

The verification level maps to UrbanpayX-managed verification settings internally; callers reference levels only by their catalog key.

Behavior

• If a matching user exists in external_attestation mode, the request is rejected with 400; the user must be switched to urbanpayx_kyc first.
• If a matching user already has a terminal status (approved, rejected, or on_hold), that status is returned immediately and no new session is created. For these users the response carries no verification_url.
• Otherwise (new user, or a user with status none or pending) a verification session is created, the user's status is set to pending, and a fresh verification_url is returned.

Response

200 OK returns a KYCVerificationResponse:

• user_id - the user's unique ID.
• kyc_status - one of none, pending, approved, rejected, on_hold.
• verification_url - the link to send to the user, or null when no link applies (for example an already-approved, rejected, or on-hold user).
• message - human-readable description of the current verification state.

Error responses

Standard 401 (authentication), 403 (insufficient permission or role), and 429 (rate limit) responses apply to every endpoint and are documented in the Error reference.