Promotion Reporting API

Learn how to generate and view API statistic reports regarding your user acquisition campaigns to customize and extract information from your campaigns.

Authentication ID

For our system to identify your API requests, you will need an authentication ID. Follow the below steps to generate this credential:

Generate your Authorization Header and add it to your PHP Code

To generate your Authorization Header, you’ll need to obtain your ironSource account’s secret key:

  1. Log in to the ironSource dashboard
  2. Click on your profile in the top right corner of the dashboard and select ‘My Account’ from within the dropdown
  3. Then go to the Reporting API tab and you’ll find your secret key
    ironsource-api-details
  4. Next, encode your “ username:secret key” based on the base64 version and add an Authorization header in your code with your encoded username:secret key.
Note: Authentication is based on basic HTTP Authentication with HTTPS.

PHP code example to generate a username:secretkey with base64

 <?php
$crl = curl_init();
$base64encoded = base64_encode("[username]:[secret key]");
$header = array();
$header[] = 'Authorization: Basic '. $base64encoded;
 $URL='https://platform.ironsrc.com/partners/publisher/applications/<API Method>';
 curl_setopt($crl, CURLOPT_URL, $URL);
curl_setopt($crl, CURLOPT_HTTPHEADER, $header);
 $response = curl_exec($crl);
 curl_close($crl);
?>

API for Ad Campaign List

Description

Get a list of promotion campaigns. The list you will get in the response will include all your campaigns.

Method

GET /advertiser/campaigns

Parameters

None

Response

GET https://platform.ironsrc.com/partners/advertiser/campaigns

JSON response

{ 
   "status": "full",
   "data": [
      { 
         "campaign_id": "12345",
         "campaign_name": "Super Campaign",
         "campaign_type": "CPI" 
         "multiple_banner": false,
         "assets":
         [
            {
               type: "icon"
               url: "local_c_12345_34_4.png"
            }
         ]
         "target_platform": [
            "apple_itunes",
            "google_play"
         ],
         "app_id": "1234",
         "bundle_id": "com.super.bestapp"
      },
      { 
         "campaign_id": "56789",
         "campaign_name": "Super Duper Campaign"
      }
   ]
}

 

Name Type Description
status full / partial “Full” means that the information collected for the date interval is complete, i.e. if we scrape at a later date this information will be the same. “Partial” could be used to indicate that the your network has not finished aggregating the data.
campaign_id String Your campaign ID
campaign_name String The campaign name
app_id String Mobile app ID
campaign_type String  The campaign type: CPI, CPC, CPE, CPV, CPA, CPCV
multiple_banner String  True or False. If true, the assets will not be displayed.
assets  List of String  Object which provides an overview of the campaign’s assets by type and with their URL. Example: icon, carrousel_image_1, carrousel_image_2,  carrousel_image_3, video_mp4.
bundle_id String The native app store bundle_id. This can either be the Google Play package name or the Apple App ID.
target_platform List of String Such as: [“apple_itunes”, “google_play”]

API for Ad Campaign Stats

Description

Get stats for each advertising campaign.

Method

GET /advertiser/campaigns/stats

Parameters

Name Type Description Required
start_date String YYYY-MM-DD (UTC Timezone) Yes
end_date String YYYY-MM-DD (UTC Timezone) Yes
campaign_id String Your campaign ID, Multiple campaign_id can be set
If not set, then return data for all campaigns.
No
break_by_app Integer Value is ‘1’ or ‘0’. ‘1’= will show media breakdown, ‘0’ will not show media breakdown. No
break_by_hour Integer If value is 1 then statistics will be broken down by hour No
add_campaign_name Integer If value is 1 then statistics will be broken down by campaign name No

Response

GET https://platform.ironsrc.com/partners/advertiser/campaigns/stats?start_date=2013-01-01&end_date=2013-01-02&campaign_id=C1234,C5678

JSON response

"status": "full",
  "data": [
    {
      "date": "2017-01-30",
      "campaign_id": "26440755",
      "data": [
        {
          "country_code": "US",
          "expense": 1781,
          "currency": "USD",
          "clicks": 51,
          "impressions": 1885,
          "conversions": 1811,
          "installs": 1,
          "applicationId": 14064
        }
      ]
    },
    {
      "date": "2017-01-30",
      "campaign_id": "26440715",
      "data": [
        {
          "country_code": "US",
          "expense": 3087,
          "currency": "USD",
          "clicks": 50,
          "impressions": 4094,
          "conversions": 3836,
          "installs": 3,
          "applicationId": 39700
        }
      ]
    },
Name Type Description
status full / partial “Full” means that the information collected for the date interval is complete, i.e. if we scrape at a later date this information will be the same. “Partial” could be used to indicate that the your network has not finished aggregating the data.
date String YYYY-MM-DD (UTC Timezone)
campaign_id String Your campaign ID
country_code String 2 letter country code, as per ISO 3166-1 Alpha-2
expense Int Money in cents¹
currency String ISO 4217 Code, e.g. USD, GBP
impressions Int Number of impressions
clicks Int Number of clicks
completions Int Number of completions. Completions are the defined payable event for each campaign.
installs Int Number of installs achieved by the campaign. For CPI campaigns, this value will be identical to the completion parameter. For CPCV and CPE campaigns you will only receive number of installs if enabled by your tracking integration.

¹ If the expense is 4 USD, the number sent will be 4 * 100 = 400. Do the same for other currencies, even if there is no subunit corresponding to the US cent. For example, if the expense is 50 JPY, the number sent should be 50 * 100 = 5000.