ayeT-Studios
API docs by Redocly

ayeT-Studios Publisher API Documentation (1.11.7)

Download OpenAPI specification:Download

ayeT-Studios GmbH: support@ayetstudios.com URL: https://www.ayetstudios.com/contact-us

Documentation for ayeT-Studios Publisher APIs

Latest Changes

2024-04-10: v1.11.7 - Updated Static API and Offerwall API to include categories and tasks in tags field.

2024-01-26: v1.11.6 - Updated Offerwall API documentation examples to include support related fields.

2024-01-10: v1.11.5 - Added include_mobile_offers, include_cpe in Offerwall API response schema and cleaned up non-documented response fields

2024-01-03: v1.11.4 - Added documentation for placements/get_ads_txt API endpoint

2023-11-21: v1.11.3 - Added languages JA, KO, TH, ZH, ID to response examples

2023-09-23: v1.11.2 - Added a persistent task_uuid field to cpe tasks in API responses.

2023-09-21: v1.11.1 - Added max_android_version and max_ios_version fields to Static API and Offerwall API response.

2023-09-11: v1.11 - Reworked the Offerwall API implementation, simplified request parameters, added client_hints and a new example for client-side requests. Older integrations are still functional for the time being, but offer and device matching is impacted.

2023-08-21: v1.10.3 - Updated Offerwall API and Static API responses to include the optionally filled video_url_vp9 field. This is a higher quality VP9 encoded video that might exist if video_url is set.

2023-07-01: v1.10.2 - Updated & improved the Static API documentation.

2023-06-06: v1.10.1 - Updated Offerwall API request to accept the optional include_mobile_offers parameter that if request is made from non mobile device also includes mobile offers.

2023-05-22: v1.10.0 - Updated Offerwall API and Static API responses to include the optionally filled icon_large and video_url fields.

2023-01-31: v1.9.9 - Live API has been removed and will no longer return offers

2022-11-29: v1.9.8 - Updated documentation examples to reflect Static API response now including field currency_amount

2022-07-18: v1.9.7 - Added DAU/ARPDAU to publisher reporting API response

2022-06-13: v1.9.6 - Changed custom_parameter into optional_parameter for Publisher Reporting API, add custom parameters to available postback parameters.

2022-06-08: v1.9.5 - Added rewarded video statistics to Publisher Reporting API.

2022-04-27: v1.9.4 - Updated documentation to include new endpoint for setting currency conversion rate via api and 2 newly available postback parameters.

2022-04-20: v1.9.3 - Updated documentation to reflect Static API change to use Static API token.

2022-01-27: v1.9.2 - Removed default "&num_offers=10" parameter in Offerwall API. By default the number of offers returned is no longer limited.

2021-07-23: v1.9.1 - Renamed "CPE Offer Status" parameter from "externalIdentifier" to "external_identifier" and added "Static API" parameter "include_cpe"

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

The Static API on the other hand is intended for special (network) integration 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 Static API key, once approved by your account manager, is available in the adslot details.

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.

Offerwall API

Retrieve offers matching the provided parameters

This endpoint can be called client-side or server-side, where the ip parameter is required only for server-side requests.

The following parameters are recommended:
[ip] + user_agent + client_hints

client_hints can be obtained in a secure (SSL) browser context - please check the example to the right.

Alternative parameter combinations for special use cases are:

  • ip + device_make + device_model + os + os_version (Android & iOS devices)
  • ip + browser + browser_version (Desktop devices)

Attention: Check the list below for the correct input format of the available parameters.

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 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Mobile Safari/537.36

User agent of user's browser

client_hints
string
Example: client_hints={"architecture":"","bitness":"","brands":[{"brand":"Chromium","version":"116"},{"brand":"Not)A;Brand","version":"24"},{"brand":"Google Chrome","version":"116"}],"fullVersionList":[{"brand":"Chromium","version":"116.0.5845.164"},{"brand":"Not)A;Brand","version":"24.0.0.0"},{"brand":"Google Chrome","version":"116.0.5845.164"}],"mobile":true,"model":"Pixel 7","platform":"Android","platformVersion":"13.0.0","uaFullVersion":"116.0.5845.164","wow64":false}

Client hints of user's browser if existent, otherwise empty string

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

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

include_cpe
boolean
Default: false
Example: include_cpe=true

Specifies whether to return cpe campaigns in the response

include_mobile_offers
boolean
Default: false
Example: include_mobile_offers=true

Specifies whether to return mobile offers for request made from non mobile device

Responses

Request samples 

