Overview

The contact exports resource creates an export job to download and store a file of contacts from the Cordial database.

API set name: contactexports

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 it 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/contactexports

• * 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 Widget page.	contactsExport
  exportType	string	Defines the type of file or report. Possible Values: CSV, JSON	csv
  fields	string	An array of system fields or contact attribute keys.	["first_name","last_name"]
  lists	array	An array of lists IDs or list names to be returned. Contacts' list association is indicated with a value of "1" if they are on the list or "0" if they are not on the list.	["monthly_newsletter","weekly_specials"] or [8756,8757]
  audience-key	string	Limits export results to a specific audience from a saved audience rule name.	30_day_engaged
  showHeader	string	Determines if the first row will display column names when export file type is CSV. The default is false. Possible Values: true, false	true
  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.	true
  confirmEmail	email	Email address to send an administrative alert when the import job has been completed.	msmith@example.com
  *destination This parameter is only required if SFTP, FTP, S3, or Google Cloud Storage (GCS) is used as the destination. Destination type "aws" should be used if the file is to be downloaded via the UI.
  type	string	Defines the destination type. PossibleValues: 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
  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
  savedKey (if using SFTP public key authentication instead of password)	string	SFTP public key authentication key name.	myKeyName
  port (required if type is FTP or SFTP)	number	Defines the port number for the FTP or SFTP server.	22
  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.	bucketname
  aws_region (required if type is S3)	string	Defines the AWS region.	us-west-2
  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
  gcs_bucket	string	Defines the GCS bucket name.	bucketname

1.) If no fields or lists parameters are passed (or passed with empty array values), all fields and lists will be returned in the file. 2.) If the lists parameter is passed with array values, and no fields parameter is passed (or passed with empty array values), the email field and designated list values will be returned in the file.

Examples

• The following will initiate an export job of a CSV file containing all contacts and all fields, downloadable via the UI on the Jobs page.

  {
      "exportType": "csv",
      "name": "contactExport",
      "destination": {
          "type": "aws"
      },
      "showHeader": true,
      "confirmEmail": "msmith@example.com"
  }

• The following will initiate an export job of a CSV file via SFTP containing all contacts and two fields.

  {
      "exportType": "csv",
      "name": "contactExport",
      "destination": {
          "type": "sftp",
          "server": "example.com",
          "port": "21",
          "username": "username",
          "password": "password",
          "path": "/"
      },
      "showHeader": true,
      "fields": [
          "channels.email.address",
          "first_name"
      ],
      "confirmEmail": "msmith@example.com"
  }

• The following will initiate an export job of all contacts in the "30_day_engaged" audience, 2 fields and 2 lists into a CSV file via Amazon S3. In this example, the file will be uploaded to s3://my_bucket/folder.

  {
    "exportType": "csv",
    "name": "myExportFilename",
    "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,
    "audience-key": "30_day_engaged",
    "fields": [
      "channels.email.address",
      "channels.email.subscribeStatus"
    ],
    "lists": [
      "monthly_newsletter",
      "first_name"
    ],
    "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/.

• The following will initiate an export job of a CSV file of all contacts in the "engaged-march" audience via Google Cloud Storage (GCS).

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

  {
      "exportType": "csv",
      "name": "contactExport",
      "destination": {
          "type": "gcs",
          "gcs_bucket": "bucketname",
          "path": "/contactexports"
      },
      "showHeader": true,
      "audience-key": "engaged-march",
      "confirmEmail": "emsmith@example.com"
  }

Example request URI

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

http://<path>/contactexports