ayeT-Studios Publisher API Documentation (v1.6)



Updates

2018-03-07: v1.6 - Renamed platform type "web" to "desktop" + "pc" and "mac" device types, added "start_date" and "end_date" to offer entities
2018-03-01: v1.5 - Updated parameters for live api requests, provided examples with plain GET requests
2018-02-08: v1.4 - Added static api response example for non-incent campaigns
2017-10-28: v1.3 - Conversions & Postbacks has been updated, parameters are no longer passed to postback URLs automatically
2017-10-23: v1.2 - Publisher account & placement creation information, virtual placements, placement_identifier in s2s callbacks
2017-05-10: v1.1 - Release of our Live Offers API
2017-04-05: v1.0 - Initial Release of our Static Offers API


Introduction

Our Publisher API allows fetching our offer inventory either statically ("Static API") or dynamically for specific users ("Live API").
The Static API is easier to integrate and should be called each 15-30 minutes to make sure our campaigns are still available, did not run into daily caps or changed targeting / bid.
The Live API delivers offers for a specific user and filters our inventory by his country, device type and other possible factors (campaign eligibility) which will increase your conversion rate and CPM. The Live API is intended to be called for each specific user whenever offers are supposed to be delivered.

Attention: Ensure these requests are made serverside, otherwise you might leak your API Key!

We use a REST API with JSON encoded responses.
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 Placement ID / Setup
  2. Static API
  3. Live API
  4. Conversions & Postbacks
  5. Virtual Placements for Ad-Networks
  6. Appendix I: IP Whitelisting
  7. Appendix II: Error Codes





1. Obtain API Key and Placement ID / Setup


Before starting with the API integration, we recommend to sign up for a publisher account. After creating your account, please evaluate whether you require "virtual placements". This usually applies to ad networks with a large number of own traffic sources. Check Virtual Placements for Ad-Networks for more information.

We will assist you in setup and initial backend configuration regarding conversion postbacks, quality of your traffic, offer categories you're looking for and possible use cases for each API.
If you're not going to use virtual placements, go to Placements / Apps and create a new API placement. You'll need a placement identifier and your api key (can be obtained under Account Settings) to proceed.
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 ayetPublisherRequest($placementId, $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/offers/'.$command.'/'.$placementId,        // Important: Endpoint for APIv2 is /api2/...!
            CURLOPT_POST => 1,
            CURLOPT_POSTFIELDS => http_build_query($requestData))
            );

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

        return json_decode($responseData, true);
    }
			        

2. Static API


Get active campaigns for your placement

Summary:

Returns a list of currently running campaigns on our platform which suit your placement. Can be filtered by additional parameters.

Call:

https://www.ayetstudios.com/offers/get/PLACEMENT_IDENTIFIER?apiKey=API_KEY...
        

Parameters:

        ARRAY platform (optional, 1..n [android, ios, desktop])
        ARRAY conversion_type (optional, 1..n [cpi, cpa, cpl])
        ARRAY countries (optional, 1..n [array of iso2 country codes])
        

Possible error codes:

errorCodeerrorMessage
100Authentification failed, check your API Key.
103Unknown placement identifier XXX.

Example:

        $responseData = ayetPublisherRequest("my_app1", "get", ['countries' => ['US', 'DE', 'IN', 'FR'], 'platform' => 'ios']);

        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 (same, but plain URL request):

https://www.ayetstudios.com/offers/get/my_app1?countries[]=US&countries[]=DE&countries[]=IN&countries[]=FR&platform=ios&apiKey=API_KEY
	                

Example Output:

