Get
/api/v1/users.info
- Retrieves information about a user. The result is limited only to what you have access to view.
- This endpoint supports lookup by
userId,username,importId,email, orfreeSwitchExtension. Provide exactly one of these parameters per request. - From version
7.0.0, this endpoint no longer supports thefieldsparameter, even when theALLOW_UNSAFE_QUERY_AND_FIELDS_API_PARAMS: trueenvironment variable is set. Instead, use theincludeUserRoomsparameter.
Changelog
| Version | Description |
|---|---|
| 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 |
Header parameters
X-Auth-Token
stringRequired
The authenticated user token.
ExampleRScctEHSmLGZGywfIhWyRpyofhKOiMoUIpimhvheU3f
X-User-Id
stringRequired
The authenticated user ID.
ExamplerbAXPnMktTFbNpwtJ
Query parameters
userId
stringRequired
The userId of the user. Alternatively, you can use username or importId to retrieve user information. Email-based lookup is not supported.
ExampleW7NHuX5ri2e3mu2Fc
username
string
The username of the user. Alternatively, you can use userId or importId to retrieve user information.
importId
string
The import ID of the user. Alternatively, you can use userId, username, email, or freeSwitchExtension to retrieve user information.
includeUserRooms
string
Whether to include the list of rooms the user is a member of.
email
string
Filter the results by entering the user's email. Alternatively, you can use userId, username, importId, or freeSwitchExtension to retrieve user information.
Examplejohn@example.com
freeSwitchExtension
string
The FreeSwitch voice call extension assigned to the user. Alternatively, you can use userId, username, importId, or email to retrieve user information.
Example1234
Responses
200
OK
Success Example
{
"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
}object
user
object
_id
string
createdAt
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
requirePasswordChange
boolean
lastLogin
string
statusConnection
string
utcOffset
integer
freeSwitchExtension
string
canViewAllInfo
boolean
success
boolean
400
Bad Request
Missing / invalid lookup
{
"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"
}User not found
{
"success": false,
"error": "User not found."
}object
success
boolean
error
string
errorType
string
401
Unauthorized
Authorization Error
{
"status": "error",
"message": "You must be logged in to do this."
}object
status
string
message
string