How can we help?

Contact Imports API

Overview

The Contact Imports resource creates an import job to batch load a file of contacts into the Cordial database from an external location.

  • API Set Name: contactimports

Additional information

  • This resource uses the JSON request information to define the host location of the data file, the transport protocol, and the host login authentication information.
  • It is important to note that this resource is not a collection of imports, but it is a resource that initiates import processing by creating an import job.
  • Import status information is available through the jobs resource using the returned jobID.

Data file information

  • Permissible import file types include CSV, TSV, TXT.
  • Column headers need to be the key value for contact attributes, and the name or ID value for account lists.
  • Import files will be stored for 30 days from the date of the import. This does not impact the data that was uploaded.
  • The file is broken up into several files and imported simultaneously to lessen the total import time. File order is not preserved in this case.
Note: First row column headers must describe the data for that column.

Parameters

* Required

Column Headers Description Expected values
*channels.channelKey.address Column for contact channel address (e.g. channels.email.address). Note that some of your channels may have custom keys. Valid channel address
channels.channelKey.subscribeStatus Column for channel subscribe status. Note that for email, the subscribe status is set to "subscribed" by default if no value is passed. To ensure subscribe status is unchanged when updating existing contacts, set the subscribe parameter in the API call to "false". subscribed, unsubscribed, none
contact attribute key The contact attribute key value. string, date (ISO 8601), number
list name or ID The list assignment of the contact, true (1) or false (0). 1, 0 (boolean)

Example CSV

channels.email.address,channels.email.subscribeStatus,ex_stng,ex_num,ex_date,fr_name,Ex-List
test1@cordial.io,subscribed,test1,1,2/1/1970,Chris,1
test2@cordial.io,subscribed,test2,1,2015-04-21,Ted,1
test3@cordial.io,subscribed,test3,2,2/2/2015,Frank,1
test4@cordial.io,subscribed,test4,2,2015-01-19,Tom,1
test5@cordial.io,subscribed,test5,3,1997-02-17T05:21:41+00:00,Tony,1
test6@cordial.io,subscribed,test6,3,2015-02-05T02:05:17+00:00,Mike,0

Resource Associations

The following resource collections are associated to this collection.

Collection Association
contacts The contactimports resource creates contact documents/records in the contacts collection/resource.
Jobs The contactimports resource creates job documents/records in the jobs collection/resource.

POST /contactimports

Method URI Path
POST /contactimports
Creates an import job using the JSON body information.

Parameters

* Required

Parameter Type Description Example
job
importName string Import job name that will be displayed alongside the job ID in the Jobs Widget. May only contain letters, numbers, and dashes. Does not accept whitespaces. ContactImport-7-31
importDescription string Briefly describe the import job. The description will appear on the jobs page in Cordial. July summer sale participants.
confirmEmail email Email address to send an administrative alert that the import job has been completed. msmith@example.com
hasHeader
(required if columns is not included)
boolean Determines if the first row column headers will be present. Default is "false". If import file type is "JSONL", will be ignored. true

columns
(required if hasHeader is not explicitly set to true)

array Array of column headers, arranged by column positionally left to right. Using "" will ignore the entire column. If import file type is "JSONL", will be ignored. ["channels.email.address", " channels.email. subscribeStatus", "first"]
delimiter string Character used to break up columns in file. The default is "," if not specified. |
strategy updateOnly or insertOnly Insert only - only adds new records. updateOnly will only update existing records. If "undefined", the import will upsert (update and insert). The default is "undefined". insertOnly
suppressTriggers boolean If "true", will suppress any triggered messages set to fire based on updates to values in the import. Default is "true". false
forceSubscribe boolean If set to "true", will allow previously unsubscribed contacts to be updated as subscribed. Default is "false". false
subscribe boolean If set to "false", will not change current contact subscribeStatus. Default is "true" and will subscribe new contacts and contacts with subscribeStatus of none. true

nullMarker

