The Get caller ID groups endpoint returns the caller ID groups you can access.

Requirements: Base URL, Authentication, Error codes

Scope: numbers.read

What this does

When you send a Get caller ID groups request, Voiso returns a paginated list of caller ID group objects.

When to use it

Populate a caller ID group selector in an external tool
Retrieve caller ID group IDs to use when configuring outbound caller ID behavior
Display caller ID group names alongside numbers or users

Prerequisites

At least one caller ID group is configured in your contact center.

Endpoint


GET /api/v4/numbers/caller-id-groups

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/caller-id-groups" \
  -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/caller-id-groups?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 caller ID group objects and pagination metadata.

{
  "caller_id_groups": [
    {
      "id": 1,
      "name": "Default"
    }
  ],
  "metadata": {
    "total": 100
  }
}

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 caller ID groups in this contact center.

429 Too many requests

What to do:

Reduce request frequency and retry with backoff.