• support@ayetstudios.com

 aye-T Studios APIv2 Documentation (V2.0)


Looking for APIv1 documentation?

As of 2016-05-23, our old API is deprecated.

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


Updates

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
        

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
                        )

                )

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

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

                )

        )
        

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}
                        )
                    [1] => Array
                        (
                            [id] => 2
                            [name] => tune
                            [instructions] => tune Tracking...
                            [redirectUrlTemplate] => http://...tunetracking...&clickid={click_id}
                        )

                )

            [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} ) ) )

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
                            [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)
                        )

                    [1] => Array
                        (
                            [campaignId] => 286
                            [identifier] =>
                            [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] => 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)
                        )

                )

        )
        

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
                    [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.

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" or "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)

        * 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
                [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
                [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
            )

        )
        

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
                    [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] =>
                    [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] =>
                    [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           // conversion rate in percent, installs/clicks
                )

        )
        

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       // conversion rate in percent, installs/clicks
                        )

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

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

                )

        )
        

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
                        [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.

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
                        [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
                )


            [summary] => Array
                (
                    [views] => 138
                    [clicks] => 72
                    [downloads] => 50
                )

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

                    [2014-02-13] => Array
                    (
                        [views] => 0
                        [clicks] => 0
                        [downloads] => 0
                    )
                )

            [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] =>
                    [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
                    [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
                        [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
                        [retentions] => 0
                        [uninstalls] => 0
                    )

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

                    [2014-02-15] => Array
                    (
                        [views] => 4
                        [clicks] => 2
                        [downloads] => 1
                        [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 relatedcampaign 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.