Adsterra Ads API: Automate, Analyze, Accelerate, Amplify…Everything

4K

The Adsterra Ads API is a versatile tool for advertisers and affiliates. Whether you’re looking to automate stats monitoring or updating bids in current campaigns, this API provides all the functionality you need. Here’s a brief overview of the core options you can use:

• Add new campaigns with targeting and bidding
• Edit bids in existing campaigns
• Monitor campaign statuses
• Check your balance
• Track performance by pulling vital stats
• 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 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 campaigns via HTTP methods. These methods facilitate adding, retrieving, and updating campaign data. 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.

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. Automate Popunder (CPM) campaign creation
2. Speed up strategic updates in current CPM Popunder campaigns
3. Keep control over core metrics: impressions, conversions, CTR, CPM, spending amount, clicks, etc.
4. Filter stats by core parameters to analyze 
5. Retrieve advertising landings
6. Refresh campaigns’ and ad creatives’ statuses
7. Add, update, and clean blacklisted and whitelisted placements

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);
}

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:

• Sign up or log in to Adsterra.
• Click Settings and select the API tab.
• Click GENERATE NEW TOKEN.

• It’s important to copy the token to the clipboard as it won’t be visible after you update the page.
• Include this token in the X-API-Key request header (not in the URL.)

Please note: Your API token has a limited lifespan and requires periodic renewal. We will notify your account when it is time to generate a new token.

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.

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:

1. Create ad campaigns (Popunder, CPM)

The most expected API functionality: you can now request Popunder CPM campaigns with basic or granular targeting settings–the same as available in your advertiser’s account.

Save time by automating:

• Campaign creation
• Targeting and bidding setup
• Adding CPA Goal and Smart CPM tools
• Request status tracking

Here’s a PHP sample campaign request sent via API (POST method):

Your request must include the same obligatory settings as any other new campaign launched via the Self-Serve Platform.

• Campaign name
• Target device types
• Type of traffic
• Internet connection type
• Category of ad unit
• Pricing model
• Allowed value:
• URL of the landing page with optional macros
• Landing page and/or prelander previews
• Bid (Country + Price)
• Campaign start option

2. Update campaigns (Popunder, CPM)

React faster than ever when it’s time to change your bidding tactic, optimize traffic limits, or swap targeting options. To update a price, send a PATCH request with the campaign ID, country ID, and a new bid amount.

This option is mainly used by agencies or affiliate teams who run ads on volatile markets with stiff competition. But it’s also a great way to maximize spending when you need to quickly change the price per this or that country’s traffic.

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

4. 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);
}

5. 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);
}

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.

Conclusion

The advertising API allows you to manage campaigns and creatives, track ad performance, and retrieve data more quickly. By mastering methods like GET, POST, and PATCH, you can easily create, update, and retrieve important advertising data. Refer to the official Ads API documentation for further details and refined options.

Ads API management FAQs:

Functionality	HTTP Method
View Your Account Balance	GET
Update a Banner’s Activity	PATCH
Get Landings’ Statuses in a Banner	GET
Get a Specific Campaign’s Status	GET
Get the Statuses of All Campaigns	GET
Update Campaign Activity	PATCH
Get Banners’ and Landings ‘Statuses in a Campaign	GET
View Blacklisted Placements for a Campaign	GET
Get Campaign Request Status	GET
Update Campaign	PATCH
Create Campaign Request	POST
Add/Remove/Clear Placements to Campaigns’ Blacklists or Whitelists	POST
View All Whitelisted Placements in a Campaign	GET
Generate Performance Reports	GET
Generate Dictionaries (Lists of Country ID, Carriers, OS, etc.)	GET
View Custom Bids for a Campaign	GET
Set Custom Bids for a Campaign	POST
Update Custom Bids for a Campaign	PATCH
Remove a Specific /All Custom Bids from a Campaign	DELETE