Please refer to the detailed API endpoint specification: List numbers

Purpose

This API allows you to query the list of your inbound phone numbers by sending a List numbers request to your contact center.

Prerequisites

Your contact center must own at least one phone number.

Making requests

Authentication

The numbers API requires the Base URL and the contact center API key.

Request parameters

The numbers API uses the following parameters.

The Authorization: Bearer token parameter is the contact center API key. It is used in the request header.

The page parameter is the pagination offset. Read the Metadata in the initial response to determine how many pages of data are available.

With these parameters, you can make a simple request:

{
  "method": "GET",
  "url": "https://cluster1.contact_center_name.com/api/numbers/v1/numbers",
  "headers": {
    "Authorization": "Bearer 8a7b2c9d3e4f5g6h7i8j9k0l1m2n3o4p5q6r7s8t9u0v1w2x"
  },
  "params": {
    "page": "1"
  }
}

Response

The following table describes the elements of the response.

Element	Sub-element	Sub-element 2	Sub-element 3	Description	Type	Notes
numbers				An array of all the numbers you own.	array
	number			The phone number in E.164 format.	string
	created_at			The date and time the number was first added.	string	Format is "YYYY-MM-DDThh:mm:ss.sssZ"
	label			The custom name your contact center applied to the number.	string
	country			The country where the number belongs.	string
	city			The city where the number belongs.	string
	type			The type of the number.	string	Supported types include Geographic, National, Toll-free, and Mobile
	provider			The name of the source of the number.	string
	activation_fee			The fee to activate the number.	string
	monthly_fee			The monthly fee to use the number.	string
	script			The script or flow where the number is used.	array
		flow		The flow where the number is used.	array
			id	The unique ID assigned to the flow when it was created.	string
			name	The name of the flow.	string
		cid_groups		The Caller ID groups associated with the number.	array
			id	The unique ID assigned to the Caller ID group when it was created.	number
			name	The name of the Caller ID group.	string
metadata				Information about the request settings and response content.	object
	total			The number of phone numbers returned.	number
	page			The page number.	number
	page_size			The number of phone numbers returned per page in the response.	number

Response sample

{
  "numbers": [
    {
      "number": "1234567890",
      "created_at": "2023-07-24T15:50:21.208Z",
      "label": "My number",
      "country": "United States",
      "city": "City",
      "type": "geographic",
      "provider": "Your Contact Center",
      "activation_fee": "1.23",
      "monthly_fee": "2.34",
      "script": {
        "flow": {
          "id": "16510ca2-7386-4829-ac6d-7f7c38a276d0",
          "name": "My Flow"
        },
        "cid_groups": [
          {
            "id": 2,
            "name": "My CID Group"
          }
        ]
      }
    }
  ],
  "metadata": {
    "total": 1,
    "page": 1,
    "page_size": 1
  }
}

Troubleshooting

The following issues are sometimes encountered:

Too many requests

If you see this error, "error": "API rate limit exceeded", reduce the number of API requests you send per second.

Unauthorized

The numbers API uses the contact center API key to validate the request. If you see this error, "error": "Invalid API key", check that you use the correct contact center API key. For more information about API keys, refer to Authentication.