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
Import new and existing profiles by identifying people by their
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
idscheme. 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.
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 firstname.lastname@example.org (it can also be a public sheet, but we strongly discourage the use of public sheets for security reasons).
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:
- Here you can select to import:
- New people only (rows where the
iddoes not match a person in your workspace)
id: Updates to existing people (rows where the
iddoes match a person in your workspace)
- By Email: Updates to existing people (rows where the
- New and existing people (all rows; will determine a person is existing based on
- New people only (rows where the
- 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.
- 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.
- 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:
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.
Data in the columns mapped to these reserved attributes should use the correct data format, described below:
|Attribute||Purpose||Required When||Data Format|
|id||This is the unique identifier that will be used to either update an existing person or to create a new person when the
|Shown in various places in your account for easy association with a person's profile. Additionally, the TO line of your email templates will be prefilled with this attribute.||Importing by email||We support valid RFC 5322 email addresses.|
|created_at||Recommended to hold the date the profile was created in your system. Will allow you to take advantage of timestamp operators in your segmentation. Shown in various places in your account for easy aging of a person's profile.||Always optional||We support:
- unix epoch
- unix epoch ms
- ISO 8601
|unsubscribed||To determine if the person is currently subscribed/unsubscribed from receiving campaigns and newsletters from you. (reference)||Always optional||We support any case of true (i.e.
Importing by Id
The following only applies when creating new people or updating existing people by
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
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
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.
We sample the first three rows of your data for the specific column. "Import as:" will be the selection of which attribute to map this column to. 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:
- 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
- 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.
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
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.