string Defines the value to use for ignoring or skipping attribute updates.
Upon import, if an attribute contains the nullMarker value, then the attribute will be skipped or ignored. See example below.
ignore
*source object See parameters for source below. "source":{}
lists object See parameters for lists below. "lists":{}
source
*transport string Defines the transport method
Possible Values:
HTTP, HTTPS, FTP, SFTP, S3, GCS (Google Cloud Storage)
https
url
(required if transport = HTTP or HTTPS)
url URL or location of the import file. http://files.example.com/file.csv
port
(required if transport = FTP or SFTP, and not using default)
string The port number for the server. 44
server
(required if if transport = FTP or SFTP)
string Domain example.com
username
(required if if transport = FTP or SFTP)
string An account username for gaining access to the file location. myusername
password
(required if if transport = FTP or SFTP)
string The account password for the above user name. Msm1th$99!
savedKey
(if using SFTP public key authentication instead of password)
string SFTP public key authentication key name. myKeyName
path
(if transport = FTP, SFTP or S3, or GCS)
string Optional directory path to the file. /folder/file.csv
aws_access_key_id
(required if transport = S3)
string Defines the public AWS id. erg45g45hsdh
aws_secret_access_key
(required if transport = S3)
string Defines the secret AWS key. dudhKDDHE476383kdsdhdk
aws_bucket
(required if transport = S3)
string Defines the AWS bucket name. bucket-name
aws_region
(required if transport = S3)
string Defines the AWS region. us-west-2
bucket
(required if transport = GCS)
string Defines the bucket name if transport is Google Cloud Storage. Be sure to use the same name from the setup process in Cordial marketplace. name_used_in_marketplace_setup
lists
addTo
(required if list parameter  passed)
array All Contacts will be added to each list in the array. If you pass this parameter, you should not pass a column in the file with the same key. This field will always win. ["foo","bar"]
removeFrom
(required if list parameter passed)
array All Contacts will be removed from each list in the array. If you pass this parameter, you should not pass a column in the file with the same key. This field will always win. ["biz","baz"]
Note: If the CSV file has both "1" (true) and "0" (false) values for each contact for list "foo", and the request contains a lists object with instructions to add all contacts to "foo", then ALL contacts will be added to "foo" irrespective of the boolean values in the files column.  In other words, the lists object in the request will overrule the values set in the file itself.
Note: Regardless of strategy, if a contact in the database has a subscribe status of "none" and no value is passed for channels.email.subscribeStatus in the import file, then the subscribe status will be updated to "subscribed". To prevent a contact's subscribe status from being automatically updated, set the subscribe parameter in the JSON body to "false".
Note: It is necessary to pass the forceSubscribe parameter with a value of "true" in order to resubscribe contacts who have previously unsubscribed. If this parameter is missing a previously unsubscribed contact will not be subscribed even if the import file contains a column for channels.email.subscribeStatus.

Example JSON request for HTTP or HTTPS

The following will initiate an import job to load a CSV file from a secure HTTP location. A confirmation email will be sent to the email address provided once the job is complete. The JSON response will provide a job ID for checking job status if needed.

{  
   "source":{  
      "transport":"https",
      "url":"https://files.example.com/new_data.csv"
   },
   "columns":[  
      "channels.email.address",
      "channels.email.subscribeStatus",
      "first"
   ],
   "confirmEmail":"msmith@example.com"
}

Example JSON request for FTP or SFTP

The following will initiate an import job to load a CSV file via a secure FTP connection on port 44 (not the default). A confirmation email will be sent to the provided email address once the job is complete. The JSON response will return a job ID for checking job status if needed.

{  
   "source":{  
      "transport":"sftp",
      "port":"44",
      "server":"example.com",
      "username":"myusername",
      "password":"Msm1th$99!",
      "path":"/files/file.csv"
   },
   "hasHeader":true,
   "confirmEmail":"msmith@example.com"
}

Example JSON request for S3

The following will initiate an import job to load a CSV file via a secure S3 connection. A confirmation email will be sent to the provided email address once the job is complete. The JSON response will return a job ID for checking job status if needed.

