Update a person on a client

Required scopes: people:read, plus people:write for follow and notifications, or case-roles:write for roles.

Changes one member's participation on a client. Send exactly one command:

  • follow: follow or unfollow the client. Requires people:write.
  • notifications: set the email notification types the member receives for this client, using values from List notification types. The member must already follow the client manually. Requires people:write.
  • roles: add, remove or set_primary case roles, using IDs from List case roles. Requires case-roles:write. View-only members cannot hold case roles, and Restricted members must already follow the client.

Every command also requires people:read, because the response returns the person. Send If-Match with the ETag from your latest Get a person on a client response. A missing If-Match returns 428; a stale one returns 412, in which case read again and retry. Requires an Idempotency-Key. Retrying with the same key and body within 24 hours returns the original result without repeating the action.

Confirming side effects. Unfollowing, replacing a role holder, changing a primary holder and overriding automatic assignments return 409 effects_confirmation_required with an error.effects object describing what will change. Review it, then resend the same command with that exact object as confirm_effects and the same If-Match. If something changed in the meantime, read the person again and review the new effects.

Manual follows only. Follow and notification commands manage manual follows. If the member follows the client through an automatic rule, they return 409 source_managed and change nothing. Removing a manual follow also removes the member's manual case role holdings and promotes the longest-standing remaining holder; automatic rules may follow the member again later. Some decision-outcome notification types can be kept but not newly added through the API (422). A busy client returns a retryable 503.

PATCH /api/v2/clients/{id}/people/{userId}
Bearer token scope people:read

Path parameters

· 2
id string required

Client ID.

userId string · uuid required

Member ID, from List account members.

Headers

· 2
Idempotency-Key string · min length: 1· max length: 128 · pattern required

Unique key for this operation, 1 to 128 visible ASCII characters (for example a UUID). Reuse it only when retrying the same request.

If-Match string required

The ETag from your latest read of this resource.

Body

· PeopleCommand
required application/json

Responses