ayeT-Studios Advertiser APIv2 Documentation (v2.2)


Looking for Advertiser APIv1 documentation?

If you're still working with our old API, please follow this link to go to its documentation.


Updates

2017-05-08: v2.2 - Added new campaign types (CPA, Managed CPA) and ayeT-Studios Tracking SDK (which can be used "whitelabeled" by resellers)
2017-03-06: v2.1 - Extended reporting/stats, reporting/summary and reporting/summary_daily with conversion data
2016-06-23: Initial release of APIv2


Quick APIv1 To APIv2 Migration Guide

- added account/bids call
- added account/tracking call
- reworked campaign/add (android & iOS, managed campaigns, bidding system, external tracking providers)
- reworked and extended campaign/edit (added bid, budget, targeting)
- changed, updated and simplified errors and response errorCodes


Tracking SDK White Label Use

If you're a reseller with customers who might want to use a free tracking SDK for CPI/CPA conversion tracking, you can redistribute our tracking library.
We prebundled the library along with a white-labeled documentation, the archive can be downloaded here: trackinglib_bundle.zip



Introduction

Our API allows our clients to automate most of their workflow.
This includes basic account information and full campaign management which allows tight integration of our services in your own website.

We use a REST API with JSON encoded data.
The examples in this documentation rely on PHP with mod_curl and have to be adapted for other languages if required.



Topics

  1. Obtain API Key and Getting Started
  2. Account Module
  3. Campaign Module
  4. Reporting Module
  5. Appendix I: Error Codes





1. Obtain API Key and Getting Started


To obtain your API Key, log into your dashboard.
In the sidebar on the left you'll find the menu entry Account Settings where you will find a menu with the subitem API Settings. It will show your current API Key and the option to renew your key if neccessary.

We've built a simple example function in PHP using mod_curl to send a request to our server and fetch the response. This function will be used throughout the documentation:
        function ayetRequest($command, $requestData = array()) {
            $apiKey = "XXX"; // TODO: Replace with your API key

            if (!is_array($requestData)) {
                $requestData=array();
            }

            $requestData['apiKey'] = $apiKey;

            $curl = curl_init();
            curl_setopt_array($curl, array(
                CURLOPT_RETURNTRANSFER => 1,
                CURLOPT_URL => 'https://www.ayetstudios.com/api2/'.$command,        // Important: Endpoint for APIv2 is /api2/...!
                CURLOPT_POST => 1,
                CURLOPT_POSTFIELDS => $requestData)
                );

            if (($responseData = curl_exec($curl))===false) {
                curl_close($curl);
                /* echo "cURL error: ".curl_error($curl); */
                return null;
            }

            return json_decode($responseData, true);
        }
        

2. Account Module


Get Account Details

Summary:

Retrieves information about the associated account, including available funds.

Call:

        account/details
        

Parameters:

        none
        

Possible error codes:

errorCodeerrorMessage
100Authentification failed, check your API Key.
429Too many consecutive API requests, throttled.

Example:

        $responseData = ayetRequest("account/details");

        if ($responseData==null || !isset($responseData['status'])) {
            // Network or server error
        }
        else if ($responseData['status']=="error") {
            // API Call failed
            echo "Error: ".$responseData['errorCode']." - '".$responseData['errorMessage']."'";
        }
        else {
            print_r($responseData);
        }
        

Example Output:

        Array
        (
            [status] => success                // string, either success or error
            [accountData] => Array
                (
                    [accountId] => 6           // integer, the ID of this account
                    [email] => my@mail.com     // string, email address associated with account
                    [runningCampaigns] => 2    // integer, number of currently running campaigns
                    [pendingCampaigns] => 0    // integer, number of currently pending (== paused) campaigns
                    [completedCampaigns] => 0  // integer, number of completed or terminated campaigns
                    [tokens] => 4100           // integer, available tokens on this account
                )

        )
        

Get Available Bid Ranges for Android And iOS Campaigns

Summary:

Retrieves information for available bid ranges in USD for both android and ios campaigns and different campaign types

Call:

        account/bids
        

Parameters:

        none
        

Possible error codes:

errorCodeerrorMessage
100Authentification failed, check your API Key.
429Too many consecutive API requests, throttled.

Example:

        $responseData = ayetRequest("account/bids");

        if ($responseData==null || !isset($responseData['status'])) {
            // Network or server error
        }
        else if ($responseData['status']=="error") {
            // API Call failed
            echo "Error: ".$responseData['errorCode']." - '".$responseData['errorMessage']."'";
        }
        else {
            print_r($responseData);
        }
        

Example Output:

       Array
        (
            [status] => success
            [android] => Array
                (
                    [normal] => Array
                        (
                            [min] => 0.09
                            [max] => 0.2
                        )

                    [retention] => Array
                        (
                            [min] => 0.14
                            [max] => 0.25
                        )

                    [managed] => Array
                        (
                            [min] => 0.15
                            [max] => 0.6
                        )
                    [cpa] => Array
                        (
                            [min] => 0.3
                            [max] => 20
                        )

                    [cpa_managed] => Array
                        (
                            [min] => 0.3
                            [max] => 20
                        )
                )

            [ios] => Array
                (
                    [normal] => Array
                        (
                            [min] => 0.15
                            [max] => 0.6
                        )

                    [managed] => Array
                        (
                            [min] => 0.25
                            [max] => 1
                        )

                    [cpa] => Array
                        (
                            [min] => 0.2
                            [max] => 20
                        )

                    [cpa_managed] => Array
                        (
                            [min] => 0.3
                            [max] => 20
                        )
                )

        )
        

Get Available Third Party Tracking Providers

Summary:

Returns all available stock and custom tracking providers your account support for third-party conversion tracking

Call:

        account/tracking
        

Parameters:

        none
        

Possible error codes:

errorCodeerrorMessage
100Authentification failed, check your API Key.
429Too many consecutive API requests, throttled.

