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

# Update phone number

> Update a phone number's display name, direction flags, inbound agent, or metadata. Toggling `inbound_enabled` reconciles the per-number LiveKit inbound routing; for BYO-trunk numbers, supply the (never-stored) SIP `auth_password` to re-provision inbound. Rejected/archived numbers cannot have their direction/agent reconfigured. Requires the admin-tier `phone_numbers:write` scope (customer/platform admins, or an API key bearing the scope). Scope `phone_numbers:write`.



## OpenAPI

````yaml /api-reference/openapi.json patch /phone-numbers/{phone_number_id}
openapi: 3.1.0
info:
  title: Lehar API
  version: v0
  description: >-
    Customer-facing REST API for the Lehar voice-AI platform. Platform-admin
    endpoints are intentionally excluded from this reference. Regenerate with
    `npm run sync:openapi`.
servers:
  - url: https://api.lehar.ai/ca/api/v0
security:
  - ApiKeyAuth: []
  - BearerAuth: []
paths:
  /phone-numbers/{phone_number_id}:
    patch:
      tags:
        - Phone Numbers
      summary: Update phone number
      description: >-
        Update a phone number's display name, direction flags, inbound agent, or
        metadata. Toggling `inbound_enabled` reconciles the per-number LiveKit
        inbound routing; for BYO-trunk numbers, supply the (never-stored) SIP
        `auth_password` to re-provision inbound. Rejected/archived numbers
        cannot have their direction/agent reconfigured. Requires the admin-tier
        `phone_numbers:write` scope (customer/platform admins, or an API key
        bearing the scope). Scope `phone_numbers:write`.
      operationId: update_phone_number_ca_api_v0_phone_numbers__phone_number_id__patch
      parameters:
        - name: phone_number_id
          in: path
          required: true
          description: The phone number id.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: At least one recognized field is required.
              properties:
                display_name:
                  type: string
                  nullable: true
                  description: Human label; empty/whitespace is stored as null.
                outbound_enabled:
                  type: boolean
                  description: Enable/disable outbound caller ID use.
                inbound_enabled:
                  type: boolean
                  description: >-
                    Enable/disable inbound answering; reconciles LiveKit inbound
                    routing.
                inbound_agent_id:
                  type: string
                  nullable: true
                  description: Published agent to answer inbound calls; null to clear.
                metadata:
                  type: object
                  nullable: true
                  description: Replaces the stored metadata object.
                auth_password:
                  type: string
                  writeOnly: true
                  description: >-
                    For BYO-trunk numbers only: the SIP password, used solely to
                    re-provision inbound. Write-only — never persisted or
                    returned.
              example:
                inbound_enabled: true
                inbound_agent_id: agt_9f8e7d
      responses:
        '200':
          description: Updated phone number.
          content:
            application/json:
              example:
                id: pn_a1b2c3d4
                number: '+919876543210'
                display_name: Sales line
                source: byo_trunk
                sip_trunk_id: trunk_x1y2z3
                sip_trunk_name: Acme SIP
                status: active
                outbound_enabled: true
                inbound_enabled: true
                inbound_agent_id: agt_9f8e7d
                provider: acme-telecom
                metadata: {}
                created_at: '2026-09-01T12:00:00Z'
                updated_at: '2026-09-02T09:30:00Z'
        '400':
          description: >-
            Invalid body: non-string display_name, non-object metadata,
            inbound_agent_id not a published agent, nothing to update, or a
            rejected inbound-routing value.
          content:
            application/json:
              example:
                error:
                  code: invalid_request
                  message: >-
                    Nothing to update. Allowed fields: display_name,
                    outbound_enabled, inbound_enabled, inbound_agent_id,
                    metadata
        '401':
          description: Authentication required.
          content:
            application/json:
              example:
                error:
                  code: unauthorized
                  message: Authentication required
        '403':
          description: Missing scope, or a role that cannot manage phone numbers.
          content:
            application/json:
              example:
                error:
                  code: forbidden
                  message: This role cannot manage phone numbers
        '404':
          description: >-
            Phone number not found, or the referenced inbound agent was not
            found.
          content:
            application/json:
              example:
                error:
                  code: not_found
                  message: Phone number not found
        '409':
          description: >-
            A terminal (failed/archived) number cannot be reconfigured, or the
            inbound DID is owned by a higher-precedence registration.
          content:
            application/json:
              example:
                error:
                  code: conflict
                  message: >-
                    This number is archived and cannot be reconfigured. Add a
                    new number instead.
        '503':
          description: Inbound call routing could not be updated with LiveKit.
          content:
            application/json:
              example:
                error:
                  code: service_unavailable
                  message: Could not update inbound call routing with LiveKit
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
    BearerAuth:
      type: http
      scheme: bearer

````