Records an externally-sourced identity verification result for an individual user that is in external-attestation mode. The endpoint stores the decision, the optional provider label, and reference on the user, updates the user's verification source, writes a verification history event, and returns the updated external verification state. The recorded result is what determines the user's payment eligibility while in external attestation.

Authentication & access

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

Verification mode precondition

This endpoint applies only to users in external attestation mode, where your client owns the verification decision and reports the outcome to UrbanpayX. The user identified by the user_id path parameter must already be set to external attestation. If the user is still in UrbanpayX-managed verification mode, the request returns 400 — switch the user to external attestation first.

Request body

How status maps to verification source

• verified — sets the verification source to external and stamps verified_at with the current time.
• rejected — sets the verification source to external and clears verified_at.
• pending — sets the verification source to none and clears verified_at.

Response

200 on success, returning the updated external verification state:

• user_id — the user that was updated.
• status — the recorded external verification status.
• source — the resulting verification source (none, urbanpayx, or external).
• provider — the stored provider label (may be null).
• reference — the stored external reference (may be null).
• verified_at — timestamp set only when status is verified, otherwise null.
• message — confirmation message.

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.