Import a verification (Sumsub share token)

curl --request POST \
  --url https://api.agentcard.sh/api/v2/kyc/import \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "user_id": "user_7g8h9i",
  "share_token": "_act-jwt-eyJhbGciOiJub25lIn0..."
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({user_id: 'user_7g8h9i', share_token: '_act-jwt-eyJhbGciOiJub25lIn0...'})
};

fetch('https://api.agentcard.sh/api/v2/kyc/import', 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/import"

payload = {
    "user_id": "user_7g8h9i",
    "share_token": "_act-jwt-eyJhbGciOiJub25lIn0..."
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "object": "kyc",
  "status": "pending"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

Identity verification

Import a verification

Import a verification you already ran on your own Sumsub account (Reusable KYC). Generate a single-use share token for the Agentcard client id, send it here, and the user skips document capture and the face scan. A successful import drops into the exact same status contract as a fresh verification: poll GET /api/v2/kyc or listen for identity.verification.updated. Requires one-time partner pairing between your Sumsub account and Agentcard’s (per environment) — ask your Agentcard contact to enable it. Share tokens are single-use with a short TTL, so generate one fresh per import attempt.

POST

api

kyc

import

Import a verification (Sumsub share token)

curl --request POST \
  --url https://api.agentcard.sh/api/v2/kyc/import \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "user_id": "user_7g8h9i",
  "share_token": "_act-jwt-eyJhbGciOiJub25lIn0..."
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({user_id: 'user_7g8h9i', share_token: '_act-jwt-eyJhbGciOiJub25lIn0...'})
};

fetch('https://api.agentcard.sh/api/v2/kyc/import', 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/import"

payload = {
    "user_id": "user_7g8h9i",
    "share_token": "_act-jwt-eyJhbGciOiJub25lIn0..."
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "object": "kyc",
  "status": "pending"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

Where the token comes from

The share_token is a Sumsub artifact you mint on your own account, so this endpoint only applies if you run KYC on Sumsub yourself. Generate it with Sumsub’s POST /resources/accessTokens/shareToken, with forClientId set to the Agentcard client id from your pairing setup. Tokens are single-use and expire after their ttlInSecs: generate one right before each import call, never from storage.

After the import

The import creates the verification on Agentcard’s side, and from that moment nothing distinguishes it from one your user ran here. Poll GET /api/v2/kyc or consume the identity.verification.updated webhook; a needs_information status carries the exact required_fields to submit via POST /api/v2/kyc/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.

A Sumsub share token generated by your account for the Agentcard client id (POST /resources/accessTokens/shareToken with forClientId). Single-use; expires after its ttlInSecs.

Response

The verification's state after the import, exactly as GET /api/v2/kyc now reports it. A complete applicant lands on pending while checks run (then approved); an applicant missing program fields lands on needs_information with the exact required_fields.

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.

⌘I

Authentication

Connect

Add a card

Balance

Withdrawals

Identity verification

Platform connect

Import a verification

Where the token comes from

After the import

Authorizations

Body

Response

​Where the token comes from

​After the import

Authorizations

Body

Response

Where the token comes from

After the import