Record external identity-verification decisions for many individual customers in one request. Each user must be in external-attestation verification mode (where you supply the decision from your own verification process rather than running UrbanpayX-managed verification). Items are processed independently with partial-success semantics: one item failing does not abort the batch. The endpoint always returns 200 with a per-item result breakdown, even when some or all items fail.

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.

Request body

Each item in items:

Verification mode requirement

Each target user must be in external-attestation verification mode. A user still in UrbanpayX-managed KYC mode is reported as a per-item failure — switch that user to external attestation first. This is an item-level error, not a request-level one.

What each status records

For each successfully processed item, the user's external verification state is set from the submitted status, provider, reference, and payload:

• verified — verification source becomes external and the verification timestamp is set to now.
• rejected — verification source becomes external; no verification timestamp.
• pending — verification source is cleared back to none; no verification timestamp.

Each successful item also writes a verification-history event and, when the resulting state differs from the prior state, emits a status-change notification. A single batch-level audit entry is recorded for the whole request with the total, succeeded, and failed counts.

Response

Returns 200 with a summary and a per-item breakdown:

• total — number of items submitted.
• succeeded — number of items processed successfully.
• failed — number of items that failed.
• results — array of per-item results in submission order. Each entry has:
  • index — zero-based position of the item in the request.
  • user_id — the user ID from the item.
  • success — whether the item was applied.
  • result — the update result (user_id, status, source, provider, reference, verified_at, message), present only when success is true.
  • error_code and error_message — populated only when success is false. For example, an item targeting a user that does not exist under your client, or a user not in external-attestation mode, fails with these fields set while other items continue.

A non-200 response is only returned when the request itself is malformed (see below).

Error responses

Item-level problems (user not found, user not in external-attestation mode, or an internal processing error) do not change the HTTP status: the request still returns 200, and the affected items appear in results with success: false and an error_code / error_message.

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