Submit information
Submits the extra fields requested by a needs_information response. Send only the fields listed in required_fields; values are trimmed, and a blank value counts as not provided. For a fresh verification, the response returns the iframe_url for the face scan. For an imported verification (Reusable KYC), the submit that completes the residential address returns pending and files the card issuer application right after it, in the background, so the response never waits on the issuer; the verification then moves to approved or rejected through the status poll or the identity.verification.updated webhook. Repeating the request is safe: it returns the current status.
Authorizations
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.
Body
The connected user's id.
ISO 8601 date, YYYY-MM-DD.
The user's national ID or tax identification number for the country that issued their document — for US documents this is the SSN; for any other country it is the national ID / tax number printed on (or associated with) the document. Forwarded to the verification provider only; never stored by Agentcard.
E.164 format with country code (e.g. +15551234567).
State, province, or region.
ISO 3166-1 alpha-2 country code (e.g. US).
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
The next step: requires_verification with the iframe_url for a fresh verification, or pending when the submit completed an imported verification (the card issuer application is filed right after the response).
The single status contract every KYC response carries.
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.
awaiting_documents, needs_information, requires_verification, pending, approved, rejected Only on needs_information — exactly the fields to collect and post to /kyc/information.
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 — actionable feedback safe to show the user (for example, that the other side of the document is still needed).
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.
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.