Delete Phone Number

DELETE

organization-phone-numbers

{id}

Delete Phone Number

curl --request DELETE \
  --url https://api.dialnexa.com/v1/organization-phone-numbers/{id} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.dialnexa.com/v1/organization-phone-numbers/{id}"

headers = {"Authorization": "Bearer <token>"}

response = requests.delete(url, headers=headers)

print(response.text)

const options = {method: 'DELETE', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.dialnexa.com/v1/organization-phone-numbers/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.dialnexa.com/v1/organization-phone-numbers/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.dialnexa.com/v1/organization-phone-numbers/{id}"

	req, _ := http.NewRequest("DELETE", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.dialnexa.com/v1/organization-phone-numbers/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "success": true,
  "error": false,
  "statusCode": 200,
  "message": "Success",
  "data": 200,
  "timestamp": "2026-09-07T06:00:00.000Z"
}

Destructive Deletes a phone number from your DialNexa workspace and stops future use of that number in DialNexa. The number is unlinked from its agents, with unlink_reason set to number_deleted in Get Agent Phone Number History. 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.

Before you delete

Confirm these conditions before sending the request:

The number is not a system default phone number.
No calls are live on the number.
No batch that is running, paused, scheduled, waiting, or active dials from the 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

curl -X DELETE "https://api.dialnexa.com/v1/organization-phone-numbers/phn_mfk3p8z2c4v6bn" \
  -H "Authorization: Bearer YOUR_API_KEY"

Result

A successful request returns 200 OK with the success envelope, whose data is the number 200. After deletion, the number no longer appears in List Phone Numbers.

Errors

404 Not Found is returned when the phone number does not exist in this workspace or has already been deleted. A number that belongs to another workspace is reported the same way.
409 Conflict is returned when the number is a system default, or is still in use. For a number in use, data.code is PHONE_NUMBER_HAS_LIVE_CALLS, NUMBER_USED_BY_BATCH, or PHONE_NUMBER_USED_IN_ACTIVE_WORKFLOWS, handled as described in Detach Agent Phone Number.
502 Bad Gateway is returned when the telephony provider does not release the rented number, the number’s provider does not support release, or DialNexa cannot remove the SIP trunk. The number is not deleted and stays in your workspace; retry later or contact support.

List Phone Numbers: confirm which numbers are available in your workspace.
Detach Agent Phone Number: remove a number from one agent without deleting it.
Get Phone Number Details: inspect a number before deleting it.
Buy Phone Number: purchase a replacement provider number.
Link SIP Trunk: connect a bring-your-own number.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

string

required

Phone number ID

Example:

"phn_mfk3p8z2c4v6bn"

Response

Phone number deleted successfully. data is the number 200.

success

enum<boolean>

required

Available options:

true

error

enum<boolean>

required

Available options:

false

statusCode

integer

required

Example:

200

message

string

required

Example:

"Success"

data

enum<integer>

required

Available options:

200

timestamp

string<date-time>

required

Delete Phone Number

curl --request DELETE \
  --url https://api.dialnexa.com/v1/organization-phone-numbers/{id} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.dialnexa.com/v1/organization-phone-numbers/{id}"

headers = {"Authorization": "Bearer <token>"}

response = requests.delete(url, headers=headers)

print(response.text)

const options = {method: 'DELETE', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.dialnexa.com/v1/organization-phone-numbers/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.dialnexa.com/v1/organization-phone-numbers/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.dialnexa.com/v1/organization-phone-numbers/{id}"

	req, _ := http.NewRequest("DELETE", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.dialnexa.com/v1/organization-phone-numbers/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "success": true,
  "error": false,
  "statusCode": 200,
  "message": "Success",
  "data": 200,
  "timestamp": "2026-09-07T06:00:00.000Z"
}

Overview

Endpoints

When to use this

Before you delete

Example request

Result

Errors

Authorizations

Path Parameters

Response

​When to use this

​Before you delete

​Example request

​Result

​Errors

​Related endpoints

Authorizations

Path Parameters

Response

When to use this

Before you delete

Example request

Result

Errors

Related endpoints