> ## 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>
Deletes a phone number from your DialNexa workspace and stops future use of that number in DialNexa. For a bring-your-own number, DialNexa removes the SIP connection and its credentials. For a rented number, DialNexa releases the provider rental.

## 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 `/v1` REST API for the DialNexa voice AI platform.
  version: 1.0.0
servers:
  - url: https://api.dialnexa.com
    description: DialNexa production API
security:
  - bearer: []
tags:
  - name: Agents
  - name: Batch Calls
  - name: Calls
  - name: Knowledge Base
  - name: Languages
  - name: LLMs
  - name: Phone Numbers
  - name: Transcribers
  - name: Webhooks
  - name: Voices
  - name: Workflows
  - name: Workflow Leads
paths:
  /v1/organization-phone-numbers/{id}:
    delete:
      tags:
        - Phone Numbers
      summary: Delete Phone Number
      description: >-
        Deletes a workspace phone number, releases its provider rental or SIP
        connection, and prevents future DialNexa routing. The request is blocked
        if the number is the workspace default or is used by an active workflow.
      operationId: deletePhoneNumber
      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
      type: http

````