Skip to main content
Retrieve a list of all available phone numbers from various telephony providers. This endpoint returns phone numbers grouped by provider, allowing you to manage and assign numbers to your voice agents.

​
API Endpoint

GET /api/v1/global/list-phone-numbers Content-Type: application/json Authentication: Required (Token header: token or api_access_token)

​
Query Parameters

ParameterTypeRequiredDescription
providerstringNoFilter by specific provider. Supported values: san, ozonetell, twilio, exotel

​
Response

​
Success Response

Status Code: 200 OK 
{
  "error": false,
  "code": 200,
  "message": "",
  "timestamp": 1769244619292,
  "data": {
    "providers": {
      "San Software": [
        {
          "number": "+9180********",
          "label_name": null,
          "number_purpose": null
        },
        {
          "number": "+9180********",
          "label_name": null,
          "number_purpose": null
        },
        {
          "number": "+9180********",
          "label_name": "Sales Team",
          "number_purpose": "TEST"
        }
      ],
      "Ozonetell": [
        {
          "number": "+9180********",
          "label_name": null,
          "number_purpose": null
        }
      ],
      "Twilio": [
        {
          "number": "+120********",
          "label_name": "Customer Support",
          "number_purpose": "PRODUCTION"
        }
      ],
      "Exotel": [
        {
          "number": "+9198********",
          "label_name": "Marketing",
          "number_purpose": "OUTBOUND"
        }
      ]
    }
  }
}

​
Response Fields

FieldTypeDescription
errorbooleanIndicates if there was an error
codeintegerHTTP status code
messagestringSuccess or error message
timestampintegerUnix timestamp in milliseconds
dataobjectResponse data object
data.providersobjectPhone numbers grouped by provider name

​
Phone Number Object Fields

FieldTypeDescription
numberstringPhone number in E.164 format (e.g., +918062810341)
label_namestringCustom label assigned to the number (nullable)

​
Common Number Purpose Values

PurposeDescription
TESTNumber used for testing purposes
PRODUCTIONNumber used in production environment

​
Error Responses

​
401 - Authentication Error

Status Code: 401 Unauthorized 
{
  "error": true,
  "code": 401,
  "message": "Invalid Auth Key or Session Expired",
  "data": {}
}

​
404 - No Numbers Found

Status Code: 404 Not Found 
{
  "error": true,
  "code": 404,
  "message": "No phone numbers found",
  "data": {}
}

​
500 - Server Error

Status Code: 500 Internal Server Error 
{
  "error": true,
  "code": 500,
  "message": "Internal server error",
  "data": {}
}

​
Supported Providers

ProviderKeyDescription
San SoftwaresanSan Software telephony platform
OzonetelozonetelOzonetel cloud communication platform
TwiliotwilioGlobal cloud communications platform
ExotelexotelLeading cloud telephony provider in India

​
Important Notes

  1. Phone Number Format: Phone numbers are returned in E.164 format (e.g., +918062810341)
  2. Provider Grouping: Numbers are grouped by provider for easy organization
  3. Label Management: label_name can be used to identify numbers by custom names
  4. Available Numbers: Numbers without a number_purpose are typically available for new assignments
  5. Provider Setup: Some providers may require additional setup before numbers can be used
  6. Permissions: Ensure you have proper permissions and provider configurations before using numbers
  7. Rate Limits: API calls are subject to rate limiting based on your plan