Skip to content

CSV import

Learn how to record and update user attributes and custom events using CSV import.

About CSV import

You can use CSV import to record and update the following user attributes and custom events.

Using CSV import

Step 1: Download a CSV template

To open CSV import, go to Audiences > Import Users. Here, you’ll find a table that lists details about the most recent imports, such as the upload date, uploader’s name, file name, targeting availability, number of imported rows, and status of the import.

To get you started with your CSV, download a template for attributes or events.

The 'Import Users' page in the Braze dashboard.

Step 2: Choose an identifier

The CSV you import will need a dedicated identifier. You can choose from the following:

When importing your customer data, you can use an external_id to serve as each customer’s unique identifier. When you provide an external_id in your import, Braze updates any existing user with the same external_id or creates a newly identified user with that external_id set if one is not found.

To target users who don’t have an external_id, you can import a list of users with user aliases. An alias serves as an alternative unique user identifier, and can be helpful if you are trying to market to anonymous users who haven’t signed up or made an account with your app.

If you are uploading or updating user profiles that are alias only, you must have the following two columns in your CSV:

  • user_alias_name: A unique user identifier; an alternative to the external_id
  • user_alias_label: A common label by which to group user aliases

When you provide both a user_alias_name and user_alias_label in your import, Braze updates any existing user with the same user_alias_name and user_alias_label. If a user isn’t found, Braze creates a newly identified user with that user_alias_name set.

Download: CSV Attributes Import Template: User Alias

To update existing user profiles in Braze by using an internal Braze ID value instead of an external_id or user_alias_name and user_alias_label value, specify braze_id as a column header.

This can be helpful if you exported user data from Braze through our CSV export option within segmentation and want to add a new custom attribute to those existing users.

You can omit an external ID or user alias and use either an email address or phone number to import users. Before importing a CSV file with email addresses or phone numbers, check for the following:

  • Verify that you don’t have any external IDs or user aliases for these profiles in your CSV file. If you do, Braze will prioritize using the external ID or user alias before the email address to identify profiles.
  • Confirm that your CSV file is formatted properly.

If an existing profile has that email address or phone number, that profile is updated, and Braze doesn’t create a new profile. If there are multiple profiles with that same email address, Braze will use the same logic as the /users/track endpoint where the most recently updated profile will be updated.

If a profile with that email address or phone number doesn’t exist, Braze creates a new profile with that identifier. You can use the /users/identify endpoint to identify this profile later. To delete a user profile, you can also use the /users/delete endpoint.

Step 3: Build your CSV file

You can upload either of the following data types as a single CSV file. To upload more than one data type, upload multiple CSV files.

  • User Attributes: This includes both default and custom user attributes. Default user attributes are reserved keys in Braze (such as first_name or email) and custom attributes are user attributes unique to your business (such as last_destination_searched).
  • Custom Events: These are unique to your business and reflect actions a user has taken, such as trip_booked for a travel booking app.

When you’re ready to start building your CSV file, refer to the following information:

Required identifiers

While external_id is not required, you must include one of the following identifiers as a header in your CSV file. For details about each one, review Choose an identifier.

  • external_id
  • braze_id
  • user_alias_name and user_alias_label
  • email
  • phone

Custom attributes

The following data types can be used as custom attributes for CSV import. Column headers that don’t exactly match a default attribute are imported as custom attributes in Braze.

Default attributes

The following default attributes are available for user import.

Updating subscription group status (optional)

Additionally, you can add users to email or SMS subscription groups through user import. This is particularly useful for SMS, because a user must be enrolled into an SMS subscription group to be messaged with the SMS channel. For more information, refer to SMS subscription groups.

If you are updating subscription group statuses, you must have the following two columns in your CSV:

  • subscription_group_id: The id of the subscription group.
  • subscription_state: Available values are unsubscribed (not in the subscription group) or subscribed (in the subscription group).

Required identifiers

While external_id is not required, you must include one of the following identifiers as a header in your CSV file. For details about each one, review Choose an identifier.

  • external_id
  • braze_id
  • user_alias_name and user_alias_label
  • email
  • phone

Custom event fields

In addition to the following, your CSV may also contain additional column headers for event properties. These properties should have a column header of <event_name>.properties.<property name>.

For example, the custom event trip_booked may have the properties destination and duration. These can be imported by having the column headers trip_booked.properties.destination and trip_booked.properties.duration.

Step 4: Upload your file

To upload your file, select Attributes or Events, click Browse Files, and upload your CSV. Braze displays a preview of the first few rows and a summary of the detected fields.

The upload completed modal showing a file preview, import name field, targeting preferences, and file validation checkbox.

In the Import name field, you can rename your import. By default, the file name is used.

Step 5: Validate your file (optional)

Before starting your import, you can run file validation to check every row for errors and warnings. To validate your file, select Validate file before importing, then click Start import.

