Skip to main content
GET
Get verification status

Status values

Every KYC response carries exactly one status.

Authorizations

Authorization
string
header
required

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.

Query Parameters

user_id
string
required

The connected user's id.

Response

The current status.

The single status contract every KYC response carries.

object
enum<string>
Available options:
kyc
status
enum<string>

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.

Available options:
awaiting_documents,
needs_information,
requires_verification,
pending,
approved,
rejected
required_fields
string[]

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

iframe_url
string

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.

warnings
string[]

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

extracted
object

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.

reason
string

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.