The API allows you to programmatically manipulate and retrieve data from the ad server using command line tools or a programming language such as Java or PHP.
There are many possible use cases for the API, but some of the more common ones would be:
In fact, if you were so inclined you could actually develop your own control panel entirely from scratch, which might be of interest to a large ad network for example.
To use the API, you simply make HTTP GET or POST requests to the API modules and the API will send back an XML response. This simplicity was a design goal because it allows you to use the API with virtually any programming language because almost all programming languages include HTTP and XML support. In fact, you can even use it from your browser address bar or with a command line HTTP client such as curl or wget.
First, you need to enable the API. To do that, log in to the control panel as a privileged administrator and click on the Settings icon in the toolbar. Then click on Basic > API in the navigation menu on the left. Change the API Usage option to Enabled and then press the Save Changes button.
Make sure to take note of the Secret Key as you will need to include it with every API request!
Now that you have the API enabled, let's assume for example that you want to create about 100 different themes for your ad network to use with your publishers. Creating them one by one with the control panel would take a lot of time! You already have the list of theme names in a text file named themes.txt with the names of the themes one per line like the following:
Example One
Example Two
Example Three
...
Using a few simple Linux commands, you can read the themes.txt and create the themes by making an HTTP POST request to /servlet/control/api/themes/create (which is the URL of the API module to create themes) with the secret and name parameters:
SECRET_KEY=a78bf24c5a23581aceba1c5f51ac4cad
cat themes.txt | while read name
do curl -d "secret=$SECRET_KEY&name=$name" http://example.com/servlet/control/api/themes/create
done
Alternatively the equivalent code written in Perl and using the LWP::UserAgent module would be:
#!/usr/bin/perl -w
use strict;
use LWP::UserAgent;
my $API_KEY = "a78bf24c5a23581aceba1c5f51ac4cad";
my $API_URL = "http://example.com/servlet/control/api/themes/create";
my $ua = LWP::UserAgent->new;
open (TXT, "<themes.txt") || die "Error opening themes.txt file: $!\n";
while (<TXT>) {
my $name = $_;
chomp($name);
my %params = (
"secret" => "$API_KEY",
"name" => "$name"
);
my $response = $ua->post($API_URL, \%params);
if ($response->is_success) {
print $response->decoded_content;
}
else {
die $response->status_line;
}
}
close(TXT);
After each of the themes is created, using either the Linux commands or the Perl code, the API will respond with XML containing the ID# of the created theme:
<id>123</id>
If you are using a programming language to work with the API, you could capture that ID# and store in another database or file so that you could later query the themes by their ID# if for example you wanted to synchronize the themes with another system.
What happens if something goes wrong when creating the themes though? Good question! The API will return a 500 status response (internal server error) with an error message like the following:
<error>
The <i>Name</i> field must contain a unique value.
</error>
So, you can see that you tried to create a theme with the same name as one that already exists, which is of course not allowed.
Click on any of the links below for instructions on how to use the available API modules. In the instructions you will find the URL(s) for each of the modules. You'll also find information about required and optional parameters, data validation rules, and example XML responses.