Get User's Info

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, or importId. Email-based lookup is not supported.
From version 7.0.0, this endpoint no longer supports the fields parameter, even when the ALLOW_UNSAFE_QUERY_AND_FIELDS_API_PARAMS: true environment variable is set. Instead, use the includeUserRooms parameter.

Changelog

Version	Description
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 username of the user. Alternatively, you can use userId or username to retrieve user information.

includeUserRooms

string

Whether to include the list of rooms the user is a member of.

Responses

200

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
}

Expand All

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"
}

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

Was this article helpful?