Articles in this section

See more

CSV List Import Best Practices

Iterable allows you to upload CSV files of subscribers and their user profile fields. It's a great way to create new static lists or add users into the system, without needing the help of an engineer.

To import a CSV list, navigate to Audience > Lists and click Import List. For more information, read Adding Users and Creating Lists.

Before importing a new CSV file, pay attention to these best practices to avoid data attribution or malformation errors.

Things to remember

  • If you are creating user profile fields by using this upload tool, the only data types you can cast are strings, dates, and booleans. If your field is not formatted as a date or boolean, it will be cast as a string by default. This is permanent in format and data type. If you are not sure you'd like to change the format for this field name later, do not include that column in your CSV file.

  • Hiding unwanted fields is possible, but merging, deleting, and editing are not.

  • CSV uploads are all automatically cast as string types if they do not already exist in your project and are not formatted as a date or boolean.

  • If there are any fields you wouldn't like to be a string, date, or boolean and would prefer the data type be long, double, object, array, etc., make sure they are originally cast through another method (such as an API call).

  • Arrays and objects cannot be created or edited via CSV List Import. These must always be created or updated via the API or Segment.

Best practices

Creating your CSV file

  • Use a spreadsheet program like Microsoft Excel to create your CSV file.

  • Make sure the file is in CSV format. XLS or XLSX files can't be uploaded.

  • The first row of your CSV file should contain the names of the user profile fields you'll include in the file. For example: firstName, lastName, etc.

  • User profile fields are case and space sensitive. As a result, firstName, first name, and firstname can all exist as completely different fields. To make sure you do not upload multiple fields for the same value, first export a list out of Iterable to see the existing fields. Then, create your CSV with the existing fields as headers.

  • Make sure you don't have any duplicate or empty headers.

  • Make sure the first column in your spreadsheet contains your project's unique identifier—either email, userId, or both (as the first two columns).

  • Make sure there is only one column labeled "email" and that the email addresses in that column are valid.

Data validation

  • User records with misspelled and malformatted emails (for example, user @example.com) will not be uploaded. See Email Validation in Iterable for more information.

  • Make sure all corresponding data is attributed to the right user. If you delete a cell by accident, all data may be shifted and may be attributed to the wrong user. For example, a person may have the wrong last name on their profile. (Usually errors such as these impact multiple rows of data!)

Size limits

  • The file size limit for CSV uploads is 2GB.

  • Each CSV file can't contain more than two million users (rows). Files with more than two million users will need to be split into two or more files and uploaded separately.

Related articles