Upload the back of the ID

curl --request POST \
  --url https://api.agentcard.sh/api/v2/kyc/documents/back \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "user_id": "user_7g8h9i",
  "image": "<base64>",
  "mime_type": "image/jpeg"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({user_id: 'user_7g8h9i', image: '<base64>', mime_type: 'image/jpeg'})
};

fetch('https://api.agentcard.sh/api/v2/kyc/documents/back', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.agentcard.sh/api/v2/kyc/documents/back"

payload = {
    "user_id": "user_7g8h9i",
    "image": "<base64>",
    "mime_type": "image/jpeg"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "object": "kyc",
  "status": "needs_information",
  "required_fields": [
    "national_id_number",
    "phone_number"
  ],
  "extracted": {
    "document_type": "drivers_license",
    "issuing_country": "US",
    "document_number": "D1234567",
    "first_name": "Jane",
    "last_name": "Doe",
    "date_of_birth": "1990-05-14",
    "address_line1": "123 Market St",
    "address_city": "San Francisco",
    "address_region": "CA",
    "address_postal_code": "94105",
    "address_country": "US"
  }
}

POST

api

kyc

documents

back

Upload the back of the ID

curl --request POST \
  --url https://api.agentcard.sh/api/v2/kyc/documents/back \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "user_id": "user_7g8h9i",
  "image": "<base64>",
  "mime_type": "image/jpeg"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({user_id: 'user_7g8h9i', image: '<base64>', mime_type: 'image/jpeg'})
};

fetch('https://api.agentcard.sh/api/v2/kyc/documents/back', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.agentcard.sh/api/v2/kyc/documents/back"

payload = {
    "user_id": "user_7g8h9i",
    "image": "<base64>",
    "mime_type": "image/jpeg"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "object": "kyc",
  "status": "needs_information",
  "required_fields": [
    "national_id_number",
    "phone_number"
  ],
  "extracted": {
    "document_type": "drivers_license",
    "issuing_country": "US",
    "document_number": "D1234567",
    "first_name": "Jane",
    "last_name": "Doe",
    "date_of_birth": "1990-05-14",
    "address_line1": "123 Market St",
    "address_city": "San Francisco",
    "address_region": "CA",
    "address_postal_code": "94105",
    "address_country": "US"
  }
}

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.

image

string

required

The image bytes, base64-encoded.

mime_type

string

default:image/jpeg

The image's MIME type.

document_type

enum<string>

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.

Available options:

drivers_license,

state_id,

passport

issuing_country

string

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

The next step of the flow.

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.

Show child attributes

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.

Upload the front of the ID Submit information

⌘I

Authentication

Connect

Card attachment

Identity verification

Balance funding

Withdrawals

Platform connect

Upload the back of the ID

Authorizations

Body

Response