---
title: "Start phone verification"
method: POST
path: "/api/v2/wallet/phone/start"
tags: ["Wallet funding"]
---

# Start phone verification

`POST /api/v2/wallet/phone/start`

Sends the user a one-time code. Relay it through your UI — the user reads it back to you, same pattern as the connect code. A verification stays fresh for 60 days. Provide `phone_number` only when the user has no phone on file (US numbers only).

## Request body

- object
  - `user_id` string, required
  - `phone_number` string — E.164 US number (`+1XXXXXXXXXX`). Used only when the user has no phone on file.

## Response `200`

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

- PhoneVerification
  - `object` 'phone_verification'
  - `status` 'sent' | 'already_verified' | 'verified'
  - `channel` 'sms' | 'email' — Where the code was sent (status `sent` only).
  - `phone` string — The masked destination number (status `sent` only).
  - `expires_in_seconds` integer — How long the code stays valid (status `sent` only).

## Other responses

- `400` — `invalid_request` — malformed `phone_number`.
- `401` — `unauthorized` — the platform access token is missing or expired. Exchange your client credentials for a fresh one.
- `404` — `connection_not_found` — no connection exists for that user under your client.
- `422` — `phone_number_required` — the user has no phone on file and none was provided.
- `429` — `otp_rate_limited` (with `retry_after_seconds`).
- `502` — `otp_send_failed` — try again.

---

[API](https://skmtc.dev/agentcard/apis/agentcard-api.md) · [All operations](https://skmtc.dev/agentcard/apis/agentcard-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/agentcard/agentcard-api/revisions/638d12c8303f/schema)