Get list of users

The Get list of users endpoint returns the users you can access.

Requirements: Base URL, Authentication, Error codes

Scope: users.read

What this does

When you send a Get list of users request,

Voiso

returns a paginated list of full user objects.

When to use it

Populate a user selector in an external tool
Retrieve user IDs to use in other requests, such as routing configuration
Search for a user by name, e mail, extension, or SIP account

Prerequisites

At least one user is configured in your contact center.

Endpoint


GET /api/v4/users

Query parameters

All query parameters are optional.

Pagination:

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.

Filters:

name
Filter by user name.
email
Filter by user e mail.
sip_account
Filter by SIP account in the format username@domain.
security_access_group_id
Filter by security access group ID.
extension
Filter by extension.
caller_id
Filter by caller ID.
timezone
Filter by time zone name.

Examples

Minimal request

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

Filter by email

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

Filter by security access group

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

Response

If successful, the API returns an array of user objects and pagination metadata.

{
  "users": [
    {
      "id": "1234",
      "name": "Jane Doe",
      "email": "[email protected]",
      "sip_account": "[email protected]",
      "extension": "102",
      "caller_id": "12025550123",
      "employee_id": "E-482",
      "timezone": "America/New_York",
      "security_access_group": {
        "id": 3,
        "name": "Boarding"
      },
      "teams": [
        {
          "id": 3,
          "name": "Multilingual Support"
        }
      ],
      "supervised_teams": [
        {
          "id": 3,
          "name": "Multilingual Support"
        }
      ],
      "queues": [
        {
          "id": 1,
          "name": "Technical Support"
        }
      ],
      "supervised_queues": [
        {
          "id": 1,
          "name": "Technical Support"
        }
      ],
      "webrtc_ringtone": {
        "type": "ringtone",
        "name": "Bells (Default)"
      },
      "channels": [
        "voice",
        "chat",
        "whatsapp"
      ],
      "channel_group_capacity": {
        "chat": 5,
        "instant": 3
      },
      "channel_profiles": [
        {
          "id": 12,
          "channel": "whatsapp",
          "identifier": "18885658889",
          "name": "WhatsApp Main (18885658889)"
        }
      ],
      "speech_language": "en",
      "skills": [
        {
          "skill": {
            "id": 1,
            "name": "Sales"
          },
          "value": 5
        }
      ],
      "status": "available",
      "created_at": "2025-11-11T12:00:00.216Z",
      "updated_at": "2025-11-11T12:00:00.216Z",
      "deleted_at": "2025-11-11T12:00:00.216Z"
    }
  ],
  "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 users in this contact center.

429 Too many requests

What to do:

Reduce request frequency and retry with backoff.