Skip Navigation Links

User Attribute Definitions

List user attribute definitions

Requires authentication via bearer.

Returns all user attribute definitions for the organization, including both predefined system attributes (e.g., department, job title, location) and custom attributes.

The result is not paginated — all definitions are returned in a single response. Attribute titles are localized based on the Accept-Language header using best-match selection.

Headers

Accept-Language string

The preferred language used when returning localized strings.

Response Body

200 OK

Create user attribute definition

Requires authentication via bearer.

Creates a new custom user attribute definition in the organization.

Constraints:

  • A maximum of 50 attribute definitions (predefined + custom) is supported per organization
  • The technical_name must be unique within the organization
  • All languages provided in title must be enabled for the organization
  • If attribute_type is omitted, it defaults to TEXT

Note: Predefined attributes (department, job title, etc.) are managed by the system and cannot be created via this endpoint.

Request Body

title object[]
technical_name stringrequired

The technical name of the attribute. This is the attribute name that will be accepted and returned by API calls. Required to be unique. Must only contain alphanumeric characters and the characters -, _, .

user_permission stringrequired

The access level of the attribute. This determines if the attribute is visible to end users and whether they can edit it for themselves. "HIDDEN" attributes are only returned in User Admin APIs and User Self APIs, i.e. they can only be accessed by admins and the user themselves.

attribute_type string

The type of the attribute, which affects display and validation of user attribute values:

  • TEXT: General-purpose text attribute. No format validation.
  • PHONE_NUMBER: Displayed as a phone number (e.g., with click-to-call). No format validation.
  • DATE: Date attribute. Values must be in yyyy-MM-dd format (e.g., 2025-03-15). Empty values are allowed.

Response Body

201 Created

Error Codes

  • DUPLICATE_TECHNICAL_NAME
  • LANGUAGE_NOT_ENABLED
  • TOO_MANY_ATTRIBUTE_DEFINITIONS

Get user attribute definition

Requires authentication via bearer.

Returns a single user attribute definition by its ID, including localized titles and available actions for the requesting admin.

Path Params

definition_id stringrequired

The unique identifier (UUID) of the user attribute definition.

Response Body

200 OK

Update user attribute definition

Requires authentication via bearer.

Partially updates a user attribute definition using JSON Merge Patch semantics (RFC 7396).

Only fields included in the request body are updated. Fields not present in the request remain unchanged.

Updatable fields by attribute type:

  • Custom attributes: title, user_permission
  • Predefined attributes: title, use_custom_translation

Constraints:

  • The department attribute's user_permission cannot be set to HIDDEN
  • All languages provided in title must be enabled for the organization
  • If use_custom_translation is set to true on a predefined attribute, a non-empty title must be provided

Path Params

definition_id stringrequired

The unique identifier (UUID) of the user attribute definition.

Request Body

title object[]
user_permission string

The access level of the attribute. This determines if the attribute is visible to end users and whether they can edit it for themselves. "HIDDEN" attributes are only returned in User Admin APIs and User Self APIs, i.e. they can only be accessed by admins and the user themselves.

use_custom_translation boolean

Can only be set on attributes that are predefined. If true, uses the user-provided translations for the attribute title. If false, uses the default Flip translations and clears any custom ones that might have been stored previously.

Response Body

200 OK

Error Codes

  • DEPARTMENT_ATTRIBUTE_CANNOT_BE_HIDDEN
  • LANGUAGE_NOT_ENABLED

Delete user attribute definition

Requires authentication via bearer.

Permanently deletes a custom user attribute definition and all associated user attribute values.

Constraints:

  • Predefined attributes (e.g., department, job title) cannot be deleted
  • Attributes that are referenced by user group assignment rules cannot be deleted until the rules are removed or adapted

Side Effects:

  • All user attribute values associated with this definition are permanently deleted

Path Params

definition_id stringrequired

The unique identifier (UUID) of the user attribute definition.

Response Body

204 No Content

Error Codes

  • CAN_NOT_DELETE_PREDEFINED_USER_ATTRIBUTE
  • USER_ATTRIBUTE_IN_USE_BY_RULES