Release a Number - DialNexa Documentation

DELETE

organization-phone-numbers

{id}

Soft delete a phone number

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

import requests

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

headers = {
    "x-organization-id": "<x-organization-id>",
    "Authorization": "Bearer <token>"
}

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

print(response.text)

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

fetch('https://api.dialnexa.com/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/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>",
    "x-organization-id: <x-organization-id>"
  ],
]);

$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/organization-phone-numbers/{id}"

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

	req.Header.Add("x-organization-id", "<x-organization-id>")
	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.delete("https://api.dialnexa.com/organization-phone-numbers/{id}")
  .header("x-organization-id", "<x-organization-id>")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

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

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

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

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

Legacy endpoint - deprecated. Unversioned endpoints are scheduled for removal on July 31, 2026. For new integrations, use Delete Phone Number.

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

Update Phone Number: reassign or detach the number without releasing it.
Buy a Phone Number: purchase a replacement number.
List Phone Numbers: confirm the release and review remaining numbers.

Authorizations

Authorization

string

header

required

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

Headers

x-organization-id

string

required

RSA-encrypted organization_id string (base64 format)

Path Parameters

string

required

Response

Phone number deleted.

Create a Web CallCreate a browser-based DialNexa web call session.

Soft delete a phone number

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

import requests

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

headers = {
    "x-organization-id": "<x-organization-id>",
    "Authorization": "Bearer <token>"
}

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

print(response.text)

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

fetch('https://api.dialnexa.com/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/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>",
    "x-organization-id: <x-organization-id>"
  ],
]);

$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/organization-phone-numbers/{id}"

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

	req.Header.Add("x-organization-id", "<x-organization-id>")
	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.delete("https://api.dialnexa.com/organization-phone-numbers/{id}")
  .header("x-organization-id", "<x-organization-id>")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

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

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

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

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

​When to use this

​Behavior

​Path parameters

​Errors

​Related endpoints

Authorizations

Headers

Path Parameters

Response

When to use this

Behavior

Path parameters

Errors

Related endpoints