v1

latestOpenAPI 3.1.02026-07-26261466.6 KB

Identity verification

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.

post/api/v2/kyc/simulate

Request body

user_idstring required

The connected user's id.

outcome'approved' | 'rejected' | 'requires_input' required

The verdict to apply. approved — verification succeeds. rejected — terminal rejection. requires_input — a retryable bounce asking for new document photos.

reasonstring

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.

Response

The verification's new state, exactly as GET /api/v2/kyc now reports it.

object'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.

required_fieldsstring[]

Only on needs_information — exactly the fields to collect and post to /kyc/information.

iframe_urlstring

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.

warningsstring[]

Optional, on document uploads — actionable feedback safe to show the user (for example, that the other side of the document is still needed).

extractedobject

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.

reasonstring

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.