Retrieves information about a user, limited to the details the caller is allowed to view. Look up the user by userId, username, importId, email, or freeSwitchExtension. Provide exactly one of these parameters per request.
Starting in version 7.0.0, this endpoint no longer supports the fields parameter, even when the ALLOW_UNSAFE_QUERY_AND_FIELDS_API_PARAMS environment variable is set to true. Use includeUserRooms instead.
When the Premium User status hiding feature is enabled and the requested user has hidden their status from the caller, the response shows the user as offline and omits statusText, statusSource, statusExpiresAt, statusDefault, and statusConnection. This restriction also applies to administrators. Users always see their own status.
Changelog
| Version | Description |
|---|---|
| 8.8.0 | Added status visibility filtering |
| 8.5.0 | Added freeSwitchExtension query parameter for user lookup |
| 8.4.0 | Added email query parameter for user lookup |
| 7.0.0 | Removed the fields query parameter |
| 3.4.0 | Added unread property inside rooms object |
| 0.70.0 | Added rooms property to response if the user request it and has the view-other-user-channels permission |
| 0.49.0 | Updated to support userId or username |
| 0.48.0 | Renamed to users.info |
| 0.35.0 | Added |
The authenticated user token.
The authenticated user ID.
The userId of the user. Alternatively, you can use username, importId, email, or freeSwitchExtension to retrieve user information.
The username of the user. Alternatively, you can use userId, importId, email, or freeSwitchExtension to retrieve user information.
The import ID of the user. Alternatively, you can use userId, username, email, or freeSwitchExtension to retrieve user information.
Whether to include the list of rooms the user is a member of.
Filter the results by entering the user's email. Alternatively, you can use userId, username, importId, or freeSwitchExtension to retrieve user information.
The FreeSwitch voice call extension assigned to the user. Alternatively, you can use userId, username, importId, or email to retrieve user information.
OK
{
"user": {
"_id": "5fRTXMt7DMJbpPJfh",
"createdAt": "2023-07-10T16:44:58.548Z",
"services": {
"password": true,
"email2fa": {
"enabled": true,
"changedAt": "2023-07-10T16:44:58.546Z"
},
"resume": {
"loginTokens": [
{
"when": "2023-10-05T18:55:02.996Z",
"hashedToken": "..."
},
{
"when": "2023-10-05T19:09:30.415Z",
"hashedToken": "...."
},
{
"when": "2023-10-10T23:40:46.098Z",
"hashedToken": "...."
}
]
}
},
"username": "test.john",
"emails": [
{
"address": "test.john@test.com",
"verified": true
}
],
"type": "user",
"status": "offline",
"active": true,
"roles": [
"user",
"admin"
],
"name": "Test John",
"requirePasswordChange": false,
"lastLogin": "2023-10-10T23:40:46.093Z",
"statusConnection": "offline",
"utcOffset": 1,
"statusText": "",
"avatarETag": "GFoEi6wv3uAxnzDcD",
"nickname": "tesuser2",
"freeSwitchExtension": "1234",
"canViewAllInfo": true,
"rooms": [
{
"_id": "651667dda2f73c7460e18cce",
"unread": 1,
"rid": "JKa7R9zu2DinBhBN9",
"name": "Livestream",
"t": "c"
},
{
"_id": "64ac358a79f5c6e276cfe718",
"unread": 0,
"rid": "GENERAL",
"name": "general",
"t": "c"
},
{
"_id": "64aca0e5aa5ad4273bfbfdb8",
"unread": 0,
"rid": "6GFJ3tbmHiyHbahmC",
"name": "test-audit",
"t": "c"
},
{
"_id": "64adb09baa5ad4273bfc0cc0",
"unread": 0,
"rid": "64adb09baa5ad4273bfc0cbf",
"name": "test-room",
"t": "c",
"roles": [
"owner"
]
},
{
"_id": "64fd791c2c26843a68c1f7e5",
"unread": 0,
"rid": "siyr2oWQJBjQjhLwr",
"name": "try",
"t": "c",
"roles": []
},
{
"_id": "g5xHGWAGLA7vZXwW8",
"rid": "5fRTXMt7DMJbpPJfhrbAXPnMktTFbNpwtJ",
"name": "roxie",
"t": "d",
"unread": 2
},
{
"_id": "64ef8a982c26843a68c1f7ae",
"unread": 0,
"rid": "WDuJLFkjwk6L7LdFC",
"name": "new",
"t": "p",
"roles": [
"leader"
]
}
]
},
"success": true
}Bad Request
{
"success": false,
"error": "must have required property 'userId'\n must have required property 'username'\n must have required property 'importId'\n must match a schema in anyOf [invalid-params]",
"errorType": "invalid-params"
}{
"success": false,
"error": "User not found."
}Unauthorized
{
"status": "error",
"message": "You must be logged in to do this."
}