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 MethodURLRequires Auth

GET

/api/v1/users.list

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}

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}

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
}
  • 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.

Change Log

VersionDescription

0.49.0

Count and offset query parameters supported.

0.35.0

Added

Last updated

Rocket.Chat versions receive support for six months after release.