# List your numbers

The live Vonyx numbers on your account, to place calls from.

```http
GET https://api.vocalstack.site/v1/numbers
Authorization: Bearer YOUR_TOKEN
```

Send the token from your API key ([Authentication](/docs/call-api/authentication)). There are no parameters and no body: the token says whose numbers to list.

```bash
curl https://api.vocalstack.site/v1/numbers \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

## Response

```json
{
  "status": 200,
  "message": "numbers",
  "data": {
    "numbers": [
      { "did": "919876543210", "sub_account_id": null },
      { "did": "918012345678", "sub_account_id": "c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f" }
    ]
  }
}
```

| Field | Description |
| --- | --- |
| `data.numbers` | Your live Vonyx numbers, in number order. An empty list `[]` when you have none. |
| `did` | The number: `91` followed by the 10-digit number. Use it as `did` when you [place a call](/docs/call-api). |
| `sub_account_id` | The [sub-account](/docs/console/sub-accounts) the number belongs to, or `null` when it is in none. |

Only numbers that are live on your account are listed. A number that was released, or is not live yet, is not in the list and cannot place calls.

## Errors

Every reply is JSON: `{"status": <code>, "message": "...", "error": "..."}`, with `data` instead of `error` on success.

| HTTP | `message` | `error` | What to do |
| --- | --- | --- | --- |
| `401` | `Unauthorized` | `send Authorization: Bearer YOUR_TOKEN` | The `Authorization` header is missing or not in the form `Bearer YOUR_TOKEN`. |
| `401` | `Unauthorized` | `invalid or expired token` | Get a new token ([Authentication](/docs/call-api/authentication)) and send the request again. |
| `405` | `Method not allowed` | `use GET` | Use `GET`. |
| `429` | `Too many requests` | `at most 5 requests a second; retry shortly` | More than 5 requests a second from your IP address. Wait a second and retry. |
| `503` | `Authentication unavailable` | `retry later` | Your token could not be checked at that moment. Try again after a few seconds. |
| `503` | `Number lookup failed` | `retry later` | A temporary problem. Try again after a few seconds. |
