Fetches the full identity-verification decision for a user from the verification provider, persists it onto the user record, and reconciles the user's kyc_status from that decision. This is the manual fallback for a missed verification webhook and the way to pull extracted document, liveness, and AML data onto the user on demand.

When called, the endpoint locks the user row, retrieves the latest decision for the user's verification session, stores a compact summary and the raw payload, applies any resulting status change, and persists a normalized verification record. If billing is configured to charge on completion, a terminal decision (Approved, Declined, or In Review) meters the verification; this is deduplicated by session, so it cannot double-bill with the webhook.

Authentication & access

• Requires a Bearer token in the Authorization header.
• Permission constant: kyc.verification.initiate.
• Allowed dashboard roles: owner, operations.
• API credentials must carry the kyc.verification.initiate permission.
• The verification provider must be configured; otherwise the request returns 503.

Path parameters

• user_id (string, required) - The user whose verification decision to fetch. The user must belong to the authenticated client.

Behavior

• The user must be in the provider-driven verification mode. A user configured for external_attestation is rejected with 400.
• The user must already have a verification session; if none exists, the request returns 404.
• Status reconciliation and the stored decision are committed even when persisting the normalized verification record or enqueuing document file-fetch fails (those steps are best-effort and do not fail the request).

Response

200 OK returns the reconciled decision:

• user_id (string) - The user's ID.
• kyc_status (string) - The user's current KYC status after reconciliation. One of none, pending, approved, rejected, on_hold.
• session_id (string, nullable) - The verification session the decision was fetched from.
• decision (object, nullable) - Compact summary of the verification decision.
• updated_at (string, nullable) - When the decision was last fetched/reconciled.
• message (string) - Human-readable result.

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.