Using Pull API aggregate data – The Enterprise Integration Desk

At a glance: Use URIs to get your ZendeskConnect aggregate reports in CSV files.

Are you looking for Pull API raw data?

Pull API aggregate data characteristics

Reports return as CSV files.
Data freshness rates are the same as the equivalent report on the Export Data page.
Filter by options available: Media source and date range.
Additional capabilities in Pull API are:
- Ability to filter by attribution touch type
- Selectable timezone
Pull API is suited to use by team members and BI developers;
- Team members get reports by pasting URIs in their browser. The URI templates are available in the Dashboard. Go to Integration > API access.
- BI developers get reports by embedding the URIs in scripts.

Example URI template

Aggregate performance reports available via Pull API
Category	UA	Retargeting*	Protect360
Partners (media source)	✓	✓	✓
Partners by date	✓	✓	✓
Daily	✓	✓	✓
Geo	✓	✓	✓
Geo by date	✓	✓	✓
* For retargeting reports, add the `&reattr=true` to the URI.

Terminology

Term	Description
Pull API	Solution for downloading CSV reports using URIs.
API call or call	Sending the URI to ZendeskConnect by pasting it in the browser address bar or by using scripts.
URI	Uniform resource identifier similar to a web address (URL) containing the report specification. Template URIs are available on the API page in the Dashboard.

Guide for team members

About URI templates

URI templates available in the dashboard are populated with the app ID and report type.
They have placeholders for the API V1.0 token and from/to dates which you must edit.
The portion of the URI to the right of the question mark (?) contains parameters. Each parameter begins with an ampersand (&). Parameters are used to set filters, specify additional fields to be included, currency, and timezone. For example, in aggregate reports to limit (filter by) a specific media source, use the media_source parameter: &media_source=facebook
To get a better understanding of Pull API, complete the tutorial that follows.

Getting your first Pull API report tutorial

Before you begin:

Ask the admin to provide you with the V1.0 token.

To download a report from the dashboard:

Go to Integration > API access.
The API access page opens.
Select a report type. For example, Performance reports > Partners daily report.
The URI template displays.
Copy the URI by clicking on it.
Open a new tab in your browser, paste the URI.
Edit the URI:
1. Replace the token placeholder with the Pull API token provided by the admin.
  Example: Replace the token placeholder so that &api_token=12345678-1234-1234-1234-123456789012 Note! There are no spaces or other punctuation.
2. Replace the from/to placeholders with dates.
  Example: &from=2020-01-20&to=2020-01-31 Note! There are no spaces. Don't delete the &.
Click <Enter> to send the API call.
The report downloads.
Additional parameters can be set to customize reports, for example, select a specific media source, to return retargeting data, etc. The section that follows contains the list of parameters available.

Aggregate data Pull API parameters

Aggregate report URI and parameters

Aggregate URI mandatory parameters
Parameter	Description
api_token	V1.0 API token. In example calls, this is shown as: <API TOKEN HERE>.
from	The date range consists of a `from`and `to` parameter. The range is the LTV (install) date range. Format: `yyyy-mm-dd`, Example: 2010-01-01 or 2010-01-01
to	End date. As for `from`

Aggregate data optional filtering and display parameters excluding Protect360 reports
Parameter	Description
media_source	Use to limit (filter) to a specific media source. Example:`media_source=facebook`
attribution_touch_type	Set this parameter as shown in the example to get view-through attribution (VTA) KPIs. Example: `attribution_touch_type=impression`
currency	Currency of revenue and cost. Aggregate Pull API reports always use the app-specific currency.
reattr	Get retargeting conversions data. [Default] If false, user acquisition data (UA) campaigns returns. If true, retargeting conversion returns. Example:`reattr=true`
timezone	[Default] Data returns using UTC. Template URIs are populated with the timezone parameter set to the app-specific time zone. [Default] If the parameter is not sent, data returns using UTC. If you send`timezone=[Joda-Time]`, data returns using the app-specific time zone. Notes about selecting timezones Joda-Time time zone format takes into account daylight saving time. The Joda-Time value must be identical to the value in the app settings page. For example, if the timezone setting is Paris, the timezone value in the Pull API URL should be `timezone=Europe%2fParis`. Pulling data in the selected time zone is only available from the date when the time zone setting was made. Any data prior to the date of the change uses UTC as the timezone.

