Bulk Update User Status

PATCH /v2/clients/{client_id}/users/bulk-status

Update status for multiple users in a single request.

Use this endpoint when the same target status should be applied to many users at once. Processing is atomic per user: some users can succeed while others fail in the same call.

Path Parameters

Parameter	Type	Description
client_id	string (uuid)	Unique identifier for the client organization

Request Body

Field	Type	Required	Description
user_ids	string (uuid)[]	Yes	User IDs to update. Must contain 1-200 entries.
status	string	Yes	Status to apply to all provided users: active, archived, deleted.

Example Request Body

{
  "user_ids": [
    "a1d97031-04e2-4907-a249-093f7436207b",
    "b2e08142-15f3-5018-b350-104g8547318c"
  ],
  "status": "archived"
}

Response

Returns a BulkUserControlResult with status 200 OK.

All succeeded

{
  "succeeded": [
    "a1d97031-04e2-4907-a249-093f7436207b",
    "b2e08142-15f3-5018-b350-104g8547318c"
  ],
  "failed": []
}

Partial success

{
  "succeeded": [
    "a1d97031-04e2-4907-a249-093f7436207b"
  ],
  "failed": [
    {
      "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
      "error": "not_found"
    }
  ]
}

Business Rules

• Atomic per-user -- one failure does not roll back other users.
• A user ID that does not belong to the client is returned in failed with error: "not_found".
• Duplicate IDs may appear multiple times in succeeded if they are repeated in the request.
• Returns 200 even when all IDs fail (with succeeded: [] and failed populated).

Example Request

curl -X PATCH "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/users/bulk-status" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ids": [
      "a1d97031-04e2-4907-a249-093f7436207b",
      "b2e08142-15f3-5018-b350-104g8547318c"
    ],
    "status": "deleted"
  }'

Error Responses

Status	Description
400	Invalid request body (empty user_ids, more than 200 IDs, malformed UUID, or invalid status)
401	Authentication required
403	Insufficient permissions for this client
404	Client not found
500	Server error

Related Endpoints

• Update User - Update departments and/or status for one user
• List Users - Browse users and filter by status
• Get User - Verify status changes for a specific user