Replace Members

POST /v2/clients/{client_id}/departments/{department_id}/members/replace

Replaces each listed user's entire department assignment set with the target department. This operation is idempotent -- users already assigned only to this department succeed 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 target department

Request Body

Field	Type	Required	Description
user_ids	string[]	Yes	Array of user IDs to assign exclusively to the target 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

Replace department assignments for multiple users

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

Replace department assignment for a single user

curl -X POST "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/departments/d1a2b3c4-e5f6-7890-abcd-ef1234567890/members/replace" \
  -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 already assigned only to the target department (idempotent)

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

Users already assigned only to the target department are included in succeeded -- the desired state is already achieved.

Replace semantics

For each user in user_ids, the server sets:

{
  "departments": ["{department_id}"]
}

That means:

Current user state	Result after replace
No departments	User is assigned to the target department
One different department	Old department is removed, target department is assigned
Multiple departments	All existing departments are removed, target department is assigned
Already assigned only to target department	No change

This endpoint is for exclusive assignment. If you want to add a department without removing existing memberships, use Add Members.

Idempotency

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

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 without removing other memberships
• Remove Members - Remove users from this department
• Update User - Replace the full department array for a single user
• Get User - View a specific user's current departments array