Skip Navigation Links

User Groups

List user groups

Requires authentication via bearer.

List and search user groups.

Query Params

search_term string

A term that needs to match in the user group name, description or external id.

sort string[]
parent_candidates_for string

Filter user groups applicable as parent for given user group.

parent_id string

Filter user groups by given parent user group id. Can be used to get all child user groups of the given user group.

type string

Filter by user group type

external_id string

An arbitrary string referencing an external entity identifier.

status string

Filter user groups by user groups status

embed string[]
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.

Query Params

embed string[]

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.

Allows an admin user to get details about a user group by its ID.

Path Params

group_id stringrequired

Unique identifier of a user group.

Query Params

embed string[]

Headers

Accept-Language string

The preferred language used when returning localized strings.

Response Body

200 OK

Update user group

Requires authentication via bearer.

Allows an admin user to (partially) update a user group.

Path Params

group_id stringrequired

Unique identifier of a user group.

Query Params

embed string[]

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.

Allows an admin user to delete a user group identified by its ID and all nested groups as well. The user group to be deleted must be archived beforehand, else the deletion will fail. Pre-defined user groups cannot be deleted.

Path Params

group_id stringrequired

Unique identifier of a user group.

Response Body

200 OK

Archive user group

Requires authentication via bearer.

Allows an admin user to archive a user group. An archived group cannot be modified. On archiving a group all primary assignments of users in this group are changed to the All_USERS user group. Secondary assignments will not be changed.

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.

Allows an admin user to restore a user group. An restored group can be modified again. Primary assignments that were changed on archiving will not 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