Adsterra Ads API: User-Friendly Tutorial for Media Buyers

3.8K

The Adsterra Ads API is a versatile tool for advertisers and affiliates. Whether you’re looking to automate stats monitoring or updating your creatives, this API provides a high level of management functionality. Here’s a brief overview of the core options you can use:

• Monitor all your campaigns outside Adsterra
• Regularly check your balance
• Track performance by getting stats with all important metrics
• Update blacklists and whitelists
• Update advertising creatives’ statuses

By reading this guide, you will get a clear picture of how to navigate the ads API functions and apply them for your benefit. If you’re a publisher who wants to automate monetization efforts, jump to this guide to Adsterra Publishers API.

About the Adsterra Ads API

The Ads API is based on REST architecture. It allows advertisers and affiliate marketers to interact with their ads via HTTP methods and enhance campaign management. These methods facilitate adding, retrieving, and updating data using JSON format in the body request. The API is perfect for routine task optimization. For example, you can add campaign–placement pairs to a blacklist/whitelist in bulk, or massively add custom bids for placements. We recommend resorting to your developer and list all required actions you plan to automate.

API methods to help you out:

• GET: the GET method retrieves information from our platform. It’s most commonly used to fetch data like current balance, campaigns, stats, etc.
• POST: the POST method is used to create new entities like adding new placements to a blacklist.
• PATCH: the PATCH method helps update specific fields on an existing resource. For example, you can refresh your ad creatives’ statuses.

Typical use cases and benefits

Adsterra advertising API is used by:

• Individual media buyers or affiliates
• Media buying teams
• Advertising agencies of any level and size
• Direct advertisers

Use cases:

1. Request recent performance metrics such as: impressions, conversions, CTR, CPM, spending amount, clicks, etc.
2. Filter stats by core parameters to analyze them on the landing, creative, campaign, country, or placement level 
3. Retrieve all advertising landings
4. Update campaign and ad creatives’ statuses
5. Add, update, and clean blacklisted and whitelisted placements
6. Update bids on the dedicated placements (new!)

To Contents ↑

API usage example: whitelisting and blacklisting management

Imagine you’re an advertiser who tracks ad placement IDs. In other words, you monitor every place on publishers’ sites where your ads appear. The purpose of such tracking is to weed out the poor-performing placements and increase bids for the best-performers. That’s a crucial part of the ad campaign optimization process; it’s called blacklisting and whitelisting.

API can help in whitelists and blacklists management outside your Adsterra account. Here’s how:

1. Create a new whitelist
2. Delete placements from a whitelist
3. Check currents whitelists
4. Delete the whole selection of placements in the whitelist

For instance, the following request will return all of your whitelists on Adsterra (Javascript Fetch):

