GET

api

platform

telephony

numbers

Get Telephony Numbers

curl --request GET \
  --url https://unpod.ai/api/v2/platform/telephony/numbers/ \
  --header 'Authorization: <api-key>'

import requests

url = "https://unpod.ai/api/v2/platform/telephony/numbers/"

headers = {"Authorization": "<api-key>"}

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

print(response.text)

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://unpod.ai/api/v2/platform/telephony/numbers/', 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://unpod.ai/api/v2/platform/telephony/numbers/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <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://unpod.ai/api/v2/platform/telephony/numbers/"

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

	req.Header.Add("Authorization", "<api-key>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://unpod.ai/api/v2/platform/telephony/numbers/")
  .header("Authorization", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://unpod.ai/api/v2/platform/telephony/numbers/")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<api-key>'

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

{
  "status_code": 200,
  "message": "Telephony numbers fetched successfully.",
  "data": [
    {
      "id": 501,
      "number": "+15551234567",
      "state": "ASSIGNED",
      "active": true
    },
    {
      "id": 502,
      "number": "+15559876543",
      "state": "NOT_ASSIGNED",
      "active": true
    }
  ]
}

{
  "status_code": 200,
  "message": "Telephony numbers fetched successfully.",
  "data": [
    {
      "id": 502,
      "number": "+15559876543",
      "state": "NOT_ASSIGNED",
      "active": true
    }
  ]
}

{
  "status_code": 401,
  "message": "Authentication credentials were not provided."
}

{
  "status_code": 200,
  "message": "Telephony numbers fetched successfully.",
  "data": [
    {
      "id": 501,
      "number": "+15551234567",
      "state": "ASSIGNED",
      "active": true
    },
    {
      "id": 502,
      "number": "+15559876543",
      "state": "NOT_ASSIGNED",
      "active": true
    }
  ]
}

{
  "status_code": 200,
  "message": "Telephony numbers fetched successfully.",
  "data": [
    {
      "id": 502,
      "number": "+15559876543",
      "state": "NOT_ASSIGNED",
      "active": true
    }
  ]
}

{
  "status_code": 401,
  "message": "Authentication credentials were not provided."
}

Get Telephony Numbers

Retrieve a list of telephony numbers. Behavior depends on the Org-Handle header:

With Org-Handle — returns your organization’s own numbers (any state) plus the shared unassigned pool (NOT_ASSIGNED).
Without Org-Handle — returns only the shared unassigned pool.

Prerequisites: Make sure you have your API Token ready. See Authentication for details.

Headers

Name	Type	Required	Description
Authorization	string	Yes	API Key format: `Token <token>`
Org-Handle	string	No	Organization domain handle

You can get the Org-Handle by hitting the Get All Organizations API. The domain_handle field in the response is your Org-Handle.

Response Fields

Field	Type	Description
status_code	integer	HTTP status code
message	string	Response message
data	array	Array of number objects

Number Object Fields

Field	Type	Description
id	integer	Unique number id (use this in attach calls)
number	string	Phone number in E.164 format
state	string	`NOT_ASSIGNED` or `ASSIGNED`
active	boolean	Whether the number is usable

Common Error Codes

Status Code	Description
200	Success - Numbers fetched successfully
401	Unauthorized - Invalid or missing API token
500	Internal Server Error - Server-side error

Code Examples

const axios = require('axios');

const headers = {
  'Authorization': 'Token your-api-token',
  'Org-Handle': 'your-org-handle'  // optional — omit for pool numbers only
};

// Get org numbers + pool numbers
const getTelephonyNumbers = async () => {
  const response = await axios.get(
    'https://unpod.ai/api/v2/platform/telephony/numbers/',
    { headers }
  );
  const numbers = response.data.data;
  console.log(`Total numbers: ${numbers.length}`);
  numbers.forEach(num => {
    console.log(`${num.number} - ${num.state}`);
  });
  return numbers;
};

// Get only unassigned pool numbers (no Org-Handle)
const getPoolNumbers = async () => {
  const response = await axios.get(
    'https://unpod.ai/api/v2/platform/telephony/numbers/',
    { headers: { 'Authorization': headers.Authorization } }
  );
  return response.data.data;
};

// Example usage
getTelephonyNumbers();

import requests

headers = {
    'Authorization': 'Token your-api-token',
    'Org-Handle': 'your-org-handle'  # optional — omit for pool numbers only
}

def get_telephony_numbers():
    """Get org numbers + pool numbers"""
    url = 'https://unpod.ai/api/v2/platform/telephony/numbers/'
    response = requests.get(url, headers=headers)
    data = response.json()
    numbers = data['data']
    print(f"Total numbers: {len(numbers)}")
    for num in numbers:
        print(f"{num['number']} - {num['state']}")
    return numbers

def get_pool_numbers():
    """Get only unassigned pool numbers (no Org-Handle)"""
    pool_headers = {k: v for k, v in headers.items() if k != 'Org-Handle'}
    url = 'https://unpod.ai/api/v2/platform/telephony/numbers/'
    response = requests.get(url, headers=pool_headers)
    return response.json()['data']

# Example usage
get_telephony_numbers()

# With Org-Handle — org numbers + pool numbers
curl -X GET "https://unpod.ai/api/v2/platform/telephony/numbers/" \
  -H "Authorization: Token your-api-token" \
  -H "Org-Handle: your-org-handle"

# Without Org-Handle — pool numbers only
curl -X GET "https://unpod.ai/api/v2/platform/telephony/numbers/" \
  -H "Authorization: Token your-api-token"

Best Practices

Org Scoping: Pass Org-Handle to see your org’s numbers; omit it to see only pool numbers
Number Assignment: Use a number’s id when attaching it to a trunk
State Awareness: Check state to know if a number is NOT_ASSIGNED (available) or ASSIGNED (in use)
E.164 Format: All numbers are returned in E.164 format — use this format consistently in all API calls
Security: Keep API tokens secure and rotate them regularly

Authorizations

Authorization

string

header

required

Format: Token

Headers

Org-Handle

string

Organization domain handle. Omit to list pool numbers only.

Response

List of telephony numbers

Disconnect Provider from BridgeDisconnect a provider credential from a telephony bridge to remove the number

Get Telephony Numbers

curl --request GET \
  --url https://unpod.ai/api/v2/platform/telephony/numbers/ \
  --header 'Authorization: <api-key>'

import requests

url = "https://unpod.ai/api/v2/platform/telephony/numbers/"

headers = {"Authorization": "<api-key>"}

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

print(response.text)

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://unpod.ai/api/v2/platform/telephony/numbers/', 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://unpod.ai/api/v2/platform/telephony/numbers/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <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://unpod.ai/api/v2/platform/telephony/numbers/"

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

	req.Header.Add("Authorization", "<api-key>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://unpod.ai/api/v2/platform/telephony/numbers/")
  .header("Authorization", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://unpod.ai/api/v2/platform/telephony/numbers/")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<api-key>'

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

{
  "status_code": 200,
  "message": "Telephony numbers fetched successfully.",
  "data": [
    {
      "id": 501,
      "number": "+15551234567",
      "state": "ASSIGNED",
      "active": true
    },
    {
      "id": 502,
      "number": "+15559876543",
      "state": "NOT_ASSIGNED",
      "active": true
    }
  ]
}

{
  "status_code": 200,
  "message": "Telephony numbers fetched successfully.",
  "data": [
    {
      "id": 502,
      "number": "+15559876543",
      "state": "NOT_ASSIGNED",
      "active": true
    }
  ]
}

{
  "status_code": 401,
  "message": "Authentication credentials were not provided."
}

Getting Started

API Lists

Get Telephony Numbers

Get Telephony Numbers

Headers

Response Fields

Number Object Fields

Common Error Codes

Code Examples

Best Practices

Authorizations

Headers

Response

​Get Telephony Numbers

​Headers

​Response Fields

​Number Object Fields

​Common Error Codes

​Code Examples

​Best Practices

Authorizations

Headers

Response

Get Telephony Numbers

Headers

Response Fields

Number Object Fields

Common Error Codes

Code Examples

Best Practices