Retrieves workspace users and the information the caller is allowed to view.
Filter by username, email, or custom field values to locate a user and obtain their userId for the users.info endpoint.
The response only contains the default user fields. To read customFields, set includeCustomFields to true. Other fields, such as utcOffset, nickname, bio, and statusText, are not returned by this endpoint. Use the users.info endpoint instead.
When the Premium User status hiding feature is enabled, users who have hidden their status from the caller appear as offline, and their detailed status fields are omitted.
Permissions required:
view-d-room: View direct messages.view-full-other-user-info: View complete user details, such as account creation and last login. Also required to use thecustomFieldsandincludeCustomFieldsparameters.view-outside-room: View users outside the caller's rooms whenApply_permission_view-outside-roomis enabled under Settings > General > REST API.
Changelog
| Version | Description |
|---|---|
| 9.0.0 | Removed the query and fields parameters. Requests that include them return a 400 error. Added the username, customFields, and includeCustomFields query parameters. |
| 8.8.0 | Added status visibility filtering |
| 8.4.0 | Added email query parameter for filtering |
| 0.49.0 | Count and offset query parameters supported. |
| 0.35.0 | Added |
The authenticated user token.
The authenticated user ID.
Number of items to "skip" in the query, i.e. requests return count items, skipping the first offset items. Refer to the official documentation to learn more.
Sort the users in ascending (1) or descending (-1) order. The value must be entered as a JSON string. The options are as follows: * status: Sort by users' status. For example, sort={"status":1} (this maps to the active status). * createdAt: Sort by the time of user creation. For example, sort={"createdAt":-1} * name: Sort by user name. For example, sort={"name":1}
Filter users by email address. Minimum length: 1 character.
Filter users whose username contains this value. The match is not case-sensitive and checks the username only, not the display name. Regular expression characters are matched literally. Minimum length: 1 character. An empty value returns a 400 error.
Filter users by exact custom field values, in the format customFields[<key>]=<value>. For example, customFields[department]=Sales. The value match is case-sensitive. When you send more than one key, a user must match all of them. The filter works without includeCustomFields. Sending the parameter as a JSON string, such as customFields={"department":"Sales"}, returns a 400 error. Requires the view-full-other-user-info permission.
Whether to include each user's full customFields object in the response. Users without custom fields are returned without the customFields key. The value must be true or false; other values return a 400 error. Requires the view-full-other-user-info permission. Defaults to false.
OK
{
"users": [
{
"_id": "DGsmi2J4WjizYn7jc",
"username": "uniqueusername",
"emails": [
{
"address": "email@user.tld",
"verified": false
}
],
"type": "user",
"status": "offline",
"active": true,
"roles": [
"bot",
"user"
],
"name": "name",
"nameInsensitive": "name"
},
{
"_id": "uZ5JvvioeHK8Coyqe",
"active": true,
"type": "user",
"status": "offline",
"roles": [
"user"
],
"lastLogin": "2023-05-16T20:50:33.579Z",
"username": "user-0",
"nameInsensitive": ""
},
{
"_id": "aspKK7FHe7iQgzexX",
"active": true,
"type": "user",
"status": "offline",
"roles": [
"user"
],
"lastLogin": "2023-05-12T10:44:46.703Z",
"username": "user-00",
"name": "User 00",
"emails": [
{
"address": "user00@mail.cm",
"verified": false
}
],
"nameInsensitive": "user 00"
}
],
"count": 3,
"offset": 0,
"total": 3,
"success": true
}Returned only for users who have logged in.
Returned only when includeCustomFields is true and the user has custom fields.
Bad Request
{
"success": false,
"error": "must NOT have additional properties",
"errorType": "error-invalid-params"
}{
"success": false,
"error": "must NOT have fewer than 1 characters",
"errorType": "error-invalid-params"
}{
"success": false,
"error": "must be object",
"errorType": "error-invalid-params"
}{
"success": false,
"error": "must be boolean",
"errorType": "error-invalid-params"
}Unauthorized
{
"success": false,
"error": "You must be logged in to do this."
}Forbidden
{
"success": false,
"error": "forbidden"
}Note:
The success 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:
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 > Workspace > Settings > Accounts > Registration > Custom Fields). See the Create User and Update User endpoints to add custom fields for new and existing users, respectively.