Add/Update People via CSV

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

Import people from a CSV file

Before you import people, make sure that your CSV file is ready to import. It must contain a column that maps to id or email. If you want to import a Google sheet, you must grant Customer.io access to sheets in your Google account.

1. Go to either People > Add People and click Import a CSV.

2. Select the file you want to import. If your CSV does not validate, it may not meet our CSV requirements.

3. 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 id, email, or cio_id. Use cio_id if you want to update people’s id or email values.
   • Determine how to handle empty values—ignore them or nullify existing attribute values.

   

   

4. 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.

   

   

5. 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 campaign

   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!

6. 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.

Import a Google Sheet

If you want to import Google Sheets, you must login to your Google account and allow access to your sheets. While granting Customer.io to your Google Account, includes the ability to read, edit, create, and delete the specific files that you share with us, we will only ever read files; we don’t write changes to your documents.

After you grant access, you can select the individual sheets that you want to share with Customer.io.

Map CSV headers to attributes

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: id, email, created_at, and 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 email attribute, you can change the column name and import it as a different attribute. You cannot have multiple columns called email, nor can an email cell contain multiple values.

Review 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.

CSV Requirements

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—id, email, or 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.
• To share Google Sheets, you must login to your google account and grant Customer.io access to your sheets.

Identifiers and Required Columns in your CSV

Your CSV generally needs to include at least one identifierThe attributes you use to add, modify, and target people. Each unique identifier value represents an individual person in your workspace.. 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 id, email, or both.

For Email and ID workspaces, your CSV must include at least one of id or email but may include both.

• When you update people: if a person does not already have an id or an email attribute, your CSV can update these values for that person. For example, if you add a person by email and then want to assign an id later, 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_id results in a Failed Attribute Change error.

For ID only (classic) workspaces:

• When you add people: your sheet must include an id column (or a column that you map to id).
• When you update peopple: you can update people by email (without an id column). But, if multiple people in your workspace have the same email address, the row produces an error; in this case, we don’t know which person you want to update.

Updating people identifiers (email or ID)

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.

Export files from an import

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.