---
title: "User Attributes"
slug: "user-attributes"
tags: ["Custom Fields", "User Data Management", "Onboarding Flow"]
updated: 2026-08-06T13:20:48Z
published: 2026-08-06T13:20:48Z
canonical: "docs.thrivelearning.com/user-attributes"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thrivelearning.com/llms.txt
> Use this file to discover all available pages before exploring further.

# User Attributes

**User Attributes** gives admins full control over user data by allowing you to create and manage custom fields beyond standard profile information. You can create a range of field types – including free text, checkboxes, and email – and set granular visibility and editing permissions for each. Custom fields can also be added as steps in the onboarding flow, either as mandatory or skippable.

## Default Fields

The **Default fields** tab lists every built-in field on the user profile. Each field has two independent toggles:

- **Show in creation flow**: Controls whether the field appears on the **Create new user** form in [**Manage** > **Users**](/v1/docs/users-1).
- **Required**: Enforces the field whenever a user is created or updated – not just through the manual **Create new user** flow, but also by API-based provisioning and SCIM.

> [!NOTE]
> Note:
> 
> For details on how Required fields behave during creation and editing, see [How Required Fields Behave](/v1/docs/user-attributes#how-required-fields-behave).

### Configuring a Default Field

1. On the Thrive menu, go to **Configure** > **User Attributes**.
2. On the **Default fields** tab, find the field you want to configure.
3. Toggle **Show in creation flow** and **Required** as needed.

Changes take effect immediately across all creation surfaces – no republish is needed.

## Custom Fields

Custom fields let you capture information beyond the built-in profile fields, tailored to your organisation's needs – such as department, employee ID, or region. You can create a range of field types, including free text and checkboxes, and configure visibility, editing, and requirement rules for each.

### Creating Custom Fields

1. On the Thrive menu, go to **Configure** > **User Attributes** and click the **Custom fields** tab. ![Custom fields settings with options for required, export, visibility, and edit permissions.](https://cdn.document360.io/3a0609fb-d96c-4ce1-aabe-d9338fb1e858/Images/Documentation/image(859).png?sv=2026-02-06&spr=https&st=2026-11-05T16%3A38%3A18Z&se=2026-11-05T17%3A38%3A18Z&sr=c&sp=r&sig=p4sQqUMQNYsdcB0SXiv3tfbf9MMjZT7WKhgdVzp5EQM%3D)
2. Click **+ Create custom field**. ![Instructions for creating custom fields manually or via CSV file upload.](https://cdn.document360.io/3a0609fb-d96c-4ce1-aabe-d9338fb1e858/Images/Documentation/image(860).png?sv=2026-02-06&spr=https&st=2026-11-05T16%3A38%3A18Z&se=2026-11-05T17%3A38%3A18Z&sr=c&sp=r&sig=p4sQqUMQNYsdcB0SXiv3tfbf9MMjZT7WKhgdVzp5EQM%3D)
3. Choose if you want to manually create individual custom fields or bulk upload multiple custom fields using a CSV file.
4. Select your custom field type and click **Next**: ![Options for selecting custom field types in a form, including free text and checkboxes.](https://cdn.document360.io/3a0609fb-d96c-4ce1-aabe-d9338fb1e858/Images/Documentation/image(861).png?sv=2026-02-06&spr=https&st=2026-11-05T16%3A38%3A18Z&se=2026-11-05T17%3A38%3A18Z&sr=c&sp=r&sig=p4sQqUMQNYsdcB0SXiv3tfbf9MMjZT7WKhgdVzp5EQM%3D)
  - **Free text**: Users can enter any response using regular text, such as a country or job role.
  - **Checkbox**: Users can select a specific choice, such as agreeing to terms.
  - **Email**: Users can enter and optionally verify secondary email addresses.
5. On the **Configure […] custom field** screen:
  1. Enter a **Name** and **Ref** for your field, and an optional **Description** to guide learners.
  2. Set any options specific to your field type:
    - **Free text**: You can optionally enter a default value that appears automatically for this field.
    - **Checkbox**: You can optionally **Add link to checkbox** by entering **Link text** and a **Link URL** (e.g., for a privacy policy).
    - **Email**: You can optionally enable **Verify**, so users must confirm the email belongs to them, and **Unique**, so the email address can only be used once across the organisation for this field.
  3. Enable the following display and permission toggles as necessary:
    - **Show this field on the user’s profile**: Controls if the field is visible to the user.
    - **Allow user to update their answer**: Determines if the user can edit this detail themselves.
    - **Include custom field in exports**: Controls if this data is included in admin reports.
  4. Click **Next**.
6. If necessary, use the **Translate custom field values** screen to select a **Language** and provide translated text for the field name and description.
7. Click **Save custom field**.

The new field will now appear in your **User Attributes** table, where you can see its **Field Type**, visibility, and **Source** (**Manual** or **CSV file**). To manage existing fields, click **⋮ Actions** to **Edit** or **Delete**.

> [!NOTE]
> Note:
> 
> You can use your custom attributes to capture data from users during their first login by adding them to onboarding steps. For more information, see [Onboarding](/v1/docs/onboarding).

## Bulk Uploading Custom Fields

1. On the Thrive menu, go to **Configure** > **User Attributes**.
2. Click **+ Create custom field**.
3. Select **Bulk create Custom Fields via CSV file**, then click **Next**.
4. On the **Bulk upload custom field values** screen, upload your CSV. The maximum file size is 50 MB.

Thrive checks the file automatically – confirming it has the required fields, no missing data, the correct data format, and no duplicates.
5. When the checks pass, click **Next: Review custom fields**.
6. On the **Review custom field values** screen:
  1. Enter a **Custom field group display name**.
  2. For each field in the table, set the **Include in export**, **Show on profile**, and **User can edit** toggles as needed.
  3. Click **Next**.
7. (Optional) On the **Translate custom field values** screen, select a **Language** and translate the group and field names.
8. Click **Save custom fields**.

The published group appears as a single expandable row in your **User Attributes** table. Click the arrow to view the linked fields within it. Once published, you can add the fields to custom onboarding steps or show them on user profiles as needed.

## How Required Fields Behave

Marking a field as **Required** affects creation and editing differently, and behaves differently depending on the surface used.

- **Creating a user:** Required fields must be populated on every surface – UI, API, and SCIM – with one exception. Self-registration flows are fully controlled by the admin, who decides which fields are shown and required during sign-up.
- **Editing an existing user via the UI:** Saving any change requires all required fields to be populated first. If a required field is still empty on an existing user, a UI edit will force it to be filled in.
- **Editing an existing user via API, SCIM, or other provisioning:** These edits can go through without populating a required field, as long as it's currently empty. This is only possible for users created before the field became required.
- **Once populated, always populated:** Whether a required field's value was added through the UI or an external service, no surface can clear it back to empty.

## **CSV File Requirements**

Before you upload, make sure your CSV meets the requirements below. Thrive checks the file automatically and rejects anything that doesn't match.

| Requirement | Details |
| --- | --- |
| File format | Save as a real CSV. Files saved as .xlsx, .xls, .ods, or .numbers are rejected, even if renamed to .csv. |
| Structure | Organise the file into groups. Each group becomes a single custom field and needs an ID column (for example, `country_id`) and a value column (for example, `country`), with an optional metadata column prefixed `[meta]` (for example, `[meta]country_iso_code`). Example of a country with a linked region: `country_id, country, region_id, region`. |
| Number of columns | Include at least two columns (one ID and value pair) and no more than 30. |
| Column names | Use no duplicate names. Value and metadata columns must use lowercase letters, numbers, and underscores only, start with a lowercase letter, and be 2 to 100 characters long. ID columns are plain text with no set format but can't be empty. |
| Cell values | Every cell must have a value of up to 300 characters, except metadata cells, which can be blank. Use plain text only – no HTML tags, entities, or markup. |
| ID consistency | The same ID must always map to the same value within a group. For example, if `region_id` is `n1`, `region` must always be `North` in every row. |
| Re-uploading a file | Column names must exactly match the existing field's sub-fields – you can't add or remove value columns. Omitting a `[meta]` column that was there before removes that metadata and its stored values. For metadata sub-fields, you can only update the name and translations, not the export, profile visibility, or edit permission settings. |

API (Application Programming Interface) is a set of protocols and tools that allow different software applications to communicate with each other. APIs enable the integration of third-party services, data exchange, and interaction between systems, allowing for enhanced functionality and streamlined workflows.