{
   "source":{
      "transport":"s3",
      "aws_access_key_id":"AAAAAAAAAAAAAAAAAAAA",
      "aws_secret_access_key":"dudhKDDHE476383kdsdhdkasKDHDKDeiuealskjD",
      "aws_bucket":"a-bucket",
      "aws_region":"us-west-2",
      "path":"folder/contacts.csv"
   },
   "hasHeader":true,
   "confirmEmail":"msmith@example.com"
}

Example JSON Request for Google Cloud Storage

The following will initiate an import job to load a CSV file via a secure GCS connection. A confirmation email will be sent to the provided email address once the job is complete. The JSON response will return a job ID for checking job status if needed.

{
   "source":{
      "transport":"gcs",
      "bucket":"same_name_used_in_marketplace_setup",
      "path":"/folder/file.csv"
   },
   "hasHeader":true,
   "confirmEmail":"msmith@example.com"
}

Example Request URI

The following URI in conjunction with the JSON will perform the POST.

http://<path>/contactimports

Lists: add or remove all contacts from a list or lists

See the example below. The "lists" object will add all contacts in the imported file to lists "foo" and "bar". It will also remove all contacts in the imported file from the list "biz".

{
   "source":{
      "transport":"https",
      "url":"https://files.example.com/new_data.csv"
   },
   "columns":[
      "channels.email.address",
      "channels.email.subscribeStatus",
      "first"
   ],
   "confirmEmail":"msmith@example.com",
   "delimiter":"|",
   "lists":{
      "addTo":[
         "foo",
         "bar"
      ],
      "removeFrom":[
         "biz"
      ]
   }
}
Note: If the CVS file has both "1" (true) and "0" (false) values for each contact for list "foo", and the request contains a "lists" object with instructions to add all contacts to "foo", then ALL contacts will be added to "foo" irrespective of the boolean values in the files column.  In other words, the "lists" object in the request will overrule the values set in the file itself.

Examples of how updates are handled

When updating a contact record:

  • If providing an attribute key with a value, the attribute will be updated with the new value in the database.
  • If providing an attribute key with an empty string, the attribute will be updated with the empty string in the database.
  • If providing an attribute key with a nullMarker value, the attribute will be skipped and not updated in the database.
  • If an attribute key is not provided, the attribute will be skipped and not updated in the database.

Note in the CSV example below:

  • The first_name attribute with the value "Bill" will update the attribute in the database to "Bill".
  • The pet_name attribute with the defined nullMarker value "ignore" will ignore updating the attribute and leave it as "Sparky" in the database.
  • The pet_breed attribute with an empty string value will update the attribute in the database to an empty string.

Example contact record before import

{
   "channels":{
      "email":{
         "address":"email@example.com"
      }
   },
   "first_name":"Fred",
   "pet_name":"Sparky",
   "pet_breed":"Poodle"
}

Example CSV to be imported

Note: In this example, the nullMarker parameter value was defined as "ignore".
"channels.email.address","first_name","pet_name","pet_breed"
"email@example.com","Bill","ignore",""

Example contact record after import

{
   "channels":{
      "email":{
         "address":"email@example.com"
      }
   },
   "first_name":"Bill",
   "pet_name":"Sparky",
   "pet_breed":""
}

Error responses

The Cordial API will return an error object with an errorKey and message if there is a problem with an API call. Below is a list of errors specific to the Contact Imports API endpoint, along with suggested modifications to resolve each error. If you receive an error from this API endpoint that is not listed in this table, it is likely recorded within the Global API Error Responses page.

errorKey Message Modifications
CONTACT_IMPORT_BULK_FILES_NOT_ALLOWED Multiple import supported only in Data Job Automations. Multiple import is only supported in Data Job Automations.
SSH_KEY_NOT_FOUND SSH key with such Name/ID: :key does not exist. The SSH key provided does not exist.

Comments

0 comments

Please sign in to leave a comment.