Update User

PATCH /clients/{client_id}/users/{user_id}

Updates a user's department assignments. All fields are optional -- only include fields you want to change.

Path Parameters

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

Request Body

Field	Type	Description
departments	string[]	Array of department IDs to assign to this user. Replaces the entire departments array -- omitted departments are removed.

Fields Not Updatable via API

These fields are system-managed and cannot be changed through this endpoint:

Field	Reason
id	Immutable identifier
username	System-managed, synced from agent
user_key	Identity field, system-managed
last_activity.*	Written by the activity pipeline
created_at	Immutable audit timestamp

Response

Returns the updated User object with status 200 OK.

Example Requests

Assign departments

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

Assign to multiple departments

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

Remove from all departments

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

Example Response

{
  "id": "a1d97031-04e2-4907-a249-093f7436207b",
  "username": "mikechang",
  "user_key": "mikechang",
  "last_activity": {
    "at": "2026-02-24T21:23:53.082Z",
    "desktop_at": "2026-02-24T21:22:46.119Z",
    "web_at": "2026-02-24T21:23:53.082Z"
  },
  "departments": [
    {
      "id": "d1a2b3c4-e5f6-7890-abcd-ef1234567890",
      "name": "Engineering",
      "description": "Software development and infrastructure teams"
    }
  ],
  "created_at": "2026-02-05T21:29:34.214Z",
  "updated_at": "2026-02-24T22:00:00.000Z"
}

Department Array Behaviour

The departments field replaces the user's entire department list on every request. It does not append or remove individual entries.

Scenario	Request	Result
Move user from Sales to Engineering	{ "departments": ["eng-id"] }	User is in Engineering only
Add a second department	{ "departments": ["eng-id", "platform-id"] }	User is in both
Remove all departments	{ "departments": [] }	User has no department

For bulk department membership operations across many users, use the Add Members and Remove Members endpoints in the Departments domain.

Error Responses

Status	Description
400	Invalid request body (e.g. malformed UUID in departments array)
401	Authentication required
403	Insufficient permissions for this client
404	User, client, or one or more department IDs not found
500	Server error

Example error -- department not found

{
  "error": {
    "code": "not_found",
    "message": "One or more departments not found",
    "details": {
      "invalid_department_ids": ["ffffffff-ffff-ffff-ffff-ffffffffffff"]
    }
  }
}

Related Endpoints

• Get User - View current user state
• List Users - Browse all users
• Add Members - Bulk-add users to a department
• Remove Members - Bulk-remove users from a department