Add Members

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

Adds one or more users to a department. This operation is idempotent -- adding a user who is already 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 add to 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

Add multiple users

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

Add single user

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

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

Users already 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

Adding a user to a department does not remove them from any other departments. Users can belong to multiple departments simultaneously.

To view a user's current department assignments, see Get User -- the departments array lists all current memberships.

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

• Remove Members - Remove users from this department
• Get Department - View department including member_count
• List Users - Filter users by department_id
• Get User - View departments array for a specific user