Sign in

v1

latestOpenAPI 3.1.02026-07-26261466.6 KB
Identity verification

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.

post/api/v2/kyc/documents/front

Request body

user_idstring required

The connected user's id.

imagestring required

The image bytes, base64-encoded.

mime_typestring

The image's MIME type.

document_type'drivers_license' | 'state_id' | 'passport'

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.

issuing_countrystring

Optional ISO 3166-1 country code (alpha-2 or alpha-3) of the country that issued the document. Defaults to US when the document doesn't reveal it — always send it for non-US documents (e.g. DE for a German national ID).

Response

Receipt acknowledged — upload the back next. May include a warnings array.

object'kyc'
status'awaiting_documents' | 'needs_information' | 'requires_verification' | 'pending' | 'approved' | 'rejected'

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.