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

# Delete Phone Number

> Delete a phone number from your DialNexa workspace.

<span data-api-safety-label="destructive"><Badge color="red" size="sm" shape="pill">Destructive</Badge></span>

<Info>
  **Recommended.** This endpoint is part of the public `/v1` API reference and is the supported path for new integrations. See the [migration guide](/docs/api-reference/v1/migrating-to-v1) for versioning guidance.
</Info>

Deletes a phone number from your DialNexa workspace. The delete operation soft-deletes the workspace record and stops future use of that number in DialNexa. If the number is connected through a SIP trunk, DialNexa also removes the media-server trunk and SIP credentials. If the number was rented through a provider, DialNexa releases the rental and deactivates the active rental subscription.

## When to use this

* **Workspace cleanup**: remove numbers you no longer use for inbound or outbound calls.
* **SIP trunk teardown**: remove a bring-your-own number and its SIP routing credentials from DialNexa.
* **Cost control**: stop future rental activity for numbers that should no longer be billed through the workspace.

Do not call this endpoint for numbers that are still part of an active production flow. If you only need to inspect the number first, use [Get Phone Number Details](/docs/api-reference/v1/phone-numbers/get).

## Before you delete

Confirm these conditions before sending the request:

* The number is not your organization's default phone number.
* No active workflows are using the number.
* Any inbound routing that depends on this number has been moved to another number.
* You are comfortable losing the current provider rental or SIP trunk connection.

## Example request

```bash theme={null}
curl -X DELETE "https://api.dialnexa.com/v1/organization-phone-numbers/phn_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Result

A successful request returns `200 OK`. After deletion, the number no longer appears in [List Phone Numbers](/docs/api-reference/v1/phone-numbers/list).

## Errors

* `400 Bad Request` is returned when the phone number ID format is invalid.
* `403 Forbidden` is returned when the phone number does not belong to your organization.
* `404 Not Found` is returned when the phone number does not exist or has already been deleted.
* `409 Conflict` is returned when the number is the organization default or is used by active workflows. Move the default number or deactivate the workflows, then retry.

## Related endpoints

* [List Phone Numbers](/docs/api-reference/v1/phone-numbers/list): confirm which numbers are available in your workspace.
* [Get Phone Number Details](/docs/api-reference/v1/phone-numbers/get): inspect a number before deleting it.
* [Buy Phone Number](/docs/api-reference/v1/phone-numbers/buy): purchase a replacement provider number.
* [Link SIP Trunk](/docs/api-reference/v1/phone-numbers/link-sip-trunk): connect a bring-your-own number.


## OpenAPI

````yaml DELETE /v1/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:
  /v1/organization-phone-numbers/{id}:
    delete:
      tags:
        - Organization Phone Numbers
        - Organization Phone Numbers V1
        - V1
      summary: Delete Phone Number
      description: >-
        Soft-deletes an organization phone number. If the number has an active
        SIP trunk, tears down the trunk on the media server and removes SIP
        trunk credentials. Releases the Plivo/Twilio rental and deactivates any
        associated rental subscriptions. Returns 409 if the number is the
        organization default or has active workflows using it.
      operationId: OrganizationPhoneNumbersV1Controller_remove
      parameters:
        - name: id
          required: true
          in: path
          description: Phone number ID
          schema:
            type: string
            example: phn_abc123
      responses:
        '200':
          description: Phone number deleted successfully.
        '400':
          description: Invalid phone number ID format.
        '401':
          description: Unauthorized - missing or invalid API key.
        '403':
          description: Forbidden - phone number does not belong to your organization.
        '404':
          description: Phone number not found.
        '409':
          description: >-
            Conflict - phone number is the organization default or has active
            workflows.
        '500':
          description: Internal server error.
      security:
        - bearer: []
components:
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http

````