Validation can take up to 2 minutes for files at the maximum allowed size. While validation runs, you can select Skip validation to bypass it and proceed immediately.

Validation results

When validation completes, one of the following results appears.

The issues found dialog showing a count of rows with errors and warnings, with options to cancel, download the error report, or import anyway.

Understanding the error report

The error report is a CSV file that contains every flagged row along with its original data and a description of the issue.

After reviewing the report, you can correct the issues in your original file and re-upload, or proceed with the import and accept the partial results.

Step 6: Choose targeting preferences

You can also choose from the following targeting preferences. If you don’t need to create a new targeting filter or segment from your import, select Do not make this list available as a targeting filter.

A filter group with the "Updated/Imported from CSV" filter including a CSV file titled "Halloween season fun".

Step 7: Start your CSV import

When you’re ready, select Start import. You can track the current progress on the Import Users page, which automatically refreshes every 5 seconds.

Import statuses

After starting your import, you can check its status on the Import Users page.

The Import Users page showing a Partial success status with the context menu open, displaying Download error report and Download uploaded CSV options.

The post-import error report includes rows that failed for reasons validation doesn’t cover, such as when a user doesn’t exist in Braze.

Data point considerations

Each piece of customer data imported from a CSV file overwrites the existing value on user profiles and logs a data point, except for external IDs and blank values. If you have any questions about the nuances of Braze data points, your Braze account manager can answer them.

Troubleshooting

If you used file validation, start with the error report, as it includes the specific issue for each flagged row and a description of how to fix it. For rows that failed during import rather than validation, download the error report by hovering over the row and selecting the button on the Import Users page.

For troubleshooting CSV import, review these common issues below.

File formatting issues

Malformed row

If your upload completed with errors, there may be a malformed row in your CSV file.

To properly import data, there must be a header row. Each row must have the same number of cells as the header row. Rows with a length of more or fewer values than the header row will be excluded from the import. Commas in a value will be interpreted as a separator and can lead to this error. Additionally, all data must be UTF-8 encoded.

If your CSV file has blank rows and imports fewer rows than the total lines in the CSV file, this may not indicate a problem with the import since the blank rows wouldn’t need to be imported. Check the number of lines that were correctly imported and make sure it matches the number of users you’re attempting to import.

Missing row

There are a few reasons why the number of users imported might not match the total rows in your CSV file:

String quotation

Values encapsulated in single ('') or double ("") quotation marks will be read as strings on import.

Incorrectly formatted dates

Dates not in ISO-8601 format won’t be read as datetimes on import.

Data structure issues

Invalid email addresses

If your upload completed with errors, there may be one or more invalid encrypted email addresses. Confirm that all email addresses are encrypted properly before importing them into Braze.

  • When updating or importing email address in Braze, use the hashed email value wherever an email is included. These hash email values are provided by your internal team.
  • When creating a new user, you must add email_encrypted with the user’s encrypted email value. Otherwise, Braze won’t create the user. Similarly, if you’re adding an email address to an existing user who doesn’t have an email, you must add email_encrypted. Otherwise, Braze won’t update the user.

Data imported as custom attribute

If a piece of default user data (such as email or first_name) is imported as a custom attribute, check the case and spacing of your CSV file. For example, First_name is imported as a custom attribute, while first_name is correctly imported into the “first name” field on a user’s profile.

Change a custom attribute’s data type

If you need to change the data type of an existing custom attribute (for example, from string to boolean), update the data type on the Custom Attributes page in the dashboard before importing your CSV. If the data type in your CSV doesn’t match the attribute’s currently defined data type, the import fails with an error.

Multiple data types

Braze expects each value in a column to be of the same data type. Values that don’t match their attribute’s data type cause errors in segmenting.

Additionally, beginning a number attribute with zero will cause issues because numbers starting with zeros are considered strings. When Braze converts that string, it may be treated like an octal value (which uses digits from zero to seven), meaning it is converted to its corresponding decimal value. For example, if the value in the CSV file is 0130, the Braze profile shows 88. To prevent this issue, use attributes with string data types. However, this data type isn’t available in the segmentation number comparison.

Default attribute types

Some default attributes may only accept certain values as valid for user updates. For guidance, refer to Constructing your CSV.

Trailing spaces and differences in capitalization can cause a value to be interpreted as invalid. For example, in the following CSV file, only the user in the first row (brazetest1) has their email and push statuses updated successfully because the accepted values are unsubscribed, subscribed, and opted_in.

1
2
3

external_id,email,email_subscribe,push_subscribe
brazetest1,[email protected],unsubscribed,unsubscribed
brazetest2,[email protected],Unsubscribed,Unsubscribed

“Select CSV File” is not working

There are several reasons the Select CSV File button may not work:
Github   Edit this page on GitHub
New Stuff!