Import Contacts

Overview

Before you are able to start sending messages, you will need to import your contacts. While you are able to add contacts one at a time, you will most likely be importing them using a CSV file.

Before importing, it's recommended to perform some list hygiene best practices to help maintain healthy deliverability. We have provided some info and recommended vendors in our article: Data Validation/Hygiene Vendors and Tips.

Read on for a step by step guide on importing your contacts or watch the following video for a complete walkthrough.

 Importing Contacts Video

Create the contact attributes

Before importing any contacts, it is important to create their associated attributes first. You can create these during importing, but it is not recommended when you have a large number of attributes to create. To learn more, read the article about creating contact attributes.

Create the list attributes

Before importing any contacts, it is important to create their associated lists first.  You can create these during importing, but it is not recommended when you have a large number of lists to create. To learn more, read the 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 master database that includes all contacts, their attributes and list associations. There are not separate lists in Cordial, rather 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. However, you also have the option to 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 or 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 (comma delimited).

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 are loading the data correctly.

For example, if you had a file that contained email address, first name and last name for each contact and you wanted 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

Subscribe status management

You can update contacts' email channel 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 or unsubscribed.

When your import file does not contain the channels.email.subscribeStatus column header, and you are importing contact records with an email address, the import UI will display email subscribe status management options for new and existing contacts.

• Email subscribe status for new contacts - Upon import, set the email channel subscribe status for new contacts to subscribed or none.
• Email subscribe status for existing contacts - Upon import, set the email channel subscribe status for existing contacts to subscribed or keep existing value.
• Also subscribe existing unsubscribed contacts - Upon import, existing contacts with unsubscribed email channel status will be subscribed. Becomes an available option if you choose to subscribe existing contacts. This is equivalent to using forceSubscribe parameter via contact imports API.

Adding 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)

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 the following:

Adding arrays

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

For example, 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""]"

Adding and removing 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:

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

Upload and import the data file

Once the data file is prepared, navigate to Contacts › Import Contacts

Click the New button and fill out the form.

• Import Source - select whether the source is a local file or hosted remotely.
• Header Row - select if your data file has a header row. The use of header row is recommended to make it easier to match the columns with their corresponding attributes when importing.
• Choose Delimiter - specify delimiter type.

Follow the prompts to upload the file and then map each column of the data file to the appropriate attribute.

For attributes and lists that already exist in the system with the same name as the header column, they should be automatically mapped.

For attributes that have a different name than the header column, use the dropdown labeled Choose to map to a previously created attribute in the system.

To create new attributes and lists, click + Attribute or + List to add a new one and map it accordingly.

You can also select the ignore checkbox to ignore the column entirely.

After mapping the appropriate fields, click continue and complete the import options.

Give the import a name and description (optional). The import name may only contain letters, numbers and dashes.

Select one of the import options:

• Import all contacts - insert new contacts and update existing contacts.
• Ignore new contacts - only update existing contacts.
• Ignore existing contacts - only insert new contacts.

Choose whether or not to suppress message triggers:

• True - do not send message though event trigger meets condition.
• False - send message if event trigger meets condition.

Choose whether or not to send an email notification when import is complete.

Click the Submit button to start the import.

You will be taken to the Jobs page where you can view the status of all import jobs.

Verify upload was imported without errors

To verify that the import was created without errors, hover over the arrow in the import row to see the details of the import job. If any contacts were rejected, you will have the option to download a list of these records. This file will show the line of the rejected record and an error message.

You can access the Jobs page at any time by clicking the  icon in the header bar of the application.

Importing Contacts on a Recurring Schedule

You have the option of importing contacts on a recurring schedule.

1. Navigate to Contacts › Import Contacts or Data › Data Automations › Import Contacts
2. For Import Source, choose HTTP/HTTPS, FTP, SFTP, S3 Amazon or Google Cloud.
3. For Schedule, choose Import on a recurring interval.
   Tip: Public key authentication can be used when the import source is SFTP.
   
4. For Source URL, enter the URL path for the data file.
   

   The input field supports Smarty so you are able to use Smarty variables in the URL path. For example, you could name your data file with the desired import date (contacts_10_20_2017.csv) and then use Smarty to render the current date in the Source URL at the time of import: contacts_{$utils->getNow('America/Los_Angeles', "Y-m-d")}. This example uses the $utils.getNow function so that the import is deployed according to the account timezone. If $smarty.now is used the time will be UTC. Learn more about date and timestamp variables.

5. Set the Schedule Interval to the desired interval.
   
6. Select the Start Date and optional End Date and click Continue.
7. Map the data file to the contact attributes.
   Note:

   • No data will be imported during data mapping.
   • If you schedule an import for a future date you will still need to map the data with a file that is immediately available on the designated server source.
8. After data mapping you will be taken to the Data Automations page where you can view, disable/enable or remove a scheduled import.

Import Contacts Via the API

You also have the option to import contacts via the API. Please read the article about importing contacts via the API to learn more.

Adding a Contact via JavaScript

Contacts can also be added via JavaScript listeners that reside on your website.

Learn more about JavaScript listeners.

In the next article learn how to export contacts.