API Set Name: 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.
- 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.
Parameters
* Required
Column Headers | Description | Expected values |
---|---|---|
*channels.email.address | Email address of the contact. | Valid email address |
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) |
channels.email.subscribeStatus | Subscribe status of the contact. Note that subscribe status is set to "subscribe" 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 |
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.
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 | |||
confirmEmail | 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 | Denotes the first row column headers are present, default is false | true |
columns (required if hasHeader is not explicitly set to true) |
array | Array of column headers, ordered by column positionally left to right, using "" will ignore the entire column | ["channels.email.address", " |
delimiter | string | Character used to break up columns in file. The default is "," if not provided. | | |
strategy | updateOnly or insertOnly | Insert only - only adds new records. updateOnly will only update existing records. If undefined the import will insert and update. 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. Defaults to true. | false |
forceSubscribe | boolean | If set to true, will allow previously unsubscribed contacts to be updated as subscribed. Defaults to false. | false |
subscribe | boolean | If set to false, will not change current contact subscribeStatus. Defaults to 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 (i.e. ignore), 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! |
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 | public aws id | erg45g45hsdh |
aws_secret_access_key (required if transport = S3) |
string | secret aws key | dudhKDDHE476383kdsdhdk |
aws_bucket (required if transport = S3) |
aws bucket name | some-bucket | |
aws_region (required if transport = S3) |
string | 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 |
list | |||
addTo (required if list parameter passed) |
array | All Contacts will get 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 get 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"] |
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" }
Example JSON Request for Google Cloud Storage
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": "gcs", "bucket": "same_name_used_in_marketplace_setup", "path": "/folder/file.csv" }, "hasHeader": true, "confirmEmail": "msmith@example.com" }
Example Request URIs
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 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 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": "" }
Comments
0 comments
Please sign in to leave a comment.