Overview

Before you can import contacts in Cordial, you need to create contact attributes, list attributes, and your data file. If you've already completed these steps, visit our Import contacts via data job article.

Create contact attributes

Before importing any contacts, you need to create their associated attributes first.

You can create these during importing, but it's not the recommended method when you have a large number of attributes to create.

• To learn more, read our article about creating contact attributes.

Create list attributes

Before importing any contacts, you need to create their associated lists.

You can create these during importing, but it's not the recommended method when you have a large number of lists to create.

• To learn more, read our article about creating lists.

Create your data file

A data file may include an unlimited number of contact records with each contact record containing an unlimited number of attributes and list values. Cordial has one main database that includes all contacts, as well as their attributes and list associations. There are not separate lists in Cordial. Instead, a contact's list association is reflected by a list attribute value being true or false (1 or 0 in the data file).

The most common scenario for loading a data file is uploading a file from your computer. You can also load the file from any HTTP/HTTPS, FTP, SFTP, or S3 location. An additional option for Google Cloud Storage will be available once you've completed the Google Cloud Storage integration setup.

The following data file formats are supported when importing a local file from your computer:

• TSV: tab-separated values
• CSV: comma-separated values
• TXT: a text file

The most common file format is a CSV (comma-separated values) file, where the comma character acts as the delimiter between fields. If you are creating or manipulating your file in a program like Microsoft Excel, simply save your file in a CSV format using Excel's Save As feature and select CSV.

Import files must be saved using UTF-8 character encoding. Files using other types of encoding systems are not supported.

Check that your data file does not contain any errant characters. Some programs such as Apple Numbers or Microsoft Excel may insert errant characters when saving or exporting as a CSV. When uploading a local file via the UI, the file size is limited to 50MB. Additionally, if there are several rows in the file, it's possible the file could take too long to process and timeout.

If your import files are larger than 50MB, please consider hosting the file remotely or using the contact imports API endpoint.

In your data file, create a column header so you can match up your data values with the appropriate Cordial attribute or list value. This will be important when you import the file and want to be certain you're loading the data correctly.

Use 0 to remove contacts from the designated list or 1 to add them.

Use case

If you have a file that contains email address, first name, and last name for each contact, and you want to include them on the lists 'newsletter' and 'weekly_specials,' your data file would need to look like the following:

In table format:

In CSV format:

channels.email.address,first_name,last_name,newsletter,weekly_specials
fredgarvin@example.com,Fred,Garvin,1,0
arnoldbabar@example.com,Arnold,Babar,1,1

The values for each contact's list association are denoted by a boolean value where a 1=true (on the list) or 0=false (not on the list). For email address, be sure to use the key channels.email.address in order to map correctly into the system when importing.

Subscribe status management

You can update contacts' subscribe status using the channels.email.subscribeStatus column header in your import file. Under this header, assign one of three possible subscribe status parameters for each contact: none, subscribed, and unsubscribed.

There are two important caveats to keep in mind when it comes to managing contacts' subscribe status via UI file uploads: 1.) Once a contact's subscribe status is set to unsubscribed in the Cordial platform, it's not possible to change this status using the UI contact upload file. However, the unsubscribed status can be changed via the contact imports API endpoint, or by accessing the individual contact's profile in the platform and manually changing the subscribe status. This is intended as a precautionary measure to prevent accidental subscription modifications to previously unsubscribed contacts. 2.) If your import file does not contain instructions for handling contacts' subscribe status, and it contains contacts whose current subscribe status in the Cordial platform is none, their status will automatically be changed to subscribed. To avoid this automatic assignment, always include the channels.email.subscribeStatus header in your import file and designate the appropriate subscribe status parameter for each contact.

Add geo attributes

When importing geo field attributes, use the key that you created (hm_address, work_address, etc.) appended with the Cordial standard field name in dot notation.

Available standard fields are:

• street_address
• street_address2
• city
• state
• postal_code
• country
• tz (time zone)
• loc
  • lat (latitude)
  • lon (longitude)

City, state, country, time zone, latitude, and longitude will be added automatically by the system when a postal code is entered.

For example, if we created a geo field called hm_address, we would write each geo field as:

• hm_address.street_address
• hm_address.street_address2
• hm_address.city
• hm_address.state
• hm_address.postal_code
• hm_address.country

Your CSV file would look like this:

Add arrays

In addition to strings, numbers, dates, and geo attributes, Cordial also supports uploading arrays of comma separated values within a contact attribute.

Use case

You might have an array of values for a contact attribute called favorite_fruits. Because array values are separated by commas, they need to be escaped by double quotes to avoid errors while uploading a CSV file. Your data file might look like the following:

In table format:

In CSV format:

channels.email.address,favorite_fruits
fredgarvin@example.com,"[""apple"",""orange"",""pear""]"

Add and remove array items

The above example will replace any array items that currently exist in the array attribute.

To add an item to an existing array attribute use the following code:

channels.email.address,favorite_fruits
fredgarvin@example.com,{ "add": ["apple"] }

Alternately, if your CSV elements already contain quotes (as some applications may export) use the following syntax:

"channels.email.address","favorite_fruits"
"fredgarvin@example.com","{ ""add"": [""apple""] }"

You can also add multiple items to the array:

channels.email.address,favorite_fruits
fredgarvin@example.com,"{ ""add"": [""berry"",""kiwi""] }"

To remove items from the array, use this syntax:

channels.email.address,favorite_fruits
fredgarvin@example.com,{ "remove": ["apple"] }

In the next article, you can learn how to import contacts.