> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useanima.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Patch phonenumbers



## OpenAPI

````yaml /openapi.json patch /phone/numbers/{phoneIdentityId}
openapi: 3.1.1
info:
  title: Anima API
  version: 0.1.0
  description: >-
    The Anima API provides programmatic access to unified infrastructure for AI
    agents: create and manage agents; send and receive email; place phone calls
    and send/receive SMS and voice; store and retrieve vault credentials; manage
    agent identity; and configure webhooks for real-time events. Authenticate
    using a Bearer token or an API key passed via the X-API-Key header.
  contact:
    name: Anima Labs
    url: https://useanima.sh
    email: support@useanima.sh
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: https://api.useanima.sh/v1
    description: Production
security:
  - BearerAuth: []
  - ApiKeyAuth: []
paths:
  /phone/numbers/{phoneIdentityId}:
    patch:
      operationId: phone.updateNumber
      parameters:
        - name: phoneIdentityId
          in: path
          required: true
          schema:
            type: string
            description: The number to update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                voiceId:
                  anyOf:
                    - type: string
                    - type: 'null'
                  description: >-
                    Voice id from the catalog, or null to fall back to the
                    agent's voice. Rejected if the id is not in the catalog.
              required:
                - voiceId
              description: Update one phone number's settings
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    pattern: ^[cC][^\s-]{8,}$
                    description: Unique identifier of the phone identity
                  phoneNumber:
                    type: string
                    description: Phone number in E.164 format
                  providerId:
                    anyOf:
                      - type: string
                      - type: 'null'
                    description: Opaque carrier-side identifier for this phone number
                  capabilities:
                    type: object
                    properties:
                      sms:
                        default: false
                        type: boolean
                        description: Whether the number supports SMS messaging
                      mms:
                        default: false
                        type: boolean
                        description: Whether the number supports MMS messaging
                      voice:
                        default: false
                        type: boolean
                        description: Whether the number supports voice calls
                    description: Communication capabilities supported by this phone number
                  tenDlcStatus:
                    enum:
                      - PENDING
                      - REGISTERED
                      - REJECTED
                      - NOT_REQUIRED
                      - UNREGISTERED
                    type: string
                    description: 10DLC campaign registration status
                  isPrimary:
                    type: boolean
                    description: Whether this is the agent's primary phone identity
                  voiceId:
                    anyOf:
                      - type: string
                      - type: 'null'
                    description: >-
                      The voice this number answers with, from the voice
                      catalog. Null means it uses the agent's voice, and then
                      the system default. Set it per number so one agent's
                      support line and sales line can sound different.
                  createdAt:
                    type: string
                    format: date-time
                    description: Timestamp when the phone identity was created
                required:
                  - id
                  - phoneNumber
                  - providerId
                  - capabilities
                  - tenDlcStatus
                  - isPrimary
                  - voiceId
                  - createdAt
                description: Phone identity associated with an agent
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        JWT Bearer token obtained from authentication. Pass as: Authorization:
        Bearer <token>
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'API key for programmatic access. Pass as: X-API-Key: <your-key>'

````