ayeT-Studios
API docs by Redocly

ayeT-Studios Advertiser API Documentation (2.10.0)

Download OpenAPI specification:Download

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

Documentation for ayeT-Studios Advertiser APIs

Latest Changes

2024-07-29: v2.10.0

  • Added support for whitelisted_callback_ips parameter in campaign creation and edit routes
  • Updated Advertiser API (Api2) to return whitelisted_callback_ips with campaign entities
  • Removed tracking endpoint from Advertiser Api2Controller routes
  • Removed related tracking provider code from campaign creation call

2024-07-25: v2.9.2 Deprecated CPC (cost-per-click) campaign types

2024-03-28: v2.9.1 Added landingPage field to campaignData object

2024-02-13: v2.9.0 Added tasks element to campaignData element of CPE campaigns

2023-07-01: v2.8.0 Added new reporting/country_traffic_analysis endpoint, updated traffic_analysis example responses.

2022-12-22: v2.7.0 Added a new reporting/countries endpoint for country-campaign level statistics breakdown.

2022-06-01: v2.6.0 Added campaignIds parameter to installations, stats and traffic_analysis to query aggregate data for multiple campaigns.

2021-08-25: v2.5.1 Added "costUsd" to traffic_analysis, renamed "meanConversionTime" to "meanConversionTimeMinutes" and corrected its type to "numeric"

2021-07-28: v2.5 Added new reporting endpoint traffic_analysis

2021-03-03: Added new documentation

2019-02-20: v2.4.3 Changes to campaign handling:

  • Valid download rates are now 10-1000000 per day with a default of 1000000 (= unlimited)
  • "limitStrategy" has been removed, all campaigns are running in "burst" mode now

2018-01-17: v2.4.2 Added optional startDate and endDate parameters to reporting/stats to filter statistics to a given date range

2018-01-10: v2.4.1 Added "cost" field to reporting/stats to retrieve campaign costs in summary and on a daily basis

2017-12-29: v2.4 Added support for new incent_cpc campaign type (including example in campaign/add documentation)

2017-12-20: v2.3

  • Documented campaign/edit "addBudget", to programmatically add budget to a running or pending campaign
  • Added "campaign/reactivate" to reactivate completed campaigns, added "cpc" and "nicpi" campaign types to "campaign/add"
  • Deprecated "account/bids" and added new call "account/rates" which lists all campaign types, bid and budget ranges for the advertiser account
  • Unified campaignType for campaign creation and in campaign entities, see Appendix II for a list *. * 2.3 is fully API compatible with 2.2, so "standard" and "retention" types still work for "campaign/add", but are deprecated with 2.3

2017-10-23: v2.2.1 "Error 301 - Invalid country requested" has been removed (non-existing country codes are ignored at campaign creation / update), edit campaign now allows resetting campaign to worldwide targeting by passing "worldwide" or "ZZ" as targetCountries

2017-05-08: v2.2 - Added new campaign types (CPA, Managed CPA, Search / High Retention Search)

2017-03-06: v2.1 - Extended reporting/stats, reporting/summary and reporting/summary_daily with conversion data

2016-06-23: Initial release of APIv2

Introduction

Our Advertiser API enables 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 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

To obtain your API Key, use your advertiser account credentials to log into our dashboard.
In the sidebar on the left you'll find the menu entry Account Settings with a menu having the subitem API Settings. This section shows your current API Key and the option to renew it if neccessary.

Get Account Details

Get Account Details

Retrieves information about the associated account, including available funds.

query Parameters
apiKey
required
string

Your Advertiser API Key

Responses

Request samples 

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://ayetstudios.com/api2/account/details?apiKey=X",
  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",
  • "accountData": {
    }
}

Get Bids

Get Bids Deprecated

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

query Parameters
apiKey
required
string

Your Advertiser API Key

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "android": {
    },
  • "ios": {
    }
}

Get Rates

Get Rates

This call retrieves possible campaign types, bids and budgets (Android and iOS) for your advertiser account

query Parameters
apiKey
required
string

