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. |
|||
destination.type | string | Defines the destination type. Possible Values: AWS, FTP, SFTP, S3, GCS |
sftp |
destination.server |
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 |
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.