Users
Users in the BlueSuite REST API
List workspace users to resolve a name or email to the UUID used in owner, salesperson, account-manager, and assignee fields. Use the returned id / user_id, rather than an email address, in UUID fields.
The REST API also supports adding a user and editing membership/profile fields. POST /users returns an existing membership when the email is already in the workspace, adds an existing account when it is not a member, or invokes the invitation flow for a new account. These operations can affect workspace access.
PATCH /users updates the specified user's profile name and/or workspace role and active status. Its response is { "data": ... } without the usual success flag. MCP exposes only list_users; it does not expose these user writes.
For listing, supported sort columns are first_name, last_name, email, role, job_title, created_at, and updated_at. name is an alias for first_name.
GET /api/v1/users
GET /api/v1/usersRequired scopes: users:read.
Query parameters
| Field | Type / accepted values | Required | Details |
|---|---|---|---|
page | integer | No | Page number, starting at 1. Default: 1. |
per_page | integer | No | Records per page, from 1 to 100. Default: 25. minimum: 1. maximum: 100. |
search | string | No | Search text. maxLength: 100. |
sort_by | string | No | Sort column. See the supported columns below when listed. |
sort_direction | "asc", "desc" | No | Sort direction. Default: "desc". |
Response
200 with { "success": true, "data": [...], "pagination": { "page": 1, "per_page": 25, "total_pages": 1 } }.
See response conventions and errors.
POST /api/v1/users
POST /api/v1/usersRequired scopes: users:write.
JSON body
| Field | Type / accepted values | Required | Details |
|---|---|---|---|
email | string | Yes | Email of the user to add to this workspace. |
first_name | string | No | |
last_name | string | No | |
role | string | No | Workspace role. Default: "member". |
Response
201 with { "success": true, "data": ... }. The data contains the result of the operation.
See response conventions and errors.
PATCH /api/v1/users
PATCH /api/v1/usersRequired scopes: users:write.
JSON body
| Field | Type / accepted values | Required | Details |
|---|---|---|---|
user_id | string | Yes | Profile UUID returned by GET /users. |
first_name | string | No | |
last_name | string | No | |
role | string | No | Workspace role. |
is_active | boolean | No |
Response
200 with { "data": { "user_id": "...", ...updatedFields } }. This route omits the usual success flag.