How can we help?

Search

Audience trends export API

Overview

The Audience Trends export resource creates an export job to download and store a file of audience trends data from the Cordial database. This endpoint is only available in the v2 API. 

  • API set name: audiencetrendsexport

Additional information

  • This resource uses the JSON request information to define the target host location of the file, the transport protocol, the external host log in 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 Cordial UI, click on the   icon at the top right of the application header.
  • Export supports file type "CSV".
  • Export files in the UI will be stored for 30 days from the date of the export.

POST /v2/audiencetrendsexport

Method URI Path
POST /v2/audiencetrendsexport
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. myfilename
exportType string Defines the type of file or report. Only csv is supported. csv

*destination

Note: This parameter is only required if SFTP, FTP, S3, or Google Cloud Storage (GCS) is used as the destination.
Note: Destination type "aws" should be used if the file is to be downloaded via the UI.
destination.type string Defines the destination type.
Possible Values:
AWS, FTP, SFTP, S3, GCS		 sftp

destination.server
(required if type is FTP or SFTP)

 string Domain or IP address of the FTP/SFTP server. sftp.example.com
destination.username
(required if type is FTP or SFTP)		 string Defines the username for FTP or SFTP authentication. username
destination.password
(required if type is FTP or SFTP)		 string Defines the password for FTP or SFTP authentication. password

destination.savedKey
(if using SFTP public key authentication instead of password)

 string SFTP public key authentication key name. myKeyName
destination.port
(required if type is FTP or SFTP)		 number Defines the port number for the FTP or SFTP server. 22
destination.aws_access_key_id
(required if type is S3)		 string Defines the public AWS access key ID. A1234567890
destination.aws_secret_access_key
(required if type is S3)		 string Defines the secret AWS access key. B1234567890
destination.aws_bucket
(required if type is S3)		 string Defines the AWS bucket name. bucketname
destination.aws_region
(required if type is S3)		 string Defines the AWS region. us-west-2
destination.path 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
destination.gcs_bucket string Defines the GCS bucket name. bucketname
selected_timeframe_start date Defines the export timeframe start day. 2021-08-17
selected_timeframe_end date Defines the export timeframe end day. 2021-08-20
audiences array Array of string audience names. Defines the audiences for which to export trends. ["opened_last_30_days", "clicked_last_30_days", "purchased_last_30_days"]


Example JSON requests

UI

The following will initiate an export job of a CSV file containing a column for each day in the selected timeframe and a row for each audience in the audiences array. The file will be downloadable via the UI on the Jobs page.

{
  "name": "audiencetrends",
  "exportType": "csv",
  "destination": {
    "type": "aws"
  },
  "selected_timeframe_start": "2021-07-16",
  "selected_timeframe_end": "2021-08-16",
  "audiences": [
    "audience1","audience2"
  ]
}

SFTP

The following will initiate an export job of a CSV file via SFTP containing a column for each day in the selected timeframe and a row for each audience in the audiences array. 

{
    "name": "audiencetrends",
    "exportType": "csv",
    "destination": {
        "type": "sftp",
        "server": "example.com",
        "port": "21",
        "username": "username",
        "password": "password",
        "path": "/"
    },
    "selected_timeframe_start": "2021-07-16",
    "selected_timeframe_end": "2021-08-16",
    "audiences": [
      "audience1","audience2"
    ]
}

Amazon S3

The following will initiate an export job of CSV file via Amazon S3. In this example, the file will be uploaded to s3://my_bucket/folder.  The file will contain a column for each day in the selected timeframe and a row for each audience in the audiences array. 

{
  "name": "audiencetrends",
  "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"
  },
  "selected_timeframe_start": "2021-07-16",
    "selected_timeframe_end": "2021-08-16",
    "audiences": [
      "audience1","audience2"
    ]
}

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

The following will initiate an export job of a CSV file via Google Cloud Storage (GCS).  The file will contain a column for each day in the selected timeframe and a row for each audience in the audiences array. 

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

{
    "name": "audiencetrends",
    "exportType": "csv",
    "destination": {
        "type": "gcs",
        "gcs_bucket": "bucketname",
        "path": "/audiencetrendsexport"
    },
    "selected_timeframe_start": "2021-07-16",
    "selected_timeframe_end": "2021-08-16",
    "audiences": [
      "audience1","audience2"
    ]
}

Example request URI

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

http://<path>/v2/audiencetrendsexport

Comments

0 comments

Please sign in to leave a comment.