Change a business's verification mode.
Switches the business between urbanpayx_kyb (managed verification) and
external_attestation (you record the decision yourself). Switching modes
clears the verification source unless the business is already approved/verified.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Switch a business customer between the two KYB verification modes. When the mode actually changes, UrbanPayX recomputes the business's verification source: switching from external attestation back to managed KYB clears the recorded source unless KYB is already approved, and switching from managed KYB to external attestation clears it unless an external decision is already verified. The change is audit-logged. Returns the business id, its current verification mode, and a confirmation message.
If the requested mode matches the current mode, the request is a no-op (no source change, no audit entry) and still returns 200.
Authentication & access
- Requires a client API token:
Authorization: Bearer <token>. - The caller must hold the
kyb.businesses.writepermission and have the OWNER or OPERATIONS role.
Path parameters
| Parameter | Description |
|---|---|
business_id | The id of the business customer under your client. Must exist or the request returns 404. |
Request body
| Field | Required | Description |
|---|---|---|
verification_mode | yes | Target mode. One of urbanpayx_kyb (UrbanPayX-managed KYB) or external_attestation (you record the verification decision yourself). |
Verification modes
urbanpayx_kyb— UrbanPayX-managed verification. The business is verified through UrbanPayX's KYB flow.external_attestation— You verify the business outside UrbanPayX and record the decision via the external status endpoint.
urbanpayx_kyc is an individual-customer mode and is not accepted for a business; sending it fails validation (422).
What the switch does
When the new mode differs from the current one, UrbanPayX adjusts the stored verification source:
- Switching to
urbanpayx_kybwhile the source is external and KYB is not yet approved clears the verification source. - Switching to
external_attestationwhile the source is UrbanPayX-managed and the external decision is not yet verified clears the verification source. - An already-approved (KYB) or already-verified (external) business keeps its verification source across the switch.
Response
200 — Returns the updated state:
business_customer_id— the business id.verification_mode— the business's current verification mode after the call.message— confirmation text.
Error responses
| Status | When |
|---|---|
404 | No business customer with this id under your client |
422 | Request body failed validation (missing verification_mode, or a value other than urbanpayx_kyb / external_attestation) |
Standard 401 (authentication), 403 (insufficient permission or role), and 429 (rate limit) responses apply to every endpoint and are documented in the Error reference.