API Set Name: contactexports
API Description and Functional Purpose:
The contactexports resource creates an export job to download and store a file of contacts from the Cordial database.
- This resource uses the JSON request information to define the target host location of the file, the transport protocol, the external host login authentication information and the fields to include in the file.
- It is important to note that this resource is not a collection of exports, but is a resource that initiates export processing by creating an export job.
- Export status information is available through the jobs resource.
- Options for export file types include CSV, XLS or XLSX.
- Export files will be stored for 30 days from the date of the export.
|Creates an export job using the JSON body information.|
|* exportType||string||Defines the type of file or report. Options include CSV, XLS or XLSX.||csv|
|name||string||Defines the name of file.||contactsExport|
|fields||string||An array of system fields or contact attributes keys.||["first_name","last_name"]|
|lists||array||An array of lists IDs or list names to be returned. If contact is on list they will get a value of 1 otherwise 0.||["monthly_newsletter","weekly_specials"] or [8756,8757]|
|audience-key||string||The audience key that represents a saved audience rule.||30_day_engaged|
|showHeader||string||If true, will add headers as the first row of the output file. The default is false.||true|
|compress||boolean||Compresses the exported file. If value is "true", the file is compressed using GZIP with the file extension ".gz" added to the filename.||true|
Note: This parameter is only required if SFTP, FTP or S3 is used as the destination. If this parameter is not supplied, the exported file can be downloaded through the ui.
|type||string||Defines the destination type. Currently this option is limited to SFTP, FTP or S3.||sftp|
server (required if type is FTP or SFTP)
|string||Domain or ip address of the SFTP server.||sftp.example.com|
|username (required if type is FTP or SFTP)||string||Defines the username for FTP or SFTP authentication.||username|
|password (required if type is FTP or SFTP)||string||Defines the password for FTP or SFTP authentication.||password|
|port (required if type is FTP or SFTP)||number||Defines the port number for the FTP or SFTP server.||22|
|aws_access_key_id (required if type is S3)||string||Defines the public AWS id.||A1234567890|
|aws_secret_access_key(required if type is S3)||string||Defines the secret AWS key.||B1234567890|
|aws_bucket (required if type is S3)||string||Defines the AWS bucket name.||bucket|
|aws_region (required if type is S3)||string||Defines the AWS region.||us-west-2|
|path||string||If type is S3: path to folder and file. If type is FTP or SFTP: path to folder.||S3: /folder/contactsExport.csv FTP: /folder|
- If no
listsparameters are passed (or passed with empty array values), all fields and lists will be returned in the file.
- If the
listsparameter is passed with array values, and no
fieldsparameter is passed (or passed with empty array values), the email field and designated list values will be returned in the file.
Example JSON Requests
The following will initiate an export job of a CSV file containing all contacts and all fields, downloadable via the UI on the Jobs page.
The following will initiate an export job of a CSV file via SFTP containing all contacts and 2 fields.
"fields": ["channels.email.address", "first_name"]
The following will initiate an export job of all contacts in the 30_day_engaged audience, 2 fields and 2 lists into a CSV file via S3.
"fields": ["channels.email.address", "channels.email.subscribeStatus"],
"lists": ["monthly_newsletter", "first_name"]
Example Request URIs
The following URI in conjunction with the JSON will perform the POST.