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!
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
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.
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.
Your file must:
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.
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:
iddoes not match a person in your workspace)
id: Updates to existing people (rows where the
iddoes match a person in your workspace)
Once you have completed all fields, proceed by clicking the “Next” button.
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.
The following only applies when creating new people or updating exsting 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.
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
Now it’s time to indicate how the column headers from your file map to the custom attributes within your workspace.
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.
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!
We have two types of data validations we run against your data:
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:
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:
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.