Phone Numbers

Release Phone Number

Give a number on the carrier account back to the carrier. Admin only. Irreversible: the carrier may sell the number to someone else. confirm must repeat e164_number (422 otherwise). A number TurnCall still binds is refused (409): unbind it first with DELETE /v1/phone-numbers/{id}, which leaves it on the account. On the platform’s shared account (Twilio without an account pair; Telnyx when the project holds no telnyx credential) only a number this project bought through POST /v1/phone-numbers/purchase is released (403 otherwise); the project’s own account is not restricted.

POST

phone-numbers

release

curl --request POST \
  --url https://api.example.com/v1/phone-numbers/release \
  --header 'Content-Type: application/json' \
  --data '
{
  "e164_number": "<string>",
  "twilio_account_sid": "<string>",
  "twilio_auth_token": "<string>",
  "carrier": "twilio",
  "confirm": "<string>"
}
'

import requests

url = "https://api.example.com/v1/phone-numbers/release"

payload = {
    "e164_number": "<string>",
    "twilio_account_sid": "<string>",
    "twilio_auth_token": "<string>",
    "carrier": "twilio",
    "confirm": "<string>"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    e164_number: '<string>',
    twilio_account_sid: '<string>',
    twilio_auth_token: '<string>',
    carrier: 'twilio',
    confirm: '<string>'
  })
};

fetch('https://api.example.com/v1/phone-numbers/release', 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.example.com/v1/phone-numbers/release",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'e164_number' => '<string>',
    'twilio_account_sid' => '<string>',
    'twilio_auth_token' => '<string>',
    'carrier' => 'twilio',
    'confirm' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/phone-numbers/release"

	payload := strings.NewReader("{\n  \"e164_number\": \"<string>\",\n  \"twilio_account_sid\": \"<string>\",\n  \"twilio_auth_token\": \"<string>\",\n  \"carrier\": \"twilio\",\n  \"confirm\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/phone-numbers/release")
  .header("Content-Type", "application/json")
  .body("{\n  \"e164_number\": \"<string>\",\n  \"twilio_account_sid\": \"<string>\",\n  \"twilio_auth_token\": \"<string>\",\n  \"carrier\": \"twilio\",\n  \"confirm\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/phone-numbers/release")

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

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"e164_number\": \"<string>\",\n  \"twilio_account_sid\": \"<string>\",\n  \"twilio_auth_token\": \"<string>\",\n  \"carrier\": \"twilio\",\n  \"confirm\": \"<string>\"\n}"

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

{}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Headers

authorization

string | null

Body

application/json

Give a number on the carrier account back to the carrier. Irreversible: confirm must repeat e164_number exactly, so a release is never a default, a copied body or a stray true. On Twilio, the account it is released from is the pair given here, else the platform's TWILIO_* account, as on a purchase.

e164_number

string

required

Pattern: ^\+[1-9]\d{1,14}$

twilio_account_sid

string | null

Pattern: ^AC[0-9a-fA-F]{32}$

twilio_auth_token

string | null

Required string length: 1 - 256

carrier

enum<string>

default:twilio

The carrier whose account the number is released from.

Available options:

twilio,

telnyx

confirm

string | null

The number being released, repeated (it must equal e164_number). Releasing is irreversible: the carrier may sell the number to someone else.

Response

Successful Response

The response is of type Response Release Phone Number V1 Phone Numbers Release Post · object.

Release Phone Number

curl --request POST \
  --url https://api.example.com/v1/phone-numbers/release \
  --header 'Content-Type: application/json' \
  --data '
{
  "e164_number": "<string>",
  "twilio_account_sid": "<string>",
  "twilio_auth_token": "<string>",
  "carrier": "twilio",
  "confirm": "<string>"
}
'

import requests

url = "https://api.example.com/v1/phone-numbers/release"

payload = {
    "e164_number": "<string>",
    "twilio_account_sid": "<string>",
    "twilio_auth_token": "<string>",
    "carrier": "twilio",
    "confirm": "<string>"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    e164_number: '<string>',
    twilio_account_sid: '<string>',
    twilio_auth_token: '<string>',
    carrier: 'twilio',
    confirm: '<string>'
  })
};

fetch('https://api.example.com/v1/phone-numbers/release', 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.example.com/v1/phone-numbers/release",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'e164_number' => '<string>',
    'twilio_account_sid' => '<string>',
    'twilio_auth_token' => '<string>',
    'carrier' => 'twilio',
    'confirm' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/phone-numbers/release"

	payload := strings.NewReader("{\n  \"e164_number\": \"<string>\",\n  \"twilio_account_sid\": \"<string>\",\n  \"twilio_auth_token\": \"<string>\",\n  \"carrier\": \"twilio\",\n  \"confirm\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/phone-numbers/release")
  .header("Content-Type", "application/json")
  .body("{\n  \"e164_number\": \"<string>\",\n  \"twilio_account_sid\": \"<string>\",\n  \"twilio_auth_token\": \"<string>\",\n  \"carrier\": \"twilio\",\n  \"confirm\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/phone-numbers/release")

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

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"e164_number\": \"<string>\",\n  \"twilio_account_sid\": \"<string>\",\n  \"twilio_auth_token\": \"<string>\",\n  \"carrier\": \"twilio\",\n  \"confirm\": \"<string>\"\n}"

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

{}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Overview

Projects

Audit Log

API Keys

Credentials

Agents

Phone Numbers

Calls

Suppression List

Campaigns

Call Control

Chat

Knowledge Bases

Takeaways

Ambience

Evals

Tools

Webhooks

WebRTC

Health

Release Phone Number

Headers

Body

Response