Delete Agent

DELETE

agents

{id}

Delete Agent

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

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

fetch('https://api.dialnexa.com/v1/agents/{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/agents/{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/agents/{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/agents/{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",
  "timestamp": "2026-09-07T06:00:00.000Z"
}

Destructive Deletes an agent and all of its versions from your workspace. The agent disappears from List Agents and can no longer be assigned to phone numbers or used for new calls. Historical call logs that reference it remain available.

When to use this

Cleanup: remove test or superseded agents so pickers and audits only show agents that are in use.
Decommissioning: retire an agent after migrating its phone numbers and workflows to a replacement.

Before you call it

Deactivate any active workflows that use this agent first. While one exists, the delete returns 409 Conflict with code AGENT_USED_IN_ACTIVE_WORKFLOWS and the list of affected_workflows.
The agent’s phone numbers are unlinked automatically, with unlink_reason set to agent_deleted. The agent’s phone number history is not readable after the delete, because the agent no longer exists. Inbound calls to those numbers have no agent until you attach them to another one.
The delete is refused while one of the agent’s numbers cannot be released: 409 Conflict with code PHONE_NUMBER_HAS_LIVE_CALLS, NUMBER_USED_BY_BATCH, or PHONE_NUMBER_USED_IN_ACTIVE_WORKFLOWS. See Detach Agent Phone Number for each case.
Confirm the id with Get Agent Details; the delete is scoped to the workspace associated with your API key.

Result

The agent no longer appears in API results, but existing call history stays readable. A 404 Not Found means the agent does not exist in this workspace; a 409 Conflict means an active workflow still uses it or one of its numbers is still in use. See API errors for the standard error format.

Authorizations

Authorization

string

header

required

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

Path Parameters

string

required

Agent ID

Example:

"agent_2g7Xy3tY53gRlp"

Response

Agent deleted successfully.

The standard envelope without a data member.

success

enum<boolean>

required

Available options:

true

error

enum<boolean>

required

Available options:

false

statusCode

integer

required

Example:

200

message

string

required

Example:

"Success"

timestamp

string<date-time>

required

Delete Agent

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

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

fetch('https://api.dialnexa.com/v1/agents/{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/agents/{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/agents/{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/agents/{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",
  "timestamp": "2026-09-07T06:00:00.000Z"
}

Overview

Endpoints

When to use this

Before you call it

Result

Authorizations

Path Parameters

Response

​When to use this

​Before you call it

​Result

Authorizations

Path Parameters

Response

When to use this

Before you call it

Result