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

# Release a Number

> Release a purchased phone number from your account and stop billing for it at the end of the current cycle.

<Warning>
  **Legacy endpoint - deprecated.** Unversioned endpoints are scheduled for removal on **July 31, 2026**. For new integrations, use [Delete Phone Number](/docs/api-reference/v1/phone-numbers/delete).
</Warning>

Releases a phone number back to the upstream telephony provider's pool. The number is removed from your account immediately, any active inbound routing on the number is detached, and billing for the number stops at the end of the current billing cycle. This action is irreversible, once a number is released, DialNexa cannot guarantee it can be re-purchased, and most provider pools recycle numbers to new customers.

## When to use this

Release a number when you no longer need it on this workspace. Common cases:

* **Retiring a campaign number** that is no longer in active use.
* **Decommissioning a region** where you no longer run outbound or inbound calls.
* **Consolidating numbers** after a workspace cleanup.

If you only want to stop using the number with a specific agent, for example because you are moving the agent to a different number, call [Update Phone Number](/docs/api-reference/phone-numbers/update) and clear the `agent_id` field instead. The number stays on your account and can be reassigned later.

## Behavior

* Inbound calls arriving on the number after release fail at the carrier layer.
* Outbound calls already in progress on the number are not interrupted.
* Provider-side number reservation may not be reclaimable, releasing a number you might want to keep is a one-way action.
* Billing stops at the end of the current billing cycle, not at the moment of release.

## 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.
* `409 Conflict` is returned when the number is part of an active campaign that must be reconfigured before release.

## Related endpoints

* [Update Phone Number](/docs/api-reference/phone-numbers/update): reassign or detach the number without releasing it.
* [Buy a Phone Number](/docs/api-reference/v1/phone-numbers/buy): purchase a replacement number.
* [List Phone Numbers](/docs/api-reference/v1/phone-numbers/list): confirm the release and review remaining numbers.


## OpenAPI

````yaml DELETE /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}:
    delete:
      tags:
        - Organization Phone Numbers
      summary: Soft delete a phone number
      description: >-
        **Legacy endpoint - deprecated, scheduled for removal on July 31,
        2026.** Use the `/v1` version for new integrations. 


        Marks a phone number record as deleted without removing it, preserving
        it for historical purposes while making it inactive. Only affects the
        database record - it does not release the number from the external
        telephony provider (contact the provider directly for that). Returns 404
        if not found; only users from the owning organization can delete it.
      operationId: OrganizationPhoneNumbersController_remove
      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
      responses:
        '200':
          description: Phone number deleted.
        '403':
          description: Phone number does not belong to your organization
        '404':
          description: Phone number not found
      deprecated: true
components:
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http

````