Complex list attributes allow you to store structured, repeatable data as a list of objects. Each item in the list can contain multiple attributes (fields), such as strings, dates, or phone numbers. This enables more advanced data models, such as storing multiple contacts, accounts, or records under a single customer.

How complex lists work

A complex list stores data as an array of objects. Each object follows the structure defined by the child attributes.

For example, a list could store multiple contact records, where each item includes:

• Name
• Email
• Phone number

Depending on your configuration, you can edit attributes in:

• My Account
• Admin Console
• Organization portal

Each item is managed individually, including validation and error handling.

Capabilities

With complex list attributes, you can:

• Store multiple entries per customer, where each entry contains multiple fields.
• Define a custom structure for list items using child attributes.
• Mix different attribute types within the same list item (for example, string, email, phone).
• Add new fields to the structure later without recreating the attribute.
• Apply validation and uniqueness rules at the field level.
• Use list data in hooks and filtering.

When to use complex lists

Use complex list attributes when:

• You need to store structured, repeatable data.
• Each entry requires multiple fields.
• The data model may evolve over time (you can add new child attributes later).

For simple arrays of single values, use Simple list attributes instead.

Sample use cases

Common use cases for complex list attributes include:

• Storing multiple contact records (for example, name, email, phone number per contact).
• Managing lists of external account identifiers or references.
• Defining structured metadata for customers.
• Supporting administrative use cases where each item requires multiple related values.

Configuration

Create a complex list attribute

To create a complex list attribute:

1. In the Admin Console, go to Identities and Identity stores in the left-hand menu.
2. Select an existing identity store and go to the Attributes tab.
3. Select Create.
4. Choose Complex list.
5. Configure the attribute (see below).
6. Save the attribute.

📘

Within the complex list attribute, the Attributes tab (where you define the structure of list items) becomes available after you complete the basic configuration and save the attribute.

General settings

Attribute path: storage path created for the attribute in the identity store.


Attribute name: name of the attribute used in the identity store and in hooks.

Enable attribute: controls whether the attribute is active.

Configuration tab

Attribute display name: label shown in the Admin Console and portals.

Self-service

Show attribute on My Account page: display the attribute in customer accounts.

Enable editing of attribute on My Account page: allow the modification of the values.

Admin Console

Show attribute in Admin Console: display the attribute in admin accounts.

Enable editing of attribute in Admin Console: allow administrators to modify values.

Organization Portal

Show attribute in Organization Portal: display the attribute in organization admin accounts.

Enable editing of attribute in Admin Console: allow organization admins to modify values.

List rules

Minimum items: minimum number of values required.

Maximum items: maximum number of values allowed. If the maximum number of items is reached, additional values cannot be added.

Attributes tab

In the Attributes tab, you can create child attributes that make up each object in the list.

Add a child attribute

1. Select Create.
2. Choose the attribute type (for example, String, Select, Phone, Date, Email, or Checkbox).
3. Configure the attribute. Each child attribute has similar settings to standard attributes, including:
   1. Enable: Controls whether the field is active.
   2. Attribute name and path: Used for storage in the identity store.
   3. Searchability: Determines whether the field can be used in filtering.
   4. Display name: Label shown in the UI.
   5. Make the attribute mandatory: Requires a value for the list item.
   6. Must be unique within the list: Ensures that each list item has a unique value for this field.

Behavior and limitations

Validation behavior

Validation is applied at the item level:

• If a single list item contains invalid data, only that item is flagged.
• Other items in the list remain unaffected.
• Errors are shown inline for the specific item that needs correction.

Search and filtering

If child attributes are marked as searchable, they can be used in account filtering.

List attributes appear under Attributes in account filters when searchability is enabled.

Uniqueness

Complex lists support multiple levels of uniqueness:

• Identity store uniqueness (standard setting): prevents the same value from appearing across different accounts.
• Unique within the list: ensures that a value appears only once within a single list.

These settings can be combined to enforce stricter constraints.

Integration with hooks

Complex list attributes are available in hooks as part of the customer object.

This allows you to:

• Evaluate list data in flows
• Apply custom logic based on list values
• Influence journey behavior dynamically