API Reference
Bulk Delete Users
Overview
Delete multiple tenant users in a single request by sending an array of user ids.
Provide between 1 and 100 valid Mongo ObjectIds. The response returns how many users and related memberships were removed so you can update admin lists and confirm the cleanup.
When to use this endpoint?
Use Bulk Delete Users when:
- An admin selects several users in a table and confirms a batch remove.
- An automation job needs to purge a set of inactive or test accounts.
- You want one API call instead of looping Delete User for each id.
- You need aggregated
usersDeletedandmembersDeletedcounts after the operation.
{baseUrl}/api/{apiVersion}/client/users/bulk-deleteAuthentication
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). |
| x-client-id | {{clientId}} | Tenant (client) id. Uses the {{clientId}} variable. |
| Content-Type | application/json | — |
Request Payload
{
"userIds": [
"{{userId}}",
"699fe1377846dcfb775c645e"
]
}Success Response (HTTP 200 OK)
When bulk deletion succeeds, the API returns summary counts for users and related memberships removed.
{
"success": true,
"message": "Users deleted successfully",
"data": {
"usersDeleted": 2,
"membersDeleted": 9
},
"error": null
}Workflow
Follow this flow to remove multiple users safely and confirm the result in your admin UI.
- 1
Select resources to remove
Collect 1–100 valid IDs from your admin UI or automation job.
- 2
Call the bulk-delete endpoint
Send the ID array in the request body with tenant headers and a Bearer token.
- 3
Review the deletion summary
Use the response counts to confirm how many records were removed and refresh your list views.
Common Errors
HTTP 200 OK means the bulk delete completed. Requests fail when the id list is empty, too large, or contains invalid ids.
HTTP 400 Bad Request — Invalid ids
{
"success": false,
"message": "userIds must be 1-100 valid ids",
"data": null,
"error": "userIds must be 1-100 valid ids"
}| Code | Reason |
|---|---|
| 400 Bad Request | userIds must be 1–100 valid ids. |
| 401 Unauthorized | Access Token is missing, invalid, or expired. |
| 500 Internal Server Error | An unexpected error occurred while deleting users. |
Best Practices
- Cap selections at 100 ids per request; split larger sets into batches.
- Validate ObjectIds in the UI before submit to avoid 400 Bad Request.
- Show a confirmation step that lists how many users will be removed.
- Use the response counts to toast success and refresh List Users.
- Prefer single Delete User when only one account is selected.
Bulk delete complete
Review usersDeleted and membersDeleted, then reload your tenant user directory so removed accounts disappear from the UI.