async function fetchData() {
  let adslotId = 1234;
  let externalIdentifier = 'YOUR_VALUE';

  let userAgent = navigator.userAgent;
  let clientHints = '';

  if (navigator.userAgentData) {
      try {
          clientHints = await navigator.userAgentData.getHighEntropyValues(['architecture', 'bitness', 'brands', 'mobile', 'model', 'platform', 'platformVersion', 'uaFullVersion', 'fullVersionList', 'wow64']);
          clientHints = encodeURIComponent(JSON.stringify(clientHints));
      } catch (e) {
          console.log(e);
      }
  }

  let requestUrl = 'https://www.ayetstudios.com/offers/offerwall_api/' + adslotId + '?external_identifier=' + externalIdentifier + '&user_agent=' + encodeURIComponent(userAgent) + '&client_hints=' + clientHints;

  fetch(requestUrl)
      .then(response => {
          if (!response.ok) {
              throw new Error('Network response was not ok');
          }
          return response.json();
      })
      .then(data => {
          console.log(data);
      })
      .catch(error => {
          console.log('There was a problem with the fetch operation:', error.message);
      });
}

fetchData();

Response samples

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

Static API

The Static API is recommended only for special integrations, because not all campaigns are available without more sophisticated device match. If integrated, it 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 "Static API key" for requests is adslot specific and available in the adslot details once approved by your account manager.

Static API

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

Note: To pass custom parameters from clicks to conversion callbacks, the tracking_link parameter in offer objects can be extended with &custom_1=... to &custom_5=...
Those five parameters can be accessed in the publisher dashboard and from conversion callbacks using the {custom_1} - {custom_5} macros in the resulting callback URL.

The external_identifier parameter found as placeholder in tracking links is important for persistent user identification and also allows access to the users reward status.

path Parameters
adslot
required
string
query Parameters
apiKey
required
string

static api key that is available under adslot details in your dashboard

countries[]
Array of arrays

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

Request samples 

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.ayetstudios.com/offers/get/3142?apiKey=xxxx&countries%5B%5D=DE&platform%5B%5D=ios&conversion_type%5B%5D=cpi",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "num_offers": 3,
  • "offers": [
    ]
}

CPE Offer Status

Retrieves cpe offers reward status information for the adslot by the given external identifier. The returned data includes the offer id, click id, publisher payment, shows completed and available task etc.

path Parameters
adslot
required
string
query Parameters
apiKey
required
string

static api key that is available under adslot details in your dashboard

external_identifier
required
string

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "num_offers": 2,
  • "offers": {
    }
}

Publisher Reporting API

Our Publisher Reporting API allows publishers with and without adserver functionality to retrieve detailed statistics on their placement & adslot performance.

Publisher Reporting API

Retrieves all statistics for the account for the given date range and filtered by optional parameters. The returned data includes the impressions, clicks, conversions, revenue etc. statistics for the specified date range for each day grouped by country. If optional parameters (placements, adslots, etc.) are set, only metrics matching those parameters will be returned.

Attention: Requests to the reporting module are limited to 20 calls per hour.

query Parameters
startDate
required
string
Example: startDate=2020-05-05

The start date for the statistics retrieval

endDate
required
string
Example: endDate=2020-05-06

The end date for the statistics retrieval

placements[]
Array of integers
Example: placements[]=102&placements[]=103

Placements to get reports for

adslots[]
Array of integers
Example: adslots[]=525&adslots[]=526

Adslots to get reports for

adsource[]
Array of strings
Example: adsource[]=adnetwork_abc&adsource[]=adnetwork_xy

names of your configured partner networks (adserver customers only)

adformat[]
Array of strings
Example: adformat[]=offerwall
countries[]
Array of strings
Example: countries[]=US&countries[]=DE
optional_parameter
string
Example: optional_parameter=test_parameter

Filters statistics with a specific subtype (works only on Rewarded Video Adslots and if a optionalParameter is set/supplied in AyetVideoSdk.init(...) when initializing)

apiKey
required
string

Your publisher api key (under account settings in dashboard)

Responses

Request samples 

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.ayetstudios.com/api2/publisher/reporting?startDate=2020-05-05&endDate=2020-05-6&apiKey=xxxx&placements[]=5",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Response samples

Content type
application/json
Example
{
  • "status": "success",
  • "filters": {
    },
  • "data": {
    }
}

Publisher Set Currency Conversion Rate API

Publisher Set Currency Conversion Rate API

Allows publishers to update Currency Conversion Rate, for a specific adslot.

Attention: Requests to the set_conversion_rate module are limited to 60 calls per hour.

query Parameters
apiKey
required
string

Your publisher api key (under account settings in dashboard)

adslotId
required
integer

The id of the adslot for which the currency conversion rate is to be update.

rate
required
number <double>
Example: rate=12.2

New currency conversion rate.

Responses

Request samples 

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.ayetstudios.com/api2/publisher/placements/set_conversion_rate?apiKey=xxx&adslotId=xx&rate=25000",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "message": "Currency conversion rate for Adslot # 5 successfully updated to 25000.23 ."
}

Publisher Get Ads Txt API

Publisher Get Ads Txt API

Allows publishers to retrieve the current (raw) ads.txt file.

query Parameters
placementId
required
integer

Placement ID

hash
required
string

hash for privacy reasons (can be retrieved in the ads txt tab in the placement settings modal)

Responses

