CSV FAQs

What is a CSV?

A CSV is a comma separated value file - a plan text file that contains data separated by a comma. If you are using Excel, you simply have to save your file as .csv instead of .xlsx!

Which fields/headers should I include?

If you are adding a new contact, the following five fields are required: first_name, last_name, phone, group_list, and customer_id. If the timezone column is omitted, contacts will be assigned to your program's default timezone. However, you can also include the timezone column if contacts are located in different timezones and you have access to that data. You can also include as many additional custom fields in your upload as you would like.

If you are updating existing contacts, you must include the customer_id field, and whichever field(s) you are updating. 

If you are updating existing contacts and adding new contacts at the same time, the same five fields are required for new contacts: first_name, last_name, phone, group_list, and customer_id. For existing contacts, ensure that you do not leave any column blank for those rows - for any cell left blank, if you choose to update it in the upload process, the data will be cleared out.

Does column order matter?

No - the column order does not matter. 

What are the formatting rules for field names?

The required fields must match exactly: first_name, last_name, phone, group_list, and customer_id. If included, timezone must match exactly as well.

For custom fields, fields must be lowercase, with underscores instead of spaces, no special characters, and they cannot begin with a number. The column headers in the CSV must be an exact match to the field names in Message.

What are the formatting rules for each field type?

String fields are open text values and have no formatting restrictions.

Boolean fields contain true and false values. They are restricted to TRUE and FALSE only. Maybe Boolean fields allow blank values.

Numeric fields are restricted to whole numbers. They allow blank values.

Float fields are restricted to decimal numbers, and must contain a leading zero. They allow blank values.

Date fields are restricted to date values formatted YYYY-MM-DD. They allow blank values.

Time fields are restricted to time values formatted HH:MM:SS. They allow blank values.

DateTime fields are restricted to YYYY-MM-DD HH:MM:SS. They allow blank values.

For more information on field types, click here.

What is a group_list?

The group_list is a required data field in Message. It is updated just like any other data field, but it has unique uses on the platform. The group_list field can be used to assign user permissions - that is to say, a user can be given restricted access only to the contacts in one or more specific lists. It is possible for contacts to be in multiple lists - that is done by separating each list name with a semi-colon (for example, Group 1;Group 2). 

What happens if I leave a column out of my file?

If you are adding a new contact and the phone field is left blank, the file will error. If you leave any other column out, the missing fields will be ignored - no data will be deleted.

What happens if I leave a cell blank, or include the column header but no data?

If the phone or timezone fields are left blank, the file will error. If you leave group_list blank, the file will run but you will have problems making changes to that contact in the platform. If any other field is left blank in an upload, the field will be left blank (for new contacts), or the existing data will be deleted (for existing contacts). 

What happens if I leave a contact out of a file?

Contacts left out of files are not deleted - their data is simply unchanged.

Do I have to include all of my contacts in the file if I am just updating a few?

No - if you are only updating a few contacts, you only need to include those contacts in the file. 

Does a new import overwrite the existing data on the platform?

Yes, but only if you would like it to. When you choose to update existing contacts, you can select exactly which fields the system should override and which fields the system should leave as is. This allows you to upload a data file with many columns, but only override the data for a few of those columns.

What is the file size limit?

The file size limit for CSVs uploaded via the web application is 15 MB (10 MB in Message Classic). There is no file size limit for CSVs when using the Automated Import tool.