Skip Navigation Links

User Groups

List user groups

Requires authentication via bearer.

List and search user groups with filtering, sorting, and pagination.

Filter Combination Examples:

  • status=ACTIVE: Only active groups
  • status=ARCHIVED: Only archived groups
  • parent_id={uuid}: Direct children of a specific group
  • type=CUSTOM: Only user-created groups (excludes ROOT and ALL_USERS)
  • search_term=marketing&status=ACTIVE: Active groups matching "marketing" in name, description, or external ID
  • external_id=dept-123: Find group by external system identifier

Query Params

search_term string

A term that needs to match in the user group name, description, or external ID. The search is case-insensitive and matches partial strings.

sort string[]

Sort options for user group search results:

  • GROUP_NAME_ASC/DESC: Sort by group name alphabetically
  • STATUS_ASC/DESC: Sort by group status (ACTIVE, ARCHIVED)
  • UPDATED_AT_ASC/DESC: Sort by last modification date
  • CREATED_AT_ASC/DESC: Sort by creation date
parent_candidates_for string

Filter user groups that can serve as a valid parent for the specified user group. Excludes the group itself and any of its descendants to prevent circular hierarchies.

parent_id string

Filter by parent user group ID to get direct children only. Does not include nested descendants - only immediate child groups are returned.

type string

Filter by user group type. Use CUSTOM to exclude predefined groups (ROOT, ALL_USERS).

external_id string

An arbitrary string referencing an external entity identifier.

status string

Filter user groups by status. If not specified, groups of all statuses are returned.

embed string[]

Options for embedding additional data in user group search results:

  • NUMBER_OF_CONTAINED_USERS: Include count of users directly assigned to the group
  • PATH: Include list of ancestor groups from root to immediate parent
  • ACTIONS: Include available actions (archive, edit, delete, etc.) and list-level actions (create)
page_number integer

requested page for offset based pagination. Refer to our general "pagination" concept for more information.

page_limit integer

The maximum number of items to be contained in the response array. Refer to our general "pagination" concept for more information.

Headers

Accept-Language string

The preferred language used when returning localized strings.

Response Body

200 OK

Create user group

Requires authentication via bearer.

Create a new user group and assign it to a parent group.

Important Constraints:

  • The ALL_USERS group cannot have sub-groups
  • The external_id must be unique across all user groups if provided
  • Translations are validated against the organization's enabled languages

Query Params

embed string[]

Options for embedding additional data in user group responses:

  • NUMBER_OF_CONTAINED_USERS: Include count of users directly assigned to the group
  • PATH: Include list of ancestor groups from root to immediate parent
  • ACTIONS: Include available actions (archive, edit, delete, etc.)

Headers

Accept-Language string

The preferred language used when returning localized strings.

Request Body

id string

Unique identifier of a user group.

external_id string

Unique identifier by an external system for a user group.

title object[]
description object[]
parent_id stringrequired

Unique identifier of a user group.

Response Body

201 Created

Error Codes

  • LANGUAGE_NOT_ENABLED
  • DUPLICATE_ID
  • DUPLICATE_EXTERNAL_ID
  • USER_GROUP_MUST_NOT_HAVE_SUB_GROUPS

Get user group

Requires authentication via bearer.

Returns details about a user group by its ID.

Path Params

group_id stringrequired

Unique identifier of a user group.

Query Params

embed string[]

Options for embedding additional data in user group responses:

  • NUMBER_OF_CONTAINED_USERS: Include count of users directly assigned to the group
  • PATH: Include list of ancestor groups from root to immediate parent
  • ACTIONS: Include available actions (archive, edit, delete, etc.)

Headers

Accept-Language string

The preferred language used when returning localized strings.

Response Body

200 OK

Update user group

Requires authentication via bearer.

Partially updates an existing user group using JSON Merge Patch semantics (RFC 7396).

Only fields included in the request body are updated. To remove an optional field (like external_id), set it to null. Fields not present in the request remain unchanged.

Constraints:

  • Cannot update archived groups (returns USER_GROUP_ARCHIVED error)
  • Cannot change parent to create a circular reference
  • Cannot remove the parent from non-ROOT groups
  • Predefined groups (ROOT, ALL_USERS) have limited modifiable fields

Path Params

group_id stringrequired

Unique identifier of a user group.

Query Params

embed string[]

Options for embedding additional data in user group responses:

  • NUMBER_OF_CONTAINED_USERS: Include count of users directly assigned to the group
  • PATH: Include list of ancestor groups from root to immediate parent
  • ACTIONS: Include available actions (archive, edit, delete, etc.)

Headers

Accept-Language string

The preferred language used when returning localized strings.

Request Body

title object[]
description object[]
external_id string

Unique identifier by an external system for a user group.

parent_id string

Unique identifier of a user group. Can only be null in case of the pre-defined root user group.

Response Body

200 OK

Error Codes

  • LANGUAGE_NOT_ENABLED
  • DUPLICATE_EXTERNAL_ID
  • USER_GROUP_ARCHIVED
  • USER_GROUP_MUST_NOT_HAVE_SUB_GROUPS
  • USER_GROUP_MUST_HAVE_PARENT
  • PARENT_ID_UPDATE_WOULD_PRODUCE_A_CYCLE

Delete user group

Requires authentication via bearer.

Permanently deletes a user group identified by its ID and all nested groups.

Pre-conditions:

  • The user group must be archived beforehand (use the archive endpoint first)
  • Predefined groups (ROOT, ALL_USERS) cannot be deleted

Cascade Behavior:

  • All child groups are deleted recursively
  • All user assignments (manual, rule-based, and primary) are removed
  • This action is permanent and cannot be undone

Path Params

group_id stringrequired

Unique identifier of a user group.

Response Body

200 OK

Archive user group

Requires authentication via bearer.

Archives a user group, preventing further modifications.

Side Effects:

  • All users whose primary group is this group will have their primary assignment changed to the ALL_USERS group
  • Secondary (manual) assignments remain unchanged but become read-only
  • Child groups are also archived transitively

Constraints:

  • Predefined groups (ROOT, ALL_USERS) cannot be archived
  • Once archived, the group can be restored using the restore endpoint

Path Params

group_id stringrequired

Unique identifier of a user group.

Response Body

200 OK

Error Codes

  • USER_GROUP_IS_PREDEFINED

Restore user group

Requires authentication via bearer.

Restores an archived user group, allowing modifications again.

Important Notes:

  • Primary assignments that were changed to ALL_USERS during archiving are NOT automatically restored
  • The group's parent must be active (not archived) for restoration to succeed
  • If providing a parent_id, the group will be moved to that parent upon restoration

Constraints:

  • Predefined groups (ROOT, ALL_USERS) cannot be restored (they cannot be archived)
  • Only groups in ARCHIVED status can be restored

Path Params

group_id stringrequired

Unique identifier of a user group.

Request Body

parent_id string

Unique identifier of a user group.

Response Body

200 OK

Error Codes

  • USER_GROUP_IS_PREDEFINED
  • USER_GROUP_NOT_ARCHIVED
  • USER_GROUP_REQUIRES_ACTIVE_PARENT