# Customize user schema

Important
Support for Custom user schema is currently **available only to B2C tenants with early access** to this capability. Full availability is planned for a later stage.

If custom attributes are not reflected in API or journey behavior, contact your Transmit Security representative to verify whether this feature is enabled for your tenant.

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)


![Adding custom attributes example](/assets/custom_attribute_example.19111a5d9c744d19237c44903da9578cda9646d1af2a92f73a3528b0a970c334.2397ab79.gif)

### Attribute types

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

div
| Type | Limit |
|  --- | --- |
| String | Up to 512 characters |
| Number | 64-bit float |
| Digits only | Numeric values (0123456789) |
| Date | ISO 8601 format |
| Email | Valid email structure |
| Phone | Valid international phone format |
| JSON | Maximum size: 10 KB |
| Boolean | True or false |
| Array | Any supported type |


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:

```json
{
  "consentPreferences": {
    "analytics": "yes",
    "marketing": "no",
    "functional": "yes"
  }
}
```
* An `Array` can include elements of any supported type, such as strings, numbers, dates, or JSON objects:

```json
[
  {
    "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 **7 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](/guides/user/manage_users/#view-or-search-users). 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 (although custom identifiers are indexed, they don't count towards this quota). JSON and array attributes cannot be indexed.


Note
These properties are disabled by default, and once enabled they are not applied retroactively. If you enable or change them after the schema is already in use, the configuration only affects new user records created from that point forward.

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

| Type | Identifier | Default value | Indexed |
|  --- | --- | --- | --- |
| String | ✔ | ✔ | ✔ |
| Number | ✖ | ✔ | ✔ |
| Digits only | ✔ | ✔ | ✔ |
| Date | ✖ | ✔ | ✔ |
| Boolean | ✖ | ✔ | ✔ |
| Email | ✔ | ✖ | ✔ |
| Phone | ✔ | ✖ | ✔ |
| JSON | ✖ | ✖ | ✖ |
| Array | ✖ | ✖ | ✖ |


## 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 ![](/assets/action_icon.1ecac3af0cbb5a99cfdd0e9a3a7067f9df88a26acab052d3eced16c35ad4626a.9c1bb791.svg), 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 ![](/assets/action_icon.1ecac3af0cbb5a99cfdd0e9a3a7067f9df88a26acab052d3eced16c35ad4626a.9c1bb791.svg), and then **Set as leading identifier**.
- **Deleting**: Remove an attribute by selecting it in **Edit schema** and clicking ![](/assets/action_icon.1ecac3af0cbb5a99cfdd0e9a3a7067f9df88a26acab052d3eced16c35ad4626a.9c1bb791.svg), 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](/guides/orchestration/journeys/create_user) or [Update user](/guides/orchestration/journeys/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`).