Overview

The Contact Activity Export resource creates an export job to download and store a file of contact activities from the Cordial database to an external location.

• API Set Name: contactactivityexport

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.
• This resource is not a collection of exports. It's 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.

Due to the potential for large file size and processing time when exporting contact activities, it is recommended to test with smaller exports. To reduce file size, you can limit exports by date range, event name, message type, as well as chunk and compress files.

POST /contactactivityexport

Parameters

* Required

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

Cordial UI

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

FTP download

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

Amazon S3

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

We recommend omitting the trailing slash right after your S3 path name to avoid duplicate slashes being added by default. For example, use folder instead of /folder/.

Google Cloud Storage (GCS)

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.

Your Google Cloud Storage integration must be enabled in the Cordial Marketplace.

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

JSON file via FTP download

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

Some system and custom-named events (i.e. bounce, browse) may have additional properties (i.e. system_properties, category, product, etc.). You are able to export the values within the properties object using dot notation. For example: system_properties.bt, properties.category or properties.product.

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

Example request URI

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

http://<path>/contactactivityexport

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 Activity Export 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.