Array
(
    [status] => success
    [num_offers] => 9
    [offers] => Array
        (
            [0] => Array
                (
                    [id] => 53386
                    [store_id] => 10732214391				// android package or ios app id
                    [landing_page] => https://itunes.../id10732214391	// link to the app store or to the landing page
                    [icon] => http://...512x512bb.jpg	                // square icon
                    [name] => Super Jump & Run			        // offer name
                    [description] => 					// optional offer description
                    [icon_large] => 					// optional large icon
                    [video_url] => 						// optional video url (30s)
                    [platform] => ios					// platform [android, ios, desktop]
                    [devices] => Array					// devices [phone, tablet, (pc, mac -> for "desktop" only)]
                        (
                            [0] => phone
                            [1] => tablet
                        )

                    [category] => incent				        // campaign category [incent, nonincent]
                    [conversion_type] => cpi			        // type [cpi, cpa, cpl]
                    [conversion_time] => 300			        // approx. conversion callback time [seconds]
                    [conversion_instructions] => Install & Run		// conversion instructions for user
                    [countries] => Array					// country list (iso2, empty array is worldwide)
                        (
                        )

                    [payout_usd] => 0.09			                // the publisher payout in USD
                    [epc] => new				                // EPC in USD, "new" if not determined yet
                    [daily_cap] => 0			                // daily_cap [0=unlimited]
                    [tracking_link] => https://www.ayetstudios.com/s2s/pub/53386/1/1?sub_id={subid}&idfa={idfa}&idfa_limited_tracking={idfa_limited_tracking}
                                                                        // see "Conversions & Postbacks" for details on tracking link parameters
                    [created] => 2017-03-21 15:02:45
                    [start_date] => 2017-03-21 00:00:00 // start datetime for this offer in UTC
                    [end_date] => 2022-03-21 00:00:00 // start datetime for this offer in UTC
                )
            [1] => Array
                (
                    [id] => 53270
                    [store_id] => 106564165
                    [landing_page] => https://itunes.../id106564165
                    [icon] => http://...512x512bb.jpg
                    [name] => News & Magazines
                    [description] =>
                    [icon_large] =>
                    [video_url] =>
                    [platform] => ios
                    [devices] => Array
                        (
                            [0] => phone
                            [1] => tablet
                        )

                    [category] => incent
                    [conversion_type] => cpa
                    [conversion_time] => 600
                    [conversion_instructions] => Install, Register and Start Reading
                    [countries] => Array
                        (
                            [0] => CA
                            [1] => US
                        )

                    [payout_usd] => 0.51
                    [epc] => new
                    [daily_cap] => 0
                    [tracking_link] => https://www.ayetstudios.com/s2s/pub/53270/1/1?sub_id={subid}&idfa={idfa}&idfa_limited_tracking={idfa_limited_tracking}
                    [created] => 2017-03-19 01:50:11
                    [start_date] => 2017-03-19 00:00:00 // start datetime for this offer in UTC
                    [end_date] => 2022-03-19 00:00:00 // start datetime for this offer in UTC
                )
            [2] => Array
                (
                    [id] => 69673
                    [store_id] => com.nonincent.app
                    [landing_page] => https://play.google.com/store/apps/details?id=com.nonincent.app
                    [icon] => //lh3.googleusercontent.com/xxxv=w140
                    [name] => Promoted App Name
                    [description] =>
                    [icon_large] =>
                    [video_url] =>
                    [platform] => android
                    [devices] => Array
                        (
                            [0] => phone
                            [1] => tablet
                        )

                    [category] => nonincent
                    [conversion_type] => cpi
                    [conversion_time] => 300
                    [conversion_instructions] => Install & Run
                    [countries] => Array
                        (
                        )

                    [payout_usd] => 1.80
                    [epc] => new
                    [daily_cap] => 0
                    [tracking_link] => https://www.ayetstudios.com/s2s/pub/69673/1/1?sub_id={subid}&gaid={gaid}&gaid_limited_tracking={gaid_limited_tracking}
                    [created] => 2018-01-21 15:02:45
                    [start_date] => 2018-01-21 00:00:00 // start datetime for this offer in UTC
                    [end_date] => 2023-01-21 00:00:00 // start datetime for this offer in UTC


                    // THE FOLLOWING APPLIES TO NON-INCENT CAMPAIGNS ONLY:
                    [creatives] => Array                        // creatives is only available for non-incent campaigns
                        (
                            [0] => Array
                                (
                                    [type] => native                    // creative type [native, banner, interstitial, video]
                                    [name] => Promoted App Name
                                    [description] =>
                                    [icon] => //lh3.googleusercontent.com/xxxv=w140
                                    [countries] => Array                // country list for this creative (iso2, empty array means it can be used for all countries targeted by this campaign)
                                        (
                                        )

                                    [tracking_link] => https://www.ayetstudios.com/s2s/pub/69673/{publisher_id}/{placement_id}?sub_id={subid}&gaid={gaid}&gaid_limited_tracking={gaid_limited_tracking}
                                )

                            [1] => Array
                                (
                                    [type] => banner
                                    [asset_url] => https://....png      // asset_url is the location of this creative [applies to banner, interstitial and video]
                                    [width] => 200                      // width of this creative in pixels
                                    [height] => 200                     // height of this creative in pixels
                                    [size] => 28526                     // size of this creative in bytes
                                    [countries] => Array
                                        (
                                            [0] => US                   // country list for this creative (iso2, empty array means it can be used for all countries targeted by this campaign)
                                        )

                                    // when working with creatives, please always use the associated tracking_link, otherwise we cannot optimize campaign performances by creatives
                                    [tracking_link] => https://www.ayetstudios.com/s2s/pub/69673/{publisher_id}/{placement_id}?sub_id={subid}&gaid={gaid}&gaid_limited_tracking={gaid_limited_tracking}&crid=1
                                )

                            [2] => Array
                                (
                                    [type] => banner
                                    [asset_url] => https://....png
                                    [width] => 320
                                    [height] => 50
                                    [size] => 30445
                                    [countries] => Array
                                        (
                                            [0] => CA
                                            [1] => AU
                                        )

                                    [tracking_link] => https://www.ayetstudios.com/s2s/pub/69673/{publisher_id}/{placement_id}?sub_id={subid}&gaid={gaid}&gaid_limited_tracking={gaid_limited_tracking}&crid=3
                                )
                        )

                )
            ...
        )
)


        

