Simulate an outcome (test mode)
Test mode only. Drives a test-mode verification to a chosen terminal outcome instantly — test verifications never complete on their own. The simulated verdict flows through the same status contract and fires the same identity.verification.updated webhook a real review produces, so your status handling and webhook consumer are exercised end to end. Requires a test-mode client credential; live tokens get 403 sandbox_only.
Why this exists
Test-mode verifications never complete on their own — there is no reviewer behind them. This endpoint is the missing verdict: pick an outcome and the verification reaches it instantly, through the same status contract and the sameidentity.verification.updated webhook a real review produces.
reason to see exactly how your UI renders a specific review
message. Re-simulating overwrites the previous outcome, so a single test user
can walk approved → rejected → approved without reconnecting.
Live tokens are refused with 403 sandbox_only: live verifications are
decided by the identity provider.Authorizations
A platform access token. Get one on the Create an access token endpoint by exchanging your client_id + client_secret, then send it as Authorization: Bearer <token>. Tokens live one hour.
Body
The connected user's id.
The verdict to apply. approved — verification succeeds. rejected — terminal rejection. requires_input — a retryable bounce asking for new document photos.
approved, rejected, requires_input Optional end-user-safe explanation carried on non-approved outcomes — it appears as reason in statuses and webhook events, exactly like a real review's. It must not name internal providers or identifiers (rejected with 400 invalid_reason), since it is shown to end users verbatim.
300Response
The verification's new state, exactly as GET /api/v2/kyc now reports it.
The single status contract every KYC response carries.
kyc awaiting_documents — upload the front and back. needs_information — collect the required_fields and submit them. requires_verification — show the user the iframe_url. pending — under review, no action needed. approved — verified, done. rejected — the user did not pass. Statuses are not one-way: a review can send a user back — pending may return to needs_information (a detail didn't match the document; re-collect the listed fields and resubmit, the check re-runs automatically) or to awaiting_documents (the images were unusable; upload both sides again). Always branch on the current status.
awaiting_documents, needs_information, requires_verification, pending, approved, rejected Only on needs_information — exactly the fields to collect and post to /kyc/information.
Only on requires_verification — the URL to show the user for the face scan. Embed it in an iframe with allow="camera; microphone". Short-lived: always use the most recent one from a poll or webhook, never a stored copy.
Optional, on document uploads — actionable feedback safe to show the user (for example, that the other side of the document is still needed).
Optional, on document uploads — what the document reader pulled off the uploaded image(s), so you can prefill your details form instead of asking the user to re-type what the ID already says. Keys match the /kyc/information request fields (first_name, last_name, date_of_birth, address_line1, address_city, address_region, address_postal_code, address_country) plus document_type, issuing_country, and document_number (the number printed on the document — for US documents this is NOT the SSN, so never prefill it into national_id_number when issuing_country is US). Fields appear as they become readable: the front usually carries the name and date of birth; a US back adds the barcode address. Always let the user confirm or correct prefilled values.
Optional, on needs_information, awaiting_documents, requires_verification, and rejected — a short, end-user-safe explanation of what the review asked for (for example, “Enter your full name exactly as it appears on your identity document.”). Safe to show the user verbatim.