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,
  "message": "Agent deleted successfully"
}

{
  "statusCode": 401,
  "message": "API key is missing or invalid",
  "error": "Unauthorized"
}

{
  "statusCode": 403,
  "message": "You do not have permission to access this resource",
  "error": "Forbidden"
}

{
  "statusCode": 404,
  "message": "Agent not found",
  "error": "Not Found"
}

{
  "statusCode": 500,
  "message": "Internal server error",
  "error": "Internal Server Error"
}

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

Reassign any phone numbers or active workflows that route to this agent first. Deleting an agent that live traffic depends on will break those calls.
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. See 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.

success

boolean

Example:

true

message

string

Example:

"Agent deleted successfully"

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,
  "message": "Agent deleted successfully"
}

{
  "statusCode": 401,
  "message": "API key is missing or invalid",
  "error": "Unauthorized"
}

{
  "statusCode": 403,
  "message": "You do not have permission to access this resource",
  "error": "Forbidden"
}

{
  "statusCode": 404,
  "message": "Agent not found",
  "error": "Not Found"
}

{
  "statusCode": 500,
  "message": "Internal server error",
  "error": "Internal Server Error"
}

Overview

Endpoints

Code Examples And SDK Status

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