Google Ads filtered report

https://hq.appsflyer.com/export/com.greatapp/partners_report/v5?api_token=xxxx
&from=2018-04-09&to=2018-05-09&media_source=googleadwords_int

Facebook filtered report

https://hq.appsflyer.com/export/com.greatapp/partners_report/v5?api_token=xxxx
&from=2018-04-09&to=2018-05-09&media_source=facebook

Optional parameters for Protect360 reports
Parameter	Description
URI	Ge the Protect360 URI from the dashboard. Modify the URI as described here.
pid	To filter the report by a specific media source use the `pid`parameter. For example, to get the data of abc_net, `pid=abc_net`.
timezone	Selects the timezone used to return data. If timezone is not sent, data is returned using UTC. Templates including the timezone parameter. Example: `timezone=preferred`: Use to get data using the app-specific timezone.
KPIs	Protect360 parameters are the same in Pull API and Master API. List of KPIs and descriptions Example: `kpis=protect360_total_installs,blocked_installs_rate`

View-through attribution (VTA) KPIs

To get the VTA KPIs, add the parameter attribution_touch_type=impression to the Pull API aggregate report URI as detailed in the example.
You can use the parameter with any of the aggregate reports available. Just copy the URI from the user interface, and append the parameter.
You can also add the &media_source parameter to limit the report to a specific media source as depicted in the example that follows.
Some VTA KPIs, like clicks, impressions, and cost APIs, don't have values associated with them and display the value N/A instead.

Example	Example URI
VTA only	`https://hq.appsflyer.com/export/{app_id}/partners_report/v5?api_token={API token}&from=yyyy-mm-dd&to=yyyy-mm-dd&attribution_touch_type=impression`
VTA and media source	`https://hq.appsflyer.com/export/{app_id}/partners_report/v5?api_token={API token}&from=yyyy-mm-dd&to=yyyy-mm-dd&attribution_touch_type=impression&media_source=example_ad_network`

Pull API for developers

Principles of implementation

Prerequisite:

Familiarize yourself with the Pull API guide for team members.

Consider:

For each report type available, there is a template URI in the dashboard. Go to Integration > API access.
You modify the template to get the data you need, for example, by setting date ranges and filter by parameters.
The parameters for raw data and aggregate data reports differ and are detailed in the report sections.

Pull API basics
Path	`https://hq.appsflyer.com/export/app_id/report_type/v5`
Path parameters	`app_id` App identifier as found in ZendeskConnect. Insert the app ID exactly as found in ZendeskConnect. Prefix iOS apps with id `report_type` Defines the type of report. The list of reports and the associated URIs are in the dashboard. Go to Integration > API access.
HTTP method	`GET`

Mandatory query parameters
Parameter	Description
Example URI	`GET 'https://hq.appsflyer.com/export/app_id/installs_report/v5? from=2020-01-01?&to=2020-01-10&api_token=api_token&currency=preferred`
api_token	`api_token`: Pull API token for authentication Get the API token in the Dashboard If you change the account admin, the token changes, and you must update scripts with the new token. `api_token=`
Other parameters	Parameters differ depending Aggregate report parameters Raw data parameters Protect360 post attribution raw data fraud parameters

Example

URI call example includes additional parameters:

https://hq.appsflyer.com/export/example.app.com/installs_report/v5?
        api_token={Account owner API key should be used}&from=yyyy-mm-dd
&to=yyyy-mm-dd&additional_fields=keyword_id,store_reinstall,
deeplink_url,oaid,install_app_store,contributor1_match_type,
contributor2_match_type,contributor3_match_type,match_type

Example scripts

Integrate Pull API into scripts to retrieve data.

