API Reference
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).
{baseUrl}/api/{apiVersion}/user/list?page=1&limit=10Authentication
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.
{
"success": true,
"message": "User list fetched successfully",
"data": {
"list": [
{
"_id": "6a58...680",
"name": "Will Smith",
"email": "will.smith@example.com",
"isActive": true,
"role": "user",
"isOnline": false,
"blockedUsers": [],
"mutedUntil": null,
"isBanned": false,
"lastSeen": "2026-07-16T09:56:25.634Z",
"createdAt": "2026-07-16T09:55:19.015Z",
"updatedAt": "2026-07-17T12:28:01.102Z",
"__v": 0
}
],
"pagination": {
"currentPage": 1,
"totalCount": 1,
"hasNextPage": false,
"hasPreviousPage": false,
"pageSize": 10
}
},
"error": null
}Common Errors
List fails when the token is missing, invalid, or tenant headers are wrong.
HTTP 401 Unauthorized — No token
{
"success": false,
"message": "No token, authorization denied",
"data": null,
"error": "Unauthorized"
}| 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
limitsmall (10–20) and load more withhasNextPage. - 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.