The Get purchased phone numbers endpoint returns the phone numbers your contact center purchased from Voiso. It does not include numbers that were added manually.

Requirements: Base URL, Authentication, Error codes

Scope: numbers.read

What this does

When you send a Get purchased phone numbers request, Voiso returns a paginated list of purchased phone number objects.

When to use it

Sync purchased inventory into an external system
Populate a selector for purchased numbers in an admin tool
Retrieve number IDs to use when assigning numbers to inbound routing or outbound caller ID configurations

Prerequisites

At least one phone number is purchased for the contact center.

Endpoint


GET /api/v4/numbers

Query parameters

All query parameters are optional.

limit
The number of items to return. Default is 100. Maximum is 100.
offset
The number of items to skip before collecting results. Default is 0.

Examples

Minimal request

curl -X GET "https://{cluster_id}.voiso.com/api/v4/numbers" \
  -H "Authorization: Bearer <contact_center_api_key>" \
  -H "Content-Type: application/json"

Request the third page of results (20 per page)

curl -X GET "https://{cluster_id}.voiso.com/api/v4/numbers?limit=20&offset=40" \
  -H "Authorization: Bearer <contact_center_api_key>" \
  -H "Content-Type: application/json"

Response

If successful, the API returns an array of purchased phone number objects and pagination metadata.

{
  "numbers": [
    {
      "id": 18,
      "phone_number": "421233056080",
      "label": "Main line",
      "type": "geographic",
      "country": "Slovakia",
      "city": "Bratislava",
      "channels": 4,
      "provider": "<BrandName />",
      "pricing": {
        "activation_fee": "4.99",
        "monthly_fee": "5.99",
        "partial_month_fee": "3.79",
        "price_per_min": "0.0152"
      },
      "caller_id_groups": [
        {
          "id": 1,
          "name": "Default"
        }
      ],
      "flow": {
        "id": "0b62763c-40d6-4ec8-8380-3cb94e442a75",
        "name": "Lead Qualification"
      },
      "created_at": "2025-11-11T12:00:00.216Z"
    }
  ],
  "metadata": {
    "total": 100
  }
}

Notes

phone_number is returned without a leading plus sign.
channels is the number of channels purchased for the phone number.
pricing values are returned as strings to preserve decimal precision.
caller_id_groups lists the caller ID groups assigned to the number.
flow is included only when the phone number is assigned to a flow.
This endpoint returns only numbers purchased from Voiso. It does not include numbers that were added manually.

Troubleshooting

401 Unauthorized

What to check:

You are sending Authorization: Bearer <contact_center_api_key>.
Your Base URL includes the correct {cluster_id}.

403 Forbidden

What to check:

The API key is valid, but does not have access to numbers in this contact center.

429 Too many requests

What to do:

Reduce request frequency and retry with backoff.

200OK

400Bad Request

401Unauthorized

403Forbidden

429Too many requests