---
title: "Numbers"
slug: "numbers"
updated: 2024-10-25T15:08:04Z
published: 2024-10-25T15:08:04Z
canonical: "docs.voiso.com/numbers"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voiso.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Numbers

The **numbers** API lets you retrieve a list of the phone numbers owned by your contact center. Please refer to the detailed API endpoint specification [here](/v1-api/apidocs/list-numbers). 

## Prerequisites

* Your contact center must own at least one phone number.

## Making requests

### Authentication
The **numbers** API requires the [base URL](/v1-api/apidocs/base-endpoint) and the [contact center API key](/v1-api/apidocs/authentication). 

### Request parameters

The **numbers** API uses the following parameters.

The `Authorization: Bearer token` parameter is the [contact center API key](/v1-api/apidocs/authentication). 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:

```JSON
{
  "method": "GET",
  "url": "https://cluster1.voiso.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

```JSON
{
  "numbers": [
    {
      "number": "1234567890",
      "created_at": "2023-07-24T15:50:21.208Z",
      "label": "My number",
      "country": "United States",
      "city": "City",
      "type": "geographic",
      "provider": "Voiso",
      "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](/v1-api/apidocs/authentication).