Example:

        $responseData = ayetRequest("account/tracking");

        if ($responseData==null || !isset($responseData['status'])) {
            // Network or server error
        }
        else if ($responseData['status']=="error") {
            // API Call failed
            echo "Error: ".$responseData['errorCode']." - '".$responseData['errorMessage']."'";
        }
        else {
            print_r($responseData);
        }
        

Example Output:

       Array
        (
            [status] => success
            [standard] => Array
                (
                    [0] => Array
                        (
                            [id] => 1
                            [name] => appsflyer
                            [instructions] => appsflyer Tracking...
                            [redirectUrlTemplate] => http://app.appsflyer.com/[PACKAGE_NAME]?pid=ayetstudios_int&clickid={click_id}
                            [supportsCPI] => 1
                            [supportsCPA] => 1
                        )
                    [1] => Array
                        (
                            [id] => 2
                            [name] => tune
                            [instructions] => tune Tracking...
                            [redirectUrlTemplate] => http://...tunetracking...&clickid={click_id}
                            [supportsCPI] => 1
                            [supportsCPA] => 0
                        )

                )

            [custom] => Array
                (
                    [0] => Array
                        (
                            [id] => -1
                            [name] => appsflyer_custom
                            [instructions] => appsflyer Tracking
... [redirectUrlTemplate] => http://app.appsflyer.com/[PACKAGE_NAME]?pid=mycompany_int&clickid={click_id} [supportsCPI] => 1 [supportsCPA] => 1 ) ) )

3. Campaign Module


List all campaigns

Summary:

Retrieves all campaigns associated with this account.

Call:

        campaign/list
        

Parameters:

        ARRAY status (optional, JSON array, if set, only returns campaigns with the given statuses [pending, running, completed, review])
        STRING identifier (optional, if set, only returns campaigns matching the identifier)
        

Possible error codes:

errorCodeerrorMessage
100Authentification failed, check your API Key.
429Too many consecutive API requests, throttled.

Example:

        $responseData = ayetRequest("campaign/list", array('status' => json_encode(array('running', 'pending')), 'identifier' => 'customer1'));

        if ($responseData==null || !isset($responseData['status'])) {
            // Network or server error
        }
        else if ($responseData['status']=="error") {
            // API Call failed
            echo "Error: ".$responseData['errorCode']." - '".$responseData['errorMessage']."'";
        }
        else {
            print_r($responseData);
        }
        

Example Output:

        Array
        (
            [status] => success
            [numCampaigns] => 2
            [campaignData] => Array
                (
                    [0] => Array
                        (
                            [campaignId] => 87                          // integer, unique id for this campaign
                            [identifier] => customer1                   // string, the value supplied when creating the campaign
                            [platform] => android                       // string, android or ios
                            [campaignType] => cpi                      // campaign type, can be cpi, cpi_hr, cpi_managed, cpa, cpa_managed                            [packageName] => com.xxx.yyy                // string, Play Store package name
                            [appName] => My Cool Calculator             // string, English (US) title of the app
                            [appIcon] => //lh5.ggpht.com/xx=w140        // string, URL to app icon
                            [targetCountries] => US, GB                 // string, country codes, empty for worldwide
                            [totalBudget] => 2                          // float, total campaign budget
                            [remainingBudget] => 1.4                    // float, remaining campaign budget
                            [bidPerConversion] => 0.2                   // float, bid per conversion / download
                            [_totalDownloads] => 10                     // deprecated, "total downloads"
                            [_remainingDownloads] => 6                  // deprecated, "remaining downloads"
                            [_tokensPerDownload] => 2                   // deprecated, "tokens per download"
                            [downloadRate] => 2400                      // integer, maximum downloads per day
                                                                        //    24-2400, 2400 means "unlimited"
                            [limitStrategy] => default                  // string, "default" or "burst" (install distribution)
                            [isRetention] => 0                          // integer, 0 for standard campaigns, 1 for HR campaigns
                            [isManaged] => 0                            // integer, 1 for managed campaigns
                            [tracking] => appsflyer                     // "standard", "custom_s2s", "tracking_sdk" or the tracking provider name
                            [redirectUrl] => http://app.appsflyer.com/com.tinybytes.monkeyrope?pid=ayetstudios_int&clickid={click_id}
                                                                        // string, redirectUrl is empty for standard tracking
                            [status] => running                         // string, current campaign status
                                                                        //    review, pending, running, terminated
                            [created] => 2014-02-08 02:40:59            // string, creation date
                            [reservations] => 0                         // the number of current reservations (users with ongoing conversions)
                        )

                    [1] => Array
                        (
                            [campaignId] => 286
                            [identifier] =>
                            [platform] => android
                            [campaignType] => cpa_managed
                            [packageName] => com.xxx.zzz
                            [appName] => My Cool Watch
                            [appIcon] => //lh6.ggpht.com/xx=w140
                            [targetCountries] =>
                            [totalBudget] => 20
                            [remainingBudget] => 8.4
                            [bidPerConversion] => 0.4
                            [_totalDownloads] => 50
                            [_remainingDownloads] => 21
                            [_tokensPerDownload] => 4
                            [downloadRate] => 400
                            [limitStrategy] => burst
                            [isRetention] => 0
                            [isManaged] => 1
                            [tracking] => tracking_sdk                  // "standard", "custom_s2s", "tracking_sdk" or the tracking provider name
                            [redirectUrl] =>
                            [status] => pending
                            [created] => 2014-02-09 01:22:32
                            [retentionActualBudget] => 20               // the remaining conversion budget for retention campaigns
                            [_remainingRetentions] => 50                // deprecated, the number of remaining retention conversions
                            [reservations] => 0                         // the number of current reservations (users with ongoing conversions)
                            [eventName] => register                     // CPA: the name of the event this CPA campaign is tracking
                            [eventConversionTime] => 10                 // CPA: average conversion time for users to reach the event
                            [eventDescription] => The user has to start the app and create an account   // CPA
                        )
                )

        )
        

Get specific campaign

Summary:

Retrieves a specific campaign identified by its unique campaignId.

Call:

        campaign/get
        

Parameters:

        INTEGER campaignId (required, the id of the campaign to be returned)
        

Possible error codes:

errorCodeerrorMessage
100Authentification failed, check your API Key.
305Campaign does not exist.
429Too many consecutive API requests, throttled.

Example:

        $responseData = ayetRequest("campaign/get", array('campaignId' => 87));

        if ($responseData==null || !isset($responseData['status'])) {
            // Network or server error
        }
        else if ($responseData['status']=="error") {
            // API Call failed
            echo "Error: ".$responseData['errorCode']." - '".$responseData['errorMessage']."'";
        }
        else {
            print_r($responseData);
        }
        

Example Output:

        Array
        (
            [status] => success
            [campaignData] => Array
                (
                    [campaignId] => 87                          // integer, unique id for this campaign
                    [identifier] => customer1                   // string, the value supplied when creating the campaign
                    [platform] => android                       // string, android or ios
                    [campaignType] => cpi
                    [packageName] => com.xxx.yyy                // string, Play Store package name
                    [appName] => My Cool Calculator             // string, English (US) title of the app
                    [appIcon] => //lh5.ggpht.com/xx=w140        // string, URL to app icon
                    [targetCountries] => US, GB                 // string, country codes, empty for worldwide
                    [totalBudget] => 2                          // float, total campaign budget
                    [remainingBudget] => 1.4                    // float, remaining campaign budget
                    [bidPerConversion] => 0.2                   // float, bid per conversion / download
                    [_totalDownloads] => 10                     // deprecated, "total downloads"
                    [_remainingDownloads] => 6                  // deprecated, "remaining downloads"
                    [_tokensPerDownload] => 2                   // deprecated, "tokens per download"
                    [downloadRate] => 2400                      // integer, maximum downloads per day
                                                                //    24-2400, 2400 means "unlimited"
                    [limitStrategy] => default                  // string, "default" or "burst" (install distribution)
                    [isRetention] => 0                          // integer, 0 for standard campaigns, 1 for HR campaigns
                    [isManaged] => 0                            // integer, 1 for managed campaigns
                    [tracking] => appsflyer                     // "standard", "custom_s2s" or the tracking provider name
                    [redirectUrl] => http://app.appsflyer.com/com.tinybytes.monkeyrope?pid=ayetstudios_int&clickid={click_id}
                                                                // string, redirectUrl is empty for standard tracking
                    [status] => running                         // string, current campaign status
                                                                //    review, pending, running, terminated
                    [created] => 2014-02-08 02:40:59            // string, creation date
                    [reservations] => 0                         // the number of current reservations (users with ongoing conversions)
                )

        )
        

Add a new campaign

Summary:

Creates a new campaign for a free Google Play or iOS app.

Call:

        campaign/add
        

Parameters:

        STRING  platform (required, either "android" or "ios")
        STRING  applicationUrl (required, package name of the app, iTunes App Id or link to Google Play / iTunes)
        STRING  campaignType (optional, either "standard", "retention", "managed", "cpa", "cpa_managed")
        FLOAT   budget (required, in USD, 1-1000 for normal and high retention, 500-20000 for managed campaigns)
        MIXED   bid (required, either FLOAT in USD or "min" / "max" if you want to set the min/max available bid per conversion)
        STRING  targetCountries (optional, comma-seperated list of countries to target *)
        INTEGER downloadRate (optional, maximum number of downloads per day 24-2400)
        STRING  status (optional, initial status - "pending" (default) or "running")
        STRING  identifier (optional, an arbitary string which can be used to identify a customers campaign later)
        MIXED   trackingProvider (optional, "custom_s2s" or the id of the tracking provider to use [see "account/tracking"])
        STRING  redirectUrl (required whenever trackingProvider is set, represents the redirect URL containing a {click_id} parameter)
        STRING  eventName ("cpa" and "cpa_managed" only, the name of the event that triggers a successful conversion)
        INTEGER eventConversionTime ("cpa" and "cpa_managed" only, the average conversion time for users to complete the required action / trigger the event)
        STRING  eventDescription ("cpa" and "cpa_managed" only, the user conversion flow to complete the cpa offer - min. 20 characters)
        
        * Available countries:
        US, GB, CA, AU, DE, FR, IT, ES, NL, MX, IN, VN, JP, RU, PL,
        MY, AT, BR, PH, ID, CO, CZ, RO, HK, GR, BG, TR, KR, PT,
        UA, HU, TH, VE, CH, SA, SG, TW, MA, CL

        

Possible error codes:

errorCodeerrorMessage
100Authentification failed, check your API Key.
102[variable, general campaign creation error]
103[variable, bid related campaign creation error]
104[variable, budget relatedcampaign creation error]
105[variable, tracking related campaign creation error]
301Invalid country requested: $invalidCountryCode.
429Too many consecutive API requests, throttled.

Android example:

        $responseData = ayetRequest("campaign/add",
                array(
                    'platform' => 'android',
                    'applicationUrl' => 'com.example',
                    'budget' => 5,
                    'bid' => 'min',
                    'targetCountries' => 'US, DE, GB, CA', // optional, default is worldwide
                    'downloadRate' => 300,                  // optional, default is unlimited (= 2400)
                    'status' => 'running'  ,                 // optional, default is 'pending',
                    'identifier' => 'customer1'             // optional, we set this to customer1 and can later filter our "get" commands
                    )
                );

        if ($responseData==null || !isset($responseData['status'])) {
            // Network or server error
        }
        else if ($responseData['status']=="error") {
            // API Call failed
            echo "Error: ".$responseData['errorCode']." - '".$responseData['errorMessage']."'";
        }
        else {
            print_r($responseData);
        }
        
        Array
        (
            [status] => success
            [campaignData] => Array
            (
                [campaignId] => 39281
                [identifier] => customer1
                [platform] => android
                [campaignType] => cpi
                [packageName] => com.example
                [appName] => My Example App
                [appIcon] => //lh6.ggpht.com/a2KVKcNH3t0JsmFKLwt1izyHw4eg=w140
                [targetCountries] => US, DE, GB, CA
                [totalBudget] => 5
                [remainingBudget] => 5
                [bidPerConversion] => 0.09
                [_totalDownloads] => 55
                [_remainingDownloads] => 55
                [_tokensPerDownload] => 0.9
                [downloadRate] => 288
                [limitStrategy] => default
                [isRetention] => 0
                [isManaged] => 0
                [tracking] => standard
                [redirectUrl] =>
                [status] => running
                [created] => 2016-06-23 22:30:18
                [reservations] => 0
            )
        )
        

iOS with custom appsflyer tracking example:

        $responseData = ayetRequest("campaign/add",
                array(
                    'platform' => 'ios',
                    'applicationUrl' => 'https://itunes.apple.com/de/app/clash-of-clans/id529479190?mt=8',
                    'budget' => 5,
                    'bid' => '0.2',
                    'targetCountries' => 'US, DE, GB, CA',  // optional, default is worldwide
                    'downloadRate' => 300,                  // optional, default is unlimited (= 2400)
                    'status' => 'running'  ,                // optional, default is 'pending',
                    'trackingProvider' => -1,               // see "account/tracking" - we selected our own, custom "appsflyer" tracking
                    'redirectUrl' => 'https://app.appsflyer.com/529479190?pid=mycompany_int&clickid={click_id}'
                                                            // the appsflyer tracking url for this campaign
                    )
                );

        if ($responseData==null || !isset($responseData['status'])) {
            // Network or server error
        }
        else if ($responseData['status']=="error") {
            // API Call failed
            echo "Error: ".$responseData['errorCode']." - '".$responseData['errorMessage']."'";
        }
        else {
            print_r($responseData);
        }
        
        Array
        (
            [status] => success
            [campaignData] => Array
            (
                [campaignId] => 39283
                [identifier] =>
                [platform] => ios
                [campaignType] => cpi
                [packageName] => 529479190
                [appName] => Clash of Clans
                [appIcon] => http://is5.mzstatic.com/image/thumb/Purple20/v4/77/eb/f5/77ebf5f8-a84f-6dbd-0542-fe4db15a941f/source/512x512bb.jpg
                [targetCountries] => US, DE, GB, CA
                [totalBudget] => 5
                [remainingBudget] => 5
                [bidPerConversion] => 0.2
                [_totalDownloads] => 25
                [_remainingDownloads] => 25
                [_tokensPerDownload] => 2
                [downloadRate] => 288
                [limitStrategy] => default
                [isRetention] => 0
                [isManaged] => 0
                [tracking] => appsflyer
                [redirectUrl] => https://app.appsflyer.com/529479190?pid=mycompany_int&clickid={click_id}
                [status] => review                      // any campaign with external tracking requires manual review to verify the redirect url and postbacks
                [created] => 2016-06-24 00:31:14
                [reservations] => 0
            )

        )
        

CPA example:

        $responseData = ayetRequest("campaign/add",
                array(
                    'platform' => 'android',
                    'campaignType' => 'cpa',
                    'applicationUrl' => 'com.example',
                    'budget' => 30,
                    'bid' => 'min',
                    'targetCountries' => 'US, DE, GB, CA',      // optional, default is worldwide
                    'status' => 'running'  ,                    // optional, default is 'pending',
                    'eventName' => 'login',
                    'eventConversionTime' => 10,
                    'eventDescription' => 'The user has to install the app and login using his facebook or google account',
                    'trackingProvider' => 'tracking_sdk',       // we chose our free tracking sdk since it's the easiest option especially for CPA campaigns
                    'identifier' => 'customer1'                 // optional, we set this to customer1 and can later filter our "get" commands
                    )
                );

        if ($responseData==null || !isset($responseData['status'])) {
            // Network or server error
        }
        else if ($responseData['status']=="error") {
            // API Call failed
            echo "Error: ".$responseData['errorCode']." - '".$responseData['errorMessage']."'";
        }
        else {
            print_r($responseData);
        }
        
        Array
        (
            [status] => success
            [campaignData] => Array
                (
                    [campaignId] => 39560
                    [identifier] => customer1
                    [platform] => android
                    [campaignType] => cpa
                    [packageName] => com.example
                    [appName] => My Example App
                    [appIcon] => //lh6.ggpht.com/a2KVKcNH3t0JsmFKLwt1izyHw4eg=w140
                    [targetCountries] => US, DE, GB, CA
                    [totalBudget] => 30
                    [remainingBudget] => 30
                    [bidPerConversion] => 0.3
                    [_totalDownloads] => 100
                    [_remainingDownloads] => 100
                    [_tokensPerDownload] => 3
                    [downloadRate] => 288
                    [limitStrategy] => default
                    [isRetention] => 0
                    [isManaged] => 0
                    [tracking] => tracking_sdk
                    [redirectUrl] =>
                    [status] => review                          // CPA campaigns are always created under review, regardless of the desired campaign status
                    [created] => 2017-05-08 04:47:20
                    [eventName] => login
                    [eventConversionTime] => 10
                    [eventDescription] => The user has to install the app and login using his facebook or google account
                    [reservations] => 0
                )

        )
        

Edit campaign settings

Summary:

This command is used to edit one or multiple campaign settings

Call:

        campaign/edit
        

Parameters:

        INTEGER  campaignId (required, the id of the campaign to be edited)
        INTEGER  downloadRate (optional, desired download rate per day *)
        STRING   limitStrategy (optional, "default" for even distribution of installs along the day, "burst" for maximum output)
        STRING   targetCountries (optional, comma-separated list of countries to target for this campaign)
        MIXED    bid (optional, set the bid per conversion in USD for this campaign or "min" / "max" for minimum or maximum bid)
        

        * Hint:
        Our system converts daily caps to hourly caps, so the actual download rate might differ (see example)
        

Possible error codes:

errorCodeerrorMessage
100Authentification failed, check your API Key.
102[variable, general campaign creation error]
103[variable, bid related campaign creation error]
104[variable, budget relatedcampaign creation error]
301Invalid country requested: $invalidCountryCode.
302Campaign is managed, no permissions.
305Campaign does not exist.
306[variable, invalid campaign status]
429Too many consecutive API requests, throttled.

Example:

        $responseData = ayetRequest("campaign/edit", array(
                                            'campaignId' => 39281,
                                            'downloadRate' => 2400,
                                            'limitStrategy' => 'burst',
                                            'targetCountries' => '',
                                            'bid' => 0.1,
                                            'addBudget' => 4
                                        ));

        if ($responseData==null || !isset($responseData['status'])) {
            // Network or server error
        }
        else if ($responseData['status']=="error") {
            // API Call failed
            echo "Error: ".$responseData['errorCode']." - '".$responseData['errorMessage']."'";
        }
        else {
            print_r($responseData);
        }
        

Example Output:

        Array
        (
            [status] => success
            [campaignData] => Array
                (
                    [campaignId] => 39281
                    [identifier] => customer1
                    [platform] => android
                    [campaignType] => cpi
                    [packageName] => com.example
                    [appName] => My Example App
                    [appIcon] => //lh6.ggpht.com/a2KVKcNH3t0JsmFKLwt1izyHw4eg=w140
                    [targetCountries] =>
                    [totalBudget] => 9
                    [remainingBudget] => 9
                    [bidPerConversion] => 0.1
                    [_totalDownloads] => 90
                    [_remainingDownloads] => 90
                    [_tokensPerDownload] => 1
                    [downloadRate] => 2400
                    [limitStrategy] => burst
                    [isRetention] => 0
                    [isManaged] => 0
                    [tracking] => standard
                    [redirectUrl] =>
                    [status] => running
                    [created] => 2016-06-23 22:30:18
                    [reservations] => 0
                )

        )

        

Start a campaign

Summary:

This command starts a campaign which is currently in pending (= paused) state.

Call:

        campaign/start
        

Parameters:

        INTEGER campaignId (required, the id of the campaign to be started)
        

Possible error codes:

errorCodeerrorMessage
100Authentification failed, check your API Key.
302Campaign is managed, no permissions.
305Campaign does not exist.
306[variable, invalid campaign status]
429Too many consecutive API requests, throttled.

Example:

        $responseData = ayetRequest("campaign/start", array('campaignId' => 286));

        if ($responseData==null || !isset($responseData['status'])) {
            // Network or server error
        }
        else if ($responseData['status']=="error") {
            // API Call failed
            echo "Error: ".$responseData['errorCode']." - '".$responseData['errorMessage']."'";
        }
        else {
            print_r($responseData);
        }
        

Example Output:

        Array
        (
            [status] => success
            [campaignData] => Array
                (
                    [campaignId] => 286
                    [identifier] =>
                    [platform] => android
                    [campaignType] => cpi_hr
                    [packageName] => com.xxx.zzz
                    [appName] => My Cool Watch
                    [appIcon] => //lh6.ggpht.com/xx=w140
                    [targetCountries] =>
                    [totalBudget] => 20
                    [remainingBudget] => 8.4
                    [bidPerConversion] => 0.4
                    [_totalDownloads] => 50
                    [_remainingDownloads] => 21
                    [_tokensPerDownload] => 4
                    [downloadRate] => 400
                    [limitStrategy] => burst
                    [isRetention] => 1
                    [isManaged] => 0
                    [tracking] => standard
                    [redirectUrl] =>
                    [status] => running                 // campaign is running now
                    [created] => 2014-02-09 01:22:32
                    [retentionActualBudget] => 20
                    [_remainingRetentions] => 50
                    [reservations] => 0
                )

        )

        

Pause a campaign

Summary:

This command pauses a campaign which is currently running (new state will be "pending").

Call:

        campaign/pause
        

Parameters:

        INTEGER campaignId (required, the id of the campaign to be paused)
        

Possible error codes:

errorCodeerrorMessage
100Authentification failed, check your API Key.
302Campaign is managed, no permissions.
305Campaign does not exist.
306[variable, invalid campaign status]
429Too many consecutive API requests, throttled.

Example:

        $responseData = ayetRequest("campaign/pause", array('campaignId' => 286));

        if ($responseData==null || !isset($responseData['status'])) {
            // Network or server error
        }
        else if ($responseData['status']=="error") {
            // API Call failed
            echo "Error: ".$responseData['errorCode']." - '".$responseData['errorMessage']."'";
        }
        else {
            print_r($responseData);
        }
        

Example Output:

        Array
        (
            [status] => success
            [campaignData] => Array
                (
                    [campaignId] => 286
                    [identifier] =>
                    [platform] => android
                    [campaignType] => cpi_hr
                    [packageName] => com.xxx.zzz
                    [appName] => My Cool Watch
                    [appIcon] => //lh6.ggpht.com/xx=w140
                    [targetCountries] =>
                    [totalBudget] => 20
                    [remainingBudget] => 8.4
                    [bidPerConversion] => 0.4
                    [_totalDownloads] => 50
                    [_remainingDownloads] => 21
                    [_tokensPerDownload] => 4
                    [downloadRate] => 400
                    [limitStrategy] => burst
                    [isRetention] => 1
                    [isManaged] => 0
                    [tracking] => standard
                    [redirectUrl] =>
                    [status] => pending             // campaign is paused (== pending) now
                    [created] => 2014-02-09 01:22:32
                    [retentionActualBudget] => 20
                    [_remainingRetentions] => 50
                    [reservations] => 0
                )

        )

        

Terminates a campaign

Summary:

This command terminates a campaign which is currently in paused state and does not have any open reservations, remaining tokens from the terminated campaign will be refunded to your account balance.
The new state of the campaign will be "completed".
Open reservations expire 15 minutes after pausing a campaign.


Call:

        campaign/terminate
        

Parameters:

        INTEGER campaignId (required, the id of the campaign to be terminated)
        

Possible error codes:

errorCodeerrorMessage
100Authentification failed, check your API Key.
302Campaign is managed, no permissions.
305Campaign does not exist.
306[variable, invalid campaign status]
308This campaign still has $reservations reservations. After pausing a campaign, you may have to wait up to 15 minutes before a campaign can be completed.
429Too many consecutive API requests, throttled.

Example:

        $responseData = ayetRequest("campaign/terminate", array('campaignId' => 286));

        if ($responseData==null || !isset($responseData['status'])) {
            // Network or server error
        }
        else if ($responseData['status']=="error") {
            // API Call failed
            echo "Error: ".$responseData['errorCode']." - '".$responseData['errorMessage']."'";
        }
        else {
            print_r($responseData);
        }
        

Example Output:

        Array
        (
            [status] => success
            [refundedBalance] => 8.4		// the remaining campaign budget refunded to your account balance in USD

        )
        

4. Reporting Module


Summarized Statistics for the account

Summary:

Retrieves all statistics for the account for the given date range and filtered for an optional identifier.
The returned data includes the number of currently running and active (pending, running, review) campaigns as well as impressions, clicks and transaction statistics for the specified date range. If identifier is set, only campaigns matching "identifier" are inspected.

Call:

        reporting/summary
        

Parameters:

        STRING startDate (required, the start date for the statistics retrieval)
        STRING endDate (required, the end date for the statistics retrieval)
        STRING identifier (optional, if set, only campaigns matching the identifier are inspected)
        

Possible error codes:

errorCodeerrorMessage
100Authentification failed, check your API Key.
201Parameter out of range: Maximum date interval range is 365 days.
429Too many consecutive API requests, throttled.

Example:

        $responseData = ayetRequest("reporting/summary", array( 'startDate' => '2014-01-25',
                                                                'endDate' => '2014-12-01',
                                                                'identifier' => 'customer1283'));

        if ($responseData==null || !isset($responseData['status'])) {
            // Network or server error
        }
        else if ($responseData['status']=="error") {
            // API Call failed
            echo "Error: ".$responseData['errorCode']." - '".$responseData['errorMessage']."'";
        }
        else {
            print_r($responseData);
        }
        

Example Output:

        Array
        (
            [status] => success
            [startDate] => 2014-01-25
            [endDate] => 2014-12-01
            [statistics] => Array
                (
                    [activeCampaigns] => 70         // currently active campaigns
                    [runningCampaigns] => 51        // currently running campaigns
                    [impressions] => 8498599        // total impressions in the date range
                    [clicks] => 621865              // total clicks in the date range
                    [installs] => 349203            // total installs in the date range
                    [conversionRate] => 4           // DOWNLOAD rate in percent, installs/clicks
                    [conversions] => 346143         // total conversions in the date range
                )

        )
        

Summarized Statistics for the account per day

Summary:

Retrieves all statistics for the account for the given date range and filtered for an optional identifier.
The returned data includes the impressions, clicks and transaction statistics for the specified date range for each day. If identifier is set, only campaigns matching "identifier" are inspected.

Call:

        reporting/summary_daily
        

Parameters:

        STRING startDate (required, the start date for the statistics retrieval)
        STRING endDate (required, the end date for the statistics retrieval)
        STRING identifier (optional, if set, only campaigns matching the identifier are inspected)
        

Possible error codes:

errorCodeerrorMessage
100Authentification failed, check your API Key.
202Parameter out of range: Maximum date interval range is 62 days.
429Too many consecutive API requests, throttled.

Example:

        $responseData = ayetRequest("reporting/summary_daily", array( 'startDate' => '2015-01-25',
                                                                'endDate' => '2015-01-27',
                                                                'identifier' => 'customer1283'));

        if ($responseData==null || !isset($responseData['status'])) {
            // Network or server error
        }
        else if ($responseData['status']=="error") {
            // API Call failed
            echo "Error: ".$responseData['errorCode']." - '".$responseData['errorMessage']."'";
        }
        else {
            print_r($responseData);
        }
        

Example Output:

        Array
        (
            [status] => success
            [startDate] => 2015-01-25
            [endDate] => 2015-01-27
            [statistics] => Array
                (
                    [2015-01-25] => Array
                        (
                            [impressions] => 129337     // total impressions this day
                            [clicks] => 14148           // total clicks this day
                            [installs] => 9159          // total installs this day
                            [conversionRate] => 7       // DOWNLOAD rate in percent, installs/clicks
                            [conversions] => 9159          // total conversions this day
                        )

                    [2015-01-26] => Array
                        (
                            [impressions] => 76149
                            [clicks] => 7407
                            [installs] => 4591
                            [conversionRate] => 6
                            [conversions] => 4452
                        )

                    [2015-01-27] => Array
                        (
                            [impressions] => 97627
                            [clicks] => 11254
                            [installs] => 7099
                            [conversionRate] => 7
                            [conversions] => 7002
                        )

                )

        )
        

Installations for given campaign

Summary:

Retrieves all installations for the given campaign, timestamps are in UTC+0.
Hint: For High Retention campaigns, only installation which successfully converted are listed.

Call:

        reporting/installations
        

Parameters:

        INTEGER campaignId (required, the id of the campaign to be returned)
        

Possible error codes:

errorCodeerrorMessage
100Authentification failed, check your API Key.
305Campaign does not exist.
429Too many consecutive API requests, throttled.

Example:

        $responseData = ayetRequest("reporting/installations", array('campaignId' => 287));

        if ($responseData==null || !isset($responseData['status'])) {
            // Network or server error
        }
        else if ($responseData['status']=="error") {
            // API Call failed
            echo "Error: ".$responseData['errorCode']." - '".$responseData['errorMessage']."'";
        }
        else {
            print_r($responseData);
        }
        

Example Output:

        Array
        (
            [status] => success
            [campaignData] => Array
                (
                    [campaignId] => 87                          // integer, unique id for this campaign
                        [identifier] => customer1                   // string, the value supplied when creating the campaign
                        [platform] => android                       // string, android or ios
                        [campaignType] => cpi
                        [packageName] => com.xxx.yyy                // string, Play Store package name
                        [appName] => My Cool Calculator             // string, English (US) title of the app
                        [appIcon] => //lh5.ggpht.com/xx=w140        // string, URL to app icon
                        [targetCountries] => US, GB                 // string, country codes, empty for worldwide
                        [totalBudget] => 2                          // float, total campaign budget
                        [remainingBudget] => 1.4                    // float, remaining campaign budget
                        [bidPerConversion] => 0.2                   // float, bid per conversion / download
                        [_totalDownloads] => 10                     // deprecated, "total downloads"
                        [_remainingDownloads] => 6                  // deprecated, "remaining downloads"
                        [_tokensPerDownload] => 2                   // deprecated, "tokens per download"
                        [downloadRate] => 2400                      // integer, maximum downloads per day
                                                                    //    24-2400, 2400 means "unlimited"
                        [limitStrategy] => default                  // string, "default" or "burst" (install distribution)
                        [isRetention] => 0                          // integer, 0 for standard campaigns, 1 for HR campaigns
                        [isManaged] => 0                            // integer, 1 for managed campaigns
                        [tracking] => appsflyer                     // "standard", "custom_s2s" or the tracking provider name
                        [redirectUrl] => http://app.appsflyer.com/com.tinybytes.monkeyrope?pid=ayetstudios_int&clickid={click_id}
                                                                    // string, redirectUrl is empty for standard tracking
                        [status] => completed                         // string, current campaign status
                                                                    //    review, pending, running, terminated
                        [created] => 2014-02-08 02:40:59            // string, creation date
                        [reservations] => 0
                )

            [installations] => Array
                (
                    [0] => Array
                        (
                            [timestamp] => 2014-02-12 15:19:49
                            [country] => DE
                            [identifier] => XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
                            [make] => Samsung
                            [model] => GT-I9300
                        )

                    [1] => Array
                        (
                            [timestamp] => 2014-02-12 15:21:15
                            [country] => CZ
                            [identifier] => XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
                            [make] => samsung
                            [model] => GT-P5100
                        )

                ......
            )


        )
        


Statistics for given campaign

Summary:

Retrieves all statistics for the given campaign.
The returned data includes the campaign entry, a summary, detailed statistics (per day) and a list with country codes and their respective installation numbers.
For most campaign types, "conversions" is the number of actually billed installs/conversions and matches "retentions" for HR campaigns.

Call:

        reporting/stats
        

Parameters:

        INTEGER campaignId (required, the id of the campaign to be returned)
        

Possible error codes:

errorCodeerrorMessage
100Authentification failed, check your API Key.
305Campaign does not exist.
429Too many consecutive API requests, throttled.

Example:

        $responseData = ayetRequest("reporting/stats", array('campaignId' => 287));

        if ($responseData==null || !isset($responseData['status'])) {
            // Network or server error
        }
        else if ($responseData['status']=="error") {
            // API Call failed
            echo "Error: ".$responseData['errorCode']." - '".$responseData['errorMessage']."'";
        }
        else {
            print_r($responseData);
        }
        

Example Output:

        Array
        (
            [status] => success
            [campaignData] => Array
                (
                    [campaignId] => 87                          // integer, unique id for this campaign
                        [identifier] => customer1                   // string, the value supplied when creating the campaign
                        [platform] => android                       // string, android or ios
                        [campaignType] => cpi
                        [packageName] => com.xxx.yyy                // string, Play Store package name
                        [appName] => My Cool Calculator             // string, English (US) title of the app
                        [appIcon] => //lh5.ggpht.com/xx=w140        // string, URL to app icon
                        [targetCountries] => US, GB                 // string, country codes, empty for worldwide
                        [totalBudget] => 9                          // float, total campaign budget
                        [remainingBudget] => 0.8                    // float, remaining campaign budget
                        [bidPerConversion] => 0.2                   // float, bid per conversion / download
                        [_totalDownloads] => 45                     // deprecated, "total downloads"
                        [_remainingDownloads] => 4                  // deprecated, "remaining downloads"
                        [_tokensPerDownload] => 2                   // deprecated, "tokens per download"
                        [downloadRate] => 2400                      // integer, maximum downloads per day
                                                                    //    24-2400, 2400 means "unlimited"
                        [limitStrategy] => default                  // string, "default" or "burst" (install distribution)
                        [isRetention] => 0                          // integer, 0 for standard campaigns, 1 for HR campaigns
                        [isManaged] => 0                            // integer, 1 for managed campaigns
                        [tracking] => appsflyer                     // "standard", "custom_s2s" or the tracking provider name
                        [redirectUrl] => http://app.appsflyer.com/com.tinybytes.monkeyrope?pid=ayetstudios_int&clickid={click_id}
                                                                    // string, redirectUrl is empty for standard tracking
                        [status] => completed                         // string, current campaign status
                                                                    //    review, pending, running, terminated
                        [created] => 2014-02-08 02:40:59            // string, creation date
                        [reservations] => 0
                )


            [summary] => Array
                (
                    [views] => 138
                    [clicks] => 72
                    [downloads] => 50           // total number of internally tracked installations
                    [conversions] => 41           // total number of conversions (in this case, reported by appsflyer)
                )

            [detailed] => Array
                (
                    [2014-02-12] => Array
                    (
                        [views] => 138
                        [clicks] => 72
                        [downloads] => 50
                        [conversions] => 40
                    )

                    [2014-02-13] => Array
                    (
                        [views] => 0
                        [clicks] => 0
                        [downloads] => 0
                        [conversions] => 1    // this conversion was delayed, the download has been tracked the day before
                    )
                )

            [countries] => Array
                (
                    [DE] => 4
                    [CZ] => 1
                    [IN] => 13
                    [DZ] => 2
                    [CA] => 2
                    [CO] => 1
                    [US] => 9
                    [GR] => 2
                    [IT] => 1
                    [AR] => 1
                    [ID] => 1
                    [ES] => 2
                    [PL] => 3
                    [GB] => 1
                    [TZ] => 1
                    [BG] => 1
                    [FR] => 1
                    [NO] => 1
                    [RU] => 1
                    [BY] => 1
                    [PH] => 1
                )


        )
        

Example Output:

        Array
        (
            [status] => success
            [campaignData] => Array
                (
                    [campaignId] => 286
                    [identifier] =>
                    [platform] => android
                    [campaignType] => cpi
                    [packageName] => com.xxx.zzz
                    [appName] => My Cool Watch
                    [appIcon] => //lh6.ggpht.com/xx=w140
                    [targetCountries] =>
                    [totalBudget] => 20
                    [remainingBudget] => 8.4
                    [bidPerConversion] => 0.4
                    [_totalDownloads] => 50
                    [_remainingDownloads] => 21
                    [_tokensPerDownload] => 4
                    [downloadRate] => 400
                    [limitStrategy] => burst
                    [isRetention] => 1
                    [isManaged] => 0
                    [tracking] => standard
                    [redirectUrl] =>
                    [status] => pending
                    [created] => 2014-02-09 01:22:32
                    [retentionActualBudget] => 17.6               // the remaining conversion budget for retention campaigns
                    [_remainingRetentions] => 44                // deprecated, the number of remaining retention conversions
                    [reservations] => 0
                )


            [summary] => Array
                (
                    [views] => 147
                    [clicks] => 80
                    [downloads] => 55
                    [conversions] => 6
                    [retentions] => 6                           // HR only: shows the number of retentions for this campaign
                    [uninstalls] => 5                           // HR only: shows the number of uninstalls for this campaign
                )

            [detailed] => Array
                (
                    [2014-02-12] => Array
                    (
                        [views] => 138
                        [clicks] => 72
                        [downloads] => 50
                        [conversions] => 0
                        [retentions] => 0                       // HR only: shows the number of successful retentions
                        [uninstalls] => 4                       // HR only: shows the number of uninstalls
                    )

                    [2014-02-13] => Array
                    (
                        [views] => 5
                        [clicks] => 5
                        [downloads] => 4
                        [conversions] => 0
                        [retentions] => 0
                        [uninstalls] => 0
                    )

                    [2014-02-14] => Array
                    (
                        [views] => 0
                        [clicks] => 0
                        [downloads] => 0
                        [conversions] => 0
                        [retentions] => 0
                        [uninstalls] => 1
                    )

                    [2014-02-15] => Array
                    (
                        [views] => 4
                        [clicks] => 2
                        [downloads] => 1
                        [conversions] => 6
                        [retentions] => 6
                        [uninstalls] => 0
                    )

                )

            [countries] => Array
                (
                    [DE] => 4
                    [CZ] => 1
                    [IN] => 13
                    [DZ] => 2
                    [CA] => 2
                    [CO] => 1
                    [US] => 14
                    [GR] => 2
                    [IT] => 1
                    [AR] => 1
                    [ID] => 1
                    [ES] => 2
                    [PL] => 3
                    [GB] => 1
                    [TZ] => 1
                    [BG] => 1
                    [FR] => 1
                    [NO] => 1
                    [RU] => 1
                    [BY] => 1
                    [PH] => 1
                )
            // retentionByDay shows how long users kept the app before uninstalling it
            [retentionByDay] => Array
                (
                    [0] => 4            // 4 users kept the app for less than 1 day
                    [1] => 0
                    [2] => 1
                    [3] => 0
                    [4] => 0
                    [5] => 0
                    [6] => 0
                    [7] => 0            // users who kept the app for 7+ days
                )

            // retentionByCountry shows how long users kept the app, segmented by country
            [retentionByCountry] => Array
                (
                    [US] => Array
                        (
                            [0] => 1    // 1 US user uninstalled on the first day
                            [1] => 0
                            [2] => 1    // 1 US user uninstalled after 2 days
                            [3] => 0
                            [4] => 0
                            [5] => 0
                            [6] => 0
                            [7] => 0
                        )
                    [IN] => Array
                        (
                            [0] => 3
                            [1] => 0
                            [2] => 0
                            [3] => 0
                            [4] => 0
                            [5] => 0
                            [6] => 0
                            [7] => 0
                        )
                    ...

                )



        )
        

4. Appendix I: Error Codes



errorCodeerrorMessage
100Authentification failed, check your API Key.
101Unknown action "$action" for $module module.
102[variable, general campaign creation error]
103[variable, bid related campaign creation error]
104[variable, budget related campaign creation error]
105[variable, tracking related campaign creation error]
201Parameter out of range: Maximum date interval range is 365 days.
202Parameter out of range: Maximum date interval range is 62 days.
301Invalid country requested: $invalidCountryCode.
302Campaign is managed, no permissions.
305Campaign does not exist.
306[variable, invalid campaign status]
308This campaign still has $reservations reservations. After pausing a campaign, you may have to wait up to 15 minutes before a campaign can be completed.
310Insufficient account permissions to create custom s2s tracking campaigns.
429Too many consecutive API requests, throttled.