Retrieves workspace users and the information the caller is allowed to view.
Use query to locate a user and obtain their userId for the users.info endpoint. The query parameter is considered unsafe and is deprecated. Its support is expected to be removed in a future major version, and there is currently no direct replacement for email-based lookup.
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. If query filters on a status field, those users are excluded from the filtered results.
Permissions required:
view-d-room: View direct messages.view-full-other-user-info: View complete user details, such as account creation and last login.view-outside-room: View users outside the caller's rooms whenApply_permission_view-outside-roomis enabled under Settings > General > REST API.
Changelog
| Version | Description |
|---|---|
| 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.
This parameter allows you to use MongoDB query operators to search for specific data. For example, to query users with a name that contains the letter "g": query={ "name": { "$regex": "g" } }. Refer to the official documentation to learn more.
This parameter accepts a JSON object with properties that have a value of 1 or 0 to include or exclude them in the response. For example, to only retrieve the usernames of users: fields={ "username": 1 }. Refer to the official documentation to learn more.
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.
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": [
"anonymous",
"user"
],
"lastLogin": "2023-05-16T20:50:33.579Z",
"username": "user-0",
"nameInsensitive": ""
},
{
"_id": "aspKK7FHe7iQgzexX",
"active": true,
"type": "user",
"status": "offline",
"roles": [
"anonymous",
"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
}Unauthorized
{
"status": "error",
"message": "You must be logged in to do this."
}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.