What this does

When you send a Get list of deleted users request, Voiso returns a paginated list of deleted user objects.

Deleted users include a deleted_at timestamp.

When to use it

Sync deleted users into an external system
Audit user lifecycle changes
Identify users that should be removed or deactivated in downstream systems

Prerequisites

At least one user has been deleted in your contact center.

Endpoint


GET /api/v4/users/deleted

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 email.
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/deleted" \
  -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/deleted?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/users/deleted?email=jane.doe@companyname.com" \
  -H "Authorization: Bearer <contact_center_api_key>" \
  -H "Content-Type: application/json"

Response

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

{
  "users": [
    {
      "id": "0b97ce11-b6e0-49b4-8f92-68040aa324bf",
      "name": "Jane Doe",
      "email": "jane.doe@companyname.com",
      "sip_account": "jane.doe@contactcenter.com",
      "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.

200OK

400Bad Request

401Unauthorized

403Forbidden

429Too many requests