ayeT-Studios Publisher API Documentation (1.9)

Download OpenAPI specification:Download

Documentation for ayeT-Studios Publisher APIs

Latest Changes

2021-03-03: Added new documentation

2021-03-03: v1.9 - Added Offerwall API, Deprecated Live API

2020-08-11: v1.8.1 - Updated documentation to introduce new parameters to differentiate chargebacks from conversions

2020-05-19: Initial release of the Publisher Reporting API

2020-04-30: v1.8 - Updated documentation to reflect Live API changes (desktop support and optional device identifiers)

2019-07-19: v1.7 - Updated documentation to reflect the adslot changes

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

Introduction

Our Publisher APIs allow fetching our offer inventory either statically from your servers ("Static API") or dynamically for specific users both server-side and client-side ("Offerwall API").

The Static API is easier to integrate and must be called from your servers each 15-30 minutes to make sure our campaigns are still available, did not run into daily caps or changed targeting / bid.

The Offerwall 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.

We use a REST API with application/json responses. Most of our examples in this documentation are available in different languages. The PHP examples rely on mod_curl being enabled.

Obtain API Key, Create Placement & Adslot / Setup

Before starting with the API integration, we recommend to sign up for a publisher account.
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.

In your account, go to Placements / Apps and create a new API placement and one or more adslots for it.
After creating a placement and adslot(s), go to Edit Adslot to get integration details in the modal's overview tab.
If you want to perform the integration manually, you'll need the adslot id and your api key (which can be obtained under Account Settings) to proceed.

Offerwall API

The Offerwall API provides a solution for publishers who want to include an offerwall in their application/website but have control over the presentation of the offers. All offers matching the parameters provided will be returned and can be displayed to the user. The Offerwall API supports both server and client-side calls, which distinguishes it from the deprecated Live API.

Offerwall API

Retrieve offers matching the provided parameters

For server-side requests, one of the following combinations is required:

  • ip + device_make + device_model + os (Android & iOS)
  • ip + browser (Desktop devices)
  • ip + user_agent (all devices)

For client-side requests, one of the following combinations is required:

  • device_make + device_model + os (Android & iOS via direct request)
  • none (all devices, will use HTTP_USER_AGENT and must be called in a browser)

If none of the above combinations is provided, the HTTP_USER_AGENT with the ip of the client is used.
Attention If making requests with make/model strings, make sure they look like this for example: make: "Samsung", model: "Galaxy S10" make: "Apple", model: "iPhone" (for iOS, iPhone or iPad are sufficient model names).

path Parameters
adslot
required
string

Id of the adslot

query Parameters
external_identifier
required
string
Example: external_identifier=id of user

External identifier

device_make
string
Example: device_make=Samsung

Make of the user's device

device_model
string
Example: device_model=GALAXY S10

Model of the user's device

os
string
Enum: "android" "ios" "desktop"
Example: os=android

Operating system of the user's device

os_version
string
Example: os_version=10.1.0

Operating system version of the user's device

browser
string
Example: browser=Chrome

Browser of user's device

browser_version
string
Example: browser_version=88.0.4324.96

Browser version of user's device

user_agent
string
Example: user_agent=Mozilla/5.0%20(Linux;%20Android%2010.1.0;%20Galaxy%20S10%20Build/IMM76B)%20AppleWebKit/535.19%20(KHTML,%20like%20Gecko)%20Chrome/64.0.1025.133%20Mobile%20Safari/535.19

User agent of user's device (if called server-side)

ip
string
Example: ip=203.0.113.1

IP address of the user (if called server-side)

gaid
string
Example: gaid=97987bca-ae59-4c7d-94ba-ee4f19ab8c21

Google Advertising Identifier of the user's device

idfa
string
Example: idfa=6D92078A-8246-4BA4-AE5B-76104861E7DC

iOS Identifier for Advertisers of the user's device

custom_1
string

Custom parameter to pass variables to the conversion callbacks

custom_2
string

Custom parameter to pass variables to the conversion callbacks

custom_3
string

Custom parameter to pass variables to the conversion callbacks

custom_4
string

Custom parameter to pass variables to the conversion callbacks

custom_5
string

Custom parameter to pass variables to the conversion callbacks

request_live_networks
boolean
Default: "false"
num_offers
integer
Default: "10"

Number of offers to return

offer_sorting
string
Enum: "payout" "conversion_rate" "epc" "ecpm"

Specify the key for sorting

minimum_payout
number <double>

Minimum payout of offers to return

header Parameters
HTTP_USER_AGENT
string
Example: Mozilla/5.0 (Linux; Android 10.1.0; Galaxy S10 Build/IMM76B) AppleWebKit/535.19 (KHTML, like Gecko) Chrome/64.0.1025.133 Mobile Safari/535.19

User agent of user's device (if called client-side)

Responses

Request samples

<?php

// Prepare required parameters:
$adslotId = 1;
$external_identifier = "test";
$user_agent = urlencode($_SERVER['HTTP_USER_AGENT']);
$ip = $_SERVER['REMOTE_ADDR'];

// Make request:
$ayetResponse = file_get_contents("https://www.ayetstudios.com/offers/offerwall_api/" . $adslotId . "?external_identifier=" . $external_identifier ."&user_agent=" . $user_agent . "&ip=" . $ip, false, stream_context_create(['http' => ['ignore_errors' => true]]));
$ayetResponse = json_decode($ayetResponse,true);

// Output response:
print_r($ayetResponse);

?>

Response samples

Content type
application/json
Example
{
  • "status": "success",
  • "num_offers": 6,
  • "filters": {
    },
  • "offerwall": {
    },
  • "offers": [
    ]
}

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

Static API

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

path Parameters
adslot
required
string
query Parameters
apiKey
required
string
countries[]
array

array of iso2 country codes

platform[]
Array of strings
Items Enum: "android" "ios" "desktop"
conversion_type[]
Array of strings
Items Enum: "cpi" "cpa" "cpl"

Responses