Skip to main content

Update User

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

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

Path Parameters​

ParameterTypeDescription
client_idstring (uuid)Unique identifier for the client organization
user_idstring (uuid)Unique identifier for the user

Request Body​

FieldTypeDescription
departmentsstring[]Array of department IDs to assign to this user. Replaces the entire departments array -- omitted departments are removed.
statusstringNew status: active, archived, deleted.

Both fields are optional -- callers can update departments, status, or both in a single request.

Fields Not Updatable via API​

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

FieldReason
idImmutable identifier
usernameSystem-managed, synced from agent
user_keyIdentity field, system-managed
last_activity.*Written by the activity pipeline
created_atImmutable 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": []
  }'

Archive a user​

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 '{
    "status": "archived"
  }'

Update departments and status together​

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"],
    "status": "active"
  }'

Example Response​

{
  "id": "a1d97031-04e2-4907-a249-093f7436207b",
  "username": "mikechang",
  "user_key": "mikechang",
  "status": "active",
  "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.

ScenarioRequestResult
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, Remove Members, and Replace Members endpoints in the Departments domain.

If the request body is omitted or empty ({}), no fields are changed and the current user state is returned.

Error Responses​

StatusDescription
400Invalid request body (e.g. malformed UUID or invalid status enum value)
401Authentication required
403Insufficient permissions for this client
404User, client, or one or more department IDs not found
500Server 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"]
    }
  }
}

Example error -- invalid status value​

{
  "error": {
    "code": "bad_request",
    "message": "Validation failed",
    "details": {
      "messages": [
        "status must be one of the following values: active, archived, deleted"
      ]
    }
  }
}