Fetch the full KYB decision for a business customer from the verification provider, persist it onto the business record, and reconcile the KYB status. Although this is a GET, it is a write operation: it stores the latest decision (summary plus raw payload), updates kyb_status when the provider status has changed, records a normalized verification record, and enqueues a background fetch of any extracted files. It is the fallback when a status webhook is missed, and the on-demand way to pull the extracted company, document, and AML data onto the business record.

Authentication & access

• Requires a client API token: Authorization: Bearer <token>.
• The caller must hold the kyb.verification.initiate permission and have the OWNER or OPERATIONS role.
• The verification backend must be configured. If it is not, the request returns 503.

Path parameters

• business_id (required) - the business customer ID. The business must exist under your client.

Behavior

• The business must not be in external_attestation verification mode; that mode is not provider-backed (400).
• The business must already have a verification session. If none exists, the request returns 404.
• On a successful fetch the decision is summarized and stored, the KYB status is reconciled, and when the on-completion billing mode is active a usage event is recorded (deduplicated by session, so it cannot double-bill with the webhook).

Response

200 - Decision fetched and reconciled. The body is a KybDecisionResponse:

• business_customer_id - the business customer ID.
• kyb_status - the reconciled status: one of none, pending, approved, rejected, on_hold.
• session_id - the verification session the decision was fetched from (nullable).
• decision - a compact summary of the verification decision (nullable object).
• updated_at - when the decision was last fetched and reconciled (nullable).
• message - a 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.