Customize user schema

In Mosaic, each user record includes a set of built-in attributes, such as name, birthday, and phone. To support more granular business needs, you can extend the user profile by defining custom attributes.

Using the User attributes configuration in the Admin Portal (B2C Identity > Users > Edit Schema), tenant administrators can add custom attributes and identifiers to the user profile in addition to the built-in ones. These attributes become part of the user record and are available during creation, update, and retrieval operations across the tenant. They can be used throughout user management flows and accessed via platform APIs and journeys.

For example, you can use custom attributes to support:

• Store and manage user preferences related to privacy and tracking:

  • cookieConsent (Boolean or String)
  • dataSharingConsentVersion (String or Number)
  • privacyNoticeAcceptedAt (Date)
  • marketingOptIn (Boolean) These fields can help enforce compliance with privacy regulations like GDPR or CCPA.

• Capture user profile extensions relevant to shopping behavior or loyalty programs:

  • loyaltyTier (String — e.g., "Gold", "Silver", "Basic")
  • preferredStoreLocation (String)
  • membershipType (String — e.g., "Premium", "Standard")
  • discountEligibility (Boolean)
  • wishlistCategories (Array of Strings) These attributes can be used to personalize the user experience, enable segmentation, and support targeted promotions.

• Leverage custom identifiers in your identity flows:

  • ssn (String)
  • nationalId (string)
  • accountNumber (digits only)

Custom attributes definition

To define custom attributes, navigate to B2C Identity > Users > Edit Schema in the Admin Portal.

Each tenant can define up to 50 custom attributes. For each attribute, you’ll set:

• Attribute name (used in APIs and journeys) and display name
• Attribute type
• Attribute configuration (e.g., default value, identifier)

Attribute types

The following data types are supported for custom attributes. They must comply with the following size and structure constraints:

When using complex types such as JSON or arrays, follow these structural rules:

• A JSON object can contain nested key-value pairs and embedded objects; JSON objects support up to 2-level depth:

  {
    "consentPreferences": {
      "analytics": "yes",
      "marketing": "no",
      "functional": "yes"
    }
  }

• An Array can include elements of any supported type, such as strings, numbers, dates, or JSON objects:

  [
    {
      "program": "Gold Membership",
      "status": "active",
      "joinedAt": "2023-04-12"
    },
    {
      "program": "Referral Program",
      "status": "pending",
      "joinedAt": "2024-01-20"
    }
  ]

Attribute configuration

Each custom attribute can be configured with the following properties:

• Identifier: When enabled, adds tenant-wide requirement for uniqueness and allows using the attribute as an identifier in the authentication flows. A maximum of 5 custom identifiers is allowed per tenant. Note that only string, digits only, phone, and email attributes can be set as identifiers. Once the attribute is saved, this setting cannot be changed.

• Default value: Sets a default value for the attribute, which remains until changed in the application. Email, phone, JSON and array attributes as well as any attribute marked as identifier cannot have default values.

• Indexed: When enabled, makes the attribute searchable in the Admin Portal user search. This setting can only be configured when the attribute is created and cannot be changed later. A maximum of 5 indexed attributes is allowed per tenant (identifiers are always indexed and count towards this quota). JSON and array attributes cannot be indexed.

The following matrix summarizes which configuration options are supported per attribute type.

Managing custom attributes

You can add, modify, or remove custom attributes at any time.

• Creating: Once created, custom attributes are propagated to the user schema and become available to all new users. Existing user records aren't modified unless you explicitly update a user and provide a value for the newly created attribute.

• Modifying: Edit an attribute by selecting it in Edit schema and clicking , and then Edit.

  • Mosaic allows updating the attribute's display name and adding a default value (if applicable). Adding or updating a default value for an attribute doesn't affect existing user records.

  • An identifier attribute can be promoted to a leading identifier–an identifier that is displayed first in the Users list. This is done by clicking , and then Set as leading identifier.

• Deleting: Remove an attribute by selecting it in Edit schema and clicking , and then Delete.

  • Mosaic allows deleting custom attributes. If an attribute is currently in use (i.e., it contains stored values for users), deleting it will permanently erase all associated data. This action is irreversible. If using API, passing a value for a deleted attribute won't fail the call. Journeys won't fail either but you are advised to update the step configuration to avoid using a deleted attribute.

  • Custom identifiers cannot be removed via Admin Portal. Contact Transmit Security support to resolve such cases.

Accessing custom attributes

Custom attributes are available via Admin Portal, APIs and journeys:

• Admin Portal: Custom attributes are available in the user profile in the Custom attributes section.
• APIs: Custom attributes (specified by attribute name) are available inside the custom_user_fields object within the user record.
• Journeys: In steps updating user records (e.g., Create user or Update user), custom attributes (specified by name) are defined within the Custom attributes group; while custom attributes set as identifiers are defined inside the Identifiers group. In output variables, custom attributes are returned inside the custom_user_fields object within the user record (e.g., update_user_output.result.custom_user_fields.preferredStoreLocation).