Detach Agent Phone Number

DELETE

agents

{agentId}

phone-numbers

{phoneNumberId}

Detach Agent Phone Number

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

import requests

url = "https://api.dialnexa.com/v1/agents/{agentId}/phone-numbers/{phoneNumberId}"

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/agents/{agentId}/phone-numbers/{phoneNumberId}', 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/agents/{agentId}/phone-numbers/{phoneNumberId}",
  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/agents/{agentId}/phone-numbers/{phoneNumberId}"

	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/agents/{agentId}/phone-numbers/{phoneNumberId}")

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": {
    "id": "k2m9q4wz1abcde",
    "direction": "outbound",
    "linked_at": "2026-09-30T06:00:00.000Z",
    "linked_by": null,
    "unlinked_at": "2026-09-30T08:00:00.000Z",
    "unlinked_by": null,
    "unlink_reason": "manual",
    "agent_id": "agent_2g7Xy3tY53gRlp",
    "phone_number_id": "phn_abc123"
  },
  "timestamp": "2026-09-07T06:00:00.000Z"
}

Destructive Detach an agent phone number to stop routing that number through the agent in one direction. The number stays in your workspace and can be attached to this or another agent later. A number linked for both directions keeps the direction you did not detach.

When to use this

Move a number to another agent: detach it here, then attach it to the new agent.
Free a slot: an agent can hold only three numbers per direction.
Stop inbound routing: after an inbound detach, calls to the number no longer reach this agent.

Before you detach

The request is refused while the number is still in use:

Calls are live on the number.
For an outbound detach, a batch that is running, paused, scheduled, or waiting dials from the number.
For an outbound detach, an active workflow uses the number in a voice call step.

Detach agent phone number request

Parameter	In	Required	Description
`agentId`	path	Yes	Agent ID from List Agents.
`phoneNumberId`	path	Yes	Phone number ID from List Agent Phone Numbers.
`direction`	query	Yes	`inbound` or `outbound`. The other direction is left unchanged.

curl -X DELETE "https://api.dialnexa.com/v1/agents/agent_2g7Xy3tY53gRlp/phone-numbers/phn_abc123?direction=outbound" \
  -H "Authorization: Bearer YOUR_API_KEY"

Verify the result

A 200 response returns the closed link in data, with unlinked_at set and unlink_reason of manual. Call List Agent Phone Numbers to confirm the number is gone from that direction.

Errors and recovery

Refusals carry a code in data.code.

Status	Code	Cause and fix
`400`	none	`direction` is missing or is not `inbound` or `outbound`.
`404`	none	The agent or number is not in this workspace, or the number is not linked to this agent in that direction.
`409`	`NUMBER_USED_BY_BATCH`	Unfinished batches dial from the number (`data.batches`, `data.live_calls`). Change those batches’ number or cancel them, then retry. A paused batch does not complete on its own.
`409`	`PHONE_NUMBER_HAS_LIVE_CALLS`	Calls are in progress (`data.live_calls`). Wait for them to finish, then retry.
`409`	`PHONE_NUMBER_USED_IN_ACTIVE_WORKFLOWS`	Active workflows use the number (`data.affected_workflows`). Pause them, then retry.

A retry after a successful detach returns 404 because the number is no longer linked in that direction.

Authorizations

Authorization

string

header

required

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

Path Parameters

agentId

string

required

Agent ID from List Agents.

Example:

"agent_2g7Xy3tY53gRlp"

phoneNumberId

string

required

Phone number ID from List Agent Phone Numbers.

Example:

"phn_2g7Xy3tY53gRlp"

Query Parameters

direction

enum<string>

required

The direction to detach. A number linked for both directions keeps the other one.

Available options:

inbound,

outbound

Response

Successful response.

success

boolean

required

error

boolean

required

statusCode

integer

required

message

string

required

data

object | null

required

Show child attributes

timestamp

string<date-time>

required

Detach Agent Phone Number

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

import requests

url = "https://api.dialnexa.com/v1/agents/{agentId}/phone-numbers/{phoneNumberId}"

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/agents/{agentId}/phone-numbers/{phoneNumberId}', 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/agents/{agentId}/phone-numbers/{phoneNumberId}",
  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/agents/{agentId}/phone-numbers/{phoneNumberId}"

	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/agents/{agentId}/phone-numbers/{phoneNumberId}")

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": {
    "id": "k2m9q4wz1abcde",
    "direction": "outbound",
    "linked_at": "2026-09-30T06:00:00.000Z",
    "linked_by": null,
    "unlinked_at": "2026-09-30T08:00:00.000Z",
    "unlinked_by": null,
    "unlink_reason": "manual",
    "agent_id": "agent_2g7Xy3tY53gRlp",
    "phone_number_id": "phn_abc123"
  },
  "timestamp": "2026-09-07T06:00:00.000Z"
}

Overview

Endpoints

When to use this

Before you detach

Detach agent phone number request

Verify the result

Errors and recovery

Authorizations

Path Parameters

Query Parameters

Response

​When to use this

​Before you detach

​Detach agent phone number request

​Verify the result

​Errors and recovery

​Related endpoints

Authorizations

Path Parameters

Query Parameters

Response

When to use this

Before you detach

Detach agent phone number request

Verify the result

Errors and recovery

Related endpoints