Switch how a single individual user is verified for payment eligibility, choosing between UrbanpayX-managed KYC and external attestation. The endpoint updates the user's verification mode, recomputes the user's effective verification source from existing status, records an audit entry, and returns the new mode. Requesting the mode the user is already in is treated as a no-op (the response says so).

Authentication & access

• Requires a client API token: Authorization: Bearer <token>.
• The caller must hold the kyc.users.write permission and have the OWNER or OPERATIONS role.

Path parameters

• user_id (required) — the individual user to update. The user must belong to your client; otherwise the request returns 404.

Request body

Only these two values are accepted for an individual user. Any other value is rejected with 422.

What switching the mode does

Changing the mode does not re-run or reset any verification; it only changes which path determines the user's eligibility, and the effective verification source is recomputed from the user's current status:

• Switching to urbanpayx_kyc — the user is treated as verified only if their UrbanpayX KYC status is already approved; otherwise the user reverts to unverified until KYC completes.
• Switching to external_attestation — the user is treated as verified only if their external verification status is already verified; otherwise the user is unverified until you mark them verified.

If verification_mode matches the user's current mode, no change is made and the response message indicates the mode is unchanged.

Response

200 OK with:

• user_id — the updated user's ID.
• verification_mode — the user's verification mode after the call.
• message — a confirmation indicating whether the mode was updated or left unchanged.

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.