Please refer to the detailed API endpoint specification: List users

User management

To build integrations, you may want to retrieve the list of the objects and their parameters programmatically before calling other APIs.

For example, when you want to get calls filtered for individual users or specific teams using the List CDRs, you need to specify the user IDs or team IDs to filter data.

The following APIs allow you to retrieve all the details (including IDs) for your contact center users and teams:

Get all users associated with your contact center : List users
Get all deleted users associated with your contact center : List deleted users
Get all teams associated with your contact center : List teams

Note: The request, response, and authentication for this endpoint have been completely updated as of October 9, 2024. Please ensure that you update any customizations that use this endpoint.

Making requests

Authentication

The users API requires the Base URL and the contact center API key.

Request parameters

The users API uses the contact center API key as a bearer token for the request.

Simple REST request example:

{
  "method": "GET",
  "url": "https://cluster1.contact_center_name.com/user_management/v1/users",
  "headers": {
    "Authorization": "Bearer ad-9433j0s...9rrk63",
    "Accept": "application/json"
  }
}

The users API also enables you to apply filters to the GET request. The following filters are supported:

Parameter	Description	Type	Required	Notes
id	The Contact Center ID of the user.	number	Optional	Get only information for the specified user.
name	The name of the user.	string	Optional	Get only information for the specified user.
email	The email address of the user.	string	Optional	Get only information for the user based on the specified sign-in email address.
sip_account	The SIP server address for the user's WebRTC Softphone.	string	Optional	Get only information for the user based on the specified SIP server address.
sag	The user's role.	string	Optional	Get only information for the users who are assigned to the specified security access group.
extension	The WebRTC extension of the user.	string	Optional	Get only information for the user based on the specified contact center extension.
caller_id	The Caller ID group of the user.	string	Optional	Get only information for the users who are assigned to the specified caller ID group.
timezone	The time zone of the user.	string	Optional	Get only information for the users who are assigned to the specified time zone.

Full request example:

{
  "method": "GET",
  "url": "https://cluster1.contact_center_name.com/api/user_management/v1/users",
  "headers": {
    "Authorization": "Bearer ad-9433j0s...9rrk63",
    "Accept": "application/json"
  },
  "params": {
    "id": "<integer>",
    "name": "<string>",
    "email": "<string>",
    "sip_account": "<string>",
    "sag": "<string>",
    "extension": "<string>",
    "caller_id": "<string>",
    "timezone": "<string>"
  }
}

Response

The following table describes the elements of the response.

Element	Description	Type	Notes
id	The ID assigned by the system when the user is created.	number
name	The name of the user, corresponding to the Name field in the User profile.	string
email	The email address the agent uses to sign in to Voiso.	string
sip_account	The SIP address of the user's softphone.	string
sag	The name of the Security Access Group to which the user is assigned.	string
extension	The contact center extension used to route calls to the user.	string
caller_id	The name of the caller ID group to which the user is assigned.	string
timezone	The name of the time zone selected for the user.	string
webrtc_ringtone	The name of the ringtone assigned to the user.	string
assigned_teams	A comma-separated list of the IDs of the Teams to which the user is assigned.	string	Use the Teams API to obtain the team IDs.
supervisor_in_teams	A comma-separated list of the IDs of the Teams that the user supervises.	string	Use the Teams API to obtain the team IDs.
assigned_skills	An object containing an array of the names of the skills and the assigned skill level.	object
assigned_channels	An object containing an array of the names of the digital channels assigned to the user.	object
assigned_queues	A comma-separated list of queue names.	string
employee_id	The value assigned to the user in the Employee ID field of the user profile.	string

Assigned skills array

Parameter	Description	Type	Notes
name	The name of the skill	string
value	The skill level	number	An integer from 1 to 10, where 10 is the highest skill level.

Assigned channels array

Parameter	Description	Type	Notes
type	Digital channel type	string	One of the supported Digital channel types.
name	The name of the channel.	string	When digital channels are added to a contact center, they are assigned unique names so that two channels of the same type may be discriminated.
value	Phone number associated with the channel	number	Not all digital channels are associated with a phone number. The phone number is in E.164 format without the initial '+' symbol.

Response sample

{
  "summary": "Agents parameters",
  "description": "All of the user data",
  "value": {
    "id": 28982,
    "name": "AG D",
    "email": "ag@g.com",
    "sip_account": "ag@cc1.email.net",
    "sag": "Agent",
    "extension": "2594",
    "caller_id": "378",
    "timezone": "Istanbul",
    "webrtc_ringtone": null,
    "assigned_teams": "3623, 2481",
    "supervisor_in_teams": "Support, Team3",
    "assigned_skills": [
      {
        "name": "Skill1",
        "value": 4
      },
      {
        "name": "Skill2",
        "value": 3
      },
      {
        "name": "Skill3",
        "value": 5
      }
    ],
    "assigned_queues": "AG Queue",
    "employee_id": 123,
    "assigned_channels": [
      {
        "type": "WhatsApp",
        "name": "WhatsApp Support 1",
        "value": 1234567890
      },
      {
        "type": "Webchat",
        "name": "Webchat Support",
        "value": 9876543210
      },
      {
        "type": "Viber",
        "name": "Viber Support",
        "value": 1122334455
      }
    ]
  }
}

Troubleshooting

The following issues are sometimes encountered:

Invalid User API Key

The users API requires the user API key to validate the request. If you see this error, "error": "Invalid User API Key", check that you use the correct user API key. For more information about API keys, refer to Authentication.