Update Session Status

Manually override the final decision of a KYC or KYB verification session. Set new_status to Approved or Declined to record a manual decision, or to Resubmitted to clear specific verification steps and let the user redo them through the same verification URL. The endpoint accepts both user (KYC) and business (KYB) session IDs.

Call it once a session has reached a reviewable state: the current status must be Approved, Declined, In Review, Kyc Expired, Abandoned, or Resubmitted. Sessions that are still Not Started, In Progress, or Awaiting User, or that ended as Expired, return 400. The new status must differ from the current one, and your API key’s organization needs the write:sessions permission. The eligible-state check runs before body validation, so an ineligible session returns the Wrong Current Status error even when the payload is also invalid.

For Resubmitted, pass nodes_to_resubmit to choose which workflow steps the user must redo, or omit it to auto-select existing feature attempts in a resubmittable state (Declined, In Review, Not Finished, Expired). Never-attempted features are not auto-selected — list them explicitly in nodes_to_resubmit, or the request returns 400 when no recorded attempt needs resubmission. Captured data for the selected steps is deleted, the steps are reordered to match the workflow graph, the session’s expiration window restarts, and the original verification URL becomes usable again. Backend-only steps (AML, DATABASE_VALIDATION, IP_ANALYSIS) at the head of the list run immediately without user interaction; if every resubmitted step is backend-only, the session re-finalizes within the same request. KYB_REGISTRY and KYB_KEY_PEOPLE cannot be resubmitted directly — resubmit the relevant child KYC sessions instead and the parent business session recomputes automatically.

Every successful call fires the status.updated webhook once the change commits and appends an activity entry — with actor attribution and your comment — to the session’s reviews, visible in Get Decision and in the console activity timeline. The user-profile aggregates linked to the session’s vendor_data update as well. Declining disables ongoing AML monitoring for the session; re-approving re-enables it (from Resubmitted, Declined, or Kyc Expired) when the workflow has monitoring turned on. Approving or declining a child KYC that belongs to a KYB key-people check recomputes the parent business session’s status. Set send_email: true (with email_address) to notify the user: a status notice for Approved/Declined, or a resubmission email containing the verification link and per-step reasons for Resubmitted.

The operation is intentionally not repeatable with the same value: re-sending the current status returns 400 (The new status is the same as the current status.), so accidental double-submissions are harmless. Authentication and permission failures both return 403 — this API never responds 401.