Remove Members

POST /clients/{client_id}/departments/{department_id}/members/remove

Removes one or more users from a department. This operation is idempotent -- removing a user who is not a member succeeds without error.

Path Parameters

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

Request Body

Field	Type	Required	Description
user_ids	string[]	Yes	Array of user IDs to remove from the department

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

Response

Returns a BulkMemberResult object with status 200 OK. Individual failures are reported inline -- the response is always 200 as long as the request itself is valid.

Example Requests

Remove multiple users

curl -X POST "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/departments/d1a2b3c4-e5f6-7890-abcd-ef1234567890/members/remove" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ids": [
      "a1d97031-04e2-4907-a249-093f7436207b",
      "b2e08142-15f3-5018-b350-104g8547318c"
    ]
  }'

Remove single user

curl -X POST "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/departments/d1a2b3c4-e5f6-7890-abcd-ef1234567890/members/remove" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ids": ["a1d97031-04e2-4907-a249-093f7436207b"]
  }'

Example Responses

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": "User not found"
    }
  ]
}

User not a member (idempotent)

{
  "succeeded": ["a1d97031-04e2-4907-a249-093f7436207b"],
  "failed": []
}

Users not in the department are included in succeeded -- the desired state is already achieved.

Idempotency

This operation is idempotent. Calling it multiple times with the same user IDs results in the same state. Safe to retry on network failures.

Multi-department membership

Removing a user from a department does not affect their membership in any other departments.

To view a user's remaining department assignments after removal, see Get User -- the departments array reflects the current state.

Error Responses

Status	Description
400	Invalid request body (e.g. missing user_ids, malformed UUID)
401	Authentication required
403	Insufficient permissions for this client
404	Department or client not found
500	Server error

Related Endpoints

• Add Members - Add users to this department
• Get Department - View department including updated member_count
• List Users - Filter users by department_id
• Get User - View departments array for a specific user
• Delete Department - Delete the entire department