Upload the front of the ID
Uploads the front of the user’s identity document as a base64-encoded image. This step acknowledges receipt; the next step (back) tells you what comes next.
Any upload response may include a warnings array with actionable feedback (for example, that the other side of the document is still needed).
The response’s extracted object carries what the document reader pulled off the image — use it to prefill your details form so the user confirms instead of typing.
Authorizations
Body
Optional document-type hint. Without it the document is auto-detected and defaults to a US driver's license. If a response warnings entry asks you to resubmit with a document_type, send the same image again with this field set — no need to go back to the user.
drivers_license, state_id, passport The end user's IP address as your frontend saw it (public IPv4 or IPv6; private or reserved addresses are rejected). Strongly recommended: identity screening checks the applicant's IP, and an IP belonging to a datacenter (such as your backend's) can fail an otherwise valid verification. Pass the address your user connected to you from; without it, your server's own address may be recorded as a last resort and can fail that screening.
Response
Receipt acknowledged — upload the back next. May include a warnings array.
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.