Users

status=ACTIVE: Only active users
status=ACTIVE,LOCKED: Active and locked users
status=PENDING_DELETION: Users within 14-day deletion grace period
attribute_technical_name=department&attribute_value=Sales: Users in Sales department
search_term=mueller&status=ACTIVE: Active users matching "mueller"

Default Behavior:

If no status filter is provided, all statuses are included
Results are paginated (default page size: 25, max: 100)

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

Filter users by a specific user attribute. Must be used together with attribute_value.

The technical name identifies the attribute definition (e.g., department, cost_center). Use the user attribute definitions API to discover available attribute names in your organization.

attribute_value string

Filter users by the value of a specific attribute. Must be used together with attribute_technical_name.

Only exact match is supported.

status string[]

The current status of a user account, determining their access and lifecycle state:

ACTIVE: User can log in and access the platform normally. This is the default operational state.
LOCKED: User is temporarily suspended and cannot log in. Intended for short-term suspension (e.g., security concerns, temporary leave). Use unlock endpoint to restore access.
DEACTIVATED: User is deactivated for long-term suspension. Intended for when employees leave the organization. Use restore or unlock endpoint to reactivate. Requires deactivation feature to be enabled.
PENDING_DELETION: User is marked for permanent deletion and enters a 14-day grace period. Use restore endpoint within 14 days to cancel deletion. After grace period, user is permanently deleted.

sort string[]

Sort options for user search results. Each option has ascending (_ASC) and descending (_DESC) variants:

FIRST_NAME: Sort by user's first name alphabetically
LAST_NAME: Sort by user's last name alphabetically
USERNAME: Sort by username alphabetically
EMAIL: Sort by email address alphabetically
DEPARTMENT: Sort by department name alphabetically
LOCATION: Sort by location name alphabetically
ROLE: Sort by system role (ADMIN, USER, etc.)
STATUS: Sort by user status (ACTIVE, LOCKED, etc.)
UPDATED_AT: Sort by last modification date
CREATED_AT: Sort by account creation date
LOGIN_STATUS: Sort by login status (has logged in, never logged in)

external_id string

An arbitrary string referencing an external entity identifier.

embed string[]

Options for embedding additional data in user list responses:

ACTIONS: Include available actions for each user (edit, delete, lock, etc.) and list-level actions (create)

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.

Creates a new user in the organization.

The user's initial status can be set to ACTIVE, LOCKED, or INACTIVE. Setting status to PENDING_DELETION is not allowed and will result in an error.

Query Params

embed string[]

Options for embedding additional data in single user responses:

ACTIONS: Include available actions for the user (edit, delete, lock, unlock, etc.)
USER_ATTRIBUTE_DEFINITIONS: Include metadata about user attributes (type, constraints, validation rules)

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 current status of a user account, determining their access and lifecycle state:

ACTIVE: User can log in and access the platform normally. This is the default operational state.
LOCKED: User is temporarily suspended and cannot log in. Intended for short-term suspension (e.g., security concerns, temporary leave). Use unlock endpoint to restore access.
DEACTIVATED: User is deactivated for long-term suspension. Intended for when employees leave the organization. Use restore or unlock endpoint to reactivate. Requires deactivation feature to be enabled.
PENDING_DELETION: User is marked for permanent deletion and enters a 14-day grace period. Use restore endpoint within 14 days to cancel deletion. After grace period, user is permanently deleted.

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
USER_CREATION_WITH_PENDING_DELETION_NOT_ALLOWED
NO_USER_ATTRIBUTE_DEFINITION_FOR_NAME_FOUND

Update multiple users

Requires authentication via bearer.

Allows to (partially) update multiple users at once using JSON Merge Patch semantics.

Batch Semantics:

Operations are non-atomic: each user is processed independently
Partial success is possible - some users may be updated while others fail
Maximum 100 users per request
Each result contains a status code (200=success, 4xx=failure with error details)
Successfully updated users are returned in the body field of each result

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. Each user is marked for deletion and enters a 14-day grace period before permanent removal. See delete-user operation for further details.

Batch Semantics:

Operations are non-atomic: each user is processed independently
Partial success is possible - some users may be deleted while others fail
Maximum 100 users per request
Each result contains a status code (200=success, 4xx=failure with error details)

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. See unlock-user operation for further details.