const url = 'https://api3.adsterratools.com/advertiser/campaign/paste-your-campaign-ID-here/linking/whitelist.json';
const options = {
  method: 'GET',
  headers: {
    Accept: 'application/json, application/xml; charset=utf-8, text/csv; charset=utf-8',
    'X-API-Key': 'your-API-key-here'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

To Contents ↑

Benefits

The advertising API is a time-saving and powerful tool if you purchase traffic from various sources and aggregate it in one place, e.g., a tracker or DSP. It empowers quality traffic analysis and campaign optimization since you operate huge volumes of data in one space and on the upper level, avoiding jumping between several platforms.

Getting started: Authentication

Before you start operating with any of the Adsterra advertising API methods, please log in as Advertiser and generate an API token/key. This key is unique for every advertiser. It identifies your account and is obligatory for all requests.

Steps to authenticate:

1 – Sign up or log in to Adsterra
2- Click Tracking >> API
3- Click GENERATE NEW TOKEN

4- Copy the token to the clipboard, as it will assign you an access level (the ability to pull and update data)
5 – Include this token in the X-API-Key request header (not in the URL).

Here’s an example of a request with the GET method, including the API key:

curl --request GET \
 --url https://api3.adsterratools.com/advertiser/stats.xml?start_date=2024-03-06&finish_date=2024-03-06&group_by=date \
 --header 'Accept: application/json' \
 --header 'X-API-Key: your-API-key-here'

Let’s learn to read this request:

1. A URL to call Adsterra’s server is -https://api3.adsterratools.com/-
2. The request method is GET, which means your level of access is limited to pulling the current info, not adding or changing anything.
3. The purpose is to get statistics without entering Adsterra.
4. The advertiser/stats piece of request is a path to a resource on the Adsterra side
5. All that comes after the “?” mark are called parameters. In our example the parameters are start date, end data and a grouping filter.
6. JSON is the format we will get data from our platform. You can also receive data in XML format.
7. X-API-Key is a header part of the request where you pass your unique token.

To Contents ↑

Adsterra ads API practice

Let’s walk through a couple of requests and examine how you can get, post, and update data, using your programming language and choosing between various output formats.

Jump to Adsterra’s official documentation and check the right upper sidebar. It’s a test widget where you can try out several API requests.

This widget is great for testing requests in any programming language. Simply choose the one you using and check how the correct request–response pair look:

To Contents ↑

1. Retrieve stats and group important metrics

Depending on your goals, you can pull core campaign stats from Adsterra grouping them by parameters needed. By default, we group statistics by date.

Here below is an example of such GET request in PHP:

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('GET', 'https://api3.adsterratools.com/advertiser/stats.json?start_date=2024-03-06&finish_date=2022-03-06&group_by=date', [
  'headers' => [
    'Accept' => 'application/json',
    'X-API-Key' => 'your-API-key-here',
  ],
]);
echo $response->getBody();

Grouping filters you can apply apart from date: Campaign, Banner, Landing, Country, Placement.

Grouping by country, for example, allows to highlight the most profitable geos. You can increase spending for these geos to enhance ROI. Or, alternatively, you can decrease bids for geos with lots of clicks but fewer conversions.

To Contents ↑

2. Update statuses of ad creatives (banners)

Every campaign requires refreshment of ad creatives (or banners, as we call them within the API documentation). With this API request, you can update creatives’ statuses avoiding manual work on the Adsterra platform.

Here’s an example in PHP:

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('PATCH', 'https://api3.adsterratools.com/advertiser/banner/your-banner-id-here.json', [
  'body' => '{
  "active": true
}',
  'headers' => [
    'Accept' => 'application/json',
    'Content-Type' => 'application/json',
    'X-API-Key' => 'your-API-key-here',
  ],
]);
echo $response->getBody();

The same request in JavaScript/Fetch:

const url = 'https://api3.adsterratools.com/advertiser/banner/your-banner-id-here.json';
const options = {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
    Accept: 'application/json',
    'X-API-Key': 'your-API-key-here'
  },
  body: '{"active":true}'
};
try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

To Contents ↑

3. Ad campaign management

When you need help in reassessing budgets, or check campaigns’ activity without jumping to Adsterra, you can access the campaign list via. Here below is a GET request (JavaScript / Fetch) that will return:

• Campaign status
• ID
• Ad format (e.g., PU = Popunder)
• Campaign type (SSP or managed)
• Pricing (CPM, CPC, CPA)
• Pricing settings (bids)

const url = 'https://api3.adsterratools.com/advertiser/campaigns.json';
const options = {
  method: 'GET',
  headers: {Accept: 'application/json', 'X-API-Key': 'your-API-key-here'}
};
try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

To Contents ↑

Handling API request errors

Apart from the “200” server response — which means SUCCESS – you sometimes can face errors. Let’s learn how to understand the most common ones and cope with them:

• 401 — wrong token or unauthorized request. Please copy your current, active token and check whether you’re logged in to Adsterra.
• 403 — access denied. It’s possible that the token is no longer valid. Check the current token and reach out to your manager for troubleshooting. Another reason for 403 error is when someone’s requesting a resource they don’t have access to.
• 404 — not found. Make sure the URL is correct.
• 500 – internal server error.

To Contents ↑

Conclusion

The Adsterra advertising API allows for campaign & creatives management, ad performance tracking, and quick data retrieval. By mastering methods like GET, POST, and PATCH, you can easily create, update, and retrieve important advertising data even if you’re not an advanced developer. Refer to the official Ads API documentation for further details and refined options.

To Contents ↑

Ads API management FAQs: