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.