Get Users List
- Print
- DarkLight
- PDF
Get Users List
- Print
- DarkLight
- PDF
Article summary
Did you find this summary helpful?
Thank you for your feedback
Get
/api/v1/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.
Changelog
| Version | Description |
|---|---|
| 0.49.0 | Count and offset query parameters supported. |
| 0.35.0 | Added |
Header parameters
X-Auth-Token
stringRequired
The authenticated user token.
ExampleRScctEHSmLGZGywfIhWyRpyofhKOiMoUIpimhvheU3f
X-User-Id
stringRequired
The authenticated user ID.
ExamplerbAXPnMktTFbNpwtJ
Query parameters
query
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" } }
fields
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 }
offset
integer
Number of items to "skip" in the query, i.e. requests return count items, skipping the first offset items.
Example50
sort
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}
count
integer
How many items to return.
Example50
Responses
200
OK
Success Example
{
"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
}object
users
Array of object
object
_id
string
username
string
emails
Array of object
object
address
string
verified
boolean
type
string
status
string
active
boolean
roles
Array of string
string
name
string
lastLogin
string
nameInsensitive
string
avatarETag
string
count
integer
offset
integer
total
integer
success
boolean
401
Unauthorized
Authorization Error
{
"status": "error",
"message": "You must be logged in to do this."
}object
status
string
message
string
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.
Was this article helpful?