> ## 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.

# Verify the phone code

> Checks the code the user read back. On success the verification stays fresh for 60 days and funding sessions can be created.

## Notes

* `phone_number` is **required when the user had no phone on file at [start](/companies/api/reference/wallet-phone-start)** (e.g. a fresh connection before KYC) — the code was sent to the number you supplied, can only be checked against it, and there's no stored number to fall back on, so a call without it returns `phone_number_required`. Keep passing that **same** number on verify until the user is verified: the code is only ever valid against the number it was sent to, so don't switch to a stored number that shows up mid-flight (a KYC backfill between start and verify). Omit `phone_number` only when start sent the code to a number already on file. It's optional in the schema only because that stored-number case exists.
* On `verified`, the user can fund immediately — the verification stays fresh for 60 days.
* `invalid_code` carries a `reason` (`incorrect`, `expired`, `too_many_attempts`, or `no_code`) so you can decide between "try again" and "send a new code".


## OpenAPI

````yaml openapi.json POST /api/v2/wallet/phone/verify
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/verify:
    post:
      tags:
        - Wallet funding
      summary: Verify the phone code
      description: >-
        Checks the code the user read back. On success the verification stays
        fresh for 60 days and funding sessions can be created.
      operationId: walletPhoneVerify
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - user_id
                - code
              properties:
                user_id:
                  type: string
                code:
                  type: string
                phone_number:
                  type: string
                  description: >-
                    Required only when the code was sent to a number you
                    provided.
            example:
              user_id: usr_123
              code: '123456'
              phone_number: '+14155550100'
      responses:
        '200':
          description: Verified.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneVerification'
              example:
                object: phone_verification
                status: verified
        '400':
          description: '`invalid_request` — missing fields.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ConnectionNotFound'
        '422':
          description: '`invalid_code` (with `reason`) or `phone_number_required`.'
          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 <token>`. Tokens live one hour.

````