Import People via CSV

Let's get you started uploading people to your account in Customer.io! This document will take you through the whole process, from preparing your file to upload, diagnosing any errors, and getting your data into Customer.io successfully!

Two ways to import

1. Import new and existing profiles by identifying people by their id.

2. Update existing people via their associated email address. It is not possible to import new people via their email address only, since we don't know your id scheme. When you import by email address, we will only update the associated profile if that email address is associated with one id. If an email address is associated with multiple ids, none of those people will be updated.

Getting your file ready for upload

Before uploading your file into Customer.io, there are a handful of things you want to check to to ensure that the data you're sending is formatted well.

CSV or Google Sheet?

You can upload a CSV directly into Customer. io, or link us to a Google Sheet.

Example File

Take a look at an example CSV

File Requirements

Your file must:

• be in CSV format (reference) OR a Google Sheet
• not exceed 100MB in size
• not contain more than 100 columns
• if it's a Google Sheet, it must be shared with cio_share@customer.io (it can also be a public sheet, but we strongly discourage the use of public sheets for security reasons).

Case Sensitivity

All attributes are case sensitive. If your file has three columns named id, Id and ID, then all three of those columns will become separate attributes in your users' profiles.

Uploading your file to Customer.io

Once your file is ready to go and you've made sure you're in the correct workspace, you begin by navigating to the "People" page and clicking the "Import CSV" button in the upper right hand corner.

When you click the "Import CSV" button, you will be presented with this screen:

1. Here you can select to import:
   • New people only (rows where the id does not match a person in your workspace)
   • By id: Updates to existing people (rows where the id does match a person in your workspace)
   • By Email: Updates to existing people (rows where the email matches a person in your workspace)
   • New and existing people (all rows; will determine a person is existing based on id matches)
2. If your file has empty values, we will automatically ignore them by default. We can also delete them for you. Just select which option works best for you from the dropdown.
3. Upload your .csv file here, or your Google Sheet
   • If you choose a Google Sheet, we'll import the sheet from the link you enter.
   • Please do not change the sheet before validation step.
4. Description is optional, but it is recommended to differentiate your imports for easy reference

Once you have completed all fields, proceed by clicking the "Next" button.

Mapping your file column headers to reserved attributes

Overall, mapping is the act of matching the headers in your columns to attributes for people in Customer.io — either telling us to use attributes that already exist (and which ones), or create new ones.

Customer.io has four reserved attributes: id, email, created_at, and unsubscribed. A lot of our core functionality is based on reserving them. If you use any of these as column names in your import, you’ll have to map them to these values in Customer.io — meaning that if you want to import the id in your column, for example, you must use it as the reserved id attribute in Customer.io. If you don’t want to map them and import them separately, you’ll have to use different column names.

Reserved Attributes

Data in the columns mapped to these reserved attributes should use the correct data format, described below:

Importing by Id

The following only applies when creating new people or updating exsting people by id.

A column must be present in your file that maps to id. If your id column is not specifically named id, you will need to map the reserved attribute to the column the system should use for import.

Be very careful when assigning profile ids. They are unique and, once created, cannot be changed. Customer.io de-duplicates profiles only on id. Multiple ids can exist with the same email address; in this case, it’s very likely you will double-mail your customers by mistake. For this reason, do not create new profile ids without first checking how your they are assigned with your technical team, and follow the rules consistently.

Importing by Email

If you selected to import updates to existing people by matching on email address, then a column must be present in your file that maps to email.

If your email column is not specifically named email, you will need to map the reserved attribute to the column the system should use for import.

Mapping your file column headers to custom attributes

Now it's time to indicate how the column headers from your file map to the custom attributes within your workspace.

1. Here is a sampling of the first five rows of your data for the specific column
2. "Import as:" will be the selection of which attribute to map this column to
3. If you do not wish to import the values in this column, select the "Skip" checkbox

You may see some additional warnings on this screen. These are best practices and recommendations, and you are not required to fix all warnings. Example: We may recommend you remove spaces from your column names because having spaces in attributes can make things difficult when using Liquid Templating in your messages.

Once you have completed this step, click the "Next" button to begin the validation of your file.

Reviewing data validation messages

Depending on your file size, your file may take some time to process through the validations. When you click "Next", we will be checking your data to ensure only the best data is brought into your account.

If validation goes well, you can skip to "Importing your data".

The above is what a fully successful import looks like. Otherwise, let's troubleshoot!

Types of Data Validations

We have two types of data validations we run against your data:

1. Required: Data vaidations that, if failed, will mean the row cannot be imported. These are considered errors. Example: The row is missing a value in the id column
2. Optional: Data validations that, if failed will result in a warning. Rows with warnings will still be imported. Example: The same email address is used for multiple ids and will create multiple people.

Errors (Required):

If there are errors that you must fix before your import can be successful, we'll generate an error file for you. This will contain all the rows with errors, plus two additional columns:

• _row: will contain the row number (from your original file) that had an error
• _errors: will list the errors for that row

Warnings (Optional):

It is very likely that you do not need to make any changes here. However as a heads-up, we wanted to bring to your attention some common items that may be missed in larger data sets.

Similar to the errors, you are able to export a file of all your warnings for your review. This will contain all the rows with warnings, plus two additional columns:

• _row: will contain the row number (from your original file) that had a warning
• _warnings: will list the warnings for that row

Importing your data

This is the final step! At this point, making sure that your data is correct is super-critical; we want to make sure the right people (and data) end up in your system, and get the right messages.

This is your last chance to review the data and configurations. You can see the actual data to be imported by clicking the Preview Import button and reviewing the CSV file. This file reflects the actual data which will imported to your account, including all data mappings, attribute skips and data conversions. Once you're happy, click the “Import” button to proceed.

Depending on the size of your file and how busy the system is, it can take approximately one minute per 20 - 30 thousand rows. Feel free to navigate away from the page, sit back and take a break. We will send you an email to notify you that your import has successfully completed when it is all done.

You can revisit this import (or any previous import) by navigating to the "Imports" page in your workspace.