Adding/Updating People via CSV
You can import a CSV to add new people, update existing people, or both.
Before you import people, make sure that your CSV file is ready to import. It must contain a column that maps to
Go to either People > Add People and click Import a CSV.
Select the file you want to import. If your CSV does not validate, it may not meet our CSV requirements.
Set up your import and then click Next.
- Set a Name and Description for your import, helping you identify your CSV on the Imports page.
- Select whether add new people or not.
- Select whether to update existing people or not. If you update existing people, determine whether to update people by
cio_idif you want to update people’s
- Determine how to handle empty values—ignore them or nullify existing attribute values.
Map fields from your CSV to attributes in Customer.io and click Next.
You must map
Creating new attributesIf you import a column, but you don’t map it to an existing attribute, we create a new attribute using the column title.
Review your import for errors and warnings.
- Check out our section about import for errors and warnings for help reviewing your CSV.
- (Optional) Click Preview Import to download a CSV file that reflects your final import, including all data mappings, skipped attributes, etc. Make sure that your import is correct. You cannot stop the import process after you click Import.
- (Optional) Add people to a new or existing Manual SegmentA segment of people you maintain manually. You must explicitly add people to, or remove people from, the segment..
Each row in your CSV can trigger a campaignCustomer.io processes imports row-by-row. Segment-triggered campaigns may fire as we create new people or change attributes, so review your import carefully!
Click Complete import to begin importing people. The import process takes approximately one minute per 20-30 thousand rows. You can navigate away from the page, and we will send you an email when your import is complete.
Go to Data & Activity > Imports to revisit this import or see your previous imports.
When you import a CSV, you match the headers in your CSV to attributes for people in Customer.io, at least one of which represents the identifier for the people you want to update (ID or email). If your column names match attributes in Customer.io, we try to map them automatically. Otherwise, you can re-map columns in your attribute to existing attributes or create new attributes.
We sample the first three rows of your data for each column, helping you understand the data that you’re mapping to each attribute. Use Import as: to select the attribute that you want to map a column to. If you do not want to import the values in a column, select Skip.
Customer.io has some reserved attributes:
unsubscribed: these attributes have a defined purpose in Customer.io and expect certain types of values. But, you can create your own attributes for similar, non-reserved purposes. For example, if you want to import a column representing an email address, but you don’t want to map that to the reserved Customer.io
On the Review step when you import a CSV file, we validate your import, returning errors and warnings for rows in your CSV file. Rows with errors will not be imported.
Depending on the size of your CSV file, it may take a moment for us to validate your import.
If there are no errors or warnings, you can continue importing your file as normal. If not, you may want to correct issues in your your CSV file to make sure that you import everybody in your CSV.
- Errors: issues that prevent us from importing a row. Example: *The row is missing a value in the
- Warnings: issues that do not prevent us from importing a row, but you may want to note to make sure that your data is well formed. You probably don’t need to fix issues resulting in warnings. Example: The same email address is used for multiple ids and will create multiple people.
In Import Details, you can click ERRORS or WARNINGS to download a CSV file containing either errors or warnings. Each file contains the rows from your original CSV file that resulted in errors or warnings respectively, including 2 new columns:
- _row: contains the row number from your original file that contained an error or warning.
- _errors or _warnings: lists errors/warnings for a row.
Re-import your error CSV
You can upload a CSV directly to Customer. io, or link us to a Google Sheet. Take a look at an example CSV. Each row in your CSV represents a person you want to add to, or update in, your workspace, and each column represents an attribute that you want to assign to that person.
Your file must:
- be in CSV format OR a Google Sheet
- not exceed 100MB in size
- not contain more than 100 columns
- contain at least one column that maps to an identifierThe attributes you use to add, modify, and target people. Each unique identifier value represents an individual person in your workspace. in your workspace—
cio_id(when updating people). This requirement changes based on the identifiers used in your workspace and whether you want to add or update people. See the section below for more information.
- Google Sheets be shared with firstname.lastname@example.org. (You can also make your sheet public, but we strongly discourage the use of public sheets for security reasons).
Nobody outside of Customer.io has access to email@example.com
Your CSV generally needs to include at least one . However, the identifier(s) your sheet can include depend on whether you want to add or update people and your workspace settings—whether you identify people by
For Email and ID workspaces, your CSV must include at least one of
- When you update people: if a person does not already have an
idlater, you can do that. If ID or email values are not empty, you cannot change them unless you identify people by
cio_id. Attempting to change identifiers without using
cio_idresults in a Failed Attribute Change error.
For ID only (classic) workspaces:
- When you add people: your sheet must include an
idcolumn (or a column that you map to
- When you update peopple: you can update people by
idcolumn). But, if multiple people in your workspace have the same
cio_id to update people’s identifiers
cio_id—an identifier assigned by Customer.io. See the section below for more information.
|Workspace type||Add||Update||Required in CSV||Notes|
|email or ID||✅||at least one of
|✅||at least one of
||Your request cannot change existing
|✅||✅||at least one of
||Your request cannot change existing
There are other reserved attributes
If you want to update a person’s email or ID, and those IdentifiersThe attributes you use to add, modify, and target people. Each unique identifier value represents an individual person in your workspace. are already set, your sheet must identify people by their cio_idAn identifier for a person that is automatically generated by Customer.io and cannot be changed. This identifier provides a complete, unbroken record of a person across changes to their other identifiers (id, email, etc).. Otherwise, trying to change a person’s email or ID value (after it was already set) results in an Failed Attribute Change error. You can find people’s
cio_id values by performing an export, or on the People page.
When you import people, select the option to Update people, and use
cio_id as the identifier. Identifying people by their canonical, CIO ID lets you change their other identifiers.
You cannot add people when you identify people by
cio_id; this value is reserved and assigned by Customer.io automatically when you add someone using an email or ID.
You can export files that you uploaded, or were otherwise generated as a part of the upload process (like errors and warnings), for up to 30 days after your import. After 30 days, these files expire and are no longer available to download.