Get verification status
Polls the current verification status — the alternative to the identity.verification.updated webhook.
Status values
Every KYC response carries exactly one status.Fully hosted, or fully custom
Every actionable status (awaiting_documents, needs_information, requires_verification) carries an iframe_url — a hosted page that walks the user through whatever the verification still needs: document capture, any typed details the review asks for, and the face scan. That gives you two integration styles with the same API:
- Fully hosted: ignore the upload and submit endpoints entirely. Whenever the status is actionable, hand the user the
iframe_url(new tab or embedded) — the flow completes end to end on the hosted page, and no identity documents or personal details ever pass through your servers. - Fully custom: drive the document upload and information submit endpoints from your own UI, and use the
iframe_urlonly atrequires_verificationfor the scan.
identity.verification.updated event rather than storing it.
Test mode reports a smaller status set. A sandbox verification never asks for identity: it reports only requires_verification (the iframe_url is the test-mode chooser), pending, approved, or rejected, so awaiting_documents and needs_information never appear. Complete it with simulate or the chooser; rehearse the full collection state machine against live with a real document.Authorizations
Response
The current status.
The single status contract every KYC response carries.
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 On every actionable status (awaiting_documents, needs_information, requires_verification): the hosted page that collects whatever the verification still needs, and the face scan at requires_verification. 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 — 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.