3. Live API


Get or preload campaigns for the specific user / device

Summary:

The call to live/get returns matching campaigns for a specific user and device. Prefiltering will significantly increase the conversion rates for our offers. The average response time for an uncached get request is about 4 seconds.
For faster execution, you can use the cache functionality by calling live/cache with the same parameters to instruct our servers to prefetch offers for the user in the background. Calling live/get for the device/user 5-240 seconds later should result in an average response time of less than 1 second.
Attention: Even if non-incent inventory is enabled for your placement, the live API only returns incent offers!

Call:

cache (optional): https://www.ayetstudios.com/offers/live/cache/PLACEMENT_IDENTIFIER?apiKey=API_KEY&ip=USER-IP-V4&platform=ios&idfa=IDFA
get             : https://www.ayetstudios.com/offers/live/get/PLACEMENT_IDENTIFIER?apiKey=API_KEY&ip=USER-IP-V4&platform=ios&idfa=IDFA
        

Parameters:

        ARRAY platform (required, 1..n [android, ios, desktop])
        STRING ip (required, IPv4 of the user on whose behalf the offers are requested)
        STRING gaid (recommended, the google advertising id for android users)
        INTEGER gaid_limited_tracking (optional, 1 = limited ad tracking enabled, 0 = ad tracking without limitation)
        STRING idfa (recommended, the apple idfa for ios users)
        INTEGER idfa_limited_tracking (optional, 0 = no tracking allowed, 1 = ad tracking allowed)
        STRING android_id (optional, ANDROID_ID for the device)
        STRING imei (optional, the IMEI of the android or ios device)
        STRING make (optional, the manufacturer of the device, e.g. "Apple" or "Samsung")
        STRING model (optional, the device model, e.h. "iPhone 3,1" or "SM-G930P")

        ARRAY conversion_type (optional, 1..n [cpi, cpa, cpl])

        Important: At least one of the parameters "gaid", "idfa", "android_id" or "imei" is required!
        

