Export API overview

The data API

The data API allows you to call data from the Engaging Networks servers over a secure connection. The export can be called from a web form that requests account authentication (using a private token set in the subaccount admin dashboard), can be automatically transferred to your server via secure copy (SCP), or by calling the data remotely using an HTTPS GET request. There are a number of parameters that can be set, including:

File format

The file contents will reflect any customization options you have specified through the Data API menu in your user dashboard.

standardcsv

csv file

The export file will be in a standardized format, common to all clients. Apart from campaign and contact reference names, any customization options specified in the Data API menu will be ignored, and tagged form data fields will be exported in our standard order.

xml

xml feed

The contents of the feed will reflect any customization options you have specified through the Data API menu in your user dashboard.

standardxml

xml feed

The contents of the feed will be in a standardized format, common to all clients. Apart from campaign and contact reference names, any customization options specified in the Data API menu will be ignored, and tagged form data fields will be exported in our standard order.

custom filter name

Custom

If a special export filter has been custom-built for your account, it can be invoked by entering the custom filter name as the ‘type’ field. The format of the resulting file will depend on the specifications of your custom export filter.

We will look at the ‘csv/standardcsv’ format in some detail. One row of transaction data is exported for each supporter activity that has taken place in the chosen date range.

The export file can broadly be divided into three sections, shown schematically below:

Common transaction data segments – this section contains data columns that are common to all transaction types, such as supporter ID, time of activity, activity reference name/ID.

Activity-specific transaction data segments – for each data row,the contents of this section will depend on the specific type of activity the row relates to. For example:

The last few columns of this section contain technical/tracking data for those records that relate to a page being accessed (e.g. e-activist actions or donation pages).

For details of all columns for all activity types, please see the provided spreadsheet.

Default data segments – this section will either consist of:

(a) ‘csv’ export type - default data columns as set up in Default Supporter Record, or a subset of these columns if an export group has been selected (see ‘customisation via dashboard’, below). In this case the total number of columns will therefore vary from client to client.

Export Version Name should be left as Version 2, the most up-to-date and comprehensive export version. Version 1 is included for backward compatibility for clients that have been using the API export for some time

Engaging Networks' transactional export file format is pre-defined with header names and columns. The settings here allow you to amend the column names or to exclude them entirely from the export.

You can also enable/disable all supporter data columns (under User Data). Additionally, you can set up your External Reference columns here.

Note: This is a global change, so please confirm this is correct for your data requirements.

Automate export

This allows you to activate a regular auto-run of the export, with the file transferred to a remote SCP server, running daily, every three days, weekly or monthly.

PLEASE NOTE:

The protocol used for secure auto-export is Secure Copy (SCP) over SSH – please ensure that your destination server has SCP transfer enabled before initiating the export in Engaging Networks.

The host name for your destination server. The format for the field should be : if your destination is ‘servername.com’ and you want to use secure copy, you should type ‘scp:servername.com’. You can also have the export service place the file in a subfolder on your destination server, for example ‘scp:servername.com/subfolder’We strongly recommend that you use the secure method if you are exporting supporters’ personal data.

You can also set a future date on which to start the regular auto-export sequence.

Override page name

This provides a listing of all pages, emails and questions/opt-ins in your account, split between four tabs. You are able to assign a new name for each item. The name or value entered will be the value exported in the ‘Campaign ID’ column in the transactional data export instead of its reference name in the software

Manage Contact Types

This displays a list of all contacts available in your account: shared contact databases, single contacts, single contact groups, and client contact databases. The listings are presented using this same category structure. You can to enter a name or value to represent these contact types. The names or values entered will be exported into ‘Campaign Data 4’ for an ‘email to target’ action only.

Transaction Types

This allows you to select which types of campaign type you want to include in the transactional export. You can select or unselect. For a list of campaign types click here.

Apply File Filters

This gives you the ability to filter your records based on supporters’ responses to opt-in questions, eg you can choose to exclude any records pertaining to supporters who have chosen not to opt in.

Setting up a basic export

This step is only required if you are exporting the data via HTML web form, or calling the data using a custom-written client application on your server. The key is not required for automated ftp transfer.

Log into your subaccount admin dashboard (as opposed to the subaccount user dashboard) and navigate to ‘marketing > tokens’. The token needed for the export API is the ‘private’ key. One private key can be created for each account user. Please note that if any private token has already been created in the account, deleting or re-generating the token will prevent any process using the old version of that token from working. It is important to protect your private token as you would your username and password combination, as it gives access to your supporter data.

Optionally set up any customisation in the export service tab in your user account dashboard. Please see the detailed individual help documents for more information. For a basic, default formatted export, no customisation options need to be set.

Automated SCP export method

In your user account dashboard, navigate to the Data & Reports > API Options > Automate Export. Fill in the required fields as detailed above and submit the page. Your recurring export will be scheduled, based on your selected export frequency and start date, and will appear as a task on your jobs monitor page.

HTML form export method

It is not necessary to be logged into your account. Make sure the URL begins with https to ensure secure transfer. Enter your private token and optional parameters as shown on the page, and submit the form – the export will be called, and after a short pause will be downloadable via your web browser. Due to the limitations of the https protocol, exports containing very large amounts of data should not be called via this method. Note that the method can only pull data from the past 31 days.

It is also possible to write a client application, in a programming language of your choice, in order to call the data service by sending an https GET request to our server. The volume limitation due to use of the https protocol and the 31-day limit apply to this method also.