API Reference
Get User Detail
Overview
Fetch the full profile of a single tenant user by their _id.
The response includes core identity fields, activity status, and usage stats such as conversation and message counts. Use this endpoint when a list row is not enough and you need the complete user record.
When to use this endpoint?
Use Get User Detail when:
- Opening a user profile or detail drawer from a list view.
- You need stats such as conversations count or messages sent.
- Confirming a user still exists before updating or deleting them.
- Loading the latest role, active status, and online presence for one user.
GET
{baseUrl}/api/{apiVersion}/client/users/:userIdAuthentication
Required (Bearer token)
Tenant-scoped
Yes (tenant DB — requires x-client-id)
Request Headers
| Header | Value | Description |
|---|---|---|
| is-tenant | true | Targets the tenant DB ("true", needs x-client-id) or the root DB ("false", e.g. client register/create). |
| x-client-id | {{clientId}} | Tenant (client) id. Required when is-tenant=true. Uses the {{clientId}} variable. |
Path Parameters
| Parameter | Example | Description |
|---|---|---|
| userId | string | The target user’s _id (24-char Mongo ObjectId). |
Success Response (HTTP 200 OK)
When the user exists in the tenant, the API returns the full user record and related stats.
json
{
"success": true,
"message": "User fetched successfully",
"data": {
"_id": "694b...d8",
"name": "project user",
"email": "userp3@hgmail.com",
"role": "user",
"isActive": true,
"isOnline": false,
"stats": {
"conversationsCount": 14,
"messagesSent": 832,
"groupsOwned": 2
},
"blockedUsers": [
"6a3c...14fe"
],
"metadata": {
"workspaceId": "c1"
},
"lastSeen": "2026-06-18T08:55:00.000Z",
"createdAt": "2026-06-01T00:00:00.000Z",
"updatedAt": "2026-06-01T00:00:00.000Z"
},
"error": null
}Common Errors
HTTP 200 OK means the user was fetched successfully. Look up failures usually come from a bad id, missing tenant headers, or an expired token.
| Code | Reason |
|---|---|
| 400 Bad Request | Required headers are missing or userId is invalid. |
| 401 Unauthorized | Access Token is missing, invalid, or expired. |
| 404 Not Found | No user exists for the given userId in this tenant. |
| 500 Internal Server Error | An unexpected error occurred while fetching the user. |
Best Practices
- Pass a valid 24-character Mongo ObjectId from List Users or another trusted source.
- Always include tenant headers (
is-tenantandx-client-id) with the Bearer token. - Cache detail responses briefly in the UI, but re-fetch after an update so role and metadata stay accurate.
- Handle 404 Not Found by returning the user to the list view.
User detail loaded
Use the returned _id with Update User or Delete User when you need to change or remove this account.