Possible error codes:

errorCodeerrorMessage
100Authentification failed, check your API Key.
103Unknown placement identifier XXX.
104Operation timed out.
105[Different error messages for missing / invalid parameters]

Example:

        $responseData = ayetPublisherRequest("my_app1", "live/get", ['ip' => '77.23.81.129', 'platform' => 'ios', 'idfa' => '87fcb61f-e7e4-479f-8539-6a50a213d2d2', 'idfa_limited_tracking' => 0]);

        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 (same, but plain URL request):

https://www.ayetstudios.com/offers/live/get/my_app1?ip=77.23.81.129&platform=ios&idfa=87fcb61f-e7e4-479f-8539-6a50a213d2d2&idfa_limited_tracking=0&apiKey=API_KEY
	                

Example Output:

Array
(
    [status] => success
    [num_offers] => 9
    [offers] => Array // only for "live/get" - not present in the response of "live/cache"
        (
            [0] => Array
                (
                    [id] => 53386
                    [store_id] => 10732214391				// android package or ios app id
                    [landing_page] => https://itunes.../id10732214391	// link to the app store or to the landing page
                    [icon] => http://...512x512bb.jpg	                // square icon
                    [name] => Super Jump & Run			        // offer name
                    [description] => 					// optional offer description
                    [icon_large] => 					// optional large icon
                    [video_url] => 						// optional video url (30s)
                    [platform] => ios					// platform [android, ios, desktop]
                    [devices] => Array					// devices [phone, tablet, (pc, mac -> for "desktop" only)]
                        (
                            [0] => phone
                            [1] => tablet
                        )

                    [category] => incent				        // campaign category [incent, nonincent]
                    [conversion_type] => cpi			        // type [cpi, cpa, cpl]
                    [conversion_time] => 300			        // approx. conversion callback time [seconds]
                    [conversion_instructions] => Install & Run		// conversion instructions for user
                    [countries] => Array					// country list (iso2, empty array is worldwide)
                        (
                        )

                    [payout_usd] => 0.09			                // the publisher payout in USD
                    [epc] => new				                // EPC in USD, "new" if not determined yet
                    [daily_cap] => 0			                // daily_cap [0=unlimited]
                    [tracking_link] => https://www.ayetstudios.com/s2s/pub/53386/1/1?sub_id={subid}
                                                                        // see "Conversions & Postbacks" for details on tracking link parameters
                    [created] => 2017-03-21 15:02:45
                    [start_date] => 2017-03-21 00:00:00 // start datetime for this offer in UTC
                    [end_date] => 2022-03-21 00:00:00 // start datetime for this offer in UTC
                )
            [1] => Array
                (
                    [id] => 53270
                    [store_id] => 106564165
                    [landing_page] => https://itunes.../id106564165
                    [icon] => http://...512x512bb.jpg
                    [name] => News & Magazines
                    [description] =>
                    [icon_large] =>
                    [video_url] =>
                    [platform] => ios
                    [devices] => Array
                        (
                            [0] => phone
                            [1] => tablet
                        )

                    [category] => incent
                    [conversion_type] => cpa
                    [conversion_time] => 600
                    [conversion_instructions] => Install, Register and Start Reading
                    [countries] => Array
                        (
                            [0] => CA
                            [1] => US
                        )

                    [payout_usd] => 0.51
                    [epc] => new
                    [daily_cap] => 0
                    [tracking_link] => https://www.ayetstudios.com/s2s/pub/53270/1/1?sub_id={subid}
                    [created] => 2017-03-19 01:50:11
                    [start_date] => 2017-03-19 00:00:00 // start datetime for this offer in UTC
                    [end_date] => 2022-03-19 00:00:00 // start datetime for this offer in UTC
                )
            ...
        )
)
        

4. Conversions & Postbacks


