User import

Braze offers a variety of ways to import user data into the platform: SDKs, APIs, cloud data ingestion, technology partner integrations, and CSVs.

REST API

You can use the /users/track endpoint to record custom events, user attributes, and purchases for users.

Cloud Data Ingestion

You can use Braze Cloud Data Ingestion to import and maintain user attributes.

CSV

You can also upload and update user profiles via CSV files from Audience > Import Users.

This feature supports recording and updating user attributes such as first name and email, in addition to custom attributes such as shoe size. There are two different ways you can approach a CSV import: importing with an external_id or with a user alias.

Importing with external ID

When importing your customer data, you’ll need to specify each customer’s unique identifier, also known as external_id. Before starting your CSV import it’s important to understand from your engineering team how users will be identified in Braze. Typically this would be a database ID used internally. This should align with how users will be identified by the Braze SDK on mobile and web, and is designed for each customer to have a single user profile within Braze across their devices. Read more about the Braze user profile lifecycle.

When you provide an external_id in your import, Braze will update any existing user with the same external_id or create a newly identified user with that external_id set if one is not found.

Download: CSV Import Template

Importing with user alias

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 will update any existing user with the same user_alias_name and user_alias_label. If a user isn’t found, Braze will create a newly identified user with that user_alias_name set.

Download: CSV Alias Import Template

Importing with Braze ID

To update existing user profiles in Braze using an internal Braze ID value instead of an external_id or user_alias_name / user_alias_label value, you can do this by specifying braze_id as a column header.

This can be helpful if you have exported user data from Braze via our CSV export option within segmentation and wish to add a new custom attribute to these existing users.

Constructing your CSV

There are several data types in Braze. When importing or updating user profiles via CSV, you can create or update default user attributes or custom attributes.

• Default user attributes are reserved keys in Braze. For example, first_name or email.
• Custom attributes are custom to your business. For example, a travel booking app may have a custom attribute called last_destination_searched.

Braze accepts user data in the standard CSV format from files up to 500 MB in size. Refer to the preceding sections on importing for downloadable CSV templates.

Data point considerations

Each piece of customer data imported via CSV will overwrite the existing value on user profiles and will count as a data point, except for external IDs and blank values.

• External IDs uploaded via CSV will not consume data points. If you are uploading a CSV to segment existing Braze users by uploading only external IDs, this can be done without consuming data points. If you were to add additional data like user email or phone number in your import, that would overwrite existing user data, consuming your data points.
  • CSV imports for segmentation purposes (imports made with external_id, braze_id, or user_alias_name as the only field) will not consume data points.
• Blank values will not overwrite existing values on the user profile, and you do not need to include all existing user attributes in your CSV file.
• Updating email_subscribe, push_subscribe, subscription_group_id, or subscription_state will not count towards data point consumption.

Default user data column headers

Importing custom data

Any headers that do not exactly match default user data will create a custom attribute within Braze.

The following data types are accepted in user import:

• Datetime (Must be stored in ISO-8601 format)
• Boolean (TRUE/FALSE)
• Number (Integer or float with no spaces or commas, floats must use a period (.) as the decimal separator)
• String (Can contain commas as long as there are double quotation marks surrounding the column value)
• Blank (Blank values will not overwrite existing values on the user profile, and you do not need to include all existing user attributes in your CSV file.)

Updating subscription group status

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

If you are updating subscription group status, 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 subscription group) or subscribed (in subscription group).

Importing a CSV

To import your CSV file, navigate to the User Import page under the Users section. In the lower text box, Recent Imports, there will be a table that lists up to twenty of your most recent imports, their file names, number of lines in the file, number of lines successfully imported, total lines in each file, and the status of each import.

The upper box, Import CSV, will contain importing directions and a button to begin your import. Click Select CSV File and select your file of interest, then click Start Upload. Braze will upload your file and check the column headers as well as the data types of each column.

