Skip to main content
POST
Submit information

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.

Body

application/json
user_id
string
required

The connected user's id.

first_name
string
last_name
string
date_of_birth
string

ISO 8601 date, YYYY-MM-DD.

national_id_number
string

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.

phone_number
string

E.164 format with country code (e.g. +15551234567).

address_line1
string
address_line2
string
address_city
string
address_region
string

State, province, or region.

address_postal_code
string
address_country
string

ISO 3166-1 alpha-2 country code (e.g. US).

user_ip
string

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.

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

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.

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.