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

# Update Phone Number

> Change the agent assigned to a phone number, set or clear the display nickname, or unassign routing without releasing the number.

<Warning>
  **Legacy endpoint - deprecated.** Unversioned endpoints are scheduled for removal on **July 31, 2026**. There is no public `/v1` replacement documented for updating a phone number yet. Keep existing integrations on this endpoint until DialNexa publishes a replacement.
</Warning>

Updates editable fields on a phone number provisioned on your workspace. The most common change is assigning or replacing the inbound agent; you can also set or clear the display `nickname` so the number is easier to identify in dashboard selectors. Only the fields you include are updated, omitted fields keep their current values. This endpoint does not change the underlying carrier configuration, the E.164 number itself, or the monthly billing.

## When to use this

* **Assigning an agent** for the first time after purchasing the number through [Buy a Phone Number](/docs/api-reference/v1/phone-numbers/buy).
* **Switching the inbound agent** when handing the number to a different team or workflow.
* **Renaming for clarity**: set a `nickname` so dashboard users can pick the right number out of a long list.
* **Detaching routing**: pass `agent_id: null` to stop routing inbound calls without releasing the number. Useful while you investigate an issue or while the new agent is being prepared.

To release the number entirely, use [Release a Number](/docs/api-reference/v1/phone-numbers/delete) instead.

## Path parameters

| Parameter | Description                                          |
| --------- | ---------------------------------------------------- |
| `id`      | The phone number ID, for example `phn_f7w2kx5mb9qz`. |

## Errors

* `404 Not Found` is returned when the phone number does not exist on this workspace.
* `400 Bad Request` is returned when the supplied `agent_id` does not exist or is not eligible to be assigned to a number.

## Related endpoints

* [Get Phone Number](/docs/api-reference/v1/phone-numbers/get): confirm new values.
* [Buy a Phone Number](/docs/api-reference/v1/phone-numbers/buy): purchase a new number.
* [Release a Number](/docs/api-reference/v1/phone-numbers/delete): return the number to the provider's pool.
* [Receive Inbound Calls](/docs/calls/inbound-calls): end-to-end inbound setup guide.


## OpenAPI

````yaml PATCH /organization-phone-numbers/{id}
openapi: 3.0.0
info:
  title: DialNexa API
  description: >-
    Public REST API for the DialNexa voice AI platform. Versioned endpoints are
    under /v1; unversioned endpoints are legacy and deprecated.
  version: 1.0.0
servers:
  - url: https://api.dialnexa.com
    description: DialNexa production API
security:
  - bearer: []
tags:
  - name: API Keys
  - name: Agent Functions
  - name: Agents V1
  - name: Agents2
  - name: Batch Calls
  - name: Batch Calls V1
  - name: Call Logs
  - name: Calls
  - name: Calls V1
  - name: Campaign Leads
  - name: Campaigns
  - name: External Webhooks
  - name: Knowledge Base
  - name: Knowledge Base V1
  - name: LLMs
  - name: LLMs V1
  - name: Languages
  - name: Languages V1
  - name: Organization Phone Numbers
  - name: Organization Phone Numbers V1
  - name: Phone Number Pricing
  - name: Phone Number Pricing V1
  - name: Transcribers
  - name: Transcribers V1
  - name: User Webhooks
  - name: User Webhooks V1
  - name: V1
  - name: Voices
  - name: Voices V1
  - name: Webcall
  - name: Workflow Leads
  - name: Workflow Leads V1
  - name: Workflows
  - name: Workflows V1
paths:
  /organization-phone-numbers/{id}:
    patch:
      tags:
        - Organization Phone Numbers
      summary: Update a phone number
      description: >-
        **Legacy endpoint - deprecated, scheduled for removal on July 31,
        2026.** Use the `/v1` version for new integrations. 


        Updates the database record for an existing phone number, e.g. its
        organization association or other metadata. Only updates the database
        record - it cannot change the actual phone number with the external
        telephony provider. Returns 404 if not found; only users from the owning
        organization can update it.
      operationId: OrganizationPhoneNumbersController_update
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
        - name: x-organization-id
          in: header
          description: RSA-encrypted organization_id string (base64 format)
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOrganizationPhoneNumberDto'
      responses:
        '200':
          description: Phone number updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationPhoneNumber'
        '403':
          description: Phone number does not belong to your organization
        '404':
          description: Phone number not found
      deprecated: true
components:
  schemas:
    UpdateOrganizationPhoneNumberDto:
      type: object
      properties:
        country_iso:
          type: string
          example: '91'
          description: >-
            Country calling code digits only (e.g. "91" for India, "1" for US);
            stored as VARCHAR(3)
        phone_number:
          type: number
          example: 1234567890
          description: Phone number assigned to organization (without country code)
        telephony_provider_id:
          type: string
          example: prov_xxxxxx
          description: ID of telephony provider (14-char string)
        status:
          type: string
          example: active
          enum:
            - pending
            - active
          description: Status of the phone number
        inbound_agent_id:
          type: string
          example: A1B2C3D4E5F6G7
          description: Inbound agent ID
        outbound_agent_id:
          type: string
          example: B1C2D3E4F5G6H7
          description: Outbound agent ID
        inbound_agent_version_number:
          type: number
          example: 1
          description: Inbound agent version number
        outbound_agent_version_number:
          type: number
          example: 2
          description: Outbound agent version number
        sip_trunk_enabled:
          type: boolean
          default: false
          description: >-
            When true, Speech IO uses SIP trunking (e.g. asterisk) for this
            number.
        rental_start_date:
          type: string
          example: '2026-04-07'
          description: Rental start date in YYYY-MM-DD format
        rental_end_date:
          type: string
          example: '2026-05-07'
          description: Rental end date in YYYY-MM-DD format
        rental_status:
          type: string
          example: active
          enum:
            - active
            - expired
            - available_for_reassignment
          description: Rental lifecycle status for this phone number
        nickname:
          type: string
          example: Sales Line
          description: Human-readable nickname for this phone number
    OrganizationPhoneNumber:
      type: object
      properties:
        sip_trunk_enabled:
          type: boolean
          default: false
          description: >-
            When true, Speech IO uses SIP trunking (e.g. asterisk) for this
            number.
      required:
        - sip_trunk_enabled
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http

````