Start phone verification

curl --request POST \
  --url https://api.agentcard.sh/api/v2/wallet/phone/start \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "user_id": "usr_123",
  "phone_number": "+14155550100"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({user_id: 'usr_123', phone_number: '+14155550100'})
};

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

import requests

url = "https://api.agentcard.sh/api/v2/wallet/phone/start"

payload = {
    "user_id": "usr_123",
    "phone_number": "+14155550100"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "object": "phone_verification",
  "status": "sent",
  "channel": "sms",
  "phone": "+1••••••0100",
  "expires_in_seconds": 600
}

{
  "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>"
    ]
  }
}

POST

api

wallet

phone

start

Start phone verification

curl --request POST \
  --url https://api.agentcard.sh/api/v2/wallet/phone/start \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "user_id": "usr_123",
  "phone_number": "+14155550100"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({user_id: 'usr_123', phone_number: '+14155550100'})
};

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

import requests

url = "https://api.agentcard.sh/api/v2/wallet/phone/start"

payload = {
    "user_id": "usr_123",
    "phone_number": "+14155550100"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "object": "phone_verification",
  "status": "sent",
  "channel": "sms",
  "phone": "+1••••••0100",
  "expires_in_seconds": 600
}

{
  "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>"
    ]
  }
}

How it works

Some flows need the user’s phone OTP-verified — for example, card attachment lists phone_number under user_info_required. Same embedded pattern as connect: we send the code, your UI collects it, you verify it server-to-server.

If the user already has a verified phone that’s still fresh, the response is already_verified — nothing more to collect.
Pass phone_number only when the user has no phone on file. US numbers only (+1XXXXXXXXXX).
A verification stays fresh for 60 days; after that, run this flow again when a phone is required.

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

phone_number

string

E.164 US number (+1XXXXXXXXXX). Used only when the user has no phone on file.

Response

sent (code on its way) or already_verified (nothing to do — proceed to fund).

object

string

Allowed value: "phone_verification"

status

enum<string>

Available options:

sent,

already_verified,

verified

channel

enum<string>

Where the code was sent (status sent only).

Available options:

sms,

email

phone

string

The masked destination number (status sent only).

expires_in_seconds

integer

How long the code stays valid (status sent only).

Simulate an outcome (test mode)Verify the phone code

⌘I

Authentication

Connect

Card attachment

Identity verification

Balance funding

Withdrawals

Platform connect

Start phone verification

How it works

Authorizations

Body

Response

​How it works

Authorizations

Body

Response

How it works