As needed, edit the scripts in terms of report type, date range, and filters.
These examples use the install report.

import okhttp3.*;

import java.io.BufferedWriter;
import java.io.FileWriter;

import java.util.concurrent.TimeUnit;

public class PullApi {
  public static void main(String[] args){

    String appID = "<APP_ID>";
    String reportType = "<REPORT_TYPE>";
    String apiToken = "<API_TOKEN>";
    String from = "<FROM_DATE>";
    String to = "<TO_DATE>";
    String requestUrl = "https://hq.appsflyer.com/export/" + appID + "/" + reportType + "/v5?api_token=" + apiToken + "&from=" + from + "&to=" + to;

    OkHttpClient client = new OkHttpClient.Builder()
        .connectTimeout(30, TimeUnit.SECONDS)
        .readTimeout(30, TimeUnit.SECONDS)

        .build();

    Request request = new Request.Builder()
        .url(requestUrl)
        .addHeader("Accept", "text/csv")
        .build();

    try {
      Response response = client.newCall(request).execute();

      if(response.code() != 200) {
        if(response.code() == 404) {
          System.out.println("There is a problem with the request URL. Please make sure it is correct");
        }
        else {
          assert response.body() != null;
          System.out.println("There was a problem retrieving the data: " + response.body().string());
        }
      } else {
        assert response.body() != null;
        String data = response.body().string();
        BufferedWriter writer;

        writer = new BufferedWriter(new FileWriter(appID + "-" + reportType + "-" + from + "-to-" + to + ".csv"));
        writer.write("");
        writer.write(data);
        writer.close();
      }
      System.exit(0);
    } catch (Exception e) {
      e.printStackTrace();
      System.exit(1);
    }
  }
}


request = require('request');
const fs = require('fs');

const appID = '<APP_ID>';
const reportType = '<REPORT_TYPE>';
const apiToken = '<API_TOKEN>';
const from = '<FROM_DATA>';
const to = '<T0_DATE>';
const requestUrl = `https://hq.appsflyer.com/export/${appID}/${reportType}/v5?api_token=${apiToken}&from=${from}&to=${to}`;

request(requestUrl, (error, response, body) => {
  if (error) {
    console.log('There was a problem retrieving data:', error);
  }
  else if (response.statusCode != 200) {
    if (response.statusCode === 404) {
      console.log('There is a problem with the request URL. Make sure that it is correct');
    } else {
      console.log('There was a problem retrieving data:', response.body);
    }
  } else {
    fs.writeFile(`${appID}-${reportType}-${from}-to-${to}.csv`, response.body, (err) => {
      if (err) {
        console.log('There was a problem writing to file: ', err);
      } else {
        console.log('File was saved');
      }
    });
  }
  
});

import requests

app_id = '<APP_ID>'
report_type = '<REPORT_TYPE>'

params = {
  'api_token': '<API_TOKEN>',
  'from': 'FROM_DATE',
  'to': 'TO_DATE'
}

request_url = 'https://hq.appsflyer.com/export/{}/{}/v5'.format(app_id, report_type)

res = requests.request('GET', request_url, params=params)

if res.status_code != 200:
  if res.status_code == 404:
    print('There is a problem with the request URL. Make sure that it is correct')
  else:
    print('There was a problem retrieving data: ', res.text)
else:
  f = open('{}-{}-{}-to-{}.csv'.format(app_id, report_type, params['from'], params['to']), 'w', newline='', encoding="utf-8")
  f.write(res.text)
  f.close()

