get-users-list.md

Get Users List

Gets all of the users in the system and their information, the result is only limited to what the request sender has access to view.

HTTP Method	URL	Requires Auth
GET	/api/v1/users.list	yes

Query Parameters

This endpoint supports the optional #pagination parameters and the #query-and-fields parameters.

Example Call

curl -H "X-Auth-Token: 9HqLlyZOugoStsXCUfD_0YdwnNnunAJF8V47U3QHXSq" \
     -H "X-User-Id: aobEdbYhXfu5hkeqG" \
     http://localhost:3000/api/v1/users.list

Example Response

If the request sender is a regular user:

{
  "users": [
    {
      "_id": "nSYqWzZ4GsKTX4dyK",
      "type": "user",
      "status": "offline",
      "active": true,
      "name": "Example User",
      "utcOffset": 0,
      "username": "example"
    },
    {
      ...
    }
  ],
  "count": 10,
  "offset": 0,
  "total": 10,
  "success": true
}

If the request sender is an admin:

{
    "users": [
        {
            "_id": "Bm9YcfBCrwSTSGof7",
            "username": "botkit.user",
            "emails": [
                {
                    "address": "botkit@user.cm",
                    "verified": false
                }
            ],
            "status": "offline",
            "active": true,
            "roles": [
                "bot"
            ],
            "name": "Botkit User",
            "nameInsensitive": "botkit user"
        },
        
        {
            "_id": "Fdh2KgsB7dtwbYrNw",
            "username": "john.m",
            "emails": [
                {
                    "address": "john@m.com",
                    "verified": true
                }
            ],
            "status": "offline",
            "active": true,
            "roles": [
                "user"
            ],
            "name": "John M",
            "nameInsensitive": "john m"
        },
        {...},
        {
            "_id": "jowYXPgJoKaoxzz4q",
            "username": "user.one",
            "emails": [
                {
                    "address": "remego8086@d3ff.com",
                    "verified": false
                }
            ],
            "status": "offline",
            "active": true,
            "roles": [
                "livechat-manager",
                "livechat-agent"
            ],
            "name": "User One",
            "nameInsensitive": "user one"
        }
    ],
    "count": 11,
    "offset": 0,
    "total": 11,
    "success": true
}

Note that the response does not return the custom fields for users. To view the custom field information, you must add the query and fields parameters.

For example, you want to view the users having the custom field clearance with the value High. To do this, update the request URL as follows:

• Add the query parameter: query={"customFields.clearance" : "High"}
• Add the fields parameter: fields={"customFields" : 1}

{% code overflow="wrap" %}

curl -H "X-Auth-Token: 9HqLlyZOugoStsXCUfD_0YdwnNnunAJF8V47U3QHXSq" \
     -H "X-User-Id: aobEdbYhXfu5hkeqG" \
     http://localhost:3000/api/v1/users.list?query={"customFields.clearance" : "High"}&fields={"customFields" : 1}

{% endcode %}

The response looks something like this:

{
    "users": [
        {
            "_id": "ebKHhqGzw3Mu4KeBw",
            "username": "ciel",
            "emails": [
                {
                    "address": "example@test.com",
                    "verified": false
                }
            ],
            "type": "user",
            "roles": [
                "user"
            ],
            "status": "offline",
            "active": true,
            "name": "Ciel",
            "customFields": {
                "clearance": "High",
                "team": "Queen"
            },
            "nameInsensitive": "ciel"
        }
    ],
    "count": 1,
    "offset": 0,
    "total": 1,
    "success": true
}

{% hint style="info" %}

• To save and view the custom fields, you must first define the Custom Fields in the admin panel of your workspace (Administration > Settings > Accounts > Registration > Custom Fields).
• See the Create User and Update User endpoints to add custom fields for new and existing users, respectively. {% endhint %}

Change Log

Version	Description
0.49.0	Count and offset query parameters supported.
0.35.0	Added