Your Advertiser API Key

Responses

Request samples 

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://ayetstudios.com/api2/account/rates?apiKey=X",
  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",
  • "android": {
    },
  • "ios": {
    },
  • "web": {
    }
}

List Campaigns

List Campaigns

Retrieves all campaigns associated with this account.

query Parameters
status
string
Example: status=["running","pending","completed","review"]

optional, JSON array, if set, only returns campaigns with the given statuses

identifier
string
apiKey
required
string

Your Advertiser API Key

Responses

Response samples

Content type
application/json
{}

Get Campaign

Get Campaign

Retrieves a specific campaign identified by its unique campaignId.

query Parameters
apiKey
required
string

Your Advertiser API Key

campaignId
required
integer

the id of the campaign to be returned

Responses

Response samples

Content type
application/json
{}

Create Campaign

Create Campaign

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

query Parameters
apiKey
required
string

Your Advertiser API Key

platform
required
string
Enum: "android" "ios"
Example: platform=android
applicationUrl
required
string
Example: applicationUrl=com.example

package name of the app, iTunes App Id or link to Google Play / iTunes

campaignType
string
Default: "cpi"
Enum: "cpi" "cpi_managed" "cpa" "cpa_managed" "nicpi_managed"
Example: campaignType=cpi
budget
required
number
Example: budget=5

in USD, 1-5000 for normal and high retention, 500-20000 for managed campaigns

bid
number

in USD

bid
string
Enum: "min" "max"
Example: bid=min

"min" / "max" if you want to set the min/max available bid per conversion

targetCountries
Array of strings
Items Enum: "ZZ" "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"
Example: targetCountries=CA,US,GB,DE

comma-seperated list of countries to target (ISO 3166-1 alpha-2)

downloadRate
integer [ 10 .. 1000000 ]
Example: downloadRate=300

maximum number of downloads per day

status
string
Default: "pending"
Enum: "pending" "running"
Example: status=running

initial status

identifier
string
Example: identifier=customer1

an arbitary string which can be used to identify a customers campaign later

trackingProvider
string
Example: trackingProvider=custom_s2s

"custom_s2s" or the id of the tracking provider to use [see "account/tracking"]

redirectUrl
string

required whenever trackingProvider is set, represents the redirect URL containing a {click_id} parameter

eventName
string

"cpa" and "cpa_managed" only, the name of the event that triggers a successful conversion

eventConversionTime
integer

"cpa" and "cpa_managed" only, the average conversion time for users to complete the required action / trigger the event

eventDescription
string >= 20 characters

"cpa" and "cpa_managed" only, the user conversion flow to complete the cpa offer

whitelistedCallbackIps
string
Example: whitelistedCallbackIps=143.21.224.72/23;91.17.119.190/22;45.165.206.98/32

Semicolon-separated list of IP ranges (CIDR notation) for whitelisted callback IPs

Responses

Request samples 

<?php

$apikey = 'X'; // TODO: Replace with your API key

// Android Campaign:
$campaign = [
    'platform' => 'android',
    'applicationUrl' => 'org.mozilla.firefox',
    'campaignType' => 'cpi',
    'budget' => '5',
    'bid' => 'min',
    'targetCountries' => 'US,DE,GB,CA', // optional, default is worldwide
    'downloadRate' => '300', // optional, default is 1000000
    'status' => 'running', // optional, default is 'pending',
    'identifier' => 'customer1', // optional, we set this to customer1 and can later filter our "get" commands
];

// iOS Campaign:
$campaign = [
    'platform' => 'ios',
    'campaignType' => 'cpi',
    '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 1000000
    'status' => 'running'  ,                // optional, default is 'pending',
    'trackingProvider' => 'appsflyer',
    'redirectUrl' => 'https://app.appsflyer.com/529479190?pid=mycompany_int&clickid={click_id}' // the appsflyer tracking url for this campaign
    'whitelistedCallbackIps' => '143.21.224.72/23;91.17.119.190/22;45.165.206.98' // optional semicolon-separated list of IP addresses to whitelist for callbacks, when left empty any callback ip is permitted
];

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

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://ayetstudios.com/api2/campaign/add?apiKey=" . $apikey . "&" . http_build_query($campaign),
    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
{}

