Skip to main content
GET
/
api
/
v2
/
platform
/
telephony
/
numbers
Get Telephony Numbers
curl --request GET \
  --url http://localhost:3001/api/v2/platform/telephony/numbers/ \
  --header 'Authorization: <api-key>' \
  --header 'Org-Handle: <org-handle>'
{
  "status_code": 200,
  "message": "Numbers fetched successfully.",
  "data": [
    {
      "id": 501,
      "number": "+1234567890",
      "provider": "twilio",
      "bridge_slug": "sales-bridge-001",
      "status": "active"
    },
    {
      "id": 502,
      "number": "+0987654321",
      "provider": "twilio",
      "bridge_slug": null,
      "status": "inactive"
    }
  ]
}
{
  "status_code": 200,
  "message": "Numbers fetched successfully.",
  "data": [
    {
      "id": 501,
      "number": "+1234567890",
      "provider": "twilio",
      "bridge_slug": "sales-bridge-001",
      "status": "active"
    },
    {
      "id": 502,
      "number": "+0987654321",
      "provider": "twilio",
      "bridge_slug": null,
      "status": "inactive"
    }
  ]
}

Get Telephony Numbers

Retrieve a list of all telephony numbers associated with your organization. This includes all numbers from connected providers, along with their assignment status, bridge associations, and current activity state.
Prerequisites: Make sure you have your API Token and Org-Handle ready. See Authentication for details.

Headers

NameTypeRequiredDescription
AuthorizationstringYesAPI Key format: Token <token>
Org-HandlestringYesOrganization 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

FieldTypeDescription
status_codeintegerHTTP status code
messagestringResponse message
dataarrayArray of number objects

Number Object Fields

FieldTypeDescription
idintegerUnique number identifier
numberstringPhone number in E.164 format
providerstringProvider slug this number belongs to
bridge_slugstringSlug of the bridge this number is assigned to (null if unassigned)
statusstringNumber status: active, inactive

Common Error Codes

Status CodeDescription
200Success - Numbers fetched successfully
401Unauthorized - Invalid or missing API token
403Forbidden - Invalid organization handle
404Not Found - Organization not found
500Internal Server Error - Server-side error

Code Examples

const axios = require('axios');

const headers = {
  'Authorization': 'Token your-api-token',
  'Org-Handle': 'your-org-handle'
};

// Get all telephony numbers
const getTelephonyNumbers = async () => {
  const response = await axios.get(
    'https://unpod.dev/api/v2/platform/telephony/numbers/',
    { headers }
  );
  const numbers = response.data.data;
  console.log(`Total numbers: ${numbers.length}`);
  numbers.forEach(num => {
    const bridgeInfo = num.bridge_slug ? `assigned to ${num.bridge_slug}` : 'unassigned';
    console.log(`${num.number} (${num.provider}) - ${num.status} - ${bridgeInfo}`);
  });
  return numbers;
};

// Get only unassigned numbers
const getUnassignedNumbers = async () => {
  const numbers = await getTelephonyNumbers();
  return numbers.filter(num => num.bridge_slug === null);
};

// Example usage
getTelephonyNumbers();

Best Practices

  1. Bridge Assignment: Check bridge_slug to identify unassigned numbers available for new bridge connections
  2. Status Check: Only numbers with status: active can handle calls — filter inactive numbers in your application
  3. Provider Tracking: Use the provider field to understand which provider account each number belongs to
  4. Number Inventory: Regularly audit your number list to identify unused or misconfigured numbers
  5. E.164 Format: All numbers are returned in E.164 format — use this format consistently in all API calls
  6. Security: Keep API tokens secure and rotate them regularly

Authorizations

Authorization
string
header
required

Format: Token

Headers

Org-Handle
string
required

Organization domain handle

Example:

"unpod"

Response

List of telephony numbers