How can we help?

Contact activity export API

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 CSV and JSON file types.
  • 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, we recommend that you 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

Method URI Path
POST /contactactivityexport
Creates an export job using the JSON body information.
  • * Required

    Parameter Type Description Example
    name string Defines the export file name. The name may only contain letters, numbers, and dashes. If provided, this value will be displayed next to the job ID on the Jobs page. 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. Input is ISO 08601 date format (e.g. YYYY-MM-DDThh:mm:ss). 2017-11-01T15:28:04.124Z
    selected_timeframe_end string End date and time of selected timeframe to be exported. Input is ISO 08601 date format (e.g. YYYY-MM-DDThh:mm:ss). 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 An array of message or custom events to be exported. For use when exporting more than one event.
    Possible values: message-sent, open, click, optout, bounce, complaint, custom
    open, click, bounce, optout
    selected_message_type string Defines the message type for which events are 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. Possible values: true, false

    true
    showHeader

    boolean

    For use when export type is CSV to determine if first row will display column names.
    Possible values: true, false
    true
    selected_message_id

    string

    Defines the message ID for which events are to be exported.
    Possible values: bmID or mdtID

    Note: When using selected_message_id to fetch events for a specific message/automation, you must also include selected_message_type to specify that the message ID is for either a batch or automated send.

    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. Default is "0". 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

    Export only the activities associated with the specified contact record.
    Possible values:
    A valid primary or secondary contact identifier value.
    email@example.com, ID1234, 16198880000
    selected_audience_key

    string

    Limit export results to a specific audience using a saved audience rule name. 30_Day_Engaged
    confirmEmail

    email

    Email address to send an administrative alert that the import job has been completed. msmith@example.com

    *destination

    1.) This parameter is only required if SFTP, FTP, S3, or Google Cloud Storage (GCS) is used as the destination. 2.) Destination type aws should be used if the file is to be downloaded via the UI. 3.) API calls for destination type S3 should be made using /v2/contactactivityexport.

    type string Defines the destination type.
    Possible values: aws, ftp, sftp, s3, gcs
    sftp

    server
    (required if type is FTP or SFTP)

    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
    For use when explicitly defining the output column headers. If no column headers are provided, the following default column headers will be included in the CSV output file. A JSON file type will export all column headers if none provided.

    • action
    • time
    • bmID
    • cID (or the default primary key for the account)
    name string Name of column in Cordial system. email
    label string Label for column which will be represented in file. Contact email

    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.

  • 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 under Integrations > Partners.

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

    For users of v1 POST/contactactivityexport, the following system names have been deprecated, but are still supported:
    • a
    • sp
    • ats
    • bmID
  • 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.

errorKey Message Modifications
CONTACT_ACTIVITY_EXPORT_MESSAGE_TYPE_NOT_SPECIFIED Field selected_message_type should be specified Please specify the message type.
CONTACT_ACTIVITY_EXPORT_ACTION_FILTER_CONFLICT Please use only one from existing filters selected_action_name OR selected_action_names Either the selected_action_name or selected_action_names filter may be used, but not both.
CONTACT_ACTIVITY_EXPORT_INVALID_ACTION_NAMES_FILTER Incorrect format for selected_action_names An array should be used for selected_action_names.
CONTACT_ACTIVITY_EXPORT_INVALID_ADDITIONAL_JSON_FIELDS Incorrect format for additionalJsonlFields An array should be used for additionalJsonIFields (only supported with JSON file type eports).
CONTACT_ACTIVITY_EXPORT_AUDIENCE_FILTER_CONFLICT Please use only one from existing filters selected_audience_key OR selected_contact Either the selected_audience_key or selected_contact filter may be used, but not both.
CONTACT_ACTIVITY_EXPORT_CONTACT_NOT_FOUND Such contact :selected_contact does not exist The contact identier value did not return an existing contact.
CONTACT_ACTIVITY_EXPORT_AUDIENCE_NOT_FOUND Audience with name :selected_audience_key does not exist The provided audience rule name did not return an existing audience.
CONTACT_ACTIVITY_EXPORT_INVALID_EXPORT_TYPE Field exportType should be specified The possible values for exportType are CSV and JSON.
CONTACT_ACTIVITY_EXPORT_END_TIME_MUST_BE_LATER_THAN_START_TIME selected_timeframe_end cannot be in past in comparison with selected_timeframe_start The provided end time must come after the provided start time.

Comments

0 comments

Please sign in to leave a comment.