Edit Campaign

Edit Campaign

This command is used to edit one or multiple campaign settings

query Parameters
apiKey
required
string

Your Advertiser API Key

campaignId
required
integer

the id of the campaign to be edited

downloadRate
integer [ 10 .. 1000000 ] characters

desired download rate per day

targetCountries
Array of strings
Items Enum: "ZZ" "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"
Example: targetCountries=CA,US,GB,DE

comma-seperated list of countries to target (ISO 3166-1 alpha-2)

bid
number

set the bid per conversion in USD for this campaign

bid
string
Enum: "min" "max"
Example: bid=min

"min" / "max" for minimum or maximum bid

addBudget
number

if set, this amount of budget in USD will be added to the campaign budget and deducted from your advertiser account

whitelistedCallbackIps
string
Example: whitelistedCallbackIps=143.21.224.72/23;91.17.119.190/22;45.165.206.98/32

Semicolon-separated list of IP ranges (CIDR notation) for whitelisted callback IPs

Responses

Response samples

Content type
application/json
{}

Start Campaign

Start Campaign

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

query Parameters
apiKey
required
string

Your Advertiser API Key

campaignId
required
integer

the id of the campaign to be started

Responses

Response samples

Content type
application/json
{}

Pause Campaign

Pause Campaign

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

query Parameters
apiKey
required
string

Your Advertiser API Key

campaignId
required
integer

the id of the campaign to be paused

Responses

Response samples

Content type
application/json
{}

Terminate Campaign

Terminate Campaign

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.

query Parameters
apiKey
required
string

Your Advertiser API Key

campaignId
required
string

the id of the campaign to be terminated

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "refundedBalance": 5
}

Reactivate Campaign

Reactivate Campaign

This command reactivates a completed (non-managed) campaign by adding the specified amount of budget. The new state of the campaign will be "pending" or "review" (if the campaign had been terminated while being under review).

query Parameters
apiKey
required
string

Your Advertiser API Key

campaignId
required
integer

the id of the campaign to be reactivated

addBudget
required
number >= 1

amount of budget to add in USD

Responses

Response samples

Content type
application/json
{}

Get Summary

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

query Parameters
apiKey
required
string

Your Advertiser API Key

startDate
required
string <date>
Example: startDate=2020-12-25

start date for the statistics retrieval

endDate
required
string <date>
Example: endDate=2021-03-01

end date for the statistics retrieval

identifier
string

if set, only campaigns matching the identifier are inspected

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "startDate": "2021-03-01",
  • "endDate": "2021-03-07",
  • "statistics": {
    }
}

Get Summary Daily

Get Summary Daily

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.

query Parameters
apiKey
required
string

Your Advertiser API Key

startDate
required
string <date>
Example: startDate=2020-12-25

start date for the statistics retrieval

endDate
required
string <date>
Example: endDate=2021-03-01

end date for the statistics retrieval

identifier
string

if set, only campaigns matching the identifier are inspected

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "startDate": "2021-03-01",
  • "endDate": "2021-03-07",
  • "statistics": {
    }
}

Get Installations

Get Installations

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

query Parameters
apiKey
required
string

Your Advertiser API Key

campaignId
required
integer

the id of the campaign to be returned (required unless campaignIds is provided)

campaignIds[]
Array of arrays

the ids of the campaigns to be returned (optional replacement for campaignId)

Responses

Response samples

Content type
application/json
Example
{
  • "status": "success",
  • "campaignData": [
    ],
  • "installations": [
    ]
}

Get Stats

Get Stats

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

query Parameters
apiKey
required
string

Your Advertiser API Key

campaignId
required
integer

the id of the campaign to be returned (required unless campaignIds is provided)

startDate
string <date>
Example: startDate=2014-02-12

inclusive, limits "summary", "detailed" and "country" to the date range

