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.

Parameters

* Required

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.

POST /contactimports

Parameters

* Required

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"
      ]
   }
}

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

"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.