Import People via CSV

You can import a CSV of people to add new people, update existing people, or both.

CSV Requirements

You can upload a CSV directly into 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 your workspace, and each column represents an attribute that you want to assign to that person.

Attributes are case sensitive

If your file has columns named id, Id and ID, all three of those columns will become separate attributes!

Your file must:

be in CSV format OR a Google Sheet
not exceed 100MB in size
not contain more than 100 columns
contain a single column that maps to an identifiers in your workspace—id or email.
Google Sheets be shared with cio_share@customer.io. (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 cio_share@customer.io

Upload a CSV to Customer.io

Before you import people, make sure that your CSV file is ready to import. It must contain a column that maps to either id or email attributes in Customer.io. If importing a Google sheet, your sheet must be shared with cio_share@customer.io.

Go to either:
- Imports > Import People
- People > Add People > Import a CSV.
Select the file you want to import.
Set a Name and Description for your import, helping you identify your CSV on the Imports page.
Determine how to handle your import and then click Next:
- Add new people or not.
- Update existing people. If you update existing people, determine whether to update people by id or email.
- 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 id or email attributes to a column if your sheet did not include columns labeled id or email; all other columns are optional.

Creating new attributes

If 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. Click Preview Import to download a CSV file that reflects your final import, including all data mappings, skiped attributes, etc. Make sure that your import is correct. You cannot stop the import process after you click Import.
(Optional) Select the boxes below the Review your data section to add imported people to a new or existing segment.

Imports process in sequence

Customer.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. It takes approximately one minute per 20-30 thousand rows to import your file. You can navigate away from the page. 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.

Mapping CSV headers to attributes

When you import a CSV, you match the headers in your CSV to attributes for people in Customer.io, 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 four reserved attributes: id, email, created_at, and unsubscribed. If you want to import a column representing an ID, but you don’t want to map that to the reserved Customer.io id attribute, you can change the column name and import it as a different attribute.

Mapping warnings

You may see some warnings when mapping attributes. These generally represent best practices and recommendations, and are not issues that you need to fix. For example, we may recommend that you remove spaces from your column names because spaces in attributes can make things difficult when using Liquid in your messages.

Reserved Attributes

When mapping data to reserved attributes, make sure you use the correct data format, described below:

Attribute	Purpose	Required	Data Format
id	This is the unique identifier for people. If the `id` does not yet exist, we create a new person.	When importing by `id`	Our default `id` limit is set to 150 characters. All valid utf characters are allowed.
email	A person’s email address. If your workspace uses `email` as a unique identifier (the default setting for new workspaces), and the email address does not yet exist, we create a new person. The TO line of your email templates is prefilled with this attribute.	When importing by email	We support valid RFC 5322 email addresses.
created_at	Recommended. Holds the date when a profile was created. This value lets you to take advantage of timestamp operators in segments and helps you determine the age of a person’s profile.	Optional	We support: - unix epoch - unix epoch ms - ISO 8601
unsubscribed	Determines whether a person is subscribed or unsubscribed from your campaigns and newsletters. (reference)	Optional	We support any case of true (i.e. `TRUE`, `true`, `tRUe`, etc.) or ‘1’ to represent unsubscribed. Any other value is considered “false”, or subscribed.
mobile_ad_id	Used to record either Apple’s Advertising Identifier (IDFA) or Android’s Advertising ID (AAID). This id can improve match accuracy in Google or Facebook Ads when using Ad Audiences.	Optional	Apple’s Advertising Identifier (IDFA) or Android’s Advertising ID (AAID)
email_sha256	To keep your data secure, you can hash your customer email using the SHA256 algorithm before sending it to your account. This field is only used in Ad Audiences and cannot be used to send messages.	Optional	Valid encoded sha256
mobile_ad_id_sha256	To keep your data secure, you can hash the mobile_ad_id using the SHA256 algorithm before sending it to your account. This field is only used in Ad Audiences.	Optional	Valid encoded sha256

Importing by id

When you import users by id, your CSV file must contain a column that maps to id. If your id column is not named id, you will map the column to id.

In a classic workspace, or a workspace in which ID is the only identifier, profile IDs are unique and cannot be changed. Customer.io de-duplicates profiles on id, but you can assign the same email address to multiple IDs. If you assign the same email address to multiple IDs, you may send people duplicate messages. Before you import people or create new profiles, check with your technical team to understand how you assign and organize profiles to make sure that you don’t inadvertently add duplicates to your workspace.

If your workspace uses both ID and email as identifiers, you can set email addresses for people if they weren’t already set, but you cannot modify identifiers that have already been set.

For example, if your workspace uses both ID and email to identify people and a person has both an ID and email attributes, attempting to set a new email address for that person with a CSV upload will result in an attribute change error—the person’s email will remain unchanged.

Importing by email

When you add people to a workspace by email, or update people by email address, your CSV file must contain a column that maps to the email attribute.

If your email column is not named email, you will map the column to email.

When importing people to a workspace supporting email as a unique identifier, your CSV file cannot contain an id column. You must set user IDs outside of the CSV-import process.

Updating email identifiers

You cannot update people’s email addresses by CSV import if your workspace uses email as an identifier (the default setting). To update people’s email addresses, you must manually update people or use our API and reference them by their auto-generated cio_id.

Reviewing import errors and warnings

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 id column._
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 import users directly from an error or warning CSV file after you correct errors and remove the “_row” and “_errors” or “_warnings” columns.

Exporting files from an import

Files supplied or generated during your import expire and will no longer be available for download after 30 days.

Copied to clipboard!