Skip Navigation Links

Users

Endpoint Overview

GET /api/admin/users/v4/users
List users
POST /api/admin/users/v4/users
Create user
PATCH /api/admin/users/v4/users/batch
Update multiple users
DELETE /api/admin/users/v4/users/batch
Delete multiple users
POST /api/admin/users/v4/users/restore/batch
Restore multiple users
GET /api/admin/users/v4/users/{user_id}
Get user
PATCH /api/admin/users/v4/users/{user_id}
Update user
DELETE /api/admin/users/v4/users/{user_id}
Delete user
POST /api/admin/users/v4/users/{user_id}/deactivate
Deactivate user
POST /api/admin/users/v4/users/{user_id}/lock
Lock user
POST /api/admin/users/v4/users/{user_id}/restore
Restore user
POST /api/admin/users/v4/users/{user_id}/unlock
Unlock User

List users

Requires authentication via bearer.

Allows to search users filtered by a search term and status and sort the resulting list by various user attributes.

Query Params

search_term string

A term that needs a match in the user's first name, last name, username, email, department or location.

username string

Filter for exact username match.

attribute_technical_name string

Can be used in combination with attribute_value to filter users by a specific attribute. You need to provide both parameters or none of them.

attribute_value string

Can be used in combination with attribute_technical_name to filter users by a specific attribute. You need to provide both parameters or none of them. Only exact match is supported.

status string[]

The status of a user account:

  • ACTIVE: User is active and can log in
  • LOCKED: User account is temporarily locked
  • PENDING_DELETION: User is marked for deletion
  • DEACTIVATED: User account is deactivated
sort string[]
external_id string

An arbitrary string referencing an external entity identifier.

embed string[]
page_limit integer

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

page_number integer

requested page for offset based pagination. 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

Requires authentication via bearer.

Allows to create a new user.

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.

external_id string
first_name stringrequired
last_name stringrequired
email string
status stringrequired

The status of a user account:

  • ACTIVE: User is active and can log in
  • LOCKED: User account is temporarily locked
  • PENDING_DELETION: User is marked for deletion
  • DEACTIVATED: User account is deactivated
username stringrequired
role stringrequired
primary_user_group_id string

Unique identifier of a user group.

attributes object[]
profile_picture object
tags object[]

Response Body

200 OK
201 Created

Error Codes

  • USER_ID_ALREADY_EXISTS
  • USERNAME_ALREADY_EXISTS
  • EXTERNAL_ID_ALREADY_EXISTS
  • NO_USER_ATTRIBUTE_DEFINITION_FOR_NAME_FOUND

Update multiple users

Requires authentication via bearer.

Allows to (partially) update multiple users at once.

Headers

Accept-Language string

The preferred language used when returning localized strings.

Request Body

items object[]

Response Body

200 OK

Delete multiple users

Requires authentication via bearer.

Allows to delete multiple users at once.

Headers

Accept-Language string

The preferred language used when returning localized strings.

Request Body

items object[]

Response Body

200 OK

Restore multiple users

Requires authentication via bearer.

Allows to restore multiple users at once.

Headers

Accept-Language string

The preferred language used when returning localized strings.

Request Body

items object[]

Response Body

200 OK

Error Codes

  • USER_NOT_RESTORABLE
  • USER_MODIFICATION_NOT_ALLOWED

Get user

Requires authentication via bearer.

Allows to get details about a user by its ID.

Path Params

user_id stringrequired

Unique identifier of a user.

Query Params

embed string[]

Headers

Accept-Language string

The preferred language used when returning localized strings.

Response Body

200 OK

Update user

Requires authentication via bearer.

Allows to (partially) update a user.

Path Params

user_id stringrequired

Unique identifier of a user.

Query Params

embed string[]

Headers

Accept-Language string

The preferred language used when returning localized strings.

Request Body

external_id string
first_name string
last_name string
email string
username string
role string
required_actions string[]
primary_user_group_id string

Unique identifier of a user group.

attributes object[]
profile_picture object
tags object[]

Response Body

200 OK

Error Codes

  • USERNAME_ALREADY_EXISTS
  • EXTERNAL_ID_ALREADY_EXISTS
  • USER_MODIFICATION_NOT_ALLOWED
  • NO_USER_ATTRIBUTE_DEFINITION_FOR_NAME_FOUND
  • MAX_LENGTH_EXCEEDED

Delete user

Requires authentication via bearer.

Marks a user for deletion by their ID. The user can be restored within 14 days, otherwise they will be permanently deleted.

Path Params

user_id stringrequired

Unique identifier of a user.

Response Body

200 OK

Error Codes

  • USER_MODIFICATION_NOT_ALLOWED
  • ACTOR_MUST_NOT_CHANGE_ITSELF

Deactivate user

Requires authentication via bearer.

Allows to deactivate a user identified by its ID. A deactivated user cannot log-in anymore.

Path Params

user_id stringrequired

Unique identifier of a user.

Query Params

embed string[]

Headers

Accept-Language string

The preferred language used when returning localized strings.

Response Body

200 OK

Error Codes

  • USER_MODIFICATION_NOT_ALLOWED
  • ACTOR_MUST_NOT_CHANGE_ITSELF
  • FEATURE_NOT_ENABLED

Lock user

Requires authentication via bearer.

Allows to lock a user identified by its ID. A locked user cannot log-in anymore or get refresh tokens.

Path Params

user_id stringrequired

Unique identifier of a user.

Query Params

embed string[]

Headers

Accept-Language string

The preferred language used when returning localized strings.

Response Body

200 OK

Error Codes

  • USER_MODIFICATION_NOT_ALLOWED
  • ACTOR_MUST_NOT_CHANGE_ITSELF

Restore user

Requires authentication via bearer.

Allows to restore a user that was marked for deletion.

Path Params

user_id stringrequired

Unique identifier of a user.

Query Params

embed string[]

Headers

Accept-Language string

The preferred language used when returning localized strings.

Response Body

200 OK

Error Codes

  • USER_NOT_RESTORABLE
  • USER_MODIFICATION_NOT_ALLOWED

Unlock User

Requires authentication via bearer.

Allows to unlock a user identified by its ID. A previously locked user can log-in again once unlocked.

Path Params

user_id stringrequired

Unique identifier of a user.

Query Params

embed string[]

Headers

Accept-Language string

The preferred language used when returning localized strings.

Response Body

200 OK

Error Codes

  • USER_MODIFICATION_NOT_ALLOWED