Update Business External Verification Status

Time	Status	User Agent
Retrieving recent requests…

Record an external verification decision for a business customer that is in external attestation mode. UrbanpayX stores the decision (status, optional provider label, reference, reason, and raw payload) without running its own verification. A verified status marks the business as externally verified and stamps the time of verification; any other status clears a previously external-sourced verification. The endpoint records an audit entry, emits a kyb.status_changed event when the status or source changes, and returns the resulting verification state.

Authentication & access

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

Path parameters

business_id (string, required) — the business customer to update. Must belong to your client.

Verification mode precondition

This endpoint only applies to businesses operating in external attestation mode — where verification is performed outside UrbanpayX and the decision is reported back here. If the business is in UrbanpayX-managed KYB mode, the request is rejected with 400.

Request body

Field	Type	Required	Notes
`status`	enum	yes	The external verification decision: `pending`, `verified`, or `rejected`.
`provider`	string	no	Free-text label identifying the external verification provider. Max 128 characters.
`reference`	string	no	External case or reference id. Max 255 characters.
`reason`	string	no	Reason for the decision, recorded in the audit log and the status-change event. Max 255 characters.
`payload`	object	no	Raw external decision data, stored as-is.

What a status update does

The business's external status, provider, reference, and payload are overwritten with the values in the request (omitted optional fields are set to null).
status = verified: the verification source is set to external and the verification timestamp and acting account are recorded.
status = pending or rejected: if the business was previously verified through external attestation, its verification source is reset to none.
A verification event is written, and when the status or source actually changes a kyb.status_changed webhook event is queued.

Response

200 OK with a JSON object containing:

business_customer_id — the business id.
status — the stored external verification status (pending, verified, or rejected).
source — the resulting verification source (none, urbanpayx, or external).
provider — the stored provider label, or null.
reference — the stored external reference, or null.
verified_at — timestamp set when the status is verified, otherwise reflects any prior value.
message — a human-readable confirmation.

Error responses

Status	When
`400`	The business is not in external attestation mode.
`404`	No business customer with this `business_id` exists under your client.
`422`	Request body failed validation (e.g. missing or invalid `status`, a field over its max length).

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