Whenever a conversion for your traffic is tracked, our server sends a postback to your tracking endpoint.
In your publisher dashboard, you can configure the callback urls for each of your placements, or if you're an Ad-Network with virtual placements enabled, you can configure your global callback url for all placements.
Important: Your server must always reply with an HTTP 200 status code to our postbacks. Otherwise we will resend the postback 12 times over a span of one hour before giving up.

Our postbacks always contain revenue_usd (your revenue in USD), placement_identifier (the identifier of the placement the conversion belongs to). Also you have access to any parameter you passed to the original tracking URL clicked by your user.

Example:

Let's assume this is your configured postback URL (in our dashboard under Placements -> Settings):
https://www.your-ad-server.com/postback?payout_usd={payout_usd}&placement_identifier={placement_identifier}&sub_id={sub_id}

Your user used this tracking link and completed an offer:
https://www.ayetstudios.com/s2s/pub/53270/1/1?sub_id=your-user-id-1&_parameter=your-custom-click-id

The final postback to your server will look like this:
https://www.your-ad-server.com/postback?payout_usd=0.51&placement_identifier=my_api_placement&sub_id=your-user-id-1
payout_usd [automatically added] is the actual revenue your user generated with that conversion. When rewarding your user, make sure to calculate his reward based on payout_usd, as your own campaign information might be outdated, especially if periodically calling the Static API to fetch offers!
placement_identifier [automatically added] is the identifier you chose when creating your placement in the dashboard, check Placements / Apps for a list of your placements and identifiers.
sub_id is an additional parameter you appended to the tracking URL when redirecting the user - you can access them in your postback url to return it to your server. _parameter is another custom parameter you passed in the tracking URL - however, since you didn't configure it in your postback, we will not return it in the callback sent to your server.

Available Macros for Postback URLs:
{transaction_id}stringUnique transaction id - use for duplicate checks
{payout_usd}floatThe actual conversion payout in USD
{placement_identifier}stringThe placement_identifier for which the conversion occured
{ip}stringConverting device's IP address if known, 0.0.0.0 otherwise
{offer_id}intOffer ID of the converting offer
{offer_name}stringName / title of the converting offer
{device_uuid}stringayeT-Studios internal device identificator
{device_make}stringDevice manufacturer
{device_model}stringDevice model
{advertising_id}stringDevice advertising id (GAID/IDFA) if known, otherwise empty
{sha1_android_id}stringDevice sha1 hashed android id if known, otherwise empty
{sha1_imei}stringDevice sha1 hashed imei if known, otherwise empty

5. Virtual Placements for Ad-Networks


If you're an Ad-Network with a larger number of own publishers you want mediate our inventory to, your account manager can manually enable a special mode for your publisher account, called "virtual placements".

Using virtual placements, you cannot longer create api placements in your dashboard. Instead, any alphanumeric string can be used as placement identifier when fetching offers. We automatically create a new virtual placement if it doesn't exist or reuse the existing one.

This way you can request offers for each of your own publishers separately, which allows both us and yourself to optimize traffic.

Important: To get offers and tracking links, please request static offers for each virtual placement separately. For the live api, make sure to use the correct placement identifier and user information.

In our publisher dashboard, you can change your global callback url for all virtual placements under Apps / Placements. To identify a virtual placement, each callback contains a placement_identifier parameter, which matches the name you chose for the attributed virtual placement in your previous static / live offer request.
Check Conversions & Postbacks for more information on serverside callbacks.

6. Appendix I: IP Whitelisting


If your want to restrict postbacks to our callback server IPs, please whitelist the following IPs and check back regularly for possible changes:
35.165.166.40
35.166.159.131
52.40.3.140
	    
Last Update: 2017-04-07

7. Appendix II: Error Codes


errorCodeerrorMessage
100Authentification failed, check your API Key.
101Unknown action $action for Offers API.
103Unknown placement identifier $placementId.
104Operation timed out.
105[Different error messages for missing / invalid parameters]