> ## Documentation Index > Fetch the complete documentation index at: https://docs.agentcard.sh/llms.txt > Use this file to discover all available pages before exploring further. # Start phone verification > 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). ## How it works Some flows need the user's phone OTP-verified — for example, [card attachment](/companies/api/reference/attach-start) lists `phone_number` under `user_info_required`. Same embedded pattern as [connect](/companies/api/reference/connect-start): we send the code, your UI collects it, you [verify it](/companies/api/reference/wallet-phone-verify) 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. ## OpenAPI ````yaml openapi.json POST /api/v2/wallet/phone/start openapi: 3.1.0 info: title: Agentcard API version: 2.0.0 description: >- The Agentcard v2 API — connect your users and verify their identity from your own backend. Every call is authenticated with a platform access token minted from your `client_id` + `client_secret`. servers: - url: https://api.agentcard.sh description: >- There is one base URL. Sandbox vs production is decided by the client credential you use, never by the host. security: - platformToken: [] tags: - name: Authentication description: >- Exchange your client credentials for a platform access token, and introspect what a token acts as. - name: Connect description: >- Connect a user to your platform: send a one-time code, verify it, record consent, and keep the connection alive. - name: Identity verification description: >- Verify a connected user's identity: upload their ID, submit any extra fields we ask for, then show a short face scan. - name: Wallet funding description: >- Fund a connected user's wallet from your own UI — request a payment link, relay the phone verification code, and poll until the funds land. - name: Withdrawals description: >- Move money out of a connected user's wallet — to a saved bank account or a crypto address on Base. Transfers are processed manually by the Agentcard team, usually within 1-3 business days. paths: /api/v2/wallet/phone/start: post: tags: - Wallet funding summary: Start phone verification description: >- 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). operationId: walletPhoneStart requestBody: required: true content: application/json: schema: type: object required: - user_id properties: user_id: type: string phone_number: type: string description: >- E.164 US number (`+1XXXXXXXXXX`). Used only when the user has no phone on file. example: user_id: usr_123 phone_number: '+14155550100' responses: '200': description: >- `sent` (code on its way) or `already_verified` (nothing to do — proceed to fund). content: application/json: schema: $ref: '#/components/schemas/PhoneVerification' example: object: phone_verification status: sent channel: sms phone: +1••••••0100 expires_in_seconds: 600 '400': description: '`invalid_request` — malformed `phone_number`.' content: application/json: schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/ConnectionNotFound' '422': description: >- `phone_number_required` — the user has no phone on file and none was provided. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: '`otp_rate_limited` (with `retry_after_seconds`).' content: application/json: schema: $ref: '#/components/schemas/Error' '502': description: '`otp_send_failed` — try again.' content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: PhoneVerification: type: object properties: object: type: string const: phone_verification status: type: string enum: - sent - already_verified - verified channel: type: string enum: - sms - email description: Where the code was sent (status `sent` only). phone: type: string description: The masked destination number (status `sent` only). expires_in_seconds: type: integer description: How long the code stays valid (status `sent` only). Error: type: object description: Every v2 error uses the same envelope. properties: error: type: object properties: code: type: string description: A stable, machine-readable string (snake_case). Branch on this. message: type: string description: A human-readable explanation, safe to log. docs: type: string description: A link back to the reference. field_errors: type: object additionalProperties: type: string description: Only on `invalid_fields` — names each field to fix. warnings: type: array items: type: string description: >- Only on document upload errors — actionable feedback safe to show the user. responses: Unauthorized: description: >- `unauthorized` — the platform access token is missing or expired. Exchange your client credentials for a fresh one. content: application/json: schema: $ref: '#/components/schemas/Error' ConnectionNotFound: description: >- `connection_not_found` — no connection exists for that user under your client. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: platformToken: type: http scheme: bearer description: >- 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 `. Tokens live one hour. ````