Start attested onboarding

curl --request POST \
  --url https://api.agentcard.sh/api/v2/onboarding_attempts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "phone": "+19295550123",
  "external_user_id": "your-internal-id"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({phone: '+19295550123', external_user_id: 'your-internal-id'})
};

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

import requests

url = "https://api.agentcard.sh/api/v2/onboarding_attempts"

payload = {
    "phone": "+19295550123",
    "external_user_id": "your-internal-id"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "object": "onboarding_attempt",
  "id": "oa_1a2b3c4d5e6f7a8b9c0d1e2f",
  "status": "pending",
  "wallet_url": "https://app.agentcard.sh/w/oa_1a2b3c4d5e6f7a8b9c0d1e2f.abc123",
  "expires_at": "2026-08-23T00:00:00.000Z",
  "test_mode": true
}

Connect

Start attested onboarding

Create an onboarding attempt for a phone number you already hold and text the returned wallet_url to the user. No Agentcard account exists yet: the user sees the wallet instantly, and our one-time code fires exactly once, inside our page, at their first money action. You never see or relay the code. Requires the attested-onboarding capability on your organization (ask us to enable it).

The response is identical whether or not the phone already belongs to an Agentcard account.

POST

api

onboarding_attempts

Start attested onboarding

curl --request POST \
  --url https://api.agentcard.sh/api/v2/onboarding_attempts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "phone": "+19295550123",
  "external_user_id": "your-internal-id"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({phone: '+19295550123', external_user_id: 'your-internal-id'})
};

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

import requests

url = "https://api.agentcard.sh/api/v2/onboarding_attempts"

payload = {
    "phone": "+19295550123",
    "external_user_id": "your-internal-id"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "object": "onboarding_attempt",
  "id": "oa_1a2b3c4d5e6f7a8b9c0d1e2f",
  "status": "pending",
  "wallet_url": "https://app.agentcard.sh/w/oa_1a2b3c4d5e6f7a8b9c0d1e2f.abc123",
  "expires_at": "2026-08-23T00:00:00.000Z",
  "test_mode": true
}

How it works

You already know your user’s phone number, so assert it: create an attempt and text the returned wallet_url into your thread. The user taps it and sees their Agentcard wallet immediately. No account exists yet, nothing was created beyond the attempt, and no code has been sent. The one-time code fires exactly once, inside our page, at the user’s first money action (adding their card, or their first purchase confirmation). Passing it creates the account, or binds the phone’s existing Agentcard account, and records the connection for your client. You never see or relay the code; that is the anti-phishing property of the whole flow. Then:

Listen for the connection.created webhook. It carries user_id, your external_user_id, and onboarding_attempt_id.
Call the exchange once to collect the connection token pair, and keep it alive with POST /api/v2/connect/refresh.

Attempts expire after 48 hours. Daily quotas apply per organization and per phone number. The capability is enabled per organization; ask us to turn it on.

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

phone

string

required

The user's phone. E.164 preferred; US local formats are normalized.

external_user_id

string

Your own id for this person, echoed on connection.created and the exchange.

Response

The attempt. Text wallet_url to the user; listen for connection.created, then exchange.

⌘I

Authentication

Connect

Add a card

Member cards

Balance

Withdrawals

Identity verification

Platform connect

Start attested onboarding

How it works

Authorizations

Body

Response

​How it works

Authorizations

Body

Response

How it works