Gets all of the users in the system and their information. The result is limited to what the request sender has permission to view.
Permissons required:
view-d-room: Required to view direct messagesview-full-other-user-info: Required to view complete user information (e.g., account creation date, last login)view-outside-room: (Only required if the settingApply_permission_view-outside-roomis enabled on under Settings > General > Rest API). Required to view rooms outside of which the request sender is a member of
Changelog
| Version | Description |
|---|---|
| 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.
List of fields to order by, and in which direction. JSON object, with properties listed in desired order, with values of 1 for ascending, or -1 for descending. For example, {"value": -1, "_id": 1}. Refer to the official documentation to learn more.
OK
{
"users": [
{
"_id": "DGsmi2J4WjizYn7jc",
"username": "uniqueusername",
"emails": [
{
"address": "[email protected]",
"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": "[email protected]",
"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": "[email protected]", "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.