Contact Imports

API Set Name: contactimports

• POST /contactimports

API Description and Functional Purpose:

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

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 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, XLS or XLSV.
• 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.

First row column headers must describe the data for that column.

Example CSV

channels.email.address,channels.email.subscribeStatus,ex-stng,ex-num,last-pur,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

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

Lists

Add or remove all contacts from a list or lists

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

{
	"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":["foo2"] 
  }
}

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

Contact profile data prior to import:

Note: "num-Y" is null.

Imported data:

Note: "date-x" is not included as an imported attribute. "string-Z" is included as an imported attribute and has a null value.

Contact profile data after import & update:

Note: "date-x" was not affected. "string-Z" is now null. "numY now has a value.

Example Request URIs

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

http://<path>/contactimports