List Users

Overview

Retrieve a paginated list of chat users in the current tenant - the people your messaging app can start conversations with or show in search.

Use query parameters to paginate, search by name/email, filter by role, or match custom metadata. Built for chat UIs such as the new chat people picker and forward targets - not the Platform admin panel.

When to use this endpoint?

Use List Users when:

Building a new chat / start conversation people picker.
Searching contacts by name or email inside the chat app.
Suggesting participants for a group chat.
Filtering chat users by role or metadata.<key> (for example department) so the picker stays relevant.

Part of the Chat User APIs. For Platform panel user management, use Platform → Users instead. Requires a chat user Bearer token and tenant headers (is-tenant=true, x-client-id).

GET{baseUrl}/api/{apiVersion}/user/list?page=1&limit=10

Authentication: Required (Bearer token)
Tenant-scoped: Yes (tenant DB - requires x-client-id)

Request Headers

Header	Value	Description
Authorization	Bearer <access_token>	Chat user Access Token (Bearer) for the signed-in messaging participant.
is-tenant	true	Targets the tenant DB ("true", needs x-client-id).
x-client-id	{{clientId}}	Tenant (client) id. Required when is-tenant=true.

Query Parameters

Parameter	Required	Example	Description
page	Optional	1	Page number, 1-based. Default 1.
limit	Optional	10	Page size - items per page. Default 10.
search	Optional	—	Case-insensitive text search (input is regex-escaped). Matches this endpoint's searchable fields such as name and email.
role	Optional	user	Filter by tenant role slug (for example `admin`, `user`, or `sales-manager`).
metadata.department	Optional	sales	Filter on custom metadata. Matches `metadata.department` exactly — change the key to `metadata.<yourKey>` for any field your app stores.

Success Response (HTTP 200 OK)

On success, the API returns a list of users and a pagination object.

json

1{2  "success": true,3  "message": "User list fetched successfully",4  "data": {5    "list": [6      {7        "_id": "6a58...680",8        "name": "Will Smith",9        "email": "will.smith@example.com",10        "isActive": true,11        "role": "user",12        "isOnline": false,13        "blockedUsers": [],14        "mutedUntil": null,15        "isBanned": false,16        "lastSeen": "2026-07-16T09:56:25.634Z",17        "createdAt": "2026-07-16T09:55:19.015Z",18        "updatedAt": "2026-07-17T12:28:01.102Z",19        "__v": 020      }21    ],22    "pagination": {23      "currentPage": 1,24      "totalCount": 1,25      "hasNextPage": false,26      "hasPreviousPage": false,27      "pageSize": 1028    }29  },30  "error": null31}

Common Errors

List fails when the token is missing, invalid, or tenant headers are wrong.

HTTP 401 Unauthorized - No token

json

1{2  "success": false,3  "message": "No token, authorization denied",4  "data": null,5  "error": "Unauthorized"6}

Code	Reason
401 Unauthorized	Access Token is missing, invalid, or expired.
500 Internal Server Error	An unexpected error occurred while fetching the user list.

Best Practices

Debounce search in the people picker; keep limit small (10–20) and load more with hasNextPage.
Exclude the signed-in user from “start chat” results in the UI when that matches your product rules.
Prefer metadata filters for team or department pickers instead of overloading search.
Always send tenant headers with the chat user Bearer token over HTTPS.

People list ready

Bind results to your chat people picker, then open a contact with Get User or start a conversation from the selected id.

Overview

Retrieve a paginated list of chat users in the current tenant - the people your messaging app can start conversations with or show in search.

When to use this endpoint?

Use List Users when:

Building a new chat / start conversation people picker.
Searching contacts by name or email inside the chat app.
Suggesting participants for a group chat.
Filtering chat users by role or metadata.<key> (for example department) so the picker stays relevant.

Part of the Chat User APIs. For Platform panel user management, use Platform → Users instead. Requires a chat user Bearer token and tenant headers (is-tenant=true, x-client-id).

Header

Value

Description

Authorization

Bearer <access_token>

Chat user Access Token (Bearer) for the signed-in messaging participant.

is-tenant

true

Targets the tenant DB ("true", needs x-client-id).

x-client-id

Tenant (client) id. Required when is-tenant=true.

Query Parameters

Parameter	Required	Example	Description
page	Optional	1	Page number, 1-based. Default 1.
limit	Optional	10	Page size - items per page. Default 10.
search	Optional	—	Case-insensitive text search (input is regex-escaped). Matches this endpoint's searchable fields such as name and email.
role	Optional	user	Filter by tenant role slug (for example `admin`, `user`, or `sales-manager`).
metadata.department	Optional	sales	Filter on custom metadata. Matches `metadata.department` exactly — change the key to `metadata.<yourKey>` for any field your app stores.

Success Response (HTTP 200 OK)

On success, the API returns a list of users and a pagination object.

json

1{2  "success": true,3  "message": "User list fetched successfully",4  "data": {5    "list": [6      {7        "_id": "6a58...680",8        "name": "Will Smith",9        "email": "will.smith@example.com",10        "isActive": true,11        "role": "user",12        "isOnline": false,13        "blockedUsers": [],14        "mutedUntil": null,15        "isBanned": false,16        "lastSeen": "2026-07-16T09:56:25.634Z",17        "createdAt": "2026-07-16T09:55:19.015Z",18        "updatedAt": "2026-07-17T12:28:01.102Z",19        "__v": 020      }21    ],22    "pagination": {23      "currentPage": 1,24      "totalCount": 1,25      "hasNextPage": false,26      "hasPreviousPage": false,27      "pageSize": 1028    }29  },30  "error": null31}

Common Errors

List fails when the token is missing, invalid, or tenant headers are wrong.

HTTP 401 Unauthorized - No token

json

1{2  "success": false,3  "message": "No token, authorization denied",4  "data": null,5  "error": "Unauthorized"6}

Code	Reason
401 Unauthorized	Access Token is missing, invalid, or expired.
500 Internal Server Error	An unexpected error occurred while fetching the user list.

Best Practices

Debounce search in the people picker; keep limit small (10–20) and load more with hasNextPage.
Exclude the signed-in user from “start chat” results in the UI when that matches your product rules.
Prefer metadata filters for team or department pickers instead of overloading search.
Always send tenant headers with the chat user Bearer token over HTTPS.