Skip to main content
DELETE
/
v1
/
agents
/
{agentId}
/
telephony
/
phone-numbers
/
{phoneNumber}
Delete a single phone number
curl --request DELETE \
  --url https://api.us.poly.ai/v1/agents/{agentId}/telephony/phone-numbers/{phoneNumber} \
  --header 'X-API-KEY: <api-key>'
import requests

url = "https://api.us.poly.ai/v1/agents/{agentId}/telephony/phone-numbers/{phoneNumber}"

headers = {"X-API-KEY": "<api-key>"}

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

print(response.text)
const options = {method: 'DELETE', headers: {'X-API-KEY': '<api-key>'}};

fetch('https://api.us.poly.ai/v1/agents/{agentId}/telephony/phone-numbers/{phoneNumber}', 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.us.poly.ai/v1/agents/{agentId}/telephony/phone-numbers/{phoneNumber}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_HTTPHEADER => [
    "X-API-KEY: <api-key>"
  ],
]);

$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.us.poly.ai/v1/agents/{agentId}/telephony/phone-numbers/{phoneNumber}"

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

	req.Header.Add("X-API-KEY", "<api-key>")

	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.us.poly.ai/v1/agents/{agentId}/telephony/phone-numbers/{phoneNumber}")
  .header("X-API-KEY", "<api-key>")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.us.poly.ai/v1/agents/{agentId}/telephony/phone-numbers/{phoneNumber}")

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

request = Net::HTTP::Delete.new(url)
request["X-API-KEY"] = '<api-key>'

response = http.request(request)
puts response.read_body
{
  "deleted": "<string>"
}
{
  "success": false,
  "error": "<string>",
  "error_id": "<string>",
  "error_code": "<string>",
  "error_message": "<string>",
  "data": "<unknown>"
}
{
  "success": false,
  "error": "<string>",
  "error_id": "<string>",
  "error_code": "<string>",
  "error_message": "<string>",
  "data": "<unknown>"
}
{
  "success": false,
  "error": "Phone number does not exist.",
  "error_id": "550e8400-e29b-41d4-a716-446655440000",
  "error_code": "PHONE_NUMBERS_NOT_FOUND",
  "error_message": "Phone number does not exist.",
  "data": null
}

Authorizations

X-API-KEY
string
header
required

Path Parameters

agentId
string
required
phoneNumber
string
required

Response

Successful response

The phone number that was released.

deleted
string
required

The deleted phone number

Last modified on April 22, 2026