API Set Name: contactactivityexport
- POST /contactactivityexport
Make the export file available via: - Example Request URIs
API Description and Functional Purpose:
The contactactivityexport resource creates an export job to download and store a file of contact activities from the Cordial database to an external location.
Additional information:
- 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. To access the Jobs page via UI, click on the icon at the top right of the application header.
- Export supports file types "CSV" and "JSON".
- Export files in the UI will be stored for 30 days from the date of the export.
POST /contactactivityexport
Method | URI Path |
---|---|
POST | /contactactivityexport |
Creates an export job using the JSON body information. |
Parameters
* Required
Parameter | Type | Description | Example |
---|---|---|---|
name | string | Defines the export file name. The name may only contain letters, numbers, and dashes. | ExportClickEvents |
*exportType | string | Defines the type of the file to be exported. If value is JSON and no columnHeaders are specified, all columns will be exported. Possible Values: CSV, JSON |
JSON |
selected_timeframe_start | string | Start date and time of selected timeframe to be exported. | 2017-11-01T15:28:04.124Z |
selected_timeframe_end | string | End date and time of selected timeframe to be exported. | 2017-11-03T15:28:04.124Z |
selected_action_name | string | Defines the message or custom event to be exported. For use when exporting a single action type. Possible Values: message-sent, open, click, optout, bounce, complaint, custom |
open |
selected_action_names | array | Defines an array of message or custom events to be exported. For use when exporting an array of action types. Possible Values: message-sent, open, click, optout, bounce, complaint, custom |
open, click, bounce, optout |
selected_message_type | string | Defines the message type events to be exported. Possible Values: batch, automation |
batch |
showAllProperties | boolean |
For use when selected_action_name is supplied (ex: bounce). When true, will export columns for all event system properties. Event system properties can also be defined in the ColumnHeaders object. |
true |
showHeader | boolean | For use when export type is "CSV" to determine if first row displays column names. Possible Values: true, false |
true |
selected_message_id | string | Defines the message ID to be exported. Possible Values: bmID or mdtID |
45:5a7d2a3cc7280b410:ot |
limitRecordsPerFile | integer | Defines the number of records per file chunk to be exported. If no value is passed, all records that match the filters will be exported to one file. | 500000 |
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(s). See note below table regarding file availability. Possible Values: true, false |
true |
selected_contact | string | Defines the contract for the associated records to be exported. Possible Values: A valid primary or secondary contact identifier value. |
email@example.com, ID1234, 16198880000 |
selected_audience_key | string | Defines the audience rule for the associated records to be exported. | vip_members |
confirmEmail | Email address to send an administrative alert that the import job has been completed. | msmith@example.com | |
*destination Note: This parameter is only required if SFTP, FTP, S3, or Google Cloud Storage (GCS) is used as the destination. |
|||
type | string | Defines the destination type. Possible Values: aws, ftp, sftp, s3, gcs |
sftp |
server |
string | Domain or IP address of the SFTP server. | sftp.example.com |
port (required if type is FTP or SFTP) |
number | Defines the port number for the FTP or SFTP server. | 22 |
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 |
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 (required if type is FTP, SFTP, s3, or GCS) |
String | If type is S3: path to folder and file. If type is FTP, SFTP, or GCS: path to folder. | S3: /folder/contactsExport.csv, FTP: /folder, GCS: /folder |
gcs_bucket | string | Defines the GCS bucket name. | bucketname |
columnHeaders
|
|||
name | string | Name of column in Cordial system. | |
label | string | Label for column which will be represented in file. | Contact Email |
Note: When destination type is "S3", and if compress value is false and limitRecordsPerFile is set, each chunk will be uploaded as soon as it's ready. If compress value is true and limitRecordsPerFile is set, all chunks will be uploaded together when the export is complete.
Example JSON Requests
The following will initiate an export job of all batch message sent activities for March 25 into a CSV file that will be available via the UI on the Jobs page.
{ "name": "activities_batch_march25", "exportType": "csv", "destination": { "type": "aws" }, "showHeader": true, "selected_timeframe_start": "2019-03-24T00:00:00.000Z", "selected_timeframe_end": "2019-03-25T23:59:59.999Z", "selected_message_type": "batch", "selected_action_name": "message-sent", "compress": false, "confirmEmail": "msmith@example.com" }
The following will initiate an export job of all batch message sent activities for March 25 into a CSV file via FTP download.
{ "name": "batch-30days", "exportType": "csv", "destination": { "type": "ftp", "server": "ftp.example.com", "port": 21, "username": "cordial@example.com", "password": "cordial", "path": "./" }, "showHeader": true, "selected_timeframe_start": "2019-03-24T00:00:00.000Z", "selected_timeframe_end": "2019-03-25T23:59:59.999Z", "selected_action_names": [ "message-sent", "open", "click" ], "selected_message_type": "batch", "compress": false, "confirmEmail": "msmith@example.com" }
The following will initiate an export job of all batch message sent activities for March 25 into a CSV file via Amazon S3. In this example, the file will be uploaded to s3://my_bucket/folder
.
{ "name": "activities_batch_march25", "exportType": "csv", "destination": { "type": "s3", "aws_access_key_id": "A1234567890", "aws_secret_access_key": "B1234567890", "aws_bucket": "my_bucket", "aws_region": "us-west-2", "path": "folder" }, "showHeader": true, "selected_timeframe_start": "2019-03-24T00:00:00.000Z", "selected_timeframe_end": "2019-03-25T23:59:59.999Z", "selected_message_type": "batch", "selected_action_name": "message-sent", "compress": false, "confirmEmail": "msmith@example.com" }
folder
instead of /folder/
.The following will initiate an export job of all batch message sent activities for March 25 into a CSV file via Google Cloud Storage (GCS). The file will have the following column headers labels: Action, Contact Email and Contact ID.
{ "name": "activities_batch_march25", "exportType": "csv", "destination": { "type": "gcs", "gcs_bucket": "bucketname", "path": "/contactactivities" }, "columnHeaders": [ { "name": "action", "label": "Action" }, { "name": "email", "label": "Contact Email" }, { "name": "cID", "label": "Contact ID" } ], "showHeader": true, "selected_timeframe_start": "2019-03-24T00:00:00.000Z", "selected_timeframe_end": "2019-03-25T23:59:59.999Z", "selected_message_type": "batch", "selected_action_name": "message-sent", "compress": false, "confirmEmail": "msmith@example.com" }
The following will initiate an export job of all bounce events into a JSON file via FTP download. Note that each record is returned as a separate line consisting of a single JSON object (not an array of JSON objects).
{ "name": "bounce-30days", "exportType": "json", "destination": { "type": "ftp", "server": "ftp.example.com", "port": 21, "username": "username@example.com", "password": "password", "path": "./" }, "selected_timeframe_start": "2018-02-01T00:00:00.000Z", "selected_timeframe_end": "2018-02-27T23:59:59.999Z", "selected_action_name": "bounce", "showAllProperties":false, "compress": false,
"confirmEmail":"msmith@example.com", "columnHeaders": [ { "name": "_id", "label": "_id" }, { "name": "action", "label": "action" }, { "name": "email", "label": "email" }, { "name": "cID", "label": "cID" }, { "name": "bmID", "label": "msID" }, { "name": "mcID", "label": "mcID" }, { "name": "mdtID", "label": "mdtID" }, { "name": "time", "label": "time" }, { "name": "first", "label": "first" }, { "name": "message_name", "label": "message_name" }, { "name": "system_properties.bt", "label": "system_properties_bt" }, { "name": "system_properties.link", "label": "system_properties_link_key" }, { "name": "system_properties.rl", "label": "system_properties_redirect_link" }, { "name": "properties.custom_per_client_and_not_required", "label": "properties_custom_per_client_and_not_required" } ] }
Learn how to add send properties to your export job.
- a
- sp
- ats
- bmID
Example Request URIs
The following URI in conjunction with the JSON will perform the POST.
http://<path>/contactactivityexport
Comments
0 comments
Please sign in to leave a comment.