Batch Semantics:

Operations are non-atomic: each user is processed independently
Partial success is possible - some users may be restored while others fail
Maximum 100 users per request
Each result contains a status code (200=success, 4xx=failure with error details)

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[]

Options for embedding additional data in single user responses:

ACTIONS: Include available actions for the user (edit, delete, lock, unlock, etc.)
USER_ATTRIBUTE_DEFINITIONS: Include metadata about user attributes (type, constraints, validation rules)

Headers

Accept-Language string

The preferred language used when returning localized strings.

Response Body

200 OK

Update user

Requires authentication via bearer.

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

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

Note: The user's status cannot be changed via this endpoint. Use the dedicated lock, unlock, deactivate, or restore endpoints to change user status.

Path Params

user_id stringrequired

Unique identifier of a user.

Query Params

embed string[]

Options for embedding additional data in single user responses:

ACTIONS: Include available actions for the user (edit, delete, lock, unlock, etc.)
USER_ATTRIBUTE_DEFINITIONS: Include metadata about user attributes (type, constraints, validation rules)

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[]

Actions that can be requested from a user via email or required on next login:

ACCEPT_TERMS_AND_CONDITIONS: User must accept the organization's updated terms and conditions
UPDATE_PASSWORD: User must set a new password (e.g., after admin reset or policy change)
VERIFY_EMAIL: User must verify their email address by clicking a confirmation link

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
INVALID_DATE_ATTRIBUTE_FORMAT

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.

Deactivates a user, preventing them from logging in.

Unlike locking, deactivation is intended for longer-term or permanent disabling of a user account (e.g., when an employee leaves the organization). A deactivated user can be reactivated by an admin using the restore endpoint.

Deactivation differs from deletion in that the user's data is preserved and the account can be restored without the 14-day deletion window.

Path Params

user_id stringrequired

Unique identifier of a user.

Query Params

embed string[]

Options for embedding additional data in single user responses:

ACTIONS: Include available actions for the user (edit, delete, lock, unlock, etc.)
USER_ATTRIBUTE_DEFINITIONS: Include metadata about user attributes (type, constraints, validation rules)

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

Lock user

Requires authentication via bearer.

Temporarily locks a user account, preventing them from logging in or obtaining new access tokens.

Locking is intended for short-term account suspension (e.g., security concerns, temporary leave). The user cannot authenticate or access the application until unlocked. The locked status is not exposed within the app (e.g. employee directory).

Use the unlock endpoint to restore the user's ability to log in. For longer-term or permanent account disabling, consider using the deactivate endpoint instead.

Path Params

user_id stringrequired

Unique identifier of a user.

Query Params

embed string[]

Options for embedding additional data in single user responses:

ACTIONS: Include available actions for the user (edit, delete, lock, unlock, etc.)
USER_ATTRIBUTE_DEFINITIONS: Include metadata about user attributes (type, constraints, validation rules)

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.

Restores a user that was previously deactivated or marked for deletion.

Once restored, the user's status is set to ACTIVE and all their data is preserved.

Users marked for deletion enter a 14-day grace period during which they can be restored. After the 14-day grace period, a user marked for deletion is permanently deleted and cannot be restored. Deactivated users can be restored indefinitely.

Path Params

user_id stringrequired

Unique identifier of a user.

Query Params

embed string[]

Options for embedding additional data in single user responses:

ACTIONS: Include available actions for the user (edit, delete, lock, unlock, etc.)
USER_ATTRIBUTE_DEFINITIONS: Include metadata about user attributes (type, constraints, validation rules)

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.

Unlocks a previously locked user, allowing them to log in again.

Note: For users in PENDING_DELETION status, use the restore endpoint instead.

Path Params

user_id stringrequired

Unique identifier of a user.

Query Params

embed string[]

Options for embedding additional data in single user responses:

ACTIONS: Include available actions for the user (edit, delete, lock, unlock, etc.)
USER_ATTRIBUTE_DEFINITIONS: Include metadata about user attributes (type, constraints, validation rules)

Headers

Accept-Language string

The preferred language used when returning localized strings.

Response Body

200 OK

Error Codes

USER_MODIFICATION_NOT_ALLOWED