using System;
using RestSharp;
using System.Text;
using System.Net;
using System.IO;
namespace Pull_API
{
  class PullAPi
  {
    static void Main(string[] args)
    {
      var appID = "<APP_ID>";
      var reportType = "<REPORT_TYPE>";
      var apiToken = "<API_TOKEN>";
      var from = "<FROM_DATE>";
      var to = "<TO_DATE>";

      var requestUrl = "https://hq.appsflyer.com/export/" + appID + "/" + reportType + "/v5?api_token=" + apiToken + "&from=" + from + "&to=" + to;
      
      var client = new RestClient(requestUrl);
      var request = new RestRequest(Method.GET);
      request.AddHeader("Accept", "text/csv; charset=UTF-8");

      IRestResponse response = client.Execute(request);
      HttpStatusCode statusCode = response.StatusCode;
      int numericStatusCode = (int)statusCode;

      if(numericStatusCode != 200){

        if(numericStatusCode == 404){
          Console.WriteLine("There is a problem with the request URL. Make sure that it is correct.");
        } else {
          Console.WriteLine("There was a problem retrieving data: " + response.Content); 
        }
      } else {
        System.IO.File.WriteAllText(@"" + appID + "-" + reportType + "-" + from + "-to-" + to + ".csv", response.Content);
        Console.WriteLine("Data retrieved succesfully"); 
      }
    }
  }
}

<?

$appID = '<APP_ID>';
$reportType = '<REPORT_TYPE>';
$apiToken = '<API_TOKEN>';
$from = '<FROM_DATE>';
$to = '<TO_DATE>';
$query = http_build_query([
'api_token' => $apiToken,
'from' => $from,
'to' => $to
]);
$requestUrl = 'https://hq.appsflyer.com/export/' . $appID . '/' . $reportType . '/v5?'.$query;
$report = $appID . '-' . $report . '-' . $from . '-to-' . $to; 

$curl = curl_init($requestUrl);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_ENCODING, "");
curl_setopt($curl, CURLOPT_NOSIGNAL, true);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($curl, CURLOPT_MAXREDIRS, 10);
curl_setopt($curl, CURLOPT_FAILONERROR, true);
curl_setopt($curl, CURLOPT_TIMEOUT, 100);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($curl, CURLOPT_HTTPHEADER, array(
 "cache-control: no-cache",
 "Accept: text/csv; charset=UTF-8"
));


$response = curl_exec($curl);
$info = curl_getinfo($curl);
$err = curl_error($curl);
curl_close($curl);

var_dump($response);
if ($err) {
 echo $info['http_code']; 
 echo "cURL Error #: " . $err . '. ';
 if ($info['http_code'] == 404) {
  echo 'There is a problem with the request URL. Make sure that it is correct';
 } 
 if ($info['http_code'] == 401) {
  echo 'There was a problem retrieving data: authentication failed.';
 }
 
 echo PHP_EOL;

} else {
 $fp = fopen($report, 'w+');
 fwrite($fp, $response);
 fclose($fp);
 echo $response;
}
?>

Additional information

Traits and limitations

Trait
Trait	Comments
API token type required	V1.0 token
Ad network access	N
Agency access	Y
Agency transparency	Y
App-specific currency	Y
App-specific timezone	Y
Cost	Cost data is for UA campaigns only; not for retargeting or inactive campaigns (campaigns without any installs).
Data freshness	Continuous
Historical data	Y
Non-organic data	Y
Organic data	Y
Rate limitations	Limitation
Size limitations	API calls return a max. of 200K rows. If a report has exactly 200K rows, then assume rows are missing. Make multiple API calls, using from/to parameters that include the time of day.
Campaign name changes	Pull API reports don't support campaign name changes

API error codes and troubleshooting

Error codes and solutions
Status	Code	Symptom/message	Solution
OK	200	Empty CSV file	`addtional_fields`appears more than once in the URI Ensure that both from and to dates have the format yyyy-mm-dd
OK	200		No API token found in the URI
Bad request	400	Raw Reports historical lookback is limited to 90 days	Use `to` and `from` to limit the date range to 3 months or less.
Bad request	400	Your API calls limit has been reached for the given report type	-
Unauthorized	401	Supplied API token is invalid	Ask the admin for the current token.
Unauthorized	401	Account may be suspended	Log in to the dashboard and check the account status.
Not found	404	ZendeskConnect 404 error message page displays	Ensure that the app id is correct. iOS apps must start with id. The token doesn't match the app. Are you using the correct token?