Request samples 

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.ayetstudios.com/api2/publisher/placements/get_ads_txt?placementId=22&hash=0abd827e81729b681b85022ca8dd14d1914e215c",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Response samples

Content type
text/plain
# AYET-STUDIOS
ayetstudios.com, AYETSTUDIOS, DIRECT
ayetstudios.com, PL-22, DIRECT

Callbacks/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. 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.

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}&adslot_id={adslot_id}&sub_id={external_identifier}&your_parameter={custom_1}

Your user used this tracking link and completed an offer: https://www.ayetstudios.com/s2s/pub/53270/1/1?external_identifier=your-user-id-1&custom_1=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&adslot_id=18&sub_id=your-user-id-1&your_parameter=your-custom-click-id&is_chargeback=0-or-1

Postback Verification with HMAC Security Hash (optional): Our server will always add a custom header, X-Ayetstudios-Security-Hash, containing a SHA256 HMAC hash of the request parameters and your publisher api key. Your API key can be found in your dashboard at ayetstudios.com under settings.

To verify the hash, perform the following steps: (1) Get all request parameters (2) Order the request parameters alphabetically (3) Build and compare the HMAC hash using the ordered request parameter string and your API key

Available Macros for Postback URLs:

Placeholder Type Description
{transaction_id} string Unique transaction id - use for duplicate checks. If chargeback it's prepend with r-
{payout_usd} float The actual conversion payout in USD. If chargeback value is negative.
{currency_amount} float The amount of currency the user earned (taken from your offerwall currency configuration). If chargeback value is negative.
{external_identifier} string Offerwall API: The external_identifier parameter passed when requesting the offers; Static API: The value of the sub_id parameter appended to the original tracking link
{user_id} int Our internal ID for this offerwall user.
{placement_identifier} string The placement_identifier for which the conversion occured
{adslot_id} int The id of the adslot for which the conversion occured
{sub_id} string The ID of the Placement for which the conversion occured[PL-1...n]
{ip} string Converting device's IP address if known, 0.0.0.0 otherwise
{offer_id} int Offer ID of the converting offer
{offer_name} string Name / title of the converting offer
{device_uuid} string ayeT-Studios internal device identificator
{device_make} string Device manufacturer
{device_model} string Device model
{advertising_id} string Device advertising id (GAID/IDFA) if known, otherwise empty
{sha1_android_id} string Device sha1 hashed android id if known, otherwise empty
{sha1_imei} string Device sha1 hashed imei if known, otherwise empty
{is_chargeback} int Either 0 or 1. Indicator if the callback is a conversion (0) or a chargeback (1).
{chargeback_reason} string Reason why chargeback created. Only available if is_chargeback set to 1.
{chargeback_date} string Date of chargeback creation. Only available if is_chargeback set to 1.
{task_name} string CPE campaigns only, shows individual task name for that conversion.
{task_uuid} string CPE campaigns only, shows the persistent task UUID for that conversion.
{currency_identifier} string Shows virtual currency name as set in adslot.
{currency_conversion_rate} number Shows currency conversion rate used to calculate user currency for the given conversion.
{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

Conversions & Postbacks

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

query Parameters
transaction_id
string

Unique transaction id - use for duplicate checks. If chargeback it's prepend with r-

payout_usd
float

The actual conversion payout in USD. If chargeback value is negative.

currency_amount
float

The amount of currency the user earned (taken from your offerwall currency configuration). If chargeback value is negative.

external_identifier
string

Offerwall only: The external_identifier parameter passed when requesting the offers

user_id
int

Our internal ID for this offerwall user

placement_identifier
string

The placement_identifier for which the conversion occured

adslot_id
int

The id of the adslot for which the conversion occured

sub_id
string

The value of the sub_id parameter appended to the original tracking link

ip
string

Converting device's IP address if known, 0.0.0.0 otherwise

offer_id
int

Offer ID of the converting offer

offer_name
string

Name / title of the converting offer

device_uuid
string

ayeT-Studios internal device identificator

device_make
string

Device manufacturer

device_model
string

Device model

advertising_id
string

Device advertising id (GAID/IDFA) if known, otherwise empty

sha1_android_id
string

Device sha1 hashed android id if known, otherwise empty

sha1_imei
string

Device sha1 hashed imei if known, otherwise empty

is_chargeback
int [ 0 .. 1 ]

Values 0 or 1. Indicator if the callback is conversion or chargeback. If set to 0 then it's conversion else it's chargeback.

chargeback_reason
string

Reason why chargeback created. Only available if is_chargeback set to 1.

chargeback_date
string

Date of chargeback creation. Only available if is_chargeback set to 1.

task_name
string

CPE campaigns only, shows individual task name for that conversion.

task_uuid
string

CPE campaigns only, shows persistent task UUID for that conversion.

currency_identifier
string

Shows virtual currency name as set in adslot.

currency_conversion_rate
number <double>

Shows currency conversion rate used to calculate user currency for the given conversion.

header Parameters
X-Ayetstudios-Security-Hash
string

HMAC Security Hash

Responses

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