To download a CSV template, refer to the sections Importing with external ID or Importing with user alias on this page.

Once the upload is complete, you will see a modal with a preview of the contents of your file. All the information in this table is based on the values in the top few rows of your CSV file. For column headers, standard attributes will be written in normal text, while custom attributes will be italicized and have their type noted in parentheses. There will also be a short summary of your file at the top of the pop-up.

You can import more than one CSV at the same time. CSV imports will run concurrently, and as such the order of updates is not guaranteed to be serial. If you require CSV imports to run one after another, you should wait until a CSV import has finished before uploading a second one.

If Braze notices something malformed in your file during the upload, these errors will be shown with the summary. For example, if your file includes a malformed row, then this error will be noted in the preview when you import the file. So, a file can be imported with errors, but an import can’t be canceled or rolled-back after it’s started. Review the preview, and if you find any errors, cancel the import and modify your file. It’s important to examine the full CSV file before upload, as Braze doesn’t scan every row of the input file for the preview. This means errors can exist which Braze doesn’t catch while generating this preview.

Malformed rows and rows lacking an external ID will not be imported. All other errors can be imported, but may interfere with filtering when creating a segment. For more information, skip to the Troubleshooting section.

When you’re satisfied with the upload, start the import. The pop-up will close and the import will begin in the background. You can track its progress on the User Import page, which will refresh every 5 seconds, or at the press of the refresh button in the Recent Imports box.

Under Lines Processed, you will see the progress of the import; the status will change to Complete when finished. You can still use the rest of the Braze dashboard during the import, and you’ll receive notifications when the import begins and ends.

If the import process runs into an error, a yellow warning icon will be displayed next to the total number of lines in the file. You can hover over the icon to see details into why certain lines failed. After the import is completed, all data will be added to existing profiles, or new profiles will be created.

Lambda user CSV import

You can use our serverless S3 Lambda CSV import script to upload user attributes to the platform. This solution works as a CSV uploader where you drop your CSVs into an S3 bucket, and the scripts uploads it via our API.

Estimated execution times for a file with 1 million rows should be around 5 minutes. See User attribute CSV to Braze import for more information.

Segmenting

User import creates and updates user profiles, and can also be used to create segments. To create a segment, select Automatically generate a segment from the users who are imported from this CSV before starting the import.

You can set the name of the segment or accept the default, which is the name of your file. Files that were used to create a segment will have a link to view the segment after the import has been completed.

The filter used to create the segment selects users who were created or updated in a selected import and is available with all other filters in the edit segment page.

HTML data stripping

Braze does not sanitize HTML data during ingestion time. When importing data into Braze, specifically meant for personalization usage in a web browser, ensure that it is stripped of HTML, JavaScript, or any other script tag that potentially could be leveraged maliciously when rendered in a web browser.

Alternatively, for HTML, you can use Braze Liquid filters (strip_html) to HTML escape rendered text. For example:

• input
• output

1
{{ "Have <em>you</em> read <strong>Ulysses</strong>?" | strip_html }}

1
Have you read Ulysses?

Troubleshooting

Missing rows

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

• Duplicate external IDs: If there are duplicate external ID columns, then this may cause malformed or unimported rows even if the rows are correctly formatted. In some cases this may not report a specific error. Check if there are any duplicate external IDs in your CSV. If so, remove the duplicates and try uploading again.
• Accented characters: Your CSV may have names or attributes that include accents. Ensure your file is UTF-8 encoded to prevent any issues.

Malformed row

There must be a header row in order to properly import data. 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 being thrown. Additionally, all data must be UTF-8 encoded.

If your CSV file has blank rows and imports less 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.

Multiple data types

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

Incorrectly formatted dates

Dates not in ISO-8601 format will not be read as datetimes on import.

String quotation

Values encapsulated in single (‘’) or double (“”) quotation marks will be read as strings on import.

Data imported as custom attribute

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