endDate
string <date>
Example: endDate=2014-02-13

inclusive, limits "summary", "detailed" and "country" to the date range

campaignIds[]
Array of arrays

the ids of the campaigns to be returned (optional replacement for campaignId)

Responses

Response samples

Content type
application/json
Example
{
  • "status": "success",
  • "campaignData": {
    },
  • "summary": {
    },
  • "detailed": {
    },
  • "countries": {
    }
}

Get Traffic Analysis

Get Traffic Analysis

Retrieves traffic analysis for a given campaign(s) in a given date range, currently max 120 days. The returned data includes the campaign entry, publisher id in our system, specific traffic source, num of impressions, clicks, conversions, mean conversion time, num of conversions below 15s, 30s and those greater than 1 day.

query Parameters
apiKey
required
string

Your Advertiser API Key

campaignId
required
integer

the id of the campaign to be returned (required unless campaignIds is provided)

startDate
string <date>
Example: startDate=2021-07-28

start date of the date range for traffic analysis information (today if omitted)

endDate
string <date>
Example: endDate=2021-07-28

end date of the date range for traffic analysis information (today if omitted)

campaignIds[]
Array of arrays

the ids of the campaigns to be returned (optional replacement for campaignId)

Responses

Response samples

Content type
application/json
Example
{
  • "status": "success",
  • "startDate": "2021-07-21",
  • "endDate": "2021-07-28",
  • "campaignData": {
    },
  • "trafficAnalysis": [
    ]
}

Get Country Traffic Analysis

Get Country Traffic Analysis

Retrieves country traffic analysis for a given campaign(s) in a given date range, currently max 120 days. The returned data includes the campaign entry, country, publisher id in our system, num of impressions, clicks, conversions.

query Parameters
apiKey
required
string

Your Advertiser API Key

campaignId
required
integer

the id of the campaign to be returned (required unless campaignIds is provided)

startDate
string <date>
Example: startDate=2021-07-28

start date of the date range for traffic analysis information (today if omitted)

endDate
string <date>
Example: endDate=2021-07-28

end date of the date range for traffic analysis information (today if omitted)

campaignIds[]
Array of arrays

the ids of the campaigns to be returned (optional replacement for campaignId)

Responses

Response samples

Content type
application/json
Example
{
  • "status": "success",
  • "startDate": "2021-07-21",
  • "endDate": "2021-07-28",
  • "campaignData": {
    },
  • "trafficAnalysis": [
    ]
}

Get Countries

Get Countries

Retrieves all statistics for the countries and the campaigns. The returned data includes the campaign entry, a summary, detailed statistics (per day). For most campaign types, "conversions" is the number of actually billed installs/conversions and matches "retentions" for HR campaigns.

query Parameters
apiKey
required
string

Your Advertiser API Key

startDate
required
string <date>
Example: startDate=2014-02-12

inclusive, limits "summary", "detailed" and "country" to the date range

endDate
required
string <date>
Example: endDate=2014-02-13

inclusive, limits "summary", "detailed" and "country" to the date range

campaignIds[]
number

the ids of the campaigns to be filtered

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "campaignData": [
    ],
  • "summary": {
    },
  • "detailed": {
    }
}

Error Codes - Advertiser API

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

Campaign Types & Platforms

Android:

  • "cpi" [Incent cost-per-install campaign (does not require external tracking)]
  • "cpi_hr" [High-retention incent cost-per-install campaign (does not require external tracking)]
  • "cpi_managed" [Managed incent cost-per-install campaign]
  • "cpa" [Incent cost-per-action campaign]
  • "cpa_managed" [Managed incent cost-per-action campaign]
  • "nicpi_managed" [Managed non-incent cost-per-install campaign]

iOS:

  • "cpi" [Incent cost-per-install campaign]
  • "cpi_managed" [Managed incent cost-per-install campaign]
  • "cpa" [Incent cost-per-action campaign]
  • "cpa_managed" [Managed incent cost-per-action campaign]
  • "nicpi_managed" [Managed non-incent cost-per-install campaign]