NOTICE: You're viewing documentation for an old version of our API. Check out the latest version here.
curl php node
Topics
Publishers
Header Bidding
Advertisers
Advertisements
Creatives
Placements
Targets
Statistics
VAST
Other

NOTICE: You're viewing documentation for an old version of our API. Check out the latest version here.

API Reference

API Endpoint

https://api.adbutler.com

PHP Client

https://github.com/adbutler/adbutler-php

Node.js Client

https://github.com/adbutler/adbutler-node

AdButler is designed to provide either the Publisher, Advertiser, or an Ad Network the ability to schedule and rotate ads with relevant targeting. AdButler is a powerful tool that ensures your ads are consistent, specific, and fast. It's easy to get started using the AdButler API because it is based on predictable, resource-oriented URLs. All API responses, including errors, return standard JSON. All errors are semantically mapped to HTTP response codes.

You are encouraged to explore the API during the development phase using the test mode API keys. Requests made with test mode credentials never use our ad serving infrastructure and, therefore, incur no cost. Once your product is ready for launch, just swap the test mode API key with the live mode API key. You cannot switch between key modes, just use the appropriate key.

Currently we offer clients in PHP and Node with plans for more in the future. We recommend that you use the client corresponding to your backend application code because they take away the pain of handling raw URIs and returns JSON responses nicely wrapped in language-specific objects.


Authentication

Include your secret API key in the Authorization header when making any request.

# With shell, you can just pass the correct header with each request
curl {API_ENDPOINT}
  -H "Authorization: Basic {API_KEY}"

Make sure to replace {API_ENDPOINT} with an actual API endpoint and {API_KEY} with your secret API key.

Set the secret API key during initialization. The PHP client library will then automatically send this key in each request.

\AdButler\API::init( array("api_key" => "{API_KEY}") );

Make sure to replace {API_KEY} with your secret API key.

Set the secret API key during instantiation The Node.js client library will then automatically send this key in each request.

var AdButler = require("adbutler");

var adbutler = new AdButler({
    apiKey: "{API_KEY}"
});

Make sure to replace {API_KEY} with your secret API key.

AdButler uses secret API keys to allow access to the API. You can register a new AdButler API key by visiting the AdButler API Settings page (Settings → API Settings). The API Settings page also lets you manage your existing API keys. Never share your secret API keys on public websites and in the client-side code.

You must include secret API key in all your API requests. API requests without the secret API key will fail. Language bindings take care of that for you once you initialize them with your secret API key. This is another incentive to use the appropriate language bindings whenever possible.

Always send requests over HTTPS. Language bindings does that for you automatically. Requests over HTTP will fail and you run the risk of exposing your secret API key. If you believe that your secret API key has been compromised, then go to AdButler API Settings page and delete the compromised API key and create a new one.


Errors

AdButler API uses conventional HTTP response codes to indicate the success or failure of a request, listed and described in the table below.

Code Meaning

200

OK — Everything worked as expected

400

Bad Request — The request was unacceptable, often due to missing a required parameter

401

Unauthorized — Invalid API key

402

Request Failed — parameters were valid but the request failed.

404

Not Found — The requested resource was not found

410

Gone — The resource requested has been removed from our servers

429

Too Many Requests — You're sending too many requests. Slow down!

500

Internal Server Error — We had a problem with our server. Try again after a few minutes.

501

Not Implemented — The requested method is not supported by our servers and will not be handled.

503

Service Unavailable — We're temporarily offline for maintanance. Please try again later.


Expanding Resources

Some resources reference other resources using their identifier (ID). For example, a placement resource references a particular zone and advertisement. Sometimes you need the details of the referenced resource, irrespective of the response size. Maybe you are primarily concerned with avoiding multiple network requests to minimize the latency caused by network round trips. In such cases, the ability to expand referenced resources might come in handy.

Example Request

curl "https://api.adbutler.com/v1/placements/14389?expand=all" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array('api_key' => '{API_KEY}') );

$placement = \AdButler\Placement::retrieve(14389, array(
  'expand' => 'all'
))

echo $placement;
var AdButler = require('adbutler')

var adbutler = new AdButler({
    apiKey: "{API_KEY}"
})

// using callbacks
adbutler.placements.read(14389, {
  expand: 'all'
}, function(error, response) {
  if (error) {
    console.log(error);
  } else {
    console.log(response);
  }
});

// using promises
adbutler.placements.read(14389).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

AdButler\Placement JSON: {
  "object": "placement",
  "self": "/v1/placements/14389",
  "id": 14389,
  "advertisement": AdButler\RichMediaBanner JSON: {
    "object": "rich_media_banner",
    "self": "/v1/banners/rich-media/518884770",
    "id": 518884770,
    "creative": 48155,
    ...
  },
  "schedule": AdButler\Schedule JSON: {
    "object": "schedule",
    "self": "/v1/schedules/18929",
    "id": 18929,
    ...
  },
  "zone": AdButler\BannerZone JSON: {
    "object": "banner_zone",
    "self": "/v1/zones/banner/87207",
    "id": 87207,
    "publisher": 1934,
    ...
  },
  ...
}
{
  "object": "placement",
  "self": "/v1/placements/14389",
  "id": 14389,
  "advertisement": {
    "object": "rich_media_banner",
    "self": "/v1/banners/rich-media/518884770",
    "id": 518884770,
    "creative": 48155,
    ...
  },
  "schedule": {
    "object": "schedule",
    "self": "/v1/schedules/18929",
    "id": 18929,
    ...
  },
  "zone": {
    "object": "banner_zone",
    "self": "/v1/zones/banner/87207",
    "id": 87207,
    "publisher": 1934,
    ...
  },
  ...
}

The irrelevant fields have been "ellipsed".

AdButler API lets you expand the referenced resources in place, using the expand query parameter with the value all.

Example Request

curl "https://api.adbutler.com/v1/placements/14389?expand=all&depth=3" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array('api_key' => '{API_KEY}') );

$advertiser = Advertiser::retrieveAll(array(
  'expand' => 'all',
  'depth' => 3
));

echo $advertiser;
var AdButler = require('adbutler')

var adbutler = new AdButler({
    apiKey: "{API_KEY}"
})

// using callbacks; our client library also supports promises.
adbutler.advertiser.list({
  expand: 'all',
  depth: 3
}, function(response) {
  console.log(response);
});

Example Response

AdButler\Placement JSON: {
  "object": "placement",
  "self": "/v1/placements/14389",
  "id": 14389,
  "advertisement": AdButler\RichMediaBanner JSON: {
    "object": "rich_media_banner",
    "self": "/v1/banners/rich-media/518884770",
    "id": 518884770,
    "creative": AdButler\RichMediaCreative JSON: {
      "object": "rich_media_creative",
      "self": "/v1/creatives/rich-media/48155",
      "id": 48155,
      "group": AdButler\MediaGroup JSON: {
        "object": "media_group",
        "self": "/v1/media-groups/466",
        "id": 466,
        ...
      },
      ...
    },
    ...
  },
  "zone": AdButler\BannerZone JSON: {
    "object": "banner_zone",
    "self": "/v1/zones/banner/87207",
    "id": 87207,
    "publisher": AdButler\Publisher JSON: {
      "object": "publisher",
      "self": "/v1/publishers/1934",
      "id": 1934,
      ...
    },
    ...
  },
  "schedule": AdButler\Schedule JSON: {
    "object": "schedule",
    "self": "/v1/schedules/18929",
    "id": 18929,
    ...
  },
  ...
}
{
  "object": "placement",
  "self": "/v1/placements/14389",
  "id": 14389,
  "advertisement": {
    "object": "rich_media_banner",
    "self": "/v1/banners/rich-media/518884770",
    "id": 518884770,
    "creative": {
      "object": "rich_media_creative",
      "self": "/v1/creatives/rich-media/48155",
      "id": 48155,
      "group": {
        "object": "media_group",
        "self": "/v1/media-groups/466",
        "id": 466,
        ...
      },
      ...
    },
    ...
  },
  "zone": {
    "object": "banner_zone",
    "self": "/v1/zones/banner/87207",
    "id": 87207,
    "publisher": {
      "object": "publisher",
      "self": "/v1/publishers/1934",
      "id": 1934,
      ...
    },
    ...
  },
  "schedule": {
    "object": "schedule",
    "self": "/v1/schedules/18929",
    "id": 18929,
    ...
  },
  ...
}

The irrelevant fields have been "ellipsed".

You can further expand the resources within the already expanded resources by specifying depth alongside expand. Depth controls the extent to which the objects should be expanded within a resource. The maximum value of depth is 5 and defaults to 1 if unspecified.

Example Request

curl "https://api.adbutler.com/v1/placements/14389?expand=advertisement,zone&depth=3" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array('api_key' => '{API_KEY}') );

$advertiser = Advertiser::retrieveAll(array(
  'expand' => array(advertisement, zone),
  'depth' => 3
));

echo $advertiser;
var AdButler = require('adbutler')

var adbutler = new AdButler({
    apiKey: "{API_KEY}"
})

// using callbacks; our client library also supports promises.
adbutler.advertiser.list({
  expand: [advertisement, zone],
  depth: 3
}, function(response) {
  console.log(response);
});

Example Response

AdButler\Placement JSON: {
  "object": "placement",
  "self": "/v1/placements/14389",
  "id": 14389,
  "advertisement": AdButler\RichMediaBanner JSON: {
    "object": "rich_media_banner",
    "self": "/v1/banners/rich-media/518884770",
    "id": 518884770,
    "creative": AdButler\RichMediaCreative JSON: {
      "object": "rich_media_creative",
      "self": "/v1/creatives/rich-media/48155",
      "id": 48155,
      "group": AdButler\MediaGroup JSON: {
        "object": "media_group",
        "self": "/v1/media-groups/466",
        "id": 466,
        ...
      },
      ...
    },
    ...
  },
  "zone": AdButler\BannerZone JSON: {
    "object": "banner_zone",
    "self": "/v1/zones/banner/87207",
    "id": 87207,
    "publisher": AdButler\Publisher JSON: {
      "object": "publisher",
      "self": "/v1/publishers/1934",
      "id": 1934,
      ...
    },
    ...
  },
  "schedule": 18929, 
  ...
}
{
  "object": "placement",
  "self": "/v1/placements/14389",
  "id": 14389,
  "advertisement": {
    "object": "rich_media_banner",
    "self": "/v1/banners/rich-media/518884770",
    "id": 518884770,
    "creative": {
      "object": "rich_media_creative",
      "self": "/v1/creatives/rich-media/48155",
      "id": 48155,
      "group": {
        "object": "media_group",
        "self": "/v1/media-groups/466",
        "id": 466,
        ...
      },
      ...
    },
    ...
  },
  "zone": {
    "object": "banner_zone",
    "self": "/v1/zones/banner/87207",
    "id": 87207,
    "publisher": {
      "object": "publisher",
      "self": "/v1/publishers/1934",
      "id": 1934,
      ...
    },
    ...
  },
  "schedule": 18929,
  ...
}

The irrelevant fields have been "ellipsed".

You can also restrict expansion to certain fields by using a comma separated list of fields as the value to the expand query parameter.


Filtering Response Data

Example Query Parameters Usage

curl "https://api.adbutler.com/v1/advertisers?fields=name,email" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array('api_key' => '{API_KEY}') );

$advertiser = Advertiser::retrieveAll(array(
  "fields" => array("name", "email")
));

echo $advertiser->toString();
var AdButler = require('adbutler')

var adbutler = new AdButler({
    apiKey: "{API_KEY}"
})

// using callbacks; our client library also supports promises.
adbutler.advertiser.list({
  fields: ["name", "email"]
}, function(response) {
  console.log(response);
});

Example Response

AdButler\Collection JSON: {
  "object": "list",
  "has_more": true,
  "limit": 10,
  "offset": 0,
  "url": "/v1/advertisers",
  "data": [
    AdButler\Advertiser JSON: {
      "object": "advertiser",
      "self": "/v1/advertisers/1760",
      "id": 1760,
      "email": "nobody@adbutler.com",
      "name": "Baig"
    },
    AdButler\Advertiser JSON: {
      "object": "advertiser",
      "self": "/v1/advertisers/1849",
      "id": 1849,
      "email": "colors@gmail.com",
      "name": "BLABLABLABLA Flash Creative Name"
    }
  ]
}
{
  "object": "list",
  "has_more": true,
  "limit": 10,
  "offset": 0,
  "url": "/v1/advertisers",
  "data": [
    {
      "object": "advertiser",
      "self": "/v1/advertisers/1760",
      "id": 1760,
      "email": "nobody@adbutler.com",
      "name": "Baig"
    },
    {
      "object": "advertiser",
      "self": "/v1/advertisers/1849",
      "id": 1849,
      "email": "colors@gmail.com",
      "name": "BLABLABLABLA Flash Creative Name"
    }
  ]
}

Sometimes you will need to reduce the amount of data returned from API endpoints. Either you want to keep the responses as lightweight as possible or you want to reduce the amount of the post-processing code on your end.

This is where the "fields" query parameter comes in. You may specify a comma separated list of resource field names to filter which fields appear in API responses. This optional parameters is available to all endpoints that create, retrieve, update or list resources.


Versioning

API version is part of the URL. Backwards-incompatible changes to the API may warrant version upgrades. These API upgrades will be made available under a new URL e.g. /v1/advertisers, /v2/advertisers. You will find information about how to upgrade your system in our API upgrade guide which will be published with each version upgrade.


Standard Banner Dimensions

When it comes to deciding about the size of your image, flash, custom HTML, or rich media banner, you will most likely be using dimensions commonly used for banner advertisements across the Web. For your immediate reference and convenience, standard web banner dimensions are tabulated below. All measurements are given in pixels.

Popular Name Width (px) Height (px)

3:1 Rectangle

300

100

Billboard

970

250

Button 1

120

90

Button 2

120

60

Full Banner

468

60

Half Banner

234

60

Half Page Ad

300

600

Large Rectangle

336

280

Leaderboard

728

90

Medium Rectangle

300

250

Micro Bar

88

31

Pop-Under

720

300

Rectangle

180

150

Super Leaderboard

970

90

Square Pop-Up

250

250

Square Button

125

125

Skyscraper

120

600

Vertical Rectangle

240

400

Vertical Banner

120

240

Wide Skyscraper

160

600


Native/JSON API

The AdButler JSON ad endpoint allows you to easily integrate ad serving into existing apps or websites. You can use it to build native ad serving solutions, as well as a variety of custom implementations that don't follow traditional display advertising strategies.

You can acquire the JSON serving ad tags through AdButler UI or API. Click hereexternal link icon to learn more about acquiring the JSON ad tags using the AdButler UI. See the retrieve banner, email, or text zone tags to learn more about acquiring those tags using the AdButler API.

If you are looking for easy integration of AdButler ads into iOS and Android apps, check out our Androidexternal link icon and iOS SDKexternal link icon which are built on top of the JSON ad endpoint.


Publishers

Introduction

A Publisher is typically a person or a company who owns a website, newsletter or even another ad server. Each publisher will have one or more zones which represent locations on their websites/newsletters where advertisements will be displayed.

The publisher response object has the following fields.

Example Response

{
  "object": "publisher",
  "self": "/v1/publishers/4771",
  "id": 4771,
  "can_admin_account": true,
  "can_approve_ads": false,
  "can_change_password": true,
  "default_payout_percent": 0,
  "email": "demo.publisher@adbutler.com",
  "name": "Demo Publisher"
}
AdButler\Publisher JSON: {
  "object": "publisher",
  "self": "/v1/publishers/4771",
  "id": 4771,
  "can_admin_account": true,
  "can_approve_ads": false,
  "can_change_password": true,
  "default_payout_percent": 0,
  "email": "demo.publisher@adbutler.com",
  "name": "Demo Publisher"
}
Field Type Description

object

string

A string denoting the object type which is always publisher for the current resource.

self

string

The relative URL of the current resource which is always of the form /v1/publishers/{PUBLISHER_ID}.

id

integer

The current resource identifier (ID).

can_admin_account

boolean

Whether to allow administrating user accounts.

can_approve_ads

boolean

Whether to allow approving advertisements.

can_change_password

boolean

Whether to allow changing accounts password.'

default_payout_percent

integer

The default payout percent for this account.

email

string

A valid email of the publisher.

name

string

Name of the publisher.

Create a publisher

Definition

POST https://api.adbutler.com/v1/publishers
\AdButler\Publisher::create()
adbutler.publishers.create()

Example Request

curl "https://api.adbutler.com/v1/publishers" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{  
        "can_admin_account": true,
        "can_approve_ads": false,
        "can_change_password": true,
        "default_payout_percent": 0,
        "email": "demo.publisher@adbutler.com",
        "name": "Demo Publisher"
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$publisher = \AdButler\Publisher::create(array(
  "can_admin_account" => true,
  "can_approve_ads" => false,
  "can_change_password" => true,
  "default_payout_percent" => 0,
  "email" => "demo.publisher@adbutler.com",
  "name" => "Demo Publisher"
));

echo $publisher;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var postData = {
  "can_admin_account": true,
  "can_approve_ads": false,
  "can_change_password": true,
  "default_payout_percent": 0,
  "email": "demo.publisher@adbutler.com",
  "name": "Demo Publisher"
};

// using callbacks
adbutler.publishers.create(postData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.publishers.create(postData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "publisher",
  "self": "/v1/publishers/4771",
  "id": 4771,
  "can_admin_account": true,
  "can_approve_ads": false,
  "can_change_password": true,
  "default_payout_percent": 0,
  "email": "demo.publisher@adbutler.com",
  "name": "Demo Publisher"
}
AdButler\Publisher JSON: {
  "object": "publisher",
  "self": "/v1/publishers/4771",
  "id": 4771,
  "can_admin_account": true,
  "can_approve_ads": false,
  "can_change_password": true,
  "default_payout_percent": 0,
  "email": "demo.publisher@adbutler.com",
  "name": "Demo Publisher"
}

When you create a new publisher account, a password is auto-generated for the account.

Field Type Description

name*

string

The name of the publisher which can be the name of the organization that will be implementing the advertisements or the website where the ads will be displayed.

email

string

The email address of the publisher which defaults to nobody@adbutler.com.

password

string

The password of the optional user account tied to this publisher. This field must be 8 or more characters. If left blank on publisher creation, a random password will be generated.

can_admin_account

boolean

Whether to grant administrator privileges to the publisher. If true, each publisher will have the ability to add and delete their own banners and zones without affecting other publishers.

can_approve_ads

boolean

Whether to allow publisher to approve or deny advertisements assigned to their zones. If true, each publisher will have the option to block certain ads/campaigns that you have added to their zones.

can_change_password

boolean

Whether to allow publisher to change their password.

default_payout_percent

integer/float

The default value for the percentage of revenue that will be paid out to the publisher. The default payout ratio for a publisher sets the default value for all new ad assignments in zones owned by the publisher. Payout ratio can also be edited and modified per advertisement or campaign assignment.

* = required field

Returns

Returns a publisher object if the request succeeded, or an error if something went terribly wrong.

Retrieve a publisher

Definition

GET https://api.adbutler.com/v1/publishers/{PUBLISHER-ID}
\AdButler\Publisher::retrieve()
adbutler.publishers.retrieve()

Example Request

curl "https://api.adbutler.com/v1/publishers/4771" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$publisher = \AdButler\Publisher::retrieve( 4771 );

echo $publisher;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.publishers.read(4771, function(err, response) {
  console.log(response);
});

// using promises
adbutler.publishers.read(4771).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "publisher",
  "self": "/v1/publishers/4771",
  "id": 4771,
  "can_admin_account": true,
  "can_approve_ads": false,
  "can_change_password": true,
  "default_payout_percent": 0,
  "email": "demo.publisher@adbutler.com",
  "name": "Demo Publisher"
}
AdButler\Publisher JSON: {
  "object": "publisher",
  "self": "/v1/publishers/4771",
  "id": 4771,
  "can_admin_account": true,
  "can_approve_ads": false,
  "can_change_password": true,
  "default_payout_percent": 0,
  "email": "demo.publisher@adbutler.com",
  "name": "Demo Publisher"
}

You can retrieve the information about an existing publisher by giving the publisher ID that was returned in the publisher object upon creation.

Returns

Returns a publisher object if the request succeeded, or an error if something went terribly wrong.

Update a publisher

Definition

PUT https://api.adbutler.com/v1/publishers/{PUBLISHER-ID}
\AdButler\Publisher->save()
adbutler.publishers.update()

Example Request

curl "https://api.adbutler.com/v1/publishers/4771" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{  
        "can_admin_account": true,
        "can_approve_ads": false,
        "can_change_password": true,
        "default_payout_percent": 0,
        "email": "demo.publisher@adbutler.com",
        "name": "Demo Publisher"
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$publisher = \AdButler\Publisher::retrieve( 4771 );

$publisher->can_admin_account = true;
$publisher->can_approve_ads = false;
$publisher->can_change_password = true;
$publisher->default_payout_percent = 0;
$publisher->email = "demo.publisher@adbutler.com";
$publisher->name = "Demo Publisher";

$publisher->save();

echo $publisher;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var updateData = {
  "can_admin_account": true,
  "can_approve_ads": false,
  "can_change_password": true,
  "default_payout_percent": 0,
  "email": "demo.publisher@adbutler.com",
  "name": "Demo Publisher"
};

// using callbacks
adbutler.publishers.update(4771, updateData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.publishers.update(4771, updateData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "publisher",
  "self": "/v1/publishers/4771",
  "id": 4771,
  "can_admin_account": true,
  "can_approve_ads": false,
  "can_change_password": true,
  "default_payout_percent": 0,
  "email": "demo.publisher@adbutler.com",
  "name": "Demo Publisher"
}
AdButler\Publisher JSON: {
  "object": "publisher",
  "self": "/v1/publishers/4771",
  "id": 4771,
  "can_admin_account": true,
  "can_approve_ads": false,
  "can_change_password": true,
  "default_payout_percent": 0,
  "email": "demo.publisher@adbutler.com",
  "name": "Demo Publisher"
}

You can update a specific publisher account by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the publisher creation request.

Field Type Description

name

string

The name of the publisher which can be the name of the organization that will be implementing the advertisements or the website where the ads will be displayed.

email

string

The email address of the publisher which defaults to nobody@adbutler.com.

password

string

The password of the optional user account tied to this publisher. This field must be 8 or more characters. If left blank on publisher creation, a random password will be generated.

can_admin_account

boolean

Whether to grant administrator privileges to the publisher. If true, each publisher will have the ability to add and delete their own banners and zones without affecting other publishers.

can_approve_ads

boolean

Whether to allow publisher to approve or deny advertisements assigned to their zones. If true, each publisher will have the option to block certain ads/campaigns that you have added to their zones.

can_change_password

boolean

Whether to allow publisher to change their password.

default_payout_percent

integer/float

The default value for the percentage of revenue that will be paid out to the publisher. The default payout ratio for a publisher sets the default value for all new ad assignments in zones owned by the publisher. Payout ratio can also be edited and modified per advertisement or campaign assignment.

Returns

Returns a publisher object if the request succeeded, or an error if something went terribly wrong.

Delete a publisher

Definition

DELETE https://api.adbutler.com/v1/publishers/{PUBLISHER-ID}
\AdButler\Publisher->delete()
adbutler.publishers.delete()

Example Request

curl "https://api.adbutler.com/v1/publishers/4771" \
  -H "Authorization: Basic {API_KEY}" \
  -X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$publisher = \AdButler\Publisher::retrieve( 4771 );
$publisher->delete();

echo $publisher;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.publishers.delete(4771, function(err, response) {
  console.log(response);
});

// using promises
adbutler.publishers.delete(4771).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "id": 4771,
  "delete": true
}
AdButler\Publisher JSON: {
  "id": 4771,
  "delete": true
}

Permanently deletes a publisher. if successful, this operation cannot be undone so be very sure when deleting one.

Returns

Returns a publisher ID if the request succeeded, or an error if something went terribly wrong.

List all publishers

Definition

GET https://api.adbutler.com/v1/publishers
\AdButler\Publisher::retrieveAll()
adbutler.publishers.list()

Example Request

curl "https://api.adbutler.com/v1/publishers?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$publisher = \AdButler\Publisher::retrieveAll(array(
  "limit" => 2
));

echo $publisher;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.publishers.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.publishers.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/publishers",
  "data": [
    {
      "object": "publisher",
      "self": "/v1/publishers/4722",
      "id": 4722,
      "can_admin_account": false,
      "can_approve_ads": true,
      "can_change_password": true,
      "default_payout_percent": null,
      "email": "nobody@adbutler.com",
      "name": "Default Publisher"
    },
    {
      "object": "publisher",
      "self": "/v1/publishers/4723",
      "id": 4723,
      "can_admin_account": true,
      "can_approve_ads": false,
      "can_change_password": true,
      "default_payout_percent": 0,
      "email": "demo.publisher@adbutler.com",
      "name": "Demo Publisher"
    }
  ]
}
AdButler\Publisher JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/publishers",
  "data": [
    {
      "object": "publisher",
      "self": "/v1/publishers/4722",
      "id": 4722,
      "can_admin_account": false,
      "can_approve_ads": true,
      "can_change_password": true,
      "default_payout_percent": null,
      "email": "nobody@adbutler.com",
      "name": "Default Publisher"
    },
    {
      "object": "publisher",
      "self": "/v1/publishers/4723",
      "id": 4723,
      "can_admin_account": true,
      "can_approve_ads": false,
      "can_change_password": true,
      "default_payout_percent": 0,
      "email": "demo.publisher@adbutler.com",
      "name": "Demo Publisher"
    }
  ]
}

Returns a list of all the publisher accounts. Most recent publisher accounts appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is a publisher object, and if no objects were found the list will be empty.

Archive a publisher

Definition

GET https://api.adbutler.com/v1/publishers/{PUBLISHER-ID}/archive
\AdButler\PublisherArchive::retrieve()
adbutler.publishers.archive.retrieve()

Example Request

curl "https://api.adbutler.com/v1/publishers/ID/archive/4772" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$publisherArchive = \AdButler\PublisherArchive::retrieve( 4772 );

echo $publisherArchive;
var AdButler = require("adbutler");

var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.publishers.archive.read(4772, function(err, response) {
  console.log(response);
});

// using promises
adbutler.publishers.archive.read(4772).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Archives the resource and all direct descendents of this resource. Archived resources will be treated the same as deleted resources but can be restored through unarchiving.

Returns

Example Response

{
  "object": "archive",
  "url": "/v1/publishers/4772/archive",
  "data": {
    "archived_resources": [
      {
        "object": "publisher",
        "id": 4772
      },
      {
        "object": "zone",
        "id": 104143
      }
    ]
  }
}
AdButler\PublisherArchive JSON: {
  "object": "archive",
  "url": "/v1/publishers/4772/archive",
  "data": {
    "archived_resources": [
      {
        "object": "publisher",
        "id": 4772
      },
      {
        "object": "zone",
        "id": 104143
      }
    ]
  }
}
Field Type Description

object

string

A string denoting the object type which is always archive for the current resource.

url

string

The relative URL of the current resource which is always of the form /v1/publishers/{PUBLISHER-ID}/archive.

data

array

The data object containing a list of the resources archived by this action.

 

Returns an archive object if the request succeeded, or an error if something went terribly wrong.

Unarchive a publisher

Definition

GET https://api.adbutler.com/v1/publishers/{PUBLISHER-ID}/unarchive
\AdButler\PublisherUnarchive::retrieve()
adbutler.publishers.unarchive.retrieve()

Example Request

curl "https://api.adbutler.com/v1/publishers/ID/unarchive/4772" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$publisherUnarchive = \AdButler\PublisherUnarchive::retrieve( 4772 );

echo $publisherUnarchive;
var AdButler = require("adbutler");

var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.publishers.unarchive.read(4772, function(err, response) {
  console.log(response);
});

// using promises
adbutler.publishers.unarchive.read(4772).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Unarchives the resource and all resources that were previously archived with the resource.

Query Parameters

Parameter Description

include_campaign_assignments

Whether or not to include related campaign assignments when unarchiving the resource. If an unarchived assignment references an invalid resource, the campaign assignment will not be unarchived and information about the invalid resource and references will be returned. The publisher resource will still be unarchived.

include_placements

Whether or not to include related placements when unarchiving the resource. If an unarchived placement references an invalid resource, the placement will not be unarchived and information about the invalid resource and references will be returned. The publisher resource will still be unarchived.

Returns

Example Response

{
  "object": "unarchive",
  "url": "/v1/publishers/4772/unarchive",
  "data": {
    "unarchived_resources": [
      {
        "object": "publisher",
        "id": 4772
      },
      {
        "object": "zone",
        "id": 104143
      }
    ]
  }
}
AdButler\PublisherUnarchive JSON: {
  "object": "unarchive",
  "url": "/v1/publishers/4772/unarchive",
  "data": {
    "unarchived_resources": [
      {
        "object": "publisher",
        "id": 4772
      },
      {
        "object": "zone",
        "id": 104143
      }
    ]
  }
}
Field Type Description

object

string

A string denoting the object type which is always unarchive for the current resource.

url

string

The relative URL of the current resource which is always of the form /v1/publishers/{PUBLISHER-ID}/unarchive.

data

array

The data object containing a list of the resources unarchived by this action. When including assignments, a list of resources that reference deleted or invalid resources will also be returned.

 

Returns an unarchive object if the request succeeded, or an error if something went terribly wrong.


Zones

List all zones

Definition

GET https://api.adbutler.com/v1/zones
\AdButler\Zone::retrieveAll()
adbutler.zones.list()

Example Request

curl "https://api.adbutler.com/v1/zones?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$zone = \AdButler\Zone::retrieveAll(array(
  "limit" => 2
));

echo $zone;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.zones.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.zones.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/zones/banner",
  "data": [
    {
      "object": "banner_zone",
      "self": "/v1/zones/banner/104022",
      "id": 104022,
      "dimensions": "fixed",
      "height": 250,
      "name": "Default Zone",
      "popup_frequency": 1,
      "publisher": 4722,
      "refresh_frequency": 0,
      "refresh_limit": 0,
      "responsive": "fixed",
      "unique_delivery": false,
      "width": 300,
      "flexible_type": 0,
      "deleted": false
    },
    {
      "object": "text_zone",
      "self": "/v1/zones/text/104023",
      "id": 104023,
      "name": "Default Text Zone",
      "publisher": 4722
    }
  ]
}
AdButler\Zone JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/zones/banner",
  "data": [
    {
      "object": "banner_zone",
      "self": "/v1/zones/banner/104022",
      "id": 104022,
      "dimensions": "fixed",
      "height": 250,
      "name": "Default Zone",
      "popup_frequency": 1,
      "publisher": 4722,
      "refresh_frequency": 0,
      "refresh_limit": 0,
      "responsive": "fixed",
      "unique_delivery": false,
      "width": 300,
      "flexible_type": 0,
      "deleted": false
    },
    {
      "object": "text_zone",
      "self": "/v1/zones/text/104023",
      "id": 104023,
      "name": "Default Text Zone",
      "publisher": 4722
    }
  ]
}

You can retrieve a list of all the zones regardless of their type. You can optionally restrict the fields that you are interested in retrieving by using the fields query parameter.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is an object, and if no objects were found the list will be empty.


Email Zones

Introduction

Email zones are a restricted form of zones which are only used in emails. Due to the specific requirements for serving ads in email, it's necessary to use a basic HTML zone tag setup to effectively deliver ads.

You can create zones of any dimensions you require, but it is usually a good idea to stick with the commonly used sizes according to the IAB.

The email_zone response object has the following fields.

Example Response

{
  "object": "email_zone",
  "self": "/v1/zones/email/104145",
  "id": 104145,
  "height": 90,
  "name": "120-90-sidebar",
  "publisher": 4771,
  "width": 120
}
AdButler\EmailZone JSON: {
  "object": "email_zone",
  "self": "/v1/zones/email/104145",
  "id": 104145,
  "height": 90,
  "name": "120-90-sidebar",
  "publisher": 4771,
  "width": 120
}
Field Type Description

object

string

A string denoting the object type which is always email_zone for the current resource.

self

string

The relative URL of the current resource which is always of the form /v1/zones/email/{EMAIL_ZONE_ID}.

id

integer

The current resource identifier (ID).

name

string

The name of the email zone.

width

integer

The width of the email zone.

height

integer

The height of the email zone.

publisher

integer

The publisher identifier (ID) representing the publisher who owns the email zone.

Create an email zone

Definition

POST https://api.adbutler.com/v1/zones/email
\AdButler\EmailZone::create()
adbutler.zones.emails.create()

Example Request

curl "https://api.adbutler.com/v1/zones/email" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{  
        "height": 90,
        "name": "120-90-sidebar",
        "publisher": 4771,
        "width": 120
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$emailZone = \AdButler\EmailZone::create(array(
  "height" => 90,
  "name" => "120-90-sidebar",
  "publisher" => 4771,
  "width" => 120
));

echo $emailZone;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var postData = {
  "height": 90,
  "name": "120-90-sidebar",
  "publisher": 4771,
  "width": 120
};

// using callbacks
adbutler.zones.emails.create(postData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.zones.emails.create(postData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "email_zone",
  "self": "/v1/zones/email/104145",
  "id": 104145,
  "height": 90,
  "name": "120-90-sidebar",
  "publisher": 4771,
  "width": 120
}
AdButler\EmailZone JSON: {
  "object": "email_zone",
  "self": "/v1/zones/email/104145",
  "id": 104145,
  "height": 90,
  "name": "120-90-sidebar",
  "publisher": 4771,
  "width": 120
}

Creates a new email zone.

Field Type Description

name*

string

A descriptive name of the email zone. We recommend using a naming convention that is consistent, relevant, and clear.

width*

integer

The width of the email zone which must correspond to the banner width (see common banner dimensions). The width and height of the zone will restrict the banner or campaign that can be displayed within the zone.

height*

integer

The height of the email zone which must correspond to the banner height (see common banner dimensions). The height and width of the zone will restrict the banner or campaign that can be displayed within the zone.

publisher

integer

The publisher identifier (ID) the email zone belongs to. You can create zones without a publisher but you cannot use them unless you associate them with a publisher first.

* = required field

Returns

Returns an email_zone object if the request succeeded, or an error if something went terribly wrong.

Retrieve an email zone

Definition

GET https://api.adbutler.com/v1/zones/email/{EMAIL-ZONE-ID}
\AdButler\EmailZone::retrieve()
adbutler.zones.emails.retrieve()

Example Request

curl "https://api.adbutler.com/v1/zones/email/104145" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$emailZone = \AdButler\EmailZone::retrieve( 104145 );

echo $emailZone;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.zones.emails.read(104145, function(err, response) {
  console.log(response);
});

// using promises
adbutler.zones.emails.read(104145).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "email_zone",
  "self": "/v1/zones/email/104145",
  "id": 104145,
  "height": 90,
  "name": "120-90-sidebar",
  "publisher": 4771,
  "width": 120
}
AdButler\EmailZone JSON: {
  "object": "email_zone",
  "self": "/v1/zones/email/104145",
  "id": 104145,
  "height": 90,
  "name": "120-90-sidebar",
  "publisher": 4771,
  "width": 120
}

You can retrieve the information about an existing email zone by giving the email zone ID that was returned in the email zone object upon creation. You will see at the most 10 email zones in the response. You can change this default limit by appending ?limit=25 if you want this request to return 25 zones_email.

Returns

Returns an email_zone object if the request succeeded, or an error if something went terribly wrong.

Update an email zone

Definition

PUT https://api.adbutler.com/v1/zones/email/{EMAIL-ZONE-ID}
\AdButler\EmailZone->save()
adbutler.zones.emails.update()

Example Request

curl "https://api.adbutler.com/v1/zones/email/104145" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{  
        "height": 90,
        "name": "120-90-sidebar",
        "publisher": 4771,
        "width": 120
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$emailZone = \AdButler\EmailZone::retrieve( 104145 );

$emailZone->height = 90;
$emailZone->name = "120-90-sidebar";
$emailZone->publisher = 4771;
$emailZone->width = 120;

$emailZone->save();

echo $emailZone;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var updateData = {
  "height": 90,
  "name": "120-90-sidebar",
  "publisher": 4771,
  "width": 120
};

// using callbacks
adbutler.zones.emails.update(104145, updateData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.zones.emails.update(104145, updateData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "email_zone",
  "self": "/v1/zones/email/104145",
  "id": 104145,
  "height": 90,
  "name": "120-90-sidebar",
  "publisher": 4771,
  "width": 120
}
AdButler\EmailZone JSON: {
  "object": "email_zone",
  "self": "/v1/zones/email/104145",
  "id": 104145,
  "height": 90,
  "name": "120-90-sidebar",
  "publisher": 4771,
  "width": 120
}

You can update a specific email zones by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the email zone creation request.

Field Type Description

name

string

A descriptive name of the email zone. We recommend using a naming convention that is consistent, relevant, and clear.

width

integer

The width of the email zone which must correspond to the banner width (see common banner dimensions). The width and height of the zone will restrict the banner or campaign that can be displayed within the zone.

height

integer

The height of the email zone which must correspond to the banner height (see common banner dimensions). The height and width of the zone will restrict the banner or campaign that can be displayed within the zone.

publisher

integer

The publisher identifier (ID) the email zone belongs to. You can create zones without a publisher but you cannot use them unless you associate them with a publisher first.

Returns

Returns an email_zone object if the request succeeded, or an error if something went terribly wrong.

Delete an email zone

Definition

DELETE https://api.adbutler.com/v1/zones/email/{EMAIL-ZONE-ID}
\AdButler\EmailZone->delete()
adbutler.zones.emails.delete()

Example Request

curl "https://api.adbutler.com/v1/zones/email/104145" \
  -H "Authorization: Basic {API_KEY}" \
  -X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$emailZone = \AdButler\EmailZone::retrieve( 104145 );
$emailZone->delete();

echo $emailZone;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.zones.emails.delete(104145, function(err, response) {
  console.log(response);
});

// using promises
adbutler.zones.emails.delete(104145).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "id": 104145,
  "delete": true
}
AdButler\EmailZone JSON: {
  "id": 104145,
  "delete": true
}

Permanently deletes an email zone. if successful, this operation cannot be undone so be very sure when deleting one.

Returns

Returns an email zone ID if the request succeeded, or an error if something went terribly wrong.

List all email zones

Definition

GET https://api.adbutler.com/v1/zones/email
\AdButler\EmailZone::retrieveAll()
adbutler.zones.emails.list()

Example Request

curl "https://api.adbutler.com/v1/zones/email?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$emailZone = \AdButler\EmailZone::retrieveAll(array(
  "limit" => 2
));

echo $emailZone;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.zones.emails.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.zones.emails.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/zones/email",
  "data": [
    {
      "object": "email_zone",
      "self": "/v1/zones/email/104025",
      "id": 104025,
      "height": 90,
      "name": "120-90-sidebar",
      "publisher": 4723,
      "width": 120
    },
    {
      "object": "email_zone",
      "self": "/v1/zones/email/104028",
      "id": 104028,
      "height": 90,
      "name": "120-90-sidebar",
      "publisher": 4724,
      "width": 120
    }
  ]
}
AdButler\EmailZone JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/zones/email",
  "data": [
    {
      "object": "email_zone",
      "self": "/v1/zones/email/104025",
      "id": 104025,
      "height": 90,
      "name": "120-90-sidebar",
      "publisher": 4723,
      "width": 120
    },
    {
      "object": "email_zone",
      "self": "/v1/zones/email/104028",
      "id": 104028,
      "height": 90,
      "name": "120-90-sidebar",
      "publisher": 4724,
      "width": 120
    }
  ]
}

Returns a list of all the email zones. Most recent email zones appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is a email_zone object, and if no objects were found the list will be empty.

Retrieve email zone tags

Definition

GET https://api.adbutler.com/v1/zones/email/{EMAIL-ZONE-ID}/tags
\AdButler\ZoneTag::retrieve()
adbutler.zones.tags.retrieve()

Example Request

curl "https://api.adbutler.com/v1/zones/email/104145/tags" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$zoneTag = \AdButler\ZoneTag::retrieve( 104145 );

echo $zoneTag;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.zones.tags.read(104145, function(err, response) {
  console.log(response);
});

// using promises
adbutler.zones.tags.read(104145).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

You can also retrieve the banner zone tags using the banner zone identifier (ID).

Query Parameters

Parameter Description

type

Specifies the type of the tag which can be any of the following value: async, js, iframe, image, json, or iframe‑no‑js. Async tags are recommended. You can specify multiple values by separating them with a comma e.g. type=async,js,image. Omitting the type will return all of them in the response. Consult your webmaster if unsure which tags to use.

protocol

Whether to use http or https protocol when serving the advertisements. Use https only if you are using secure pages becasue it does not support Custom Domains.

fallback

Whether to include <noscript> tag for supporting the older browsers (true). or not (false). <noscript> tag does not lend itself to easy tracking.

click

Unescaped third party click macro for use in other ad servers. The value must be RFC 3986 encoded.

extra

Extra data to pass along to the destination URLs when the user clicks on your advertisement. The value must be RFC 3986 encoded.

uid*

These zone tags require the implementation of an Email User ID macro (EUID). This macro must be provided by your newsletter service and must distribute with a unique ID for each recipient. This unique ID is required for accurate serving. Banners will not rotate properly or track clicks if it is omitted.

* = required field

Returns

Example Response

{
  "object": "zone_tag",
  "url": "/v1/zones/email/104145/tags",
  "data": {
    "email": "<a href=\"http://servedbyadbutler.com.vm.test/go2/;ID=108607;size=120x90;setID=104145;uid=;\" target=\"_blank\"><img src=\"http://servedbyadbutler.com.vm.test/adserve/;ID=108607;size=120x90;setID=104145;type=img;uid=; width=\"120\" height=\"90\"></a>"
  }
}
AdButler\ZoneTag JSON: {
  "object": "zone_tag",
  "url": "/v1/zones/email/104145/tags",
  "data": {
    "email": "<a href=\"http://servedbyadbutler.com.vm.test/go2/;ID=108607;size=120x90;setID=104145;uid=;\" target=\"_blank\"><img src=\"http://servedbyadbutler.com.vm.test/adserve/;ID=108607;size=120x90;setID=104145;type=img;uid=; width=\"120\" height=\"90\"></a>"
  }
}
Field Type Description

object

string

A string denoting the object type which is always zone_tag for the current resource.

url

string

The relative URL of the current resource which is always of the form /v1/zones/banner/{BANNER_ZONE_ID}/tags.

data

array

The data object containing the zone tags requested in the URL.

 

Returns a zone_tag object if the request succeeded, or an error if something went terribly wrong.

Retrieve email zone conversion tag

Definition

GET https://api.adbutler.com/v1/zones/email/{EMAIL-ZONE-ID}/conversion-tag
\AdButler\EmailZoneConvTag::retrieve()
adbutler.zones.conversionTag.retrieve()

Example Request

curl "https://api.adbutler.com/v1/zones/email/ID/conversion-tag/104145" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$emailZoneConvTag = \AdButler\EmailZoneConvTag::retrieve( 104145 );

echo $emailZoneConvTag;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.zones.conversionTag.read(104145, function(err, response) {
  console.log(response);
});

// using promises
adbutler.zones.conversionTag.read(104145).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Retrieves an HTML tag which can be used to track conversions for the provided zone.

Query Parameters

Parameter Description

protocol

Whether to use http or https protocol when serving the advertisements. Use https only if you are using secure pages because it does not support Custom Domains.

Returns

Example Response

{
  "object": "conv_tag",
  "url": "/v1/zones/email/104145/conversion-tag",
  "data": {
    "src": "https://servedbyadbutler.com.vm.test/convtrack.spark?MID=108607&zoneID=104145",
    "html": "<img src='https://servedbyadbutler.com.vm.test/convtrack.spark?MID=108607&zoneID=104145' width='1' height='1' border='0' />"
  }
}
AdButler\EmailZoneConvTag JSON: {
  "object": "conv_tag",
  "url": "/v1/zones/email/104145/conversion-tag",
  "data": {
    "src": "https://servedbyadbutler.com.vm.test/convtrack.spark?MID=108607&zoneID=104145",
    "html": "<img src='https://servedbyadbutler.com.vm.test/convtrack.spark?MID=108607&zoneID=104145' width='1' height='1' border='0' />"
  }
}
Field Type Description

object

string

A string denoting the object type which is always conv_tag for the current resource.

url

string

The relative URL of the current resource which is always of the form /v1/zones/email/{EMAIL_ZONE_ID}/conversion-tag.

data

array

The data object containing the conversion tag.

 

Returns a conv_tag object if the request succeeded, or an error if something went terribly wrong.


Text Zones

Introduction

Text zones are specific to textual advertisements and campaigns, and are served as text directly into the page so that the generated advertisements appear naturally in the pages.

The text_zone response object has the following fields.

Example Response

{
  "object": "text_zone",
  "self": "/v1/zones/text/104146",
  "id": 104146,
  "name": "120-90-sidebar",
  "publisher": 4771
}
AdButler\TextZone JSON: {
  "object": "text_zone",
  "self": "/v1/zones/text/104146",
  "id": 104146,
  "name": "120-90-sidebar",
  "publisher": 4771
}
Field Type Description

object

string

A string denoting the object type which is always text_zone for the current resource.

self

string

The relative URL of the current resource which is always of the form /v1/zones/text/{TEXT_ZONE_ID}.

id

integer

The current resource identifier (ID).

name

string

The name of the banner zone.

publisher

integer

The publisher identifier (ID) representing the publisher who owns the banner zone.

Create a text ad zone

Definition

POST https://api.adbutler.com/v1/zones/text
\AdButler\TextZone::create()
adbutler.zones.textAds.create()

Example Request

curl "https://api.adbutler.com/v1/zones/text" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{  
        "name": "120-90-sidebar",
        "publisher": 4771
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$textZone = \AdButler\TextZone::create(array(
  "name" => "120-90-sidebar",
  "publisher" => 4771
));

echo $textZone;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var postData = {
  "name": "120-90-sidebar",
  "publisher": 4771
};

// using callbacks
adbutler.zones.textAds.create(postData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.zones.textAds.create(postData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "text_zone",
  "self": "/v1/zones/text/104146",
  "id": 104146,
  "name": "120-90-sidebar",
  "publisher": 4771
}
AdButler\TextZone JSON: {
  "object": "text_zone",
  "self": "/v1/zones/text/104146",
  "id": 104146,
  "name": "120-90-sidebar",
  "publisher": 4771
}

Creates a new text ad zone.

Field Type Description

name*

string

A descriptive name of the banner zone. We recommend using a naming convention that is consistent, relevant, and clear.

publisher

integer

The publisher identifier (ID) the banner zone belongs to. You can create zones without a publisher but you cannot use them unless you associate them with a publisher first.

* = required field

Returns

Returns a text_zone object if the request succeeded, or an error if something went terribly wrong.

Retrieve a text ad zone

Definition

GET https://api.adbutler.com/v1/zones/text/{TEXT-ZONE-ID}
\AdButler\TextZone::retrieve()
adbutler.zones.textAds.retrieve()

Example Request

curl "https://api.adbutler.com/v1/zones/text/104146" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$textZone = \AdButler\TextZone::retrieve( 104146 );

echo $textZone;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.zones.textAds.read(104146, function(err, response) {
  console.log(response);
});

// using promises
adbutler.zones.textAds.read(104146).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "text_zone",
  "self": "/v1/zones/text/104146",
  "id": 104146,
  "name": "120-90-sidebar",
  "publisher": 4771
}
AdButler\TextZone JSON: {
  "object": "text_zone",
  "self": "/v1/zones/text/104146",
  "id": 104146,
  "name": "120-90-sidebar",
  "publisher": 4771
}

You can retrieve the information about an existing text ad zone by giving the text ad zone ID that was returned in the text ad zone object upon creation. You will see at the most 10 text ad zones in the response. You can change this default limit by appending ?limit=25 if you want this request to return 25 zones_text.

Returns

Returns a text_zone object if the request succeeded, or an error if something went terribly wrong.

Update a text ad zone

Definition

PUT https://api.adbutler.com/v1/zones/text/{TEXT-ZONE-ID}
\AdButler\TextZone->save()
adbutler.zones.textAds.update()

Example Request

curl "https://api.adbutler.com/v1/zones/text/104146" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{  
        "name": "120-90-sidebar",
        "publisher": 4771
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$textZone = \AdButler\TextZone::retrieve( 104146 );

$textZone->name = "120-90-sidebar";
$textZone->publisher = 4771;

$textZone->save();

echo $textZone;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var updateData = {
  "name": "120-90-sidebar",
  "publisher": 4771
};

// using callbacks
adbutler.zones.textAds.update(104146, updateData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.zones.textAds.update(104146, updateData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "text_zone",
  "self": "/v1/zones/text/104146",
  "id": 104146,
  "name": "120-90-sidebar",
  "publisher": 4771
}
AdButler\TextZone JSON: {
  "object": "text_zone",
  "self": "/v1/zones/text/104146",
  "id": 104146,
  "name": "120-90-sidebar",
  "publisher": 4771
}

You can update a specific text ad zones by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the text ad zone creation request.

Field Type Description

name

string

A descriptive name of the banner zone. We recommend using a naming convention that is consistent, relevant, and clear.

publisher

integer

The publisher identifier (ID) the banner zone belongs to. You can create zones without a publisher but you cannot use them unless you associate them with a publisher first.

Returns

Returns a text_zone object if the request succeeded, or an error if something went terribly wrong.

Delete a text ad zone

Definition

DELETE https://api.adbutler.com/v1/zones/text/{TEXT-ZONE-ID}
\AdButler\TextZone->delete()
adbutler.zones.textAds.delete()

Example Request

curl "https://api.adbutler.com/v1/zones/text/104146" \
  -H "Authorization: Basic {API_KEY}" \
  -X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$textZone = \AdButler\TextZone::retrieve( 104146 );
$textZone->delete();

echo $textZone;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.zones.textAds.delete(104146, function(err, response) {
  console.log(response);
});

// using promises
adbutler.zones.textAds.delete(104146).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "id": 104146,
  "delete": true
}
AdButler\TextZone JSON: {
  "id": 104146,
  "delete": true
}

Permanently deletes a text ad zone. if successful, this operation cannot be undone so be very sure when deleting one.

Returns

Returns a text zone ID if the request succeeded, or an error if something went terribly wrong.

List all text ad zones

Definition

GET https://api.adbutler.com/v1/zones/text
\AdButler\TextZone::retrieveAll()
adbutler.zones.textAds.list()

Example Request

curl "https://api.adbutler.com/v1/zones/text?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$textZone = \AdButler\TextZone::retrieveAll(array(
  "limit" => 2
));

echo $textZone;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.zones.textAds.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.zones.textAds.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/zones/text",
  "data": [
    {
      "object": "text_zone",
      "self": "/v1/zones/text/104023",
      "id": 104023,
      "name": "Default Text Zone",
      "publisher": 4722
    },
    {
      "object": "text_zone",
      "self": "/v1/zones/text/104026",
      "id": 104026,
      "name": "120-90-sidebar",
      "publisher": 4723
    }
  ]
}
AdButler\TextZone JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/zones/text",
  "data": [
    {
      "object": "text_zone",
      "self": "/v1/zones/text/104023",
      "id": 104023,
      "name": "Default Text Zone",
      "publisher": 4722
    },
    {
      "object": "text_zone",
      "self": "/v1/zones/text/104026",
      "id": 104026,
      "name": "120-90-sidebar",
      "publisher": 4723
    }
  ]
}

Returns a list of all the text ad zones. Most recent text ad zones appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is a text_zone object, and if no objects were found the list will be empty.

Retrieve text zone tags

Definition

GET https://api.adbutler.com/v1/zones/text/{TEXT-ZONE-ID}/tags
\AdButler\ZoneTag::retrieve()
adbutler.zones.tags.retrieve()

Example Request

curl "https://api.adbutler.com/v1/zones/text/104146/tags" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$zoneTag = \AdButler\ZoneTag::retrieve( 104146 );

echo $zoneTag;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.zones.tags.read(104146, function(err, response) {
  console.log(response);
});

// using promises
adbutler.zones.tags.read(104146).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

You can also retrieve the banner zone tags using the banner zone identifier (ID).

Query Parameters

Parameter Description

type

Specifies the type of the tag which can be any of the following value: async, js, iframe, image, json, or iframe-no-js. Async tags are recommended. You can specify multiple values by separating them with a comma e.g. type=async,js,image. Omitting the type will return all of them in the response. Consult your webmaster if unsure which tags to use.

protocol

Whether to use http or https protocol when serving the advertisements. Use https only if you are using secure pages becasue it does not support Custom Domains.

fallback

Whether to include <noscript> tag for supporting the older browsers (true). or not (false). <noscript> tag does not lend itself to easy tracking.

click

Unescaped third party click macro for use in other ad servers. The value must be RFC 3986 encoded.

extra

Extra data to pass along to the destination URLs when the user clicks on your advertisement. The value must be RFC 3986 encoded.

Returns

Example Response

{
  "object": "zone_tag",
  "url": "/v1/zones/text/104146/tags",
  "data": {
    "text": "<script type=\"text/javascript\">\nfunction loadTextAd(sparkCounter, id, setID) {\n  output104146=\"//servedbyadbutler.com.vm.test/adserve/;ID=\" + id + \";setID=\" + setID + \";type=textad;kw=\" + abkw + \";pid=\" + rnd + \";layoutID=\" + sparkCounter;\n  document.writeln(\"<SCR\" + \"IPT ASYNC SRC=\" + output104146 + \" type=\\\"text/javascript\\\"> <\\/scr\" + \"ipt>\");\n}\nvar loadedTextAds104146;\nif(loadedTextAds104146 == null)\n  loadedTextAds104146= new Array();\nvar d = new Date();\nvar id104146 = 108607;\nvar setID104146 = 104146;\nvar rnd = window.rnd || Math.floor(Math.random()*10e6);\nvar abkw = window.abkw ||';\nvar sparkCounter104146;\nif(sparkCounter104146 == null)\n  sparkCounter104146 = 1;\nelse\n  sparkCounter104146 = sparkCounter104146 + 1;\nid=\"abta104146\" + sparkCounter104146;\ndocument.writeln(\"<div id='\" + id + \"'></div>\");\nloadedTextAds104146[sparkCounter104146] = false;\nloadTextAd(sparkCounter104146, id104146, setID104146);\n</script>\n"
  }
}
AdButler\ZoneTag JSON: {
  "object": "zone_tag",
  "url": "/v1/zones/text/104146/tags",
  "data": {
    "text": "<script type=\"text/javascript\">\nfunction loadTextAd(sparkCounter, id, setID) {\n  output104146=\"//servedbyadbutler.com.vm.test/adserve/;ID=\" + id + \";setID=\" + setID + \";type=textad;kw=\" + abkw + \";pid=\" + rnd + \";layoutID=\" + sparkCounter;\n  document.writeln(\"<SCR\" + \"IPT ASYNC SRC=\" + output104146 + \" type=\\\"text/javascript\\\"> <\\/scr\" + \"ipt>\");\n}\nvar loadedTextAds104146;\nif(loadedTextAds104146 == null)\n  loadedTextAds104146= new Array();\nvar d = new Date();\nvar id104146 = 108607;\nvar setID104146 = 104146;\nvar rnd = window.rnd || Math.floor(Math.random()*10e6);\nvar abkw = window.abkw ||';\nvar sparkCounter104146;\nif(sparkCounter104146 == null)\n  sparkCounter104146 = 1;\nelse\n  sparkCounter104146 = sparkCounter104146 + 1;\nid=\"abta104146\" + sparkCounter104146;\ndocument.writeln(\"<div id='\" + id + \"'></div>\");\nloadedTextAds104146[sparkCounter104146] = false;\nloadTextAd(sparkCounter104146, id104146, setID104146);\n</script>\n"
  }
}
Field Type Description

object

string

A string denoting the object type which is always zone_tag for the current resource.

url

string

The relative URL of the current resource which is always of the form /v1/zones/banner/{BANNER_ZONE_ID}/tags.

data

array

The data object containing the zone tags requested in the URL.

 

Returns a zone_tag object if the request succeeded, or an error if something went terribly wrong.

Retrieve text zone conversion tag

Definition

GET https://api.adbutler.com/v1/zones/text/{TEXT-ZONE-ID}/conversion-tag
\AdButler\TextZoneConvTag::retrieve()
adbutler.zones.textAds.conversionTag.retrieve()

Example Request

curl "https://api.adbutler.com/v1/zones/text/ID/conversion-tag/104146" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$textZoneConvTag = \AdButler\TextZoneConvTag::retrieve( 104146 );

echo $textZoneConvTag;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.zones.textAds.conversionTag.read(104146, function(err, response) {
  console.log(response);
});

// using promises
adbutler.zones.textAds.conversionTag.read(104146).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Retrieves an HTML tag which can be used to track conversions for the provided zone.

Query Parameters

Parameter Description

protocol

Whether to use http or https protocol when serving the advertisements. Use https only if you are using secure pages because it does not support Custom Domains.

Returns

Example Response

{
  "object": "conv_tag",
  "url": "/v1/zones/text/104146/conversion-tag",
  "data": {
    "src": "https://servedbyadbutler.com.vm.test/convtrack.spark?MID=108607&zoneID=104146",
    "html": "<img src='https://servedbyadbutler.com.vm.test/convtrack.spark?MID=108607&zoneID=104146' width='1' height='1' border='0' />"
  }
}
AdButler\TextZoneConvTag JSON: {
  "object": "conv_tag",
  "url": "/v1/zones/text/104146/conversion-tag",
  "data": {
    "src": "https://servedbyadbutler.com.vm.test/convtrack.spark?MID=108607&zoneID=104146",
    "html": "<img src='https://servedbyadbutler.com.vm.test/convtrack.spark?MID=108607&zoneID=104146' width='1' height='1' border='0' />"
  }
}
Field Type Description

object

string

A string denoting the object type which is always conv_tag for the current resource.

url

string

The relative URL of the current resource which is always of the form /v1/zones/text/{TEXT_ZONE_ID}/conversion-tag.

data

array

The data object containing the conversion tag.

 

Returns a conv_tag object if the request succeeded, or an error if something went terribly wrong.


Bidders

Introduction

To run a header bidding auction with AdButler, you need to create a Bidder. A Bidder will contain all of the necessary information required to insert itself into a Prebid auction, as well as a name to help you identify it.

The bidder response object has the following fields.

Example Response

{
  "object": "bidder",
  "self": "/v1/bidders/98",
  "id": 98,
  "bidder_code": "adbutler",
  "created_date": "2018-11-28 11:49:48",
  "name": "AdButler Bidder",
  "parameters": {
    "accountID": "108607",
    "keyword": "green",
    "maxCPM": "5.00",
    "minCPM": "1.00",
    "zoneID": "104144"
  }
}
AdButler\Bidder JSON: {
  "object": "bidder",
  "self": "/v1/bidders/98",
  "id": 98,
  "bidder_code": "adbutler",
  "created_date": "2018-11-28 11:49:48",
  "name": "AdButler Bidder",
  "parameters": {
    "accountID": 108607,
    "keyword": "green",
    "maxCPM": 5,
    "minCPM": 1,
    "zoneID": 104144
  }
}
Field Type Description

object

string

A string denoting the object type which is always bidder for the current resource.

self

string

The relative URL of the current resource which is always of the form /v1/bidders/{BIDDER_ID}.

id

integer

The current resource identifier (ID).

bidder_code

string

A string token representing the bidding partner.

created_date

string

The date and time when the bidder was created.

name

string

The name of the bidder.

parameters

array

The custom parameters of the chosen bidding partner.

Create a bidder

Definition

POST https://api.adbutler.com/v1/bidders
\AdButler\Bidder::create()
adbutler.bidders.create()

Example Request

curl "https://api.adbutler.com/v1/bidders" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{  
        "bidder_code": "adbutler",
        "name": "AdButler Bidder",
        "parameters": 
                {
                        accountID: "108607",
                        keyword: "green",
                        maxCPM: "5.00",
                        minCPM: "1.00",
                        zoneID: "104144"
                }
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$bidder = \AdButler\Bidder::create(array(
  "bidder_code" => "adbutler",
  "name" => "AdButler Bidder",
  "parameters" => 
    [
      accountID => "108607",
      keyword => "green",
      maxCPM => "5.00",
      minCPM => "1.00",
      zoneID => "104144"
    ]
));

echo $bidder;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var postData = {
  "bidder_code": "adbutler",
  "name": "AdButler Bidder",
  "parameters": 
    {
      accountID: "108607",
      keyword: "green",
      maxCPM: "5.00",
      minCPM: "1.00",
      zoneID: "104144"
    }
};

// using callbacks
adbutler.bidders.create(postData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.bidders.create(postData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "bidder",
  "self": "/v1/bidders/98",
  "id": 98,
  "bidder_code": "adbutler",
  "created_date": "2018-11-28 11:49:48",
  "name": "AdButler Bidder",
  "parameters": {
    "accountID": "108607",
    "keyword": "green",
    "maxCPM": "5.00",
    "minCPM": "1.00",
    "zoneID": "104144"
  }
}
AdButler\Bidder JSON: {
  "object": "bidder",
  "self": "/v1/bidders/98",
  "id": 98,
  "bidder_code": "adbutler",
  "created_date": "2018-11-28 11:49:48",
  "name": "AdButler Bidder",
  "parameters": {
    "accountID": 108607,
    "keyword": "green",
    "maxCPM": 5,
    "minCPM": 1,
    "zoneID": 104144
  }
}

Creates a new bidder.

Field Type Description

bidder_code*

string

The bidding partner that this bidder will represent. See the up-to-date list of bidder codes.

name*

string

A descriptive name of the bidder. We recommend using a naming convention that is consistent, relevant, and clear.

parameters*

object

The parameters that are accepted by the chosen bidding partner. See parameter details for various bidders.

* = required field

Returns

Returns an bidder object if the request succeeded, or an error if something went terribly wrong.

Retrieve a bidder

Definition

GET https://api.adbutler.com/v1/bidders/{BIDDER-ID}
\AdButler\Bidder::retrieve()
adbutler.bidders.retrieve()

Example Request

curl "https://api.adbutler.com/v1/bidders/98" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$bidder = \AdButler\Bidder::retrieve( 98 );

echo $bidder;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.bidders.read(98, function(err, response) {
  console.log(response);
});

// using promises
adbutler.bidders.read(98).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "bidder",
  "self": "/v1/bidders/98",
  "id": 98,
  "bidder_code": "adbutler",
  "created_date": "2018-11-28 11:49:48",
  "name": "AdButler Bidder",
  "parameters": {
    "accountID": "108607",
    "keyword": "green",
    "maxCPM": "5.00",
    "minCPM": "1.00",
    "zoneID": "104144"
  }
}
AdButler\Bidder JSON: {
  "object": "bidder",
  "self": "/v1/bidders/98",
  "id": 98,
  "bidder_code": "adbutler",
  "created_date": "2018-11-28 11:49:48",
  "name": "AdButler Bidder",
  "parameters": {
    "accountID": 108607,
    "keyword": "green",
    "maxCPM": 5,
    "minCPM": 1,
    "zoneID": 104144
  }
}

You can retrieve the information about an existing bidder by giving the bidder ID that was returned in the bidder object upon creation. You will see at the most 10 bidders in the response. You can change this default limit by appending ?limit=25 if you want this request to return 25 bidders.

Returns

Returns an bidder object if the request succeeded, or an error if something went terribly wrong.

Update a bidder

Definition

PUT https://api.adbutler.com/v1/bidders/{BIDDER-ID}
\AdButler\Bidder->save()
adbutler.bidders.update()

Example Request

curl "https://api.adbutler.com/v1/bidders/98" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{  
        "bidder_code": "adbutler",
        "name": "AdButler Bidder",
        "parameters": 
                {
                        accountID: "108607",
                        keyword: "green",
                        maxCPM: "5.00",
                        minCPM: "1.00",
                        zoneID: "104144"
                }
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$bidder = \AdButler\Bidder::retrieve( 98 );

$bidder->bidder_code = "adbutler";
$bidder->name = "AdButler Bidder";
$bidder->parameters = 
[
accountID = "108607",
keyword = "green",
maxCPM = "5.00",
minCPM = "1.00",
zoneID = "104144"
];

$bidder->save();

echo $bidder;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var updateData = {
  "bidder_code": "adbutler",
  "name": "AdButler Bidder",
  "parameters": 
    {
      accountID: "108607",
      keyword: "green",
      maxCPM: "5.00",
      minCPM: "1.00",
      zoneID: "104144"
    }
};

// using callbacks
adbutler.bidders.update(98, updateData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.bidders.update(98, updateData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "bidder",
  "self": "/v1/bidders/98",
  "id": 98,
  "bidder_code": "adbutler",
  "created_date": "2018-11-28 11:49:48",
  "name": "AdButler Bidder",
  "parameters": {
    "accountID": "108607",
    "keyword": "green",
    "maxCPM": "5.00",
    "minCPM": "1.00",
    "zoneID": "104144"
  }
}
AdButler\Bidder JSON: {
  "object": "bidder",
  "self": "/v1/bidders/98",
  "id": 98,
  "bidder_code": "adbutler",
  "created_date": "2018-11-28 11:49:48",
  "name": "AdButler Bidder",
  "parameters": {
    "accountID": 108607,
    "keyword": "green",
    "maxCPM": 5,
    "minCPM": 1,
    "zoneID": 104144
  }
}

You can update a specific bidder account by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the bidder creation request.

Field Type Description

bidder_code

string

The bidding partner that this bidder will represent. See the up-to-date list of bidder codes.

name

string

A descriptive name of the bidder. We recommend using a naming convention that is consistent, relevant, and clear.

parameters

object

The parameters that are accepted by the chosen bidding partner. See parameter details for various bidders.

† = Must be given if bidder_code is set. All the old values will be overwritten.

Returns

Returns an bidder object if the request succeeded, or an error if something went terribly wrong.

Delete a bidder

Definition

DELETE https://api.adbutler.com/v1/bidders/{BIDDER-ID}
\AdButler\Bidder->delete()
adbutler.bidders.delete()

Example Request

curl "https://api.adbutler.com/v1/bidders/98" \
  -H "Authorization: Basic {API_KEY}" \
  -X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$bidder = \AdButler\Bidder::retrieve( 98 );
$bidder->delete();

echo $bidder;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.bidders.delete(98, function(err, response) {
  console.log(response);
});

// using promises
adbutler.bidders.delete(98).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "id": 98,
  "delete": true
}
AdButler\Bidder JSON: {
  "id": 98,
  "delete": true
}

Permanently deletes an bidder. if successful, this operation cannot be undone so be very sure when deleting one. Also immediately stops serving any ads belonging to this bidder account.

Returns

Returns an bidder ID if the request succeeded, or an error if something went terribly wrong.

List all bidders

Definition

GET https://api.adbutler.com/v1/bidders
\AdButler\Bidder::retrieveAll()
adbutler.bidders.list()

Example Request

curl "https://api.adbutler.com/v1/bidders?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$bidder = \AdButler\Bidder::retrieveAll(array(
  "limit" => 2
));

echo $bidder;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.bidders.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.bidders.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/bidders",
  "data": [
    {
      "object": "bidder",
      "self": "/v1/bidders/85",
      "id": 85,
      "bidder_code": "adbutler",
      "created_date": "2018-06-28 09:55:56",
      "name": "AdButler Bidder",
      "parameters": {
        "accountID": "108607",
        "keyword": "green",
        "maxCPM": "5.00",
        "minCPM": "1.00",
        "zoneID": "104024"
      }
    },
    {
      "object": "bidder",
      "self": "/v1/bidders/86",
      "id": 86,
      "bidder_code": "adbutler",
      "created_date": "2018-06-28 10:16:20",
      "name": "AdButler Bidder",
      "parameters": {
        "accountID": "108607",
        "keyword": "green",
        "maxCPM": "5.00",
        "minCPM": "1.00",
        "zoneID": "104027"
      }
    }
  ]
}
AdButler\Bidder JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/bidders",
  "data": [
    {
      "object": "bidder",
      "self": "/v1/bidders/85",
      "id": 85,
      "bidder_code": "adbutler",
      "created_date": "2018-06-28 09:55:56",
      "name": "AdButler Bidder",
      "parameters": {
        "accountID": 108607,
        "keyword": "green",
        "maxCPM": 5,
        "minCPM": 1,
        "zoneID": 104024
      }
    },
    {
      "object": "bidder",
      "self": "/v1/bidders/86",
      "id": 86,
      "bidder_code": "adbutler",
      "created_date": "2018-06-28 10:16:20",
      "name": "AdButler Bidder",
      "parameters": {
        "accountID": 108607,
        "keyword": "green",
        "maxCPM": 5,
        "minCPM": 1,
        "zoneID": 104027
      }
    }
  ]
}

Returns a list of all the bidder accounts. Most recent bidder accounts appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is an bidder object, and if no objects were found the list will be empty.


Advertisers

Introduction

An advertiser is an individual or a company paying for one or more advertisements to be served. You and your managers (if permitted) can create advertiser accounts. They may also copy conversion tags and optionally be able to submit new advertisements for review.

The advertiser response object has the following fields.

Example Response

{
  "object": "advertiser",
  "self": "/v1/advertisers/5129",
  "id": 5129,
  "can_change_password": true,
  "can_add_banners": true,
  "email": "demo.advertiser@adbutler.com",
  "name": "Demo Advertiser",
  "has_password": true
}
AdButler\Advertiser JSON: {
  "object": "advertiser",
  "self": "/v1/advertisers/5129",
  "id": 5129,
  "can_change_password": true,
  "can_add_banners": true,
  "email": "demo.advertiser@adbutler.com",
  "name": "Demo Advertiser",
  "has_password": true
}
Field Type Description

object

string

A string denoting the object type which is always advertiser for the current resource.

self

string

The relative URL of the current resource which is always of the form /v1/advertisers/{ADVERTISER_ID}.

id

integer

The current resource identifier (ID).

can_change_password

boolean

Whether to allow this advertiser to change their password.

can_add_banners

boolean

Whether to allow this advertiser to submit advertisements for scheduling in the zones you own.

email

string

A valid email of the advertiser.

name

string

Name of the advertiser.

has_password

boolean

A field indicating if the password is set.

Create an advertiser

Definition

POST https://api.adbutler.com/v1/advertisers
\AdButler\Advertiser::create()
adbutler.advertisers.create()

Example Request

curl "https://api.adbutler.com/v1/advertisers" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{  
        "can_change_password": true,
        "can_add_banners": true,
        "email": "demo.advertiser@adbutler.com",
        "name": "Demo Advertiser",
        "password": "some_password"
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$advertiser = \AdButler\Advertiser::create(array(
  "can_change_password" => true,
  "can_add_banners" => true,
  "email" => "demo.advertiser@adbutler.com",
  "name" => "Demo Advertiser",
  "password" => "some_password"
));

echo $advertiser;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var postData = {
  "can_change_password": true,
  "can_add_banners": true,
  "email": "demo.advertiser@adbutler.com",
  "name": "Demo Advertiser",
  "password": "some_password"
};

// using callbacks
adbutler.advertisers.create(postData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.advertisers.create(postData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "advertiser",
  "self": "/v1/advertisers/5129",
  "id": 5129,
  "can_change_password": true,
  "can_add_banners": true,
  "email": "demo.advertiser@adbutler.com",
  "name": "Demo Advertiser",
  "has_password": true
}
AdButler\Advertiser JSON: {
  "object": "advertiser",
  "self": "/v1/advertisers/5129",
  "id": 5129,
  "can_change_password": true,
  "can_add_banners": true,
  "email": "demo.advertiser@adbutler.com",
  "name": "Demo Advertiser",
  "has_password": true
}

Creates a new advertiser.

Field Type Description

name*

string

A descriptive name of the advertiser.

email

string

The email address of the advertiser.

password

string

The password of the advertiser.

can_add_banners

boolean

Whether this advertiser can schedule advertisements in your zones or not.

can_change_password

boolean

Whether this advertiser can change password or not.

* = required field

Optionally, you can give advertisers access to their account, as well as the ability to schedule new ads if you give them user access.

Returns

Returns an advertiser object if the request succeeded, or an error if something went terribly wrong.

Retrieve an advertiser

Definition

GET https://api.adbutler.com/v1/advertisers/{ADVERTISER-ID}
\AdButler\Advertiser::retrieve()
adbutler.advertisers.retrieve()

Example Request

curl "https://api.adbutler.com/v1/advertisers/5129" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$advertiser = \AdButler\Advertiser::retrieve( 5129 );

echo $advertiser;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.advertisers.read(5129, function(err, response) {
  console.log(response);
});

// using promises
adbutler.advertisers.read(5129).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "advertiser",
  "self": "/v1/advertisers/5129",
  "id": 5129,
  "can_change_password": true,
  "can_add_banners": true,
  "email": "demo.advertiser@adbutler.com",
  "name": "Demo Advertiser",
  "has_password": true
}
AdButler\Advertiser JSON: {
  "object": "advertiser",
  "self": "/v1/advertisers/5129",
  "id": 5129,
  "can_change_password": true,
  "can_add_banners": true,
  "email": "demo.advertiser@adbutler.com",
  "name": "Demo Advertiser",
  "has_password": true
}

You can retrieve the information about an existing advertiser by giving the advertiser ID that was returned in the advertiser object upon creation. You will see at the most 10 advertisers in the response. You can change this default limit by appending ?limit=25 if you want this request to return 25 advertisers.

Returns

Returns an advertiser object if the request succeeded, or an error if something went terribly wrong.

Update an advertiser

Definition

PUT https://api.adbutler.com/v1/advertisers/{ADVERTISER-ID}
\AdButler\Advertiser->save()
adbutler.advertisers.update()

Example Request

curl "https://api.adbutler.com/v1/advertisers/5129" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{  
        "can_change_password": true,
        "can_add_banners": true,
        "email": "demo.advertiser@adbutler.com",
        "name": "Demo Advertiser",
        "password": "some_password"
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$advertiser = \AdButler\Advertiser::retrieve( 5129 );

$advertiser->can_change_password = true;
$advertiser->can_add_banners = true;
$advertiser->email = "demo.advertiser@adbutler.com";
$advertiser->name = "Demo Advertiser";
$advertiser->password = "some_password";

$advertiser->save();

echo $advertiser;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var updateData = {
  "can_change_password": true,
  "can_add_banners": true,
  "email": "demo.advertiser@adbutler.com",
  "name": "Demo Advertiser",
  "password": "some_password"
};

// using callbacks
adbutler.advertisers.update(5129, updateData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.advertisers.update(5129, updateData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "advertiser",
  "self": "/v1/advertisers/5129",
  "id": 5129,
  "can_change_password": true,
  "can_add_banners": true,
  "email": "demo.advertiser@adbutler.com",
  "name": "Demo Advertiser",
  "has_password": true
}
AdButler\Advertiser JSON: {
  "object": "advertiser",
  "self": "/v1/advertisers/5129",
  "id": 5129,
  "can_change_password": true,
  "can_add_banners": true,
  "email": "demo.advertiser@adbutler.com",
  "name": "Demo Advertiser",
  "has_password": true
}

You can update a specific advertiser account by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the advertiser creation request.

Field Type Description

name

string

A descriptive name of the advertiser.

email

string

The email address of the advertiser.

password

string

The password of the advertiser.

can_add_banners

boolean

Whether this advertiser can schedule advertisements in your zones or not.

can_change_password

boolean

Whether this advertiser can change password or not.

Returns

Returns an advertiser object if the request succeeded, or an error if something went terribly wrong.

Delete an advertiser

Definition

DELETE https://api.adbutler.com/v1/advertisers/{ADVERTISER-ID}
\AdButler\Advertiser->delete()
adbutler.advertisers.delete()

Example Request

curl "https://api.adbutler.com/v1/advertisers/5129" \
  -H "Authorization: Basic {API_KEY}" \
  -X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$advertiser = \AdButler\Advertiser::retrieve( 5129 );
$advertiser->delete();

echo $advertiser;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.advertisers.delete(5129, function(err, response) {
  console.log(response);
});

// using promises
adbutler.advertisers.delete(5129).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "id": 5129,
  "delete": true
}
AdButler\Advertiser JSON: {
  "id": 5129,
  "delete": true
}

Permanently deletes an advertiser. if successful, this operation cannot be undone so be very sure when deleting one. Also immediately stops serving any ads belonging to this advertiser account.

Returns

Returns an advertiser ID if the request succeeded, or an error if something went terribly wrong.

List all advertisers

Definition

GET https://api.adbutler.com/v1/advertisers
\AdButler\Advertiser::retrieveAll()
adbutler.advertisers.list()

Example Request

curl "https://api.adbutler.com/v1/advertisers?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$advertiser = \AdButler\Advertiser::retrieveAll(array(
  "limit" => 2
));

echo $advertiser;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.advertisers.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.advertisers.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/advertisers",
  "data": [
    {
      "object": "advertiser",
      "self": "/v1/advertisers/5057",
      "id": 5057,
      "can_change_password": true,
      "can_add_banners": false,
      "email": "nobody@adbutler.com",
      "name": "Default Advertiser",
      "has_password": true
    },
    {
      "object": "advertiser",
      "self": "/v1/advertisers/5058",
      "id": 5058,
      "can_change_password": true,
      "can_add_banners": true,
      "email": "demo.advertiser@adbutler.com",
      "name": "Demo Advertiser",
      "has_password": true
    }
  ]
}
AdButler\Advertiser JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/advertisers",
  "data": [
    {
      "object": "advertiser",
      "self": "/v1/advertisers/5057",
      "id": 5057,
      "can_change_password": true,
      "can_add_banners": false,
      "email": "nobody@adbutler.com",
      "name": "Default Advertiser",
      "has_password": true
    },
    {
      "object": "advertiser",
      "self": "/v1/advertisers/5058",
      "id": 5058,
      "can_change_password": true,
      "can_add_banners": true,
      "email": "demo.advertiser@adbutler.com",
      "name": "Demo Advertiser",
      "has_password": true
    }
  ]
}

Returns a list of all the advertiser accounts. Most recent advertiser accounts appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is an advertiser object, and if no objects were found the list will be empty.

Archive an advertiser

Definition

GET https://api.adbutler.com/v1/advertisers/{ADVERTISER-ID}/archive
\AdButler\AdvertiserArchive::retrieve()
adbutler.advertisers.archive.retrieve()

Example Request

curl "https://api.adbutler.com/v1/advertisers/ID/archive/5130" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$advertiserArchive = \AdButler\AdvertiserArchive::retrieve( 5130 );

echo $advertiserArchive;
var AdButler = require("adbutler");

var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.advertisers.archive.read(5130, function(err, response) {
  console.log(response);
});

// using promises
adbutler.advertisers.archive.read(5130).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Archives the resource and all direct descendents of this resource. Archived resources will be treated the same as deleted resources but can be restored through unarchiving.

Returns

Example Response

{
  "object": "archive",
  "url": "/v1/advertisers/5130/archive",
  "data": {
    "archived_resources": [
      {
        "object": "advertiser",
        "id": 5130
      },
      {
        "object": "campaign",
        "id": 10272
      }
    ]
  }
}
AdButler\AdvertiserArchive JSON: {
  "object": "archive",
  "url": "/v1/advertisers/5130/archive",
  "data": {
    "archived_resources": [
      {
        "object": "advertiser",
        "id": 5130
      },
      {
        "object": "campaign",
        "id": 10272
      }
    ]
  }
}
Field Type Description

object

string

A string denoting the object type which is always archive for the current resource.

url

string

The relative URL of the current resource which is always of the form /v1/advertisers/{ADVERTISER-ID}/archive.

data

array

The data object containing a list of the resources archived by this action.

 

Returns an archive object if the request succeeded, or an error if something went terribly wrong.

Unarchive an advertiser

Definition

GET https://api.adbutler.com/v1/advertisers/{ADVERTISER-ID}/unarchive
\AdButler\AdvertiserUnarchive::retrieve()
adbutler.advertisers.unarchive.retrieve()

Example Request

curl "https://api.adbutler.com/v1/advertisers/ID/unarchive/5130" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$advertiserUnarchive = \AdButler\AdvertiserUnarchive::retrieve( 5130 );

echo $advertiserUnarchive;
var AdButler = require("adbutler");

var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.advertisers.unarchive.read(5130, function(err, response) {
  console.log(response);
});

// using promises
adbutler.advertisers.unarchive.read(5130).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Unarchives the resource and all resources that were previously archived with the resource.

Query Parameters

Parameter Description

include_campaign_assignments

Whether or not to include related campaign assignments when unarchiving the resource. If an unarchived assignment references an invalid resource, the campaign assignment will not be unarchived and information about the invalid resource and references will be returned. The advertiser resource will still be unarchived.

include_placements

Whether or not to include related placements when unarchiving the resource. If an unarchived placement references an invalid resource, the placement will not be unarchived and information about the invalid resource and references will be returned. The advertiser resource will still be unarchived.

Returns

Example Response

{
  "object": "unarchive",
  "url": "/v1/advertisers/5130/unarchive",
  "data": {
    "unarchived_resources": [
      {
        "object": "advertiser",
        "id": 5130
      },
      {
        "object": "campaign",
        "id": 10272
      }
    ]
  }
}
AdButler\AdvertiserUnarchive JSON: {
  "object": "unarchive",
  "url": "/v1/advertisers/5130/unarchive",
  "data": {
    "unarchived_resources": [
      {
        "object": "advertiser",
        "id": 5130
      },
      {
        "object": "campaign",
        "id": 10272
      }
    ]
  }
}
Field Type Description

object

string

A string denoting the object type which is always unarchive for the current resource.

url

string

The relative URL of the current resource which is always of the form /v1/advertisers/{ADVERTISER-ID}/unarchive.

data

array

The data object containing a list of the resources unarchived by this action. When including assignments, a list of resources that reference deleted or invalid resources will also be returned.

 

Returns an unarchive object if the request succeeded, or an error if something went terribly wrong.


Campaigns

List all campaigns

Definition

GET https://api.adbutler.com/v1/campaigns
\AdButler\Campaign::retrieveAll()
adbutler.campaigns.list()

Example Request

curl "https://api.adbutler.com/v1/campaigns?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$campaign = \AdButler\Campaign::retrieveAll(array(
  "limit" => 2
));

echo $campaign;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.campaigns.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.campaigns.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/campaigns",
  "data": [
    {
      "object": "banner_campaign",
      "self": "/v1/campaigns/banner/10154",
      "id": 10154,
      "advertiser": 5057,
      "height": 250,
      "name": "Default Campaign",
      "roadblock_tags": null,
      "width": 300,
      "flexible_type": 0,
      "deleted": false
    },
    {
      "object": "banner_campaign",
      "self": "/v1/campaigns/banner/10156",
      "id": 10156,
      "advertiser": 5058,
      "height": 250,
      "name": "Demo Banner Campaign",
      "roadblock_tags": null,
      "width": 300,
      "flexible_type": 0,
      "deleted": false
    }
  ]
}
AdButler\Campaign JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/campaigns",
  "data": [
    {
      "object": "banner_campaign",
      "self": "/v1/campaigns/banner/10154",
      "id": 10154,
      "advertiser": 5057,
      "height": 250,
      "name": "Default Campaign",
      "roadblock_tags": null,
      "width": 300,
      "flexible_type": 0,
      "deleted": false
    },
    {
      "object": "banner_campaign",
      "self": "/v1/campaigns/banner/10156",
      "id": 10156,
      "advertiser": 5058,
      "height": 250,
      "name": "Demo Banner Campaign",
      "roadblock_tags": null,
      "width": 300,
      "flexible_type": 0,
      "deleted": false
    }
  ]
}

You can retrieve a list of all the campaigns regardless of their type. You can optionally restrict the fields that you are interested in retrieving by using the fields query parameter.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is an object, and if no objects were found the list will be empty.


Text Campaigns

Introduction

Text campaigns are an effective way for you to organize your text ads under an Advertiser. Campaigns can be scheduled to serve in zones of matching sizes, enabling you to easily collect grouped statistics and determine payouts for Advertisers.

The text_campaign response object has the following fields.

Example Response

{
  "object": "text_campaign",
  "self": "/v1/campaigns/text/10274",
  "id": 10274,
  "advertiser": 5129,
  "name": "Demo Text Campaign"
}
AdButler\TextAdCampaign JSON: {
  "object": "text_campaign",
  "self": "/v1/campaigns/text/10274",
  "id": 10274,
  "advertiser": 5129,
  "name": "Demo Text Campaign"
}
Field Type Description

object

string

A string denoting the object type which is always text_campaign for the current resource.

self

string

The relative URL of the current resource which is always of the form /v1/campaigns/text/{TEXT_CAMPAIGN_ID}.

id

integer

The current resource identifier (ID).

advertiser

integer

The advertiser identifier (ID).

name

string

The name of the text campaign.

Create a text ad campaign

Definition

POST https://api.adbutler.com/v1/campaigns/text
\AdButler\TextAdCampaign::create()
adbutler.campaigns.textAds.create()

Example Request

curl "https://api.adbutler.com/v1/campaigns/text" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{  
        "advertiser": 5129,
        "name": "Demo Text Campaign"
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$textAdCampaign = \AdButler\TextAdCampaign::create(array(
  "advertiser" => 5129,
  "name" => "Demo Text Campaign"
));

echo $textAdCampaign;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var postData = {
  "advertiser": 5129,
  "name": "Demo Text Campaign"
};

// using callbacks
adbutler.campaigns.textAds.create(postData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.campaigns.textAds.create(postData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "text_campaign",
  "self": "/v1/campaigns/text/10274",
  "id": 10274,
  "advertiser": 5129,
  "name": "Demo Text Campaign"
}
AdButler\TextAdCampaign JSON: {
  "object": "text_campaign",
  "self": "/v1/campaigns/text/10274",
  "id": 10274,
  "advertiser": 5129,
  "name": "Demo Text Campaign"
}

Creates a new text ad campaign.

Field Type Description

name*

string

A descriptive name of the text ad campaign.

advertiser

integer

The advertiser resource identifier (ID).

* = required field

Returns

Returns a text_campaign object if the request succeeded, or an error if something went terribly wrong.

Retrieve a text ad campaign

Definition

GET https://api.adbutler.com/v1/campaigns/text/{TEXT-CAMPAIGN-ID}
\AdButler\TextAdCampaign::retrieve()
adbutler.campaigns.textAds.retrieve()

Example Request

curl "https://api.adbutler.com/v1/campaigns/text/10274" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$textAdCampaign = \AdButler\TextAdCampaign::retrieve( 10274 );

echo $textAdCampaign;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.campaigns.textAds.read(10274, function(err, response) {
  console.log(response);
});

// using promises
adbutler.campaigns.textAds.read(10274).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "text_campaign",
  "self": "/v1/campaigns/text/10274",
  "id": 10274,
  "advertiser": 5129,
  "name": "Demo Text Campaign"
}
AdButler\TextAdCampaign JSON: {
  "object": "text_campaign",
  "self": "/v1/campaigns/text/10274",
  "id": 10274,
  "advertiser": 5129,
  "name": "Demo Text Campaign"
}

You can retrieve the information about an existing text ad campaign by giving the text ad campaign ID that was returned in the text ad campaign object upon creation.

Returns

Returns a text_campaign object if the request succeeded, or an error if something went terribly wrong.

Update a text ad campaign

Definition

PUT https://api.adbutler.com/v1/campaigns/text/{TEXT-CAMPAIGN-ID}
\AdButler\TextAdCampaign->save()
adbutler.campaigns.textAds.update()

Example Request

curl "https://api.adbutler.com/v1/campaigns/text/10274" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{  
        "advertiser": 5129,
        "name": "Demo Text Campaign"
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$textAdCampaign = \AdButler\TextAdCampaign::retrieve( 10274 );

$textAdCampaign->advertiser = 5129;
$textAdCampaign->name = "Demo Text Campaign";

$textAdCampaign->save();

echo $textAdCampaign;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var updateData = {
  "advertiser": 5129,
  "name": "Demo Text Campaign"
};

// using callbacks
adbutler.campaigns.textAds.update(10274, updateData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.campaigns.textAds.update(10274, updateData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "text_campaign",
  "self": "/v1/campaigns/text/10274",
  "id": 10274,
  "advertiser": 5129,
  "name": "Demo Text Campaign"
}
AdButler\TextAdCampaign JSON: {
  "object": "text_campaign",
  "self": "/v1/campaigns/text/10274",
  "id": 10274,
  "advertiser": 5129,
  "name": "Demo Text Campaign"
}

You can update a specific text ad campaign account by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the text ad campaign creation request.

Field Type Description

name

string

A descriptive name of the text ad campaign.

advertiser

integer

The advertiser resource identifier (ID).

Returns

Returns a text_campaign object if the request succeeded, or an error if something went terribly wrong.

Delete a text ad campaign

Definition

DELETE https://api.adbutler.com/v1/campaigns/text/{TEXT-CAMPAIGN-ID}
\AdButler\TextAdCampaign->delete()
adbutler.campaigns.textAds.delete()

Example Request

curl "https://api.adbutler.com/v1/campaigns/text/10274" \
  -H "Authorization: Basic {API_KEY}" \
  -X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$textAdCampaign = \AdButler\TextAdCampaign::retrieve( 10274 );
$textAdCampaign->delete();

echo $textAdCampaign;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.campaigns.textAds.delete(10274, function(err, response) {
  console.log(response);
});

// using promises
adbutler.campaigns.textAds.delete(10274).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "id": 10274,
  "delete": true
}
AdButler\TextAdCampaign JSON: {
  "id": 10274,
  "delete": true
}

Permanently deletes a Text Ad Campaign. if successful, this operation cannot be undone so be very sure when deleting one.

Returns

Returns a text campaign ID if the request succeeded, or an error if something went terribly wrong.

List all text ad campaigns

Definition

GET https://api.adbutler.com/v1/campaigns/text
\AdButler\TextAdCampaign::retrieveAll()
adbutler.campaigns.textAds.list()

Example Request

curl "https://api.adbutler.com/v1/campaigns/text?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$textAdCampaign = \AdButler\TextAdCampaign::retrieveAll(array(
  "limit" => 2
));

echo $textAdCampaign;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.campaigns.textAds.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.campaigns.textAds.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/campaigns/text",
  "data": [
    {
      "object": "text_campaign",
      "self": "/v1/campaigns/text/10155",
      "id": 10155,
      "advertiser": 5057,
      "name": "Default Campaign"
    },
    {
      "object": "text_campaign",
      "self": "/v1/campaigns/text/10157",
      "id": 10157,
      "advertiser": 5058,
      "name": "Demo Text Campaign"
    }
  ]
}
AdButler\TextAdCampaign JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/campaigns/text",
  "data": [
    {
      "object": "text_campaign",
      "self": "/v1/campaigns/text/10155",
      "id": 10155,
      "advertiser": 5057,
      "name": "Default Campaign"
    },
    {
      "object": "text_campaign",
      "self": "/v1/campaigns/text/10157",
      "id": 10157,
      "advertiser": 5058,
      "name": "Demo Text Campaign"
    }
  ]
}

Returns a list of all the text ad campaigns. Most recent text ad campaigns appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is a text_campaign object, and if no objects were found the list will be empty.

Retrieve text campaign conversion tag

Definition

GET https://api.adbutler.com/v1/campaigns/{CAMPAIGN-ID}/conversion-tag
\AdButler\TextCampaignConvTag::retrieve()
adbutler.campaigns.textAds.conversionTag.retrieve()

Example Request

curl "https://api.adbutler.com/v1/campaigns/text/ID/conversion-tag/10274" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$textCampaignConvTag = \AdButler\TextCampaignConvTag::retrieve( 10274 );

echo $textCampaignConvTag;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.campaigns.textAds.conversionTag.read(10274, function(err, response) {
  console.log(response);
});

// using promises
adbutler.campaigns.textAds.conversionTag.read(10274).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Retrieves an HTML tag which can be used to track conversions for the provided campaign.

Query Parameters

Parameter Description

protocol

Whether to use http or https protocol when serving the advertisements. Use https only if you are using secure pages because it does not support Custom Domains.

Returns

Example Response

{
  "object": "conv_tag",
  "url": "/v1/campaigns/text/10274/conversion-tag",
  "data": {
    "src": "https://servedbyadbutler.com.vm.test/convtrack.spark?MID=108607&CID=10274",
    "html": "<img src='https://servedbyadbutler.com.vm.test/convtrack.spark?MID=108607&CID=10274' width='1' height='1' border='0' />"
  }
}
AdButler\TextCampaignConvTag JSON: {
  "object": "conv_tag",
  "url": "/v1/campaigns/text/10274/conversion-tag",
  "data": {
    "src": "https://servedbyadbutler.com.vm.test/convtrack.spark?MID=108607&CID=10274",
    "html": "<img src='https://servedbyadbutler.com.vm.test/convtrack.spark?MID=108607&CID=10274' width='1' height='1' border='0' />"
  }
}
Field Type Description

object

string

A string denoting the object type which is always conv_tag for the current resource.

url

string

The relative URL of the current resource which is always of the form /v1/campaigns/text/{CAMPAIGN_ID}/conversion-tag.

data

array

The data object containing the conversion tag.

 

Returns a conv_tag object if the request succeeded, or an error if something went terribly wrong.


Campaign Assignments

Introduction

A campaign assignment represents the relationship between a banner and a campaign.

The campaign_assignment response object has the following fields.

Example Response

{
  "object": "campaign_assignment",
  "self": "/v1/campaign-assignments/8030",
  "id": 8030,
  "active": true,
  "advertisement": {
    "id": 518889981,
    "type": "image_banner"
  },
  "campaign": {
    "id": 10273,
    "type": "banner_campaign"
  },
  "weight": 2
}
AdButler\CampaignAssignment JSON: {
  "object": "campaign_assignment",
  "self": "/v1/campaign-assignments/8030",
  "id": 8030,
  "active": true,
  "advertisement": {
    "id": 518889981,
    "type": "image_banner"
  },
  "campaign": {
    "id": 10273,
    "type": "banner_campaign"
  },
  "weight": 2
}
Field Type Description

object

string

A string denoting the object type which is always campaign_assignment for the current resource.

self

string

The relative URL of the current resource which is always of the form /v1/campaign‑assignments/{CAMPAIGN_ASSIGNMENT_ID}.

id

integer

The current resource identifier (ID).

active

boolean

The status of ad serving whether it is being served in the given zone or not.

advertisement

array

An object containing image, flash, rich media, or custom HTML banner identifier (ID) and type.

campaign

array

An object containing banner or text campaign identifier (ID) and type.

weight

integer

A number used to compute the probability of serving a particular ad.

Create a campaign assignment

Definition

POST https://api.adbutler.com/v1/campaign-assignments
\AdButler\CampaignAssignment::create()
adbutler.campaignAssignments.create()

Example Request

curl "https://api.adbutler.com/v1/campaign-assignments" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{  
        "active": true,
        "advertisement": 
                {
                        id: 518889981,
                        type: "image_banner"
                },
        "campaign": 
                {
                        id: 10273,
                        type: "banner_campaign"
                },
        "weight": 2
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$campaignAssignment = \AdButler\CampaignAssignment::create(array(
  "active" => true,
  "advertisement" => 
    [
      id => 518889981,
      type => "image_banner"
    ],
  "campaign" => 
    [
      id => 10273,
      type => "banner_campaign"
    ],
  "weight" => 2
));

echo $campaignAssignment;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var postData = {
  "active": true,
  "advertisement": 
    {
      id: 518889981,
      type: "image_banner"
    },
  "campaign": 
    {
      id: 10273,
      type: "banner_campaign"
    },
  "weight": 2
};

// using callbacks
adbutler.campaignAssignments.create(postData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.campaignAssignments.create(postData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "campaign_assignment",
  "self": "/v1/campaign-assignments/8030",
  "id": 8030,
  "active": true,
  "advertisement": {
    "id": 518889981,
    "type": "image_banner"
  },
  "campaign": {
    "id": 10273,
    "type": "banner_campaign"
  },
  "weight": 2
}
AdButler\CampaignAssignment JSON: {
  "object": "campaign_assignment",
  "self": "/v1/campaign-assignments/8030",
  "id": 8030,
  "active": true,
  "advertisement": {
    "id": 518889981,
    "type": "image_banner"
  },
  "campaign": {
    "id": 10273,
    "type": "banner_campaign"
  },
  "weight": 2
}

Creates a new campaign assignment.

Field Type Description

campaign*

string

An object containing banner or text campaign identifier (ID) and type.

advertisement*

object

An object containing image, flash, rich media, or custom HTML banner identifier (ID) and type. The type should correspond to the value of the object field of the corresponding resource.

weight

integer

A number used to determine the serving frequency of an advertisement. This number is used to compute the probability of an ad being served in a particular zone. Defaults to 1 which means every ad has an equal chance of being served. For example, consider three banners assigned to a zone with weights of 1, 4 and 5. The ratio works out to a corresponding probability of 10%, 40% and 50% chance of each banner being served.

active

boolean

Whether to actively serve ads in the zones (true) or pause ad serving (false). Defaults to true.

* = required field

Returns

Returns a campaign_assignment object if the request succeeded, or an error if something went terribly wrong.

Retrieve a campaign assignment

Definition

GET https://api.adbutler.com/v1/campaign-assignments/{CAMPAIGN-ASSIGNMENT-ID}
\AdButler\CampaignAssignment::retrieve()
adbutler.campaignAssignments.retrieve()

Example Request

curl "https://api.adbutler.com/v1/campaign-assignments/8030" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$campaignAssignment = \AdButler\CampaignAssignment::retrieve( 8030 );

echo $campaignAssignment;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.campaignAssignments.read(8030, function(err, response) {
  console.log(response);
});

// using promises
adbutler.campaignAssignments.read(8030).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "campaign_assignment",
  "self": "/v1/campaign-assignments/8030",
  "id": 8030,
  "active": true,
  "advertisement": {
    "id": 518889981,
    "type": "image_banner"
  },
  "campaign": {
    "id": 10273,
    "type": "banner_campaign"
  },
  "weight": 2
}
AdButler\CampaignAssignment JSON: {
  "object": "campaign_assignment",
  "self": "/v1/campaign-assignments/8030",
  "id": 8030,
  "active": true,
  "advertisement": {
    "id": 518889981,
    "type": "image_banner"
  },
  "campaign": {
    "id": 10273,
    "type": "banner_campaign"
  },
  "weight": 2
}

You can retrieve the information about an existing campaign assignment by giving the campaign assignment ID that was returned in the campaign assignment object upon creation. You will see at the most 10 campaign assignments in the response. You can change this default limit by appending ?limit=25 if you want this request to return 25 campaign assignments.

Returns

Returns a campaign_assignment object if the request succeeded, or an error if something went terribly wrong.

Update a campaign assignment

Definition

PUT https://api.adbutler.com/v1/campaign-assignments/{CAMPAIGN-ASSIGNMENT-ID}
\AdButler\CampaignAssignment->save()
adbutler.campaignAssignments.update()

Example Request

curl "https://api.adbutler.com/v1/campaign-assignments/8030" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{  
        "active": true,
        "advertisement": 
                {
                        id: 518889981,
                        type: "image_banner"
                },
        "campaign": 
                {
                        id: 10273,
                        type: "banner_campaign"
                },
        "weight": 2
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$campaignAssignment = \AdButler\CampaignAssignment::retrieve( 8030 );

$campaignAssignment->active = true;
$campaignAssignment->advertisement = 
[
id = 518889981,
type = "image_banner"
];
$campaignAssignment->campaign = 
[
id = 10273,
type = "banner_campaign"
];
$campaignAssignment->weight = 2;

$campaignAssignment->save();

echo $campaignAssignment;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var updateData = {
  "active": true,
  "advertisement": 
    {
      id: 518889981,
      type: "image_banner"
    },
  "campaign": 
    {
      id: 10273,
      type: "banner_campaign"
    },
  "weight": 2
};

// using callbacks
adbutler.campaignAssignments.update(8030, updateData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.campaignAssignments.update(8030, updateData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "campaign_assignment",
  "self": "/v1/campaign-assignments/8030",
  "id": 8030,
  "active": true,
  "advertisement": {
    "id": 518889981,
    "type": "image_banner"
  },
  "campaign": {
    "id": 10273,
    "type": "banner_campaign"
  },
  "weight": 2
}
AdButler\CampaignAssignment JSON: {
  "object": "campaign_assignment",
  "self": "/v1/campaign-assignments/8030",
  "id": 8030,
  "active": true,
  "advertisement": {
    "id": 518889981,
    "type": "image_banner"
  },
  "campaign": {
    "id": 10273,
    "type": "banner_campaign"
  },
  "weight": 2
}

You can update a specific campaign assignment by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the campaign assignment creation request.

Field Type Description

campaign

string

An object containing banner or text campaign identifier (ID) and type.

advertisement

object

An object containing image, flash, rich media, or custom HTML banner identifier (ID) and type. The type should correspond to the value of the object field of the corresponding resource.

weight

integer

A number used to determine the serving frequency of an advertisement. This number is used to compute the probability of an ad being served in a particular zone. Defaults to 1 which means every ad has an equal chance of being served. For example, consider three banners assigned to a zone with weights of 1, 4 and 5. The ratio works out to a corresponding probability of 10%, 40% and 50% chance of each banner being served.

active

boolean

Whether to actively serve ads in the zones (true) or pause ad serving (false). Defaults to true.

Returns

Returns a campaign_assignment object if the request succeeded, or an error if something went terribly wrong.

Delete a campaign assignment

Definition

DELETE https://api.adbutler.com/v1/campaign-assignments/{CAMPAIGN-ASSIGNMENT-ID}
\AdButler\CampaignAssignment->delete()
adbutler.campaignAssignments.delete()

Example Request

curl "https://api.adbutler.com/v1/campaign-assignments/8030" \
  -H "Authorization: Basic {API_KEY}" \
  -X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$campaignAssignment = \AdButler\CampaignAssignment::retrieve( 8030 );
$campaignAssignment->delete();

echo $campaignAssignment;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.campaignAssignments.delete(8030, function(err, response) {
  console.log(response);
});

// using promises
adbutler.campaignAssignments.delete(8030).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "id": 8030,
  "delete": true
}
AdButler\CampaignAssignment JSON: {
  "id": 8030,
  "delete": true
}

Permanently deletes a campaign assignment. If successful, this operation cannot be undone so be very sure when deleting one.

Returns

Returns a campaign_assignment ID if the request succeeded, or an error if something went terribly wrong.

List all campaign assignments

Definition

GET https://api.adbutler.com/v1/campaign-assignments
\AdButler\CampaignAssignment::retrieveAll()
adbutler.campaignAssignments.list()

Example Request

curl "https://api.adbutler.com/v1/campaign-assignments?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$campaignAssignment = \AdButler\CampaignAssignment::retrieveAll(array(
  "limit" => 2
));

echo $campaignAssignment;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.campaignAssignments.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.campaignAssignments.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/campaign-assignment",
  "data": [
    {
      "object": "campaign_assignment",
      "self": "/v1/campaign-assignments/7924",
      "id": 7924,
      "active": true,
      "advertisement": {
        "id": 518889709,
        "type": "image_banner"
      },
      "campaign": {
        "id": 10154,
        "type": "banner_campaign"
      },
      "weight": 1
    },
    {
      "object": "campaign_assignment",
      "self": "/v1/campaign-assignments/7925",
      "id": 7925,
      "active": true,
      "advertisement": {
        "id": 4568,
        "type": "text_ad"
      },
      "campaign": {
        "id": 10155,
        "type": "text_campaign"
      },
      "weight": 1
    }
  ]
}
AdButler\CampaignAssignment JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/campaign-assignment",
  "data": [
    {
      "object": "campaign_assignment",
      "self": "/v1/campaign-assignments/7924",
      "id": 7924,
      "active": true,
      "advertisement": {
        "id": 518889709,
        "type": "image_banner"
      },
      "campaign": {
        "id": 10154,
        "type": "banner_campaign"
      },
      "weight": 1
    },
    {
      "object": "campaign_assignment",
      "self": "/v1/campaign-assignments/7925",
      "id": 7925,
      "active": true,
      "advertisement": {
        "id": 4568,
        "type": "text_ad"
      },
      "campaign": {
        "id": 10155,
        "type": "text_campaign"
      },
      "weight": 1
    }
  ]
}

Returns a list of all the campaign assignments. Most recent campaign assignments appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is a campaign_assignment object, and if no objects were found the list will be empty.


Banners

List all banners

Definition

GET https://api.adbutler.com/v1/banners
\AdButler\Banner::retrieveAll()
adbutler.banners.list()

Example Request

curl "https://api.adbutler.com/v1/banners?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$banner = \AdButler\Banner::retrieveAll(array(
  "limit" => 2
));

echo $banner;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.banners.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.banners.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/banners",
  "data": [
    {
      "object": "image_banner",
      "self": "/v1/banners/image/518889708",
      "id": 518889708,
      "created_date": "2018-06-28 09:48:12",
      "creative": null,
      "creative_url": "https://servedbyadbutler.com.will.test/default_banner.gif",
      "height": 250,
      "html_alt_text": null,
      "html_content_below": null,
      "html_target": null,
      "last_modified": null,
      "location": "https://www.adbutler.com",
      "name": "Default Banner",
      "tracking_pixel": null,
      "width": 300,
      "flexible_type": 0,
      "deleted": false
    },
    {
      "object": "image_banner",
      "self": "/v1/banners/image/518889709",
      "id": 518889709,
      "created_date": "2018-06-28 09:48:12",
      "creative": null,
      "creative_url": "https://servedbyadbutler.com.will.test/default_banner.gif",
      "height": 250,
      "html_alt_text": null,
      "html_content_below": null,
      "html_target": null,
      "last_modified": null,
      "location": "https://www.adbutler.com",
      "name": "Default Banner",
      "tracking_pixel": null,
      "width": 300,
      "flexible_type": 0,
      "deleted": false
    }
  ]
}
AdButler\Banner JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/banners",
  "data": [
    {
      "object": "image_banner",
      "self": "/v1/banners/image/518889708",
      "id": 518889708,
      "created_date": "2018-06-28 09:48:12",
      "creative": null,
      "creative_url": "https://servedbyadbutler.com.will.test/default_banner.gif",
      "height": 250,
      "html_alt_text": null,
      "html_content_below": null,
      "html_target": null,
      "last_modified": null,
      "location": "https://www.adbutler.com",
      "name": "Default Banner",
      "tracking_pixel": null,
      "width": 300,
      "flexible_type": 0,
      "deleted": false
    },
    {
      "object": "image_banner",
      "self": "/v1/banners/image/518889709",
      "id": 518889709,
      "created_date": "2018-06-28 09:48:12",
      "creative": null,
      "creative_url": "https://servedbyadbutler.com.will.test/default_banner.gif",
      "height": 250,
      "html_alt_text": null,
      "html_content_below": null,
      "html_target": null,
      "last_modified": null,
      "location": "https://www.adbutler.com",
      "name": "Default Banner",
      "tracking_pixel": null,
      "width": 300,
      "flexible_type": 0,
      "deleted": false
    }
  ]
}

You can retrieve a list of all the banners regardless of their type. You can optionally restrict the fields that you are interested in retrieving by using the fields query parameter.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is an object, and if no objects were found the list will be empty.


Image Banners

Introduction

Image banners (commonly known as "display ads") are an effective medium for delivering advertising messages across multiple platforms. Easy to setup and configure, you need only a creative and usually a destination URL to which users should be redirected when the ad is clicked on / interacted with.

In general, banners are assigned to an advertiser campaign, and in turn the campaign to a zone. Banners may be assigned to publishers directly if they related directly to that publisher (or are planned to be default/backfill ads).

The image_banner response object has the following fields.

Example Response

{
  "object": "image_banner",
  "self": "/v1/banners/image/518889981",
  "id": 518889981,
  "created_date": "2016-04-29 09:36:35",
  "creative": 1234,
  "creative_url": "http://bla.png",
  "height": 250,
  "html_alt_text": "An image banner",
  "html_content_below": "Hello world",
  "html_target": "http://www",
  "last_modified": "2016-04-30 11:53:35",
  "location": "http://www.bc.com",
  "name": "Demo Image Banner",
  "tracking_pixel": "url",
  "width": 300,
  "flexible_type": 0
}
AdButler\ImageBanner JSON: {
  "object": "image_banner",
  "self": "/v1/banners/image/518889981",
  "id": 518889981,
  "created_date": "2016-04-29 09:36:35",
  "creative": 1234,
  "creative_url": "http://bla.png",
  "height": 250,
  "html_alt_text": "An image banner",
  "html_content_below": "Hello world",
  "html_target": "http://www",
  "last_modified": "2016-04-30 11:53:35",
  "location": "http://www.bc.com",
  "name": "Demo Image Banner",
  "tracking_pixel": "url",
  "width": 300,
  "flexible_type": 0
}
Field Type Description

object

string

A string denoting the object type which is always banner_image for the current resource.

self

string

The relative URL of the current resource which is always of the form /v1/banners-images/{IMAGE_BANNER_ID}.

id

integer

The current resource identifier (ID).

created_date

string

The date and time when this banner was created.

creative

integer

The image creative ID or null.

creative_url

string

The image creative URL or null.

height

integer

The height of the image banner.

html_alt_text

string

Textual description of the image creative intended to be used by the Assistive Technologies.

html_content_below

string

The HTML content that will appear below the image banner.

html_target

string

The window or frame in which the destination URL is displayed.

last_modified

string

The date and time this flash banner was last modified.

location

string

The destination URL where the user will be redirected to when they click on the image banner. A null value denotes no redirection.

name

string

A descriptive name of the image banner.

tracking_pixel

string

An optional third party tracking pixel served with the ad for monitoring impressions. A null value indicates tracking pixel is not being used.

width

integer

The width of the image banner.

flexible_type

integer

The flexible type ID.
Only flexible banners can be assigned to flexible zones / campaigns. Images must be exactly the same dimensions of the max width / max height of the flexible type. POST only, cannot be changed once set.

Create an image banner

Definition

POST https://api.adbutler.com/v1/banners/image
\AdButler\ImageBanner::create()
adbutler.banners.images.create()

Example Request

curl "https://api.adbutler.com/v1/banners/image" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{  
        "creative": 1234,
        "creative_url": "http://bla.png",
        "height": 250,
        "html_alt_text": "An image banner",
        "html_content_below": "Hello world",
        "html_target": "http://www",
        "location": "http://www.bc.com",
        "name": "Demo Image Banner",
        "tracking_pixel": "url",
        "width": 300
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$imageBanner = \AdButler\ImageBanner::create(array(
  "creative" => 1234,
  "creative_url" => "http://bla.png",
  "height" => 250,
  "html_alt_text" => "An image banner",
  "html_content_below" => "Hello world",
  "html_target" => "http://www",
  "location" => "http://www.bc.com",
  "name" => "Demo Image Banner",
  "tracking_pixel" => "url",
  "width" => 300
));

echo $imageBanner;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var postData = {
  "creative": 1234,
  "creative_url": "http://bla.png",
  "height": 250,
  "html_alt_text": "An image banner",
  "html_content_below": "Hello world",
  "html_target": "http://www",
  "location": "http://www.bc.com",
  "name": "Demo Image Banner",
  "tracking_pixel": "url",
  "width": 300
};

// using callbacks
adbutler.banners.images.create(postData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.banners.images.create(postData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "image_banner",
  "self": "/v1/banners/image/518889981",
  "id": 518889981,
  "created_date": "2016-04-29 09:36:35",
  "creative": 1234,
  "creative_url": "http://bla.png",
  "height": 250,
  "html_alt_text": "An image banner",
  "html_content_below": "Hello world",
  "html_target": "http://www",
  "last_modified": "2016-04-30 11:53:35",
  "location": "http://www.bc.com",
  "name": "Demo Image Banner",
  "tracking_pixel": "url",
  "width": 300,
  "flexible_type": 0
}
AdButler\ImageBanner JSON: {
  "object": "image_banner",
  "self": "/v1/banners/image/518889981",
  "id": 518889981,
  "created_date": "2016-04-29 09:36:35",
  "creative": 1234,
  "creative_url": "http://bla.png",
  "height": 250,
  "html_alt_text": "An image banner",
  "html_content_below": "Hello world",
  "html_target": "http://www",
  "last_modified": "2016-04-30 11:53:35",
  "location": "http://www.bc.com",
  "name": "Demo Image Banner",
  "tracking_pixel": "url",
  "width": 300,
  "flexible_type": 0
}

Creates a new image banner.

Field Type Description

name*

string

A descriptive name of the image banner. We recommend using a naming convention that is consistent, relevant, and clear.

width*

integer

The width of the image banner. See Standard Banner Dimensions.

height*

integer

The height of the image banner. See Standard Banner Dimensions.

creative

integer

The image creative identifier (ID). It must be a valid ID if no creative_url is given.

creative_url

integer

Specify the URL of an image file (PNG, JPEG, or GIF). creative must be given if this is left empty.

location

string

A URL indicating where you want the user to go when they click on the banner. This field can be left blank.

tracking_pixel

string

A URL of an image, typically 1x1 pixel in size, intended for impression tracking purposes. It is loaded alongside the banner allowing an external system to monitor impressions.

html_content_below

string

The HTML content to appear below the image banner.

html_alt_text

string

Alternate text information for screen readers. Specify alternate text for an image which shows up in it's place if the image fails to load. The alternate text displayed when the image cannot load, and sometimes if the user is using an accessibility tool such as a screen reader.

html_target

string

Indicate the window/frame the destination URL should load in when clicked. You can use _blank to open the location in the new window, _top to open the location in the same window. You can also use any other suitable value.

* = required field

Returns

Returns an image_banner object if the request succeeded, or an error if something went terribly wrong.

Retrieve an image banner

Definition

GET https://api.adbutler.com/v1/banners/image/{IMAGE-BANNER-ID}
\AdButler\ImageBanner::retrieve()
adbutler.banners.images.retrieve()

Example Request

curl "https://api.adbutler.com/v1/banners/image/518889981" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$imageBanner = \AdButler\ImageBanner::retrieve( 518889981 );

echo $imageBanner;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.banners.images.read(518889981, function(err, response) {
  console.log(response);
});

// using promises
adbutler.banners.images.read(518889981).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "image_banner",
  "self": "/v1/banners/image/518889981",
  "id": 518889981,
  "created_date": "2016-04-29 09:36:35",
  "creative": 1234,
  "creative_url": "http://bla.png",
  "height": 250,
  "html_alt_text": "An image banner",
  "html_content_below": "Hello world",
  "html_target": "http://www",
  "last_modified": "2016-04-30 11:53:35",
  "location": "http://www.bc.com",
  "name": "Demo Image Banner",
  "tracking_pixel": "url",
  "width": 300,
  "flexible_type": 0
}
AdButler\ImageBanner JSON: {
  "object": "image_banner",
  "self": "/v1/banners/image/518889981",
  "id": 518889981,
  "created_date": "2016-04-29 09:36:35",
  "creative": 1234,
  "creative_url": "http://bla.png",
  "height": 250,
  "html_alt_text": "An image banner",
  "html_content_below": "Hello world",
  "html_target": "http://www",
  "last_modified": "2016-04-30 11:53:35",
  "location": "http://www.bc.com",
  "name": "Demo Image Banner",
  "tracking_pixel": "url",
  "width": 300,
  "flexible_type": 0
}

You can retrieve the information about an existing image banner by giving the image banner ID that was returned in the image banner object upon creation. You will see at the most 10 image banners in the response. You can change this default limit by appending ?limit=25 if you want this request to return 25 banners_image.

Returns

Returns an image_banner object if the request succeeded, or an error if something went terribly wrong.

Update an image banner

Definition

PUT https://api.adbutler.com/v1/banners/image/{IMAGE-BANNER-ID}
\AdButler\ImageBanner->save()
adbutler.banners.images.update()

Example Request

curl "https://api.adbutler.com/v1/banners/image/518889981" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{  
        "creative": 1234,
        "creative_url": "http://bla.png",
        "height": 250,
        "html_alt_text": "An image banner",
        "html_content_below": "Hello world",
        "html_target": "http://www",
        "location": "http://www.bc.com",
        "name": "Demo Image Banner",
        "tracking_pixel": "url",
        "width": 300
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$imageBanner = \AdButler\ImageBanner::retrieve( 518889981 );

$imageBanner->creative = 1234;
$imageBanner->creative_url = "http://bla.png";
$imageBanner->height = 250;
$imageBanner->html_alt_text = "An image banner";
$imageBanner->html_content_below = "Hello world";
$imageBanner->html_target = "http://www";
$imageBanner->location = "http://www.bc.com";
$imageBanner->name = "Demo Image Banner";
$imageBanner->tracking_pixel = "url";
$imageBanner->width = 300;

$imageBanner->save();

echo $imageBanner;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var updateData = {
  "creative": 1234,
  "creative_url": "http://bla.png",
  "height": 250,
  "html_alt_text": "An image banner",
  "html_content_below": "Hello world",
  "html_target": "http://www",
  "location": "http://www.bc.com",
  "name": "Demo Image Banner",
  "tracking_pixel": "url",
  "width": 300
};

// using callbacks
adbutler.banners.images.update(518889981, updateData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.banners.images.update(518889981, updateData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "image_banner",
  "self": "/v1/banners/image/518889981",
  "id": 518889981,
  "created_date": "2016-04-29 09:36:35",
  "creative": 1234,
  "creative_url": "http://bla.png",
  "height": 250,
  "html_alt_text": "An image banner",
  "html_content_below": "Hello world",
  "html_target": "http://www",
  "last_modified": "2016-04-30 11:53:35",
  "location": "http://www.bc.com",
  "name": "Demo Image Banner",
  "tracking_pixel": "url",
  "width": 300,
  "flexible_type": 0
}
AdButler\ImageBanner JSON: {
  "object": "image_banner",
  "self": "/v1/banners/image/518889981",
  "id": 518889981,
  "created_date": "2016-04-29 09:36:35",
  "creative": 1234,
  "creative_url": "http://bla.png",
  "height": 250,
  "html_alt_text": "An image banner",
  "html_content_below": "Hello world",
  "html_target": "http://www",
  "last_modified": "2016-04-30 11:53:35",
  "location": "http://www.bc.com",
  "name": "Demo Image Banner",
  "tracking_pixel": "url",
  "width": 300,
  "flexible_type": 0
}

You can update a specific image banner account by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the image banner creation request.

Field Type Description

name

string

A descriptive name of the image banner. We recommend using a naming convention that is consistent, relevant, and clear.

width

integer

The width of the image banner. See Standard Banner Dimensions.

height

integer

The height of the image banner. See Standard Banner Dimensions.

creative

integer

The image creative identifier (ID). It must be a valid ID if no creative_url is given.

creative_url

integer

Specify the URL of an image file (PNG, JPEG, or GIF). creative must be given if this is left empty.

location

string

A URL indicating where you want the user to go when they click on the banner. This field can be left blank.

tracking_pixel

string

A URL of an image, typically 1x1 pixel in size, intended for impression tracking purposes. It is loaded alongside the banner allowing an external system to monitor impressions.

html_content_below

string

The HTML content to appear below the image banner.

html_alt_text

string

Alternate text information for screen readers. Specify alternate text for an image which shows up in it's place if the image fails to load. The alternate text displayed when the image cannot load, and sometimes if the user is using an accessibility tool such as a screen reader.

html_target

string

Indicate the window/frame the destination URL should load in when clicked. You can use _blank to open the location in the new window, _top to open the location in the same window. You can also use any other suitable value.

Returns

Returns an image_banner object if the request succeeded, or an error if something went terribly wrong.

Delete an image banner

Definition

DELETE https://api.adbutler.com/v1/banners/image/{IMAGE-BANNER-ID}
\AdButler\ImageBanner->delete()
adbutler.banners.images.delete()

Example Request

curl "https://api.adbutler.com/v1/banners/image/518889981" \
  -H "Authorization: Basic {API_KEY}" \
  -X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$imageBanner = \AdButler\ImageBanner::retrieve( 518889981 );
$imageBanner->delete();

echo $imageBanner;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.banners.images.delete(518889981, function(err, response) {
  console.log(response);
});

// using promises
adbutler.banners.images.delete(518889981).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "id": 518889981,
  "delete": true
}
AdButler\ImageBanner JSON: {
  "id": 518889981,
  "delete": true
}

Permanently deletes an image banner. if successful, this operation cannot be undone so be very sure when deleting one.

Returns

Returns an image banner ID if the request succeeded, or an error if something went terribly wrong.

List all image banners

Definition

GET https://api.adbutler.com/v1/banners/image
\AdButler\ImageBanner::retrieveAll()
adbutler.banners.images.list()

Example Request

curl "https://api.adbutler.com/v1/banners/image?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$imageBanner = \AdButler\ImageBanner::retrieveAll(array(
  "limit" => 2
));

echo $imageBanner;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.banners.images.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.banners.images.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/banners/image",
  "data": [
    {
      "object": "image_banner",
      "self": "/v1/banners/image/518889708",
      "id": 518889708,
      "created_date": "2018-06-28 09:48:12",
      "creative": null,
      "creative_url": "https://servedbyadbutler.com.will.test/default_banner.gif",
      "height": 250,
      "html_alt_text": null,
      "html_content_below": null,
      "html_target": null,
      "last_modified": null,
      "location": "https://www.adbutler.com",
      "name": "Default Banner",
      "tracking_pixel": null,
      "width": 300,
      "flexible_type": 0
    },
    {
      "object": "image_banner",
      "self": "/v1/banners/image/518889709",
      "id": 518889709,
      "created_date": "2018-06-28 09:48:12",
      "creative": null,
      "creative_url": "https://servedbyadbutler.com.will.test/default_banner.gif",
      "height": 250,
      "html_alt_text": null,
      "html_content_below": null,
      "html_target": null,
      "last_modified": null,
      "location": "https://www.adbutler.com",
      "name": "Default Banner",
      "tracking_pixel": null,
      "width": 300,
      "flexible_type": 0
    }
  ]
}
AdButler\ImageBanner JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/banners/image",
  "data": [
    {
      "object": "image_banner",
      "self": "/v1/banners/image/518889708",
      "id": 518889708,
      "created_date": "2018-06-28 09:48:12",
      "creative": null,
      "creative_url": "https://servedbyadbutler.com.will.test/default_banner.gif",
      "height": 250,
      "html_alt_text": null,
      "html_content_below": null,
      "html_target": null,
      "last_modified": null,
      "location": "https://www.adbutler.com",
      "name": "Default Banner",
      "tracking_pixel": null,
      "width": 300,
      "flexible_type": 0
    },
    {
      "object": "image_banner",
      "self": "/v1/banners/image/518889709",
      "id": 518889709,
      "created_date": "2018-06-28 09:48:12",
      "creative": null,
      "creative_url": "https://servedbyadbutler.com.will.test/default_banner.gif",
      "height": 250,
      "html_alt_text": null,
      "html_content_below": null,
      "html_target": null,
      "last_modified": null,
      "location": "https://www.adbutler.com",
      "name": "Default Banner",
      "tracking_pixel": null,
      "width": 300,
      "flexible_type": 0
    }
  ]
}

Returns a list of all the image banners. Most recent image banners appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is an image_banner object, and if no objects were found the list will be empty.

Retrieve image banner conversion tag

Definition

GET https://api.adbutler.com/v1/banners/image/{IMAGE-BANNER-ID}/conversion-tag
\AdButler\ImageBannerConvTag::retrieve()
adbutler.banners.images.conversionTag.retrieve()

Example Request

curl "https://api.adbutler.com/v1/banners/image/ID/conversion-tag/518889981" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$imageBannerConvTag = \AdButler\ImageBannerConvTag::retrieve( 518889981 );

echo $imageBannerConvTag;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.banners.images.conversionTag.read(518889981, function(err, response) {
  console.log(response);
});

// using promises
adbutler.banners.images.conversionTag.read(518889981).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Retrieves an HTML tag which can be used to track conversions for the provided banner.

Query Parameters

Parameter Description

protocol

Whether to use http or https protocol when serving the advertisements. Use https only if you are using secure pages because it does not support Custom Domains.

Returns

Example Response

{
  "object": "conv_tag",
  "url": "/v1/banners/image/518889981/conversion-tag",
  "data": {
    "src": "https://servedbyadbutler.com.vm.test/convtrack.spark?MID=108607&BID=518889981",
    "html": "<img src='https://servedbyadbutler.com.vm.test/convtrack.spark?MID=108607&BID=518889981' width='1' height='1' border='0' />"
  }
}
AdButler\ImageBannerConvTag JSON: {
  "object": "conv_tag",
  "url": "/v1/banners/image/518889981/conversion-tag",
  "data": {
    "src": "https://servedbyadbutler.com.vm.test/convtrack.spark?MID=108607&BID=518889981",
    "html": "<img src='https://servedbyadbutler.com.vm.test/convtrack.spark?MID=108607&BID=518889981' width='1' height='1' border='0' />"
  }
}
Field Type Description

object

string

A string denoting the object type which is always conv_tag for the current resource.

url

string

The relative URL of the current resource which is always of the form /v1/banners/image/{IMAGE_BANNER_ID}/conversion-tag.

data

array

The data object containing the conversion tag.

 

Returns a conv_tag object if the request succeeded, or an error if something went terribly wrong.


Flash Banners

Introduction

Flash banners are a legacy rich media format, often used to deliver interactive and animated advertising to users directly in their browsers. These ads are rendered by a browser plugin, and can be a useful way to capture user interest.

More recently, however, Flash has fallen out of favour and is being replaced by HTML5 Rich Media ads.

In general, banners are assigned to an advertiser campaign, and in turn the campaign to a zone. Banners may be assigned to publishers directly if they related directly to that publisher (or are planned to be default/backfill ads).

The flash_banner response object has the following fields.

Example Response

{
  "object": "flash_banner",
  "self": "/v1/banners/flash/518889982",
  "id": 518889982,
  "created_date": "2016-04-29 09:36:35",
  "creative": 1234,
  "creative_url": "http://bla.swf",
  "height": 250,
  "html_content_below": "Hello world",
  "last_modified": "2016-04-30 11:53:35",
  "location": "http://www.google.ca",
  "mode": "transparent",
  "name": "Demo Flash Banner",
  "quality": "high",
  "tracking_pixel": "url",
  "version": "11",
  "width": 300
}
AdButler\FlashBanner JSON: {
  "object": "flash_banner",
  "self": "/v1/banners/flash/518889982",
  "id": 518889982,
  "created_date": "2016-04-29 09:36:35",
  "creative": 1234,
  "creative_url": "http://bla.swf",
  "height": 250,
  "html_content_below": "Hello world",
  "last_modified": "2016-04-30 11:53:35",
  "location": "http://www.google.ca",
  "mode": "transparent",
  "name": "Demo Flash Banner",
  "quality": "high",
  "tracking_pixel": "url",
  "version": 11,
  "width": 300
}
Field Type Description

object

string

A string denoting the object type which is always banner_flash for the current resource.

self

string

The relative URL of the current resource which is always of the form /v1/banners-flash/{FLASH_BANNER_ID}.

id

integer

The current resource identifier (ID).

created_date

string

The date and time when this account was created.

creative

integer

The flash creative ID or null.

creative_url

string

The flash creative URL or null.

mode

string

The window mode property of the flash file for transparency, layering, positioning, and rendering in the browser.

quality

string

The quality of the flash image or movie.

version

string

The version of the flash player ranging between 5 and 100.

height

integer

The height of the image banner.

html_content_below

string

The HTML content that will appear below the flash banner.

last_modified

string

The date and time this flash banner was last modified.

location

string

The destination URL where the user will be redirected to when they click on the image banner. A null value denotes no redirection.

name

string

A descriptive name of the image banner (for internal use only).

tracking_pixel

string

An optional third party tracking pixel served with the ad for monitoring impressions. A null value indicates tracking pixel is not being used.

width

integer

The width of the flash banner.

Create a flash Banner

Definition

POST https://api.adbutler.com/v1/banners/flash
\AdButler\FlashBanner::create()
adbutler.banners.flash.create()

Example Request

curl "https://api.adbutler.com/v1/banners/flash" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{  
        "creative": 1234,
        "creative_url": "http://bla.swf",
        "height": 250,
        "html_content_below": "Hello world",
        "location": "http://www.google.ca",
        "mode": "transparent",
        "name": "Demo Flash Banner",
        "quality": "high",
        "tracking_pixel": "url",
        "version": "11",
        "width": 300
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$flashBanner = \AdButler\FlashBanner::create(array(
  "creative" => 1234,
  "creative_url" => "http://bla.swf",
  "height" => 250,
  "html_content_below" => "Hello world",
  "location" => "http://www.google.ca",
  "mode" => "transparent",
  "name" => "Demo Flash Banner",
  "quality" => "high",
  "tracking_pixel" => "url",
  "version" => "11",
  "width" => 300
));

echo $flashBanner;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var postData = {
  "creative": 1234,
  "creative_url": "http://bla.swf",
  "height": 250,
  "html_content_below": "Hello world",
  "location": "http://www.google.ca",
  "mode": "transparent",
  "name": "Demo Flash Banner",
  "quality": "high",
  "tracking_pixel": "url",
  "version": "11",
  "width": 300
};

// using callbacks
adbutler.banners.flash.create(postData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.banners.flash.create(postData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "flash_banner",
  "self": "/v1/banners/flash/518889982",
  "id": 518889982,
  "created_date": "2016-04-29 09:36:35",
  "creative": 1234,
  "creative_url": "http://bla.swf",
  "height": 250,
  "html_content_below": "Hello world",
  "last_modified": "2016-04-30 11:53:35",
  "location": "http://www.google.ca",
  "mode": "transparent",
  "name": "Demo Flash Banner",
  "quality": "high",
  "tracking_pixel": "url",
  "version": "11",
  "width": 300
}
AdButler\FlashBanner JSON: {
  "object": "flash_banner",
  "self": "/v1/banners/flash/518889982",
  "id": 518889982,
  "created_date": "2016-04-29 09:36:35",
  "creative": 1234,
  "creative_url": "http://bla.swf",
  "height": 250,
  "html_content_below": "Hello world",
  "last_modified": "2016-04-30 11:53:35",
  "location": "http://www.google.ca",
  "mode": "transparent",
  "name": "Demo Flash Banner",
  "quality": "high",
  "tracking_pixel": "url",
  "version": 11,
  "width": 300
}

Creates a new flash banner.

Field Type Description

name*

string

A descriptive name of the flash banner. We recommend using a naming convention that is consistent, relevant, and clear.

width*

string

The width of the image banner. See Standard Banner Dimensions.

height*

string

The height of the image banner. See Standard Banner Dimensions.

creative*

string

The flash creative identifier (ID). It must be a valid ID if no creative_url is given.

creative_url*

string

Specify the URL of a flash (SWF) file. creative must be given if this is left empty.

location

string

A URL indicating where you want the user to go when they click on the banner. This field can be left blank.

tracking_pixel

string

A URL of an image, typically 1x1 pixel in size, intended for impression tracking purposes. It is loaded alongside the banner allowing an external system to monitor impressions.

html_content_below

string

The HTML content to appear below the flash banner.

mode

string

Sets the window mode property of the SWF file for transparency, layering, positioning, and rendering in the browser. It can be one of window, opaque, or transparent.

  • Window: The SWF content plays in its own rectangle ("window") on a web page. You cannot explicitly specify if SWF content appears above or below other HTML elements on the page.
  • Opaque: The SWF content is layered together with other HTML elements on the page. The SWF file is opaque and hides everything layered behind it on the page. This option reduces playback performance compared to the window mode.
  • Transparent: The SWF content is layered together with other HTML elements on the page. The SWF file background color is transparent. HTML elements beneath the SWF file are visible through any transparent areas of the SWF. This option reduces playback performance compared to the window mode.

More information can be found here.

quality

string

Possible values are low, medium, or high.

  • Low favors playback speed over appearance and never uses anti-aliasing.
  • Medium applies some anti-aliasing and does not smooth bitmaps.
  • High favors appearance over playback speed and always applies anti-aliasing. If the movie has animation, bitmaps are not smoothed.

More information can be found here.

version

string

Flash version number between 5 and 100.

* = required field

Returns

Returns a flash_banner object if the request succeeded, or an error if something went terribly wrong.

Retrieve a flash Banner

Definition

GET https://api.adbutler.com/v1/banners/flash/{FLASH-BANNER-ID}
\AdButler\FlashBanner::retrieve()
adbutler.banners.flash.retrieve()

Example Request

curl "https://api.adbutler.com/v1/banners/flash/518889982" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$flashBanner = \AdButler\FlashBanner::retrieve( 518889982 );

echo $flashBanner;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.banners.flash.read(518889982, function(err, response) {
  console.log(response);
});

// using promises
adbutler.banners.flash.read(518889982).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "flash_banner",
  "self": "/v1/banners/flash/518889982",
  "id": 518889982,
  "created_date": "2016-04-29 09:36:35",
  "creative": 1234,
  "creative_url": "http://bla.swf",
  "height": 250,
  "html_content_below": "Hello world",
  "last_modified": "2016-04-30 11:53:35",
  "location": "http://www.google.ca",
  "mode": "transparent",
  "name": "Demo Flash Banner",
  "quality": "high",
  "tracking_pixel": "url",
  "version": "11",
  "width": 300
}
AdButler\FlashBanner JSON: {
  "object": "flash_banner",
  "self": "/v1/banners/flash/518889982",
  "id": 518889982,
  "created_date": "2016-04-29 09:36:35",
  "creative": 1234,
  "creative_url": "http://bla.swf",
  "height": 250,
  "html_content_below": "Hello world",
  "last_modified": "2016-04-30 11:53:35",
  "location": "http://www.google.ca",
  "mode": "transparent",
  "name": "Demo Flash Banner",
  "quality": "high",
  "tracking_pixel": "url",
  "version": 11,
  "width": 300
}

You can retrieve the information about an existing flash banner by giving the flash banner ID that was returned in the flash banner object upon creation. You will see at the most 10 flash banners in the response. You can change this default limit by appending ?limit=25 if you want this request to return 25 banners_flash.

Returns

Returns a flash_banner object if the request succeeded, or an error if something went terribly wrong.

Update a flash Banner

Definition

PUT https://api.adbutler.com/v1/banners/flash/{FLASH-BANNER-ID}
\AdButler\FlashBanner->save()
adbutler.banners.flash.update()

Example Request

curl "https://api.adbutler.com/v1/banners/flash/518889982" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{  
        "creative": 1234,
        "creative_url": "http://bla.swf",
        "height": 250,
        "html_content_below": "Hello world",
        "location": "http://www.google.ca",
        "mode": "transparent",
        "name": "Demo Flash Banner",
        "quality": "high",
        "tracking_pixel": "url",
        "version": "11",
        "width": 300
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$flashBanner = \AdButler\FlashBanner::retrieve( 518889982 );

$flashBanner->creative = 1234;
$flashBanner->creative_url = "http://bla.swf";
$flashBanner->height = 250;
$flashBanner->html_content_below = "Hello world";
$flashBanner->location = "http://www.google.ca";
$flashBanner->mode = "transparent";
$flashBanner->name = "Demo Flash Banner";
$flashBanner->quality = "high";
$flashBanner->tracking_pixel = "url";
$flashBanner->version = "11";
$flashBanner->width = 300;

$flashBanner->save();

echo $flashBanner;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var updateData = {
  "creative": 1234,
  "creative_url": "http://bla.swf",
  "height": 250,
  "html_content_below": "Hello world",
  "location": "http://www.google.ca",
  "mode": "transparent",
  "name": "Demo Flash Banner",
  "quality": "high",
  "tracking_pixel": "url",
  "version": "11",
  "width": 300
};

// using callbacks
adbutler.banners.flash.update(518889982, updateData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.banners.flash.update(518889982, updateData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "flash_banner",
  "self": "/v1/banners/flash/518889982",
  "id": 518889982,
  "created_date": "2016-04-29 09:36:35",
  "creative": 1234,
  "creative_url": "http://bla.swf",
  "height": 250,
  "html_content_below": "Hello world",
  "last_modified": "2016-04-30 11:53:35",
  "location": "http://www.google.ca",
  "mode": "transparent",
  "name": "Demo Flash Banner",
  "quality": "high",
  "tracking_pixel": "url",
  "version": "11",
  "width": 300
}
AdButler\FlashBanner JSON: {
  "object": "flash_banner",
  "self": "/v1/banners/flash/518889982",
  "id": 518889982,
  "created_date": "2016-04-29 09:36:35",
  "creative": 1234,
  "creative_url": "http://bla.swf",
  "height": 250,
  "html_content_below": "Hello world",
  "last_modified": "2016-04-30 11:53:35",
  "location": "http://www.google.ca",
  "mode": "transparent",
  "name": "Demo Flash Banner",
  "quality": "high",
  "tracking_pixel": "url",
  "version": 11,
  "width": 300
}

You can update a specific flash banner account by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the flash banner creation request.

Field Type Description

name

string

A descriptive name of the flash banner. We recommend using a naming convention that is consistent, relevant, and clear.

width

string

The width of the image banner. See Standard Banner Dimensions.

height

string

The height of the image banner. See Standard Banner Dimensions.

creative

string

The flash creative identifier (ID). It must be a valid ID if no creative_url is given.

creative_url

string

Specify the URL of a flash (SWF) file. creative must be given if this is left empty.

location

string

A URL indicating where you want the user to go when they click on the banner. This field can be left blank.

tracking_pixel

string

A URL of an image, typically 1x1 pixel in size, intended for impression tracking purposes. It is loaded alongside the banner allowing an external system to monitor impressions.

html_content_below

string

The HTML content to appear below the flash banner.

mode

string

Sets the window mode property of the SWF file for transparency, layering, positioning, and rendering in the browser. It can be one of window, opaque, or transparent.

  • Window: The SWF content plays in its own rectangle ("window") on a web page. You cannot explicitly specify if SWF content appears above or below other HTML elements on the page.
  • Opaque: The SWF content is layered together with other HTML elements on the page. The SWF file is opaque and hides everything layered behind it on the page. This option reduces playback performance compared to the window mode.
  • Transparent: The SWF content is layered together with other HTML elements on the page. The SWF file background color is transparent. HTML elements beneath the SWF file are visible through any transparent areas of the SWF. This option reduces playback performance compared to the window mode.

More information can be found here.

quality

string

Possible values are low, medium, or high.

  • Low favors playback speed over appearance and never uses anti-aliasing.
  • Medium applies some anti-aliasing and does not smooth bitmaps.
  • High favors appearance over playback speed and always applies anti-aliasing. If the movie has animation, bitmaps are not smoothed.

More information can be found here.

version

string

Flash version number between 5 and 100.

Returns

Returns a flash_banner object if the request succeeded, or an error if something went terribly wrong.

Delete a flash Banner

Definition

DELETE https://api.adbutler.com/v1/banners/flash/{FLASH-BANNER-ID}
\AdButler\FlashBanner->delete()
adbutler.banners.flash.delete()

Example Request

curl "https://api.adbutler.com/v1/banners/flash/518889982" \
  -H "Authorization: Basic {API_KEY}" \
  -X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$flashBanner = \AdButler\FlashBanner::retrieve( 518889982 );
$flashBanner->delete();

echo $flashBanner;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.banners.flash.delete(518889982, function(err, response) {
  console.log(response);
});

// using promises
adbutler.banners.flash.delete(518889982).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "id": 518889982,
  "delete": true
}
AdButler\FlashBanner JSON: {
  "id": 518889982,
  "delete": true
}

Permanently deletes a flash Banner. if successful, this operation cannot be undone so be very sure when deleting one.

Returns

Returns a flash banner ID if the request succeeded, or an error if something went terribly wrong.

List all flash banners

Definition

GET https://api.adbutler.com/v1/banners/flash
\AdButler\FlashBanner::retrieveAll()
adbutler.banners.flash.list()

Example Request

curl "https://api.adbutler.com/v1/banners/flash?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$flashBanner = \AdButler\FlashBanner::retrieveAll(array(
  "limit" => 2
));

echo $flashBanner;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.banners.flash.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.banners.flash.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/banners/flash",
  "data": [
    {
      "object": "flash_banner",
      "self": "/v1/banners/flash/518889711",
      "id": 518889711,
      "created_date": "2016-04-29 09:36:35",
      "creative": 1234,
      "creative_url": "http://bla.swf",
      "height": 250,
      "html_content_below": "Hello world",
      "last_modified": "2016-04-30 11:53:35",
      "location": "http://www.google.ca",
      "mode": "transparent",
      "name": "Demo Flash Banner",
      "quality": "high",
      "tracking_pixel": "url",
      "version": "11",
      "width": 300
    },
    {
      "object": "flash_banner",
      "self": "/v1/banners/flash/518889715",
      "id": 518889715,
      "created_date": "2016-04-29 09:36:35",
      "creative": 1234,
      "creative_url": "http://bla.swf",
      "height": 250,
      "html_content_below": "Hello world",
      "last_modified": "2016-04-30 11:53:35",
      "location": "http://www.google.ca",
      "mode": "transparent",
      "name": "Demo Flash Banner",
      "quality": "high",
      "tracking_pixel": "url",
      "version": "11",
      "width": 300
    }
  ]
}
AdButler\FlashBanner JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/banners/flash",
  "data": [
    {
      "object": "flash_banner",
      "self": "/v1/banners/flash/518889711",
      "id": 518889711,
      "created_date": "2016-04-29 09:36:35",
      "creative": 1234,
      "creative_url": "http://bla.swf",
      "height": 250,
      "html_content_below": "Hello world",
      "last_modified": "2016-04-30 11:53:35",
      "location": "http://www.google.ca",
      "mode": "transparent",
      "name": "Demo Flash Banner",
      "quality": "high",
      "tracking_pixel": "url",
      "version": 11,
      "width": 300
    },
    {
      "object": "flash_banner",
      "self": "/v1/banners/flash/518889715",
      "id": 518889715,
      "created_date": "2016-04-29 09:36:35",
      "creative": 1234,
      "creative_url": "http://bla.swf",
      "height": 250,
      "html_content_below": "Hello world",
      "last_modified": "2016-04-30 11:53:35",
      "location": "http://www.google.ca",
      "mode": "transparent",
      "name": "Demo Flash Banner",
      "quality": "high",
      "tracking_pixel": "url",
      "version": 11,
      "width": 300
    }
  ]
}

Returns a list of all the flash banners. Most recent flash banners appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is a flash_banner object, and if no objects were found the list will be empty.

Retrieve flash banner conversion tag

Definition

GET https://api.adbutler.com/v1/banners/flash/{FLASH-BANNER-ID}/conversion-tag
\AdButler\FlashBannerConvTag::retrieve()
adbutler.campaigns.conversionTag.retrieve()

Example Request

curl "https://api.adbutler.com/v1/banners/flash/ID/conversion-tag/518889982" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$flashBannerConvTag = \AdButler\FlashBannerConvTag::retrieve( 518889982 );

echo $flashBannerConvTag;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.campaigns.conversionTag.read(518889982, function(err, response) {
  console.log(response);
});

// using promises
adbutler.campaigns.conversionTag.read(518889982).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Retrieves an HTML tag which can be used to track conversions for the provided banner.

Query Parameters

Parameter Description

protocol

Whether to use http or https protocol when serving the advertisements. Use https only if you are using secure pages because it does not support Custom Domains.

Returns

Example Response

{
  "object": "conv_tag",
  "url": "/v1/banners/flash/518889982/conversion-tag",
  "data": {
    "src": "https://servedbyadbutler.com.vm.test/convtrack.spark?MID=108607&BID=518889982",
    "html": "<img src='https://servedbyadbutler.com.vm.test/convtrack.spark?MID=108607&BID=518889982' width='1' height='1' border='0' />"
  }
}
AdButler\FlashBannerConvTag JSON: {
  "object": "conv_tag",
  "url": "/v1/banners/flash/518889982/conversion-tag",
  "data": {
    "src": "https://servedbyadbutler.com.vm.test/convtrack.spark?MID=108607&BID=518889982",
    "html": "<img src='https://servedbyadbutler.com.vm.test/convtrack.spark?MID=108607&BID=518889982' width='1' height='1' border='0' />"
  }
}
Field Type Description

object

string

A string denoting the object type which is always conv_tag for the current resource.

url

string

The relative URL of the current resource which is always of the form /v1/banners/flash/{FLASH_BANNER_ID}/conversion-tag.

data

array

The data object containing the conversion tag.

 

Returns a conv_tag object if the request succeeded, or an error if something went terribly wrong.


Rich Media Banners

Introduction

HTML5 Rich Media banners allow you to serve dynamic, interactive, animated advertisements through IFRAME elements in a secure environment. These IAB compatible HTML5 ads are typically uploaded as ZIP archives and include HTML, scripts, styles and media files as a self-contained package.

In general, banners are assigned to an advertiser campaign, and in turn the campaign to a zone. Banners may be assigned to publishers directly if they related directly to that publisher (or are planned to be default/backfill ads).

Banners are usually associated with advertiser campaigns, but may also be assigned to publishers directly.

The rich_media_banner response object has the following fields.

Example Response

{
  "object": "rich_media_banner",
  "self": "/v1/banners/rich-media/518889783",
  "id": 518889783,
  "created_date": "2016-04-29 09:36:35",
  "creative": 4321,
  "expand_horizontal_direction": "right",
  "expand_vertical_direction": "up",
  "height": 250,
  "html_content_below": "Hello world",
  "html_path": null,
  "last_modified": "2016-04-30 11:53:35",
  "location": "http://www.google.ca",
  "name": "Demo Rich Media Banner",
  "width": 300,
  "tracking_pixel": "url"
}
AdButler\RichMediaBanner JSON: {
  "object": "rich_media_banner",
  "self": "/v1/banners/rich-media/518889783",
  "id": 518889783,
  "created_date": "2016-04-29 09:36:35",
  "creative": 4321,
  "expand_horizontal_direction": "right",
  "expand_vertical_direction": "up",
  "height": 250,
  "html_content_below": "Hello world",
  "html_path": null,
  "last_modified": "2016-04-30 11:53:35",
  "location": "http://www.google.ca",
  "name": "Demo Rich Media Banner",
  "width": 300,
  "tracking_pixel": "url"
}
Field Type Description

object

string

A string denoting the object type which is always rich_media_banner for the current resource.

self

string

The relative URL of the current resource which is always of the form /v1/banners/rich-media/{RICH_MEDIA_BANNER_ID}.

id

integer

The current resource identifier (ID).

created_date

string

The date and time when this banner was created.

creative

integer

The rich media creative identifier (ID).

expand_horizontal_direction

string

The rich media expansion in the horizontal direction.

expand_vertical_direction

string

The rich media expansion in the vertical direction.

height

integer

The height of the rich media banner

html_content_below

string

The HTML content that will appear below the rich media banner.

html_path

NULL

The relative path to the HTML file contained in the rich media creative.

last_modified

string

The date and time this banner was last modified.

location

string

The destination URL where the user will be redirected to when they click on the rich media banner. A null value denotes no redirection.

name

string

A descriptive name of the rich media banner.

width

integer

The width of the rich media banner.

tracking_pixel

string

A URL string of the third party tracking pixel for monitoring impressions. A null value indicates tracking pixel is not being used.

Create a rich media banner

Definition

POST https://api.adbutler.com/v1/banners/rich-media
\AdButler\RichMediaBanner::create()
adbutler.banners.richMedia.create()

Example Request

curl "https://api.adbutler.com/v1/banners/rich-media" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{  
        "creative": 4321,
        "expand_horizontal_direction": "right",
        "expand_vertical_direction": "up",
        "height": 250,
        "html_content_below": "Hello world",
        "html_path": null,
        "location": "http://www.google.ca",
        "name": "Demo Rich Media Banner",
        "width": 300,
        "tracking_pixel": "url"
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$richMediaBanner = \AdButler\RichMediaBanner::create(array(
  "creative" => 4321,
  "expand_horizontal_direction" => "right",
  "expand_vertical_direction" => "up",
  "height" => 250,
  "html_content_below" => "Hello world",
  "html_path" => null,
  "location" => "http://www.google.ca",
  "name" => "Demo Rich Media Banner",
  "width" => 300,
  "tracking_pixel" => "url"
));

echo $richMediaBanner;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var postData = {
  "creative": 4321,
  "expand_horizontal_direction": "right",
  "expand_vertical_direction": "up",
  "height": 250,
  "html_content_below": "Hello world",
  "html_path": null,
  "location": "http://www.google.ca",
  "name": "Demo Rich Media Banner",
  "width": 300,
  "tracking_pixel": "url"
};

// using callbacks
adbutler.banners.richMedia.create(postData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.banners.richMedia.create(postData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "rich_media_banner",
  "self": "/v1/banners/rich-media/518889783",
  "id": 518889783,
  "created_date": "2016-04-29 09:36:35",
  "creative": 4321,
  "expand_horizontal_direction": "right",
  "expand_vertical_direction": "up",
  "height": 250,
  "html_content_below": "Hello world",
  "html_path": null,
  "last_modified": "2016-04-30 11:53:35",
  "location": "http://www.google.ca",
  "name": "Demo Rich Media Banner",
  "width": 300,
  "tracking_pixel": "url"
}
AdButler\RichMediaBanner JSON: {
  "object": "rich_media_banner",
  "self": "/v1/banners/rich-media/518889783",
  "id": 518889783,
  "created_date": "2016-04-29 09:36:35",
  "creative": 4321,
  "expand_horizontal_direction": "right",
  "expand_vertical_direction": "up",
  "height": 250,
  "html_content_below": "Hello world",
  "html_path": null,
  "last_modified": "2016-04-30 11:53:35",
  "location": "http://www.google.ca",
  "name": "Demo Rich Media Banner",
  "width": 300,
  "tracking_pixel": "url"
}

Creates a new rich media banner.

Field Type Description

name*

string

A descriptive name of the rich media banner. We recommend using a naming convention that is consistent, relevant, and clear.

width*

integer

The width of the rich media banner. See Standard Banner Dimensions.

height*

integer

The height of the rich media banner. See Standard Banner Dimensions.

creative*

integer

The rich media creative identifier (ID).

location

string

A URL indicating where you want the user to go when they click on the banner. This field can be left blank.

tracking_pixel

string

A URL of an image, typically 1x1 pixel in size, intended for impression tracking purposes. It is loaded alongside the banner allowing an external system to monitor impressions.

html_content_below

string

The HTML content to appear below the image banner.

html_path

string

The relative path to the HTML file contained in the rich media creative.

expand_horizontal_direction

string

Whether to allow the rich media banner to expand in the horizontal direction. The value can be none, left, or rigth.

expand_vertical_direction

string

Whether to allow the rich media banner to expand in the vertical direction. The value can be none, up, or down.

* = required field

Returns

Returns a rich_media_banner object if the request succeeded, or an error if something went terribly wrong.

Retrieve a rich media banner

Definition

GET https://api.adbutler.com/v1/banners/rich-media/{RICH-MEDIA-BANNER-ID}
\AdButler\RichMediaBanner::retrieve()
adbutler.banners.richMedia.retrieve()

Example Request

curl "https://api.adbutler.com/v1/banners/rich-media/518889783" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$richMediaBanner = \AdButler\RichMediaBanner::retrieve( 518889783 );

echo $richMediaBanner;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.banners.richMedia.read(518889783, function(err, response) {
  console.log(response);
});

// using promises
adbutler.banners.richMedia.read(518889783).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "rich_media_banner",
  "self": "/v1/banners/rich-media/518889783",
  "id": 518889783,
  "created_date": "2016-04-29 09:36:35",
  "creative": 4321,
  "expand_horizontal_direction": "right",
  "expand_vertical_direction": "up",
  "height": 250,
  "html_content_below": "Hello world",
  "html_path": null,
  "last_modified": "2016-04-30 11:53:35",
  "location": "http://www.google.ca",
  "name": "Demo Rich Media Banner",
  "width": 300,
  "tracking_pixel": "url"
}
AdButler\RichMediaBanner JSON: {
  "object": "rich_media_banner",
  "self": "/v1/banners/rich-media/518889783",
  "id": 518889783,
  "created_date": "2016-04-29 09:36:35",
  "creative": 4321,
  "expand_horizontal_direction": "right",
  "expand_vertical_direction": "up",
  "height": 250,
  "html_content_below": "Hello world",
  "html_path": null,
  "last_modified": "2016-04-30 11:53:35",
  "location": "http://www.google.ca",
  "name": "Demo Rich Media Banner",
  "width": 300,
  "tracking_pixel": "url"
}

You can retrieve the information about an existing rich media banner by giving the rich media banner ID that was returned in the rich media banner object upon creation. You will see at the most 10 rich media banners in the response. You can change this default limit by appending ?limit=25 if you want this request to return 25 banners_rich-media.

Returns

Returns a rich_media_banner object if the request succeeded, or an error if something went terribly wrong.

Update a rich media banner

Definition

PUT https://api.adbutler.com/v1/banners/rich-media/{RICH-MEDIA-BANNER-ID}
\AdButler\RichMediaBanner->save()
adbutler.banners.richMedia.update()

Example Request

curl "https://api.adbutler.com/v1/banners/rich-media/518889783" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{  
        "creative": 4321,
        "expand_horizontal_direction": "right",
        "expand_vertical_direction": "up",
        "height": 250,
        "html_content_below": "Hello world",
        "html_path": null,
        "location": "http://www.google.ca",
        "name": "Demo Rich Media Banner",
        "width": 300,
        "tracking_pixel": "url"
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$richMediaBanner = \AdButler\RichMediaBanner::retrieve( 518889783 );

$richMediaBanner->creative = 4321;
$richMediaBanner->expand_horizontal_direction = "right";
$richMediaBanner->expand_vertical_direction = "up";
$richMediaBanner->height = 250;
$richMediaBanner->html_content_below = "Hello world";
$richMediaBanner->html_path = null;
$richMediaBanner->location = "http://www.google.ca";
$richMediaBanner->name = "Demo Rich Media Banner";
$richMediaBanner->width = 300;
$richMediaBanner->tracking_pixel = "url";

$richMediaBanner->save();

echo $richMediaBanner;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var updateData = {
  "creative": 4321,
  "expand_horizontal_direction": "right",
  "expand_vertical_direction": "up",
  "height": 250,
  "html_content_below": "Hello world",
  "html_path": null,
  "location": "http://www.google.ca",
  "name": "Demo Rich Media Banner",
  "width": 300,
  "tracking_pixel": "url"
};

// using callbacks
adbutler.banners.richMedia.update(518889783, updateData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.banners.richMedia.update(518889783, updateData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "rich_media_banner",
  "self": "/v1/banners/rich-media/518889783",
  "id": 518889783,
  "created_date": "2016-04-29 09:36:35",
  "creative": 4321,
  "expand_horizontal_direction": "right",
  "expand_vertical_direction": "up",
  "height": 250,
  "html_content_below": "Hello world",
  "html_path": null,
  "last_modified": "2016-04-30 11:53:35",
  "location": "http://www.google.ca",
  "name": "Demo Rich Media Banner",
  "width": 300,
  "tracking_pixel": "url"
}
AdButler\RichMediaBanner JSON: {
  "object": "rich_media_banner",
  "self": "/v1/banners/rich-media/518889783",
  "id": 518889783,
  "created_date": "2016-04-29 09:36:35",
  "creative": 4321,
  "expand_horizontal_direction": "right",
  "expand_vertical_direction": "up",
  "height": 250,
  "html_content_below": "Hello world",
  "html_path": null,
  "last_modified": "2016-04-30 11:53:35",
  "location": "http://www.google.ca",
  "name": "Demo Rich Media Banner",
  "width": 300,
  "tracking_pixel": "url"
}

You can update a specific rich media banner account by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the reqeust. The update request accepts mostly the same arguments as the rich media banner creation request.

Field Type Description

name

string

A descriptive name of the rich media banner. We recommend using a naming convention that is consistent, relevant, and clear.

width

integer

The width of the rich media banner. See Standard Banner Dimensions.

height

integer

The height of the rich media banner. See Standard Banner Dimensions.

creative

integer

The rich media creative identifier (ID).

location

string

A URL indicating where you want the user to go when they click on the banner. This field can be left blank.

tracking_pixel

string

A URL of an image, typically 1x1 pixel in size, intended for impression tracking purposes. It is loaded alongside the banner allowing an external system to monitor impressions.

html_content_below

string

The HTML content to appear below the image banner.

html_path

string

The relative path to the HTML file contained in the rich media creative.

expand_horizontal_direction

string

Whether to allow the rich media banner to expand in the horizontal direction. The value can be none, left, or rigth.

expand_vertical_direction

string

Whether to allow the rich media banner to expand in the vertical direction. The value can be none, up, or down.

Returns

Returns a rich_media_banner object if the request succeeded, or an error if something went terribly wrong.

Delete a rich media banner

Definition

DELETE https://api.adbutler.com/v1/banners/rich-media/{RICH-MEDIA-BANNER-ID}
\AdButler\RichMediaBanner->delete()
adbutler.banners.richMedia.delete()

Example Request

curl "https://api.adbutler.com/v1/banners/rich-media/518889783" \
  -H "Authorization: Basic {API_KEY}" \
  -X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$richMediaBanner = \AdButler\RichMediaBanner::retrieve( 518889783 );
$richMediaBanner->delete();

echo $richMediaBanner;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.banners.richMedia.delete(518889783, function(err, response) {
  console.log(response);
});

// using promises
adbutler.banners.richMedia.delete(518889783).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "id": 518889783,
  "delete": true
}
AdButler\RichMediaBanner JSON: {
  "id": 518889783,
  "delete": true
}

Permanently deletes a rich media banner. if successful, this operation cannot be undone so be very sure when deleting one. Also immediately stops serving any ads belonging to this rich media banner account.

Returns

Returns a rich media banner ID if the request succeeded, or an error if something went terribly wrong.

List all rich media banners

Definition

GET https://api.adbutler.com/v1/banners/rich-media
\AdButler\RichMediaBanner::retrieveAll()
adbutler.banners.richMedia.list()

Example Request

curl "https://api.adbutler.com/v1/banners/rich-media?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$richMediaBanner = \AdButler\RichMediaBanner::retrieveAll(array(
  "limit" => 2
));

echo $richMediaBanner;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.banners.richMedia.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.banners.richMedia.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/banners/rich-media",
  "data": [
    {
      "object": "rich_media_banner",
      "self": "/v1/banners/rich-media/518889713",
      "id": 518889713,
      "created_date": "2016-04-29 09:36:35",
      "creative": 4321,
      "expand_horizontal_direction": "right",
      "expand_vertical_direction": "up",
      "height": 250,
      "html_content_below": "Hello world",
      "html_path": null,
      "last_modified": "2016-04-30 11:53:35",
      "location": "http://www.google.ca",
      "name": "Demo Rich Media Banner",
      "width": 300,
      "tracking_pixel": "url"
    },
    {
      "object": "rich_media_banner",
      "self": "/v1/banners/rich-media/518889717",
      "id": 518889717,
      "created_date": "2016-04-29 09:36:35",
      "creative": 4321,
      "expand_horizontal_direction": "right",
      "expand_vertical_direction": "up",
      "height": 250,
      "html_content_below": "Hello world",
      "html_path": null,
      "last_modified": "2016-04-30 11:53:35",
      "location": "http://www.google.ca",
      "name": "Demo Rich Media Banner",
      "width": 300,
      "tracking_pixel": "url"
    }
  ]
}
AdButler\RichMediaBanner JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/banners/rich-media",
  "data": [
    {
      "object": "rich_media_banner",
      "self": "/v1/banners/rich-media/518889713",
      "id": 518889713,
      "created_date": "2016-04-29 09:36:35",
      "creative": 4321,
      "expand_horizontal_direction": "right",
      "expand_vertical_direction": "up",
      "height": 250,
      "html_content_below": "Hello world",
      "html_path": null,
      "last_modified": "2016-04-30 11:53:35",
      "location": "http://www.google.ca",
      "name": "Demo Rich Media Banner",
      "width": 300,
      "tracking_pixel": "url"
    },
    {
      "object": "rich_media_banner",
      "self": "/v1/banners/rich-media/518889717",
      "id": 518889717,
      "created_date": "2016-04-29 09:36:35",
      "creative": 4321,
      "expand_horizontal_direction": "right",
      "expand_vertical_direction": "up",
      "height": 250,
      "html_content_below": "Hello world",
      "html_path": null,
      "last_modified": "2016-04-30 11:53:35",
      "location": "http://www.google.ca",
      "name": "Demo Rich Media Banner",
      "width": 300,
      "tracking_pixel": "url"
    }
  ]
}

Returns a list of all the rich media banner accounts. Most recent rich media banner accounts appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is a rich_media_banner object, and if no objects were found the list will be empty.

Retrieve rich-media banner conversion tag

Definition

GET https://api.adbutler.com/v1/banners/rich-media/{RICH-MEDIA-BANNER-ID}/conversion-tag
\AdButler\RichMediaBannerConvTag::retrieve()
adbutler.banners.richMedia.conversionTag.retrieve()

Example Request

curl "https://api.adbutler.com/v1/banners/rich-media/ID/conversion-tag/518889783" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$richMediaBannerConvTag = \AdButler\RichMediaBannerConvTag::retrieve( 518889783 );

echo $richMediaBannerConvTag;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.banners.richMedia.conversionTag.read(518889783, function(err, response) {
  console.log(response);
});

// using promises
adbutler.banners.richMedia.conversionTag.read(518889783).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Retrieves an HTML tag which can be used to track conversions for the provided banner.

Query Parameters

Parameter Description

protocol

Whether to use http or https protocol when serving the advertisements. Use https only if you are using secure pages because it does not support Custom Domains.

Returns

Example Response

{
  "object": "conv_tag",
  "url": "/v1/banners/rich-media/518889783/conversion-tag",
  "data": {
    "src": "https://servedbyadbutler.com.vm.test/convtrack.spark?MID=108607&BID=518889783",
    "html": "<img src='https://servedbyadbutler.com.vm.test/convtrack.spark?MID=108607&BID=518889783' width='1' height='1' border='0' />"
  }
}
AdButler\RichMediaBannerConvTag JSON: {
  "object": "conv_tag",
  "url": "/v1/banners/rich-media/518889783/conversion-tag",
  "data": {
    "src": "https://servedbyadbutler.com.vm.test/convtrack.spark?MID=108607&BID=518889783",
    "html": "<img src='https://servedbyadbutler.com.vm.test/convtrack.spark?MID=108607&BID=518889783' width='1' height='1' border='0' />"
  }
}
Field Type Description

object

string

A string denoting the object type which is always conv_tag for the current resource.

url

string

The relative URL of the current resource which is always of the form /v1/banners/rich-media/{RICH_MEDIA_BANNER_ID}/conversion-tag.

data

array

The data object containing the conversion tag.

 

Returns a conv_tag object if the request succeeded, or an error if something went terribly wrong.


Custom HTML Banners

Introduction

If you need to serve a third-party advertisement from an ad network or another advertiser, or find yourself needing to do something extremely custom that you cannot achieve with traditional display advertising, the Custom HTML Banner is here to help.

Custom HTML Banners effectively give you the freedom to implement virtually any type of advertisements you need through the use of AdButler's ad serving macros and a text box.

In general, banners are assigned to an advertiser campaign, and in turn the campaign to a zone. Banners may be assigned to publishers directly if they related directly to that publisher (or are planned to be default/backfill ads).

The custom_html_banner response object has the following fields.

Example Response

{
  "object": "custom_html_banner",
  "self": "/v1/banners/custom-html/518889978",
  "id": 518889978,
  "created_date": "2016-04-29 09:36:35",
  "custom_html": "",
  "expand_horizontal_direction": "left",
  "expand_vertical_direction": "down",
  "height": 250,
  "html_content_below": "Hello world",
  "last_modified": "2016-04-30 11:53:35",
  "location": "http://www.google.ca",
  "name": "Demo Custom HTML Banner",
  "tracking_pixel": "url",
  "width": 300
}
AdButler\CustomHTMLBanner JSON: {
  "object": "custom_html_banner",
  "self": "/v1/banners/custom-html/518889978",
  "id": 518889978,
  "created_date": "2016-04-29 09:36:35",
  "custom_html": "",
  "expand_horizontal_direction": "left",
  "expand_vertical_direction": "down",
  "height": 250,
  "html_content_below": "Hello world",
  "last_modified": "2016-04-30 11:53:35",
  "location": "http://www.google.ca",
  "name": "Demo Custom HTML Banner",
  "tracking_pixel": "url",
  "width": 300
}
Field Type Description

object

string

A string denoting the object type which is always custom_html_banner for the current resource.

self

string

The relative URL of the current resource which is always of the form /v1/banners/custom-html/{CUSTOM_HTML_BANNER_ID}.

id

integer

The current resource identifier (ID).

created_date

string

The date and time this banner was created.

custom_html

string

The HTML content of the banner.

expand_horizontal_direction

string

The custom HTML banner expansion in the horizontal direction.

expand_vertical_direction

string

The custom HTML banner expansion in the vertical direction.

height

integer

The height of the custom HTML banner

html_content_below

string

The HTML content that will appear below the custom HTML banner.

last_modified

string

The date and time this banner was last modified.

location

string

The destination URL where the user will be redirected to when they click on the custom HTML banner. A null value denotes no redirection.

name

string

A descriptive name of the custom HTML banner.

tracking_pixel

string

A URL string of the third party tracking pixel for monitoring impressions. A null value indicates tracking pixel is not being used.

width

integer

The width of the custom HTML banner.

Create a custom HTML banner

Definition

POST https://api.adbutler.com/v1/banners/custom-html
\AdButler\CustomHTMLBanner::create()
adbutler.banners.customHTML.create()

Example Request

curl "https://api.adbutler.com/v1/banners/custom-html" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{  
        "custom_html": "",
        "expand_horizontal_direction": "left",
        "expand_vertical_direction": "down",
        "height": 250,
        "html_content_below": "Hello world",
        "location": "http://www.google.ca",
        "name": "Demo Custom HTML Banner",
        "tracking_pixel": "url",
        "width": 300
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$customHTMLBanner = \AdButler\CustomHTMLBanner::create(array(
  "custom_html" => "",
  "expand_horizontal_direction" => "left",
  "expand_vertical_direction" => "down",
  "height" => 250,
  "html_content_below" => "Hello world",
  "location" => "http://www.google.ca",
  "name" => "Demo Custom HTML Banner",
  "tracking_pixel" => "url",
  "width" => 300
));

echo $customHTMLBanner;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var postData = {
  "custom_html": "",
  "expand_horizontal_direction": "left",
  "expand_vertical_direction": "down",
  "height": 250,
  "html_content_below": "Hello world",
  "location": "http://www.google.ca",
  "name": "Demo Custom HTML Banner",
  "tracking_pixel": "url",
  "width": 300
};

// using callbacks
adbutler.banners.customHTML.create(postData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.banners.customHTML.create(postData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "custom_html_banner",
  "self": "/v1/banners/custom-html/518889978",
  "id": 518889978,
  "created_date": "2016-04-29 09:36:35",
  "custom_html": "",
  "expand_horizontal_direction": "left",
  "expand_vertical_direction": "down",
  "height": 250,
  "html_content_below": "Hello world",
  "last_modified": "2016-04-30 11:53:35",
  "location": "http://www.google.ca",
  "name": "Demo Custom HTML Banner",
  "tracking_pixel": "url",
  "width": 300
}
AdButler\CustomHTMLBanner JSON: {
  "object": "custom_html_banner",
  "self": "/v1/banners/custom-html/518889978",
  "id": 518889978,
  "created_date": "2016-04-29 09:36:35",
  "custom_html": "",
  "expand_horizontal_direction": "left",
  "expand_vertical_direction": "down",
  "height": 250,
  "html_content_below": "Hello world",
  "last_modified": "2016-04-30 11:53:35",
  "location": "http://www.google.ca",
  "name": "Demo Custom HTML Banner",
  "tracking_pixel": "url",
  "width": 300
}
Field Type Description

name*

string

A descriptive name of the custom HTML banner. We recommend using a naming convention that is consistent, relevant, and clear.

width*

integer

The width of the custom HTML banner. See Standard Banner Dimensions.

height*

integer

The height of the custom HTML banner. See Standard Banner Dimensions.

custom_html*

integer

The HTML content of the banner.

location

string

A URL indicating where you want the user to go when they click on the banner. This field can be left blank.

tracking_pixel

string

A URL of an image, typically 1x1 pixel in size, intended for impression tracking purposes. It is loaded alongside the banner allowing an external system to monitor impressions.

html_content_below

string

The HTML content to appear below the custom HTML banner.

expand_horizontal_direction

string

Whether to allow the custom HTML banner to expand in the horizontal direction. The value can be none, left, or rigth.

expand_vertical_direction

string

Whether to allow the custom HTML banner to expand in the vertical direction. The value can be none, up, or down.

* = required field

Returns

Returns a custom_html_banner object if the request succeeded, or an error if something went terribly wrong.

Retrieve a custom HTML banner

Definition

GET https://api.adbutler.com/v1/banners/custom-html/{CUSTOM-HTML-BANNER-ID}
\AdButler\CustomHTMLBanner::retrieve()
adbutler.banners.customHTML.retrieve()

Example Request

curl "https://api.adbutler.com/v1/banners/custom-html/518889978" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$customHTMLBanner = \AdButler\CustomHTMLBanner::retrieve( 518889978 );

echo $customHTMLBanner;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.banners.customHTML.read(518889978, function(err, response) {
  console.log(response);
});

// using promises
adbutler.banners.customHTML.read(518889978).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "custom_html_banner",
  "self": "/v1/banners/custom-html/518889978",
  "id": 518889978,
  "created_date": "2016-04-29 09:36:35",
  "custom_html": "",
  "expand_horizontal_direction": "left",
  "expand_vertical_direction": "down",
  "height": 250,
  "html_content_below": "Hello world",
  "last_modified": "2016-04-30 11:53:35",
  "location": "http://www.google.ca",
  "name": "Demo Custom HTML Banner",
  "tracking_pixel": "url",
  "width": 300
}
AdButler\CustomHTMLBanner JSON: {
  "object": "custom_html_banner",
  "self": "/v1/banners/custom-html/518889978",
  "id": 518889978,
  "created_date": "2016-04-29 09:36:35",
  "custom_html": "",
  "expand_horizontal_direction": "left",
  "expand_vertical_direction": "down",
  "height": 250,
  "html_content_below": "Hello world",
  "last_modified": "2016-04-30 11:53:35",
  "location": "http://www.google.ca",
  "name": "Demo Custom HTML Banner",
  "tracking_pixel": "url",
  "width": 300
}

You can retrieve the information about an existing custom HTML banner by giving the custom HTML banner ID that was returned in the custom HTML banner object upon creation. You will see at the most 10 custom HTML banners in the response. You can change this default limit by appending ?limit=25 if you want this request to return 25 banners_custom-html.

Returns

Returns a custom_html_banner object if the request succeeded, or an error if something went terribly wrong.

Update a custom HTML banner

Definition

PUT https://api.adbutler.com/v1/banners/custom-html/{CUSTOM-HTML-BANNER-ID}
\AdButler\CustomHTMLBanner->save()
adbutler.banners.customHTML.update()

Example Request

curl "https://api.adbutler.com/v1/banners/custom-html/518889978" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{  
        "custom_html": "",
        "expand_horizontal_direction": "left",
        "expand_vertical_direction": "down",
        "height": 250,
        "html_content_below": "Hello world",
        "location": "http://www.google.ca",
        "name": "Demo Custom HTML Banner",
        "tracking_pixel": "url",
        "width": 300
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$customHTMLBanner = \AdButler\CustomHTMLBanner::retrieve( 518889978 );

$customHTMLBanner->custom_html = "";
$customHTMLBanner->expand_horizontal_direction = "left";
$customHTMLBanner->expand_vertical_direction = "down";
$customHTMLBanner->height = 250;
$customHTMLBanner->html_content_below = "Hello world";
$customHTMLBanner->location = "http://www.google.ca";
$customHTMLBanner->name = "Demo Custom HTML Banner";
$customHTMLBanner->tracking_pixel = "url";
$customHTMLBanner->width = 300;

$customHTMLBanner->save();

echo $customHTMLBanner;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var updateData = {
  "custom_html": "",
  "expand_horizontal_direction": "left",
  "expand_vertical_direction": "down",
  "height": 250,
  "html_content_below": "Hello world",
  "location": "http://www.google.ca",
  "name": "Demo Custom HTML Banner",
  "tracking_pixel": "url",
  "width": 300
};

// using callbacks
adbutler.banners.customHTML.update(518889978, updateData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.banners.customHTML.update(518889978, updateData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "custom_html_banner",
  "self": "/v1/banners/custom-html/518889978",
  "id": 518889978,
  "created_date": "2016-04-29 09:36:35",
  "custom_html": "",
  "expand_horizontal_direction": "left",
  "expand_vertical_direction": "down",
  "height": 250,
  "html_content_below": "Hello world",
  "last_modified": "2016-04-30 11:53:35",
  "location": "http://www.google.ca",
  "name": "Demo Custom HTML Banner",
  "tracking_pixel": "url",
  "width": 300
}
AdButler\CustomHTMLBanner JSON: {
  "object": "custom_html_banner",
  "self": "/v1/banners/custom-html/518889978",
  "id": 518889978,
  "created_date": "2016-04-29 09:36:35",
  "custom_html": "",
  "expand_horizontal_direction": "left",
  "expand_vertical_direction": "down",
  "height": 250,
  "html_content_below": "Hello world",
  "last_modified": "2016-04-30 11:53:35",
  "location": "http://www.google.ca",
  "name": "Demo Custom HTML Banner",
  "tracking_pixel": "url",
  "width": 300
}

You can update a specific custom HTML banner account by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the reqeust. The update request accepts mostly the same arguments as the custom HTML banner creation request.

Field Type Description

name

string

A descriptive name of the custom HTML banner. We recommend using a naming convention that is consistent, relevant, and clear.

width

integer

The width of the custom HTML banner. See Standard Banner Dimensions.

height

integer

The height of the custom HTML banner. See Standard Banner Dimensions.

custom_html

integer

The HTML content of the banner.

location

string

A URL indicating where you want the user to go when they click on the banner. This field can be left blank.

tracking_pixel

string

A URL of an image, typically 1x1 pixel in size, intended for impression tracking purposes. It is loaded alongside the banner allowing an external system to monitor impressions.

html_content_below

string

The HTML content to appear below the custom HTML banner.

expand_horizontal_direction

string

Whether to allow the custom HTML banner to expand in the horizontal direction. The value can be none, left, or rigth.

expand_vertical_direction

string

Whether to allow the custom HTML banner to expand in the vertical direction. The value can be none, up, or down.

Returns

Returns a custom_html_banner object if the request succeeded, or an error if something went terribly wrong.

Delete a custom HTML banner

Definition

DELETE https://api.adbutler.com/v1/banners/custom-html/{CUSTOM-HTML-BANNER-ID}
\AdButler\CustomHTMLBanner->delete()
adbutler.banners.customHTML.delete()

Example Request

curl "https://api.adbutler.com/v1/banners/custom-html/518889978" \
  -H "Authorization: Basic {API_KEY}" \
  -X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$customHTMLBanner = \AdButler\CustomHTMLBanner::retrieve( 518889978 );
$customHTMLBanner->delete();

echo $customHTMLBanner;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.banners.customHTML.delete(518889978, function(err, response) {
  console.log(response);
});

// using promises
adbutler.banners.customHTML.delete(518889978).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "id": 518889978,
  "delete": true
}
AdButler\CustomHTMLBanner JSON: {
  "id": 518889978,
  "delete": true
}

Permanently deletes a custom HTML banner. if successful, this operation cannot be undone so be very sure when deleting one. Also immediately stops serving any ads belonging to this custom HTML banner account.

Returns

Returns a custom HTML banner ID if the request succeeded, or an error if something went terribly wrong.

List all custom HTML banners

Definition

GET https://api.adbutler.com/v1/banners/custom-html
\AdButler\CustomHTMLBanner::retrieveAll()
adbutler.banners.customHTML.list()

Example Request

curl "https://api.adbutler.com/v1/banners/custom-html?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$customHTMLBanner = \AdButler\CustomHTMLBanner::retrieveAll(array(
  "limit" => 2
));

echo $customHTMLBanner;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.banners.customHTML.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.banners.customHTML.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/banners/custom-html",
  "data": [
    {
      "object": "custom_html_banner",
      "self": "/v1/banners/custom-html/518889712",
      "id": 518889712,
      "created_date": "2016-04-29 09:36:35",
      "custom_html": "",
      "expand_horizontal_direction": "left",
      "expand_vertical_direction": "down",
      "height": 250,
      "html_content_below": "Hello world",
      "last_modified": "2016-04-30 11:53:35",
      "location": "http://www.google.ca",
      "name": "Demo Custom HTML Banner",
      "tracking_pixel": "url",
      "width": 300
    },
    {
      "object": "custom_html_banner",
      "self": "/v1/banners/custom-html/518889716",
      "id": 518889716,
      "created_date": "2016-04-29 09:36:35",
      "custom_html": "",
      "expand_horizontal_direction": "left",
      "expand_vertical_direction": "down",
      "height": 250,
      "html_content_below": "Hello world",
      "last_modified": "2016-04-30 11:53:35",
      "location": "http://www.google.ca",
      "name": "Demo Custom HTML Banner",
      "tracking_pixel": "url",
      "width": 300
    }
  ]
}
AdButler\CustomHTMLBanner JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/banners/custom-html",
  "data": [
    {
      "object": "custom_html_banner",
      "self": "/v1/banners/custom-html/518889712",
      "id": 518889712,
      "created_date": "2016-04-29 09:36:35",
      "custom_html": "",
      "expand_horizontal_direction": "left",
      "expand_vertical_direction": "down",
      "height": 250,
      "html_content_below": "Hello world",
      "last_modified": "2016-04-30 11:53:35",
      "location": "http://www.google.ca",
      "name": "Demo Custom HTML Banner",
      "tracking_pixel": "url",
      "width": 300
    },
    {
      "object": "custom_html_banner",
      "self": "/v1/banners/custom-html/518889716",
      "id": 518889716,
      "created_date": "2016-04-29 09:36:35",
      "custom_html": "",
      "expand_horizontal_direction": "left",
      "expand_vertical_direction": "down",
      "height": 250,
      "html_content_below": "Hello world",
      "last_modified": "2016-04-30 11:53:35",
      "location": "http://www.google.ca",
      "name": "Demo Custom HTML Banner",
      "tracking_pixel": "url",
      "width": 300
    }
  ]
}

Returns a list of all the custom HTML banner accounts. Most recent custom HTML banner accounts appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is a custom_html_banner object, and if no objects were found the list will be empty.

Retrieve custom HTML banner conversion tag

Definition

GET https://api.adbutler.com/v1/banners/custom-html/{CUSTOM-HTML-BANNER-ID}/conversion-tag
\AdButler\CustomHTMLBannerConvTag::retrieve()
adbutler.banners.customHTML.conversionTag.retrieve()

Example Request

curl "https://api.adbutler.com/v1/banners/custom-html/ID/conversion-tag/518889978" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$customHTMLBannerConvTag = \AdButler\CustomHTMLBannerConvTag::retrieve( 518889978 );

echo $customHTMLBannerConvTag;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.banners.customHTML.conversionTag.read(518889978, function(err, response) {
  console.log(response);
});

// using promises
adbutler.banners.customHTML.conversionTag.read(518889978).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Retrieves an HTML tag which can be used to track conversions for the provided banner.

Query Parameters

Parameter Description

protocol

Whether to use http or https protocol when serving the advertisements. Use https only if you are using secure pages because it does not support Custom Domains.

Returns

Example Response

{
  "object": "conv_tag",
  "url": "/v1/banners/custom-html/518889978/conversion-tag",
  "data": {
    "src": "https://servedbyadbutler.com.vm.test/convtrack.spark?MID=108607&BID=518889978",
    "html": "<img src='https://servedbyadbutler.com.vm.test/convtrack.spark?MID=108607&BID=518889978' width='1' height='1' border='0' />"
  }
}
AdButler\CustomHTMLBannerConvTag JSON: {
  "object": "conv_tag",
  "url": "/v1/banners/custom-html/518889978/conversion-tag",
  "data": {
    "src": "https://servedbyadbutler.com.vm.test/convtrack.spark?MID=108607&BID=518889978",
    "html": "<img src='https://servedbyadbutler.com.vm.test/convtrack.spark?MID=108607&BID=518889978' width='1' height='1' border='0' />"
  }
}
Field Type Description

object

string

A string denoting the object type which is always conv_tag for the current resource.

url

string

The relative URL of the current resource which is always of the form /v1/banners/custom-html/{CUSTOM_HTML_BANNER_ID}/conversion-tag.

data

array

The data object containing the conversion tag.

 

Returns a conv_tag object if the request succeeded, or an error if something went terribly wrong.


Text Ads

Introduction

A text ad as general term for a text and link formatted advertisement often styled to match the theme of your site.

Each text ad is typically accompanied by some meta information indicating how to serve it including a destination URL that a user should be directed to on click.

You can create a new text ad, retrieve one or more text ads, update an existing text ad, or delete the text ad.

The text_ad response object has the following fields.

Example Response

{
  "object": "text_ad",
  "self": "/v1/text-ads/4623",
  "id": 4623,
  "content": "hello",
  "content_alignment": "left",
  "destination_url": "http://www.calgaryflames.com",
  "display_url": "http://www.nhl.com",
  "display_url_alignment": "left",
  "name": "Justin's Ad",
  "target_window": "hello",
  "title": "Demo Text Ad",
  "title_alignment": "left"
}
AdButler\TextAd JSON: {
  "object": "text_ad",
  "self": "/v1/text-ads/4623",
  "id": 4623,
  "content": "hello",
  "content_alignment": "left",
  "destination_url": "http://www.calgaryflames.com",
  "display_url": "http://www.nhl.com",
  "display_url_alignment": "left",
  "name": "Justin's Ad",
  "target_window": "hello",
  "title": "Demo Text Ad",
  "title_alignment": "left"
}
Field Type Description

object

string

A string denoting the object type which is always text_ad for the current resource.

self

string

The relative URL of the current resource which is always of the form /v1/text-ads/{TEXT_AD_ID}.

id

integer

The current resource identifier (ID).

name

string

A descriptive name of the text ad.

title

string

The title of the text ad.

content

string

The content of the text ad

destination_url

string

The destination URL

display_url

string

The display URL

target_window

string

Whether to open in a new window.

title_alignment

string

Alignment of the text ad title.

content_alignment

string

Alignment of the text ad content

display_url_alignment

string

Alignment of the display url

Create a text ad

Definition

POST https://api.adbutler.com/v1/text-ads
\AdButler\TextAd::create()
adbutler.textAds.create()

Example Request

curl "https://api.adbutler.com/v1/text-ads" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{  
        "content": "hello",
        "content_alignment": "left",
        "destination_url": "http://www.calgaryflames.com",
        "display_url": "http://www.nhl.com",
        "display_url_alignment": "left",
        "name": "Justin's Ad",
        "target_window": "hello",
        "title": "Demo Text Ad",
        "title_alignment": "left"
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$textAd = \AdButler\TextAd::create(array(
  "content" => "hello",
  "content_alignment" => "left",
  "destination_url" => "http://www.calgaryflames.com",
  "display_url" => "http://www.nhl.com",
  "display_url_alignment" => "left",
  "name" => "Justin's Ad",
  "target_window" => "hello",
  "title" => "Demo Text Ad",
  "title_alignment" => "left"
));

echo $textAd;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var postData = {
  "content": "hello",
  "content_alignment": "left",
  "destination_url": "http://www.calgaryflames.com",
  "display_url": "http://www.nhl.com",
  "display_url_alignment": "left",
  "name": "Justin's Ad",
  "target_window": "hello",
  "title": "Demo Text Ad",
  "title_alignment": "left"
};

// using callbacks
adbutler.textAds.create(postData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.textAds.create(postData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "text_ad",
  "self": "/v1/text-ads/4623",
  "id": 4623,
  "content": "hello",
  "content_alignment": "left",
  "destination_url": "http://www.calgaryflames.com",
  "display_url": "http://www.nhl.com",
  "display_url_alignment": "left",
  "name": "Justin's Ad",
  "target_window": "hello",
  "title": "Demo Text Ad",
  "title_alignment": "left"
}
AdButler\TextAd JSON: {
  "object": "text_ad",
  "self": "/v1/text-ads/4623",
  "id": 4623,
  "content": "hello",
  "content_alignment": "left",
  "destination_url": "http://www.calgaryflames.com",
  "display_url": "http://www.nhl.com",
  "display_url_alignment": "left",
  "name": "Justin's Ad",
  "target_window": "hello",
  "title": "Demo Text Ad",
  "title_alignment": "left"
}

Creates a new text ad.

Field Type Description

name*

string

A descriptive name of the text advertisement. We recommend using a naming convention that is consistent, relevant, and clear.

title*

string

The link text displayed to someone viewing the advertisement.

content*

string

The text content of up to 1000 characters to be displayed as the advertisement.

destination_url*

string

The URL indicating where you want the user to go when they click on the advertisement.

display_url

string

A URL that is displayed to the user instead of the destination URL. Often a more compact version of the destination URL.

target_window

string

Indicate the window/frame that the destination URL should load in when clicked. Possible values are _blank, _top, or any valid string (should it be just valid values for the target attribute).

title_alignment

string

How to orient the title text of the ad. Possible values are left, right, center.

content_alignment

string

How to orient the text ad's content. Possible values are left, right, center.

display_url_alignment

string

How to orient the displayed URL to the user. Possible values are left, right, center.

* = required field

Returns

Returns a text_ad object if the request succeeded, or an error if something went terribly wrong.

Retrieve a text ad

Definition

GET https://api.adbutler.com/v1/text-ads/{TEXT-AD-ID}
\AdButler\TextAd::retrieve()
adbutler.textAds.retrieve()

Example Request

curl "https://api.adbutler.com/v1/text-ads/4623" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$textAd = \AdButler\TextAd::retrieve( 4623 );

echo $textAd;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.textAds.read(4623, function(err, response) {
  console.log(response);
});

// using promises
adbutler.textAds.read(4623).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "text_ad",
  "self": "/v1/text-ads/4623",
  "id": 4623,
  "content": "hello",
  "content_alignment": "left",
  "destination_url": "http://www.calgaryflames.com",
  "display_url": "http://www.nhl.com",
  "display_url_alignment": "left",
  "name": "Justin's Ad",
  "target_window": "hello",
  "title": "Demo Text Ad",
  "title_alignment": "left"
}
AdButler\TextAd JSON: {
  "object": "text_ad",
  "self": "/v1/text-ads/4623",
  "id": 4623,
  "content": "hello",
  "content_alignment": "left",
  "destination_url": "http://www.calgaryflames.com",
  "display_url": "http://www.nhl.com",
  "display_url_alignment": "left",
  "name": "Justin's Ad",
  "target_window": "hello",
  "title": "Demo Text Ad",
  "title_alignment": "left"
}

You can retrieve the information about an existing text ad by giving the text ad ID that was returned in the text ad object upon creation. You will see at the most 10 text ads in the response. You can change this default limit by appending ?limit=25 if you want this request to return 25 text-ads.

Returns

Returns a text_ad object if the request succeeded, or an error if something went terribly wrong.

Update a text ad

Definition

PUT https://api.adbutler.com/v1/text-ads/{TEXT-AD-ID}
\AdButler\TextAd->save()
adbutler.textAds.update()

Example Request

curl "https://api.adbutler.com/v1/text-ads/4623" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{  
        "content": "hello",
        "content_alignment": "left",
        "destination_url": "http://www.calgaryflames.com",
        "display_url": "http://www.nhl.com",
        "display_url_alignment": "left",
        "name": "Justin's Ad",
        "target_window": "hello",
        "title": "Demo Text Ad",
        "title_alignment": "left"
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$textAd = \AdButler\TextAd::retrieve( 4623 );

$textAd->content = "hello";
$textAd->content_alignment = "left";
$textAd->destination_url = "http://www.calgaryflames.com";
$textAd->display_url = "http://www.nhl.com";
$textAd->display_url_alignment = "left";
$textAd->name = "Justin's Ad";
$textAd->target_window = "hello";
$textAd->title = "Demo Text Ad";
$textAd->title_alignment = "left";

$textAd->save();

echo $textAd;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var updateData = {
  "content": "hello",
  "content_alignment": "left",
  "destination_url": "http://www.calgaryflames.com",
  "display_url": "http://www.nhl.com",
  "display_url_alignment": "left",
  "name": "Justin's Ad",
  "target_window": "hello",
  "title": "Demo Text Ad",
  "title_alignment": "left"
};

// using callbacks
adbutler.textAds.update(4623, updateData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.textAds.update(4623, updateData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "text_ad",
  "self": "/v1/text-ads/4623",
  "id": 4623,
  "content": "hello",
  "content_alignment": "left",
  "destination_url": "http://www.calgaryflames.com",
  "display_url": "http://www.nhl.com",
  "display_url_alignment": "left",
  "name": "Justin's Ad",
  "target_window": "hello",
  "title": "Demo Text Ad",
  "title_alignment": "left"
}
AdButler\TextAd JSON: {
  "object": "text_ad",
  "self": "/v1/text-ads/4623",
  "id": 4623,
  "content": "hello",
  "content_alignment": "left",
  "destination_url": "http://www.calgaryflames.com",
  "display_url": "http://www.nhl.com",
  "display_url_alignment": "left",
  "name": "Justin's Ad",
  "target_window": "hello",
  "title": "Demo Text Ad",
  "title_alignment": "left"
}

You can update a specific text ad account by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the text ad creation request.

Field Type Description

name

string

A descriptive name of the text advertisement. We recommend using a naming convention that is consistent, relevant, and clear.

title

string

The link text displayed to someone viewing the advertisement.

content

string

The text content of up to 1000 characters to be displayed as the advertisement.

destination_url

string

The URL indicating where you want the user to go when they click on the advertisement.

display_url

string

A URL that is displayed to the user instead of the destination URL. Often a more compact version of the destination URL.

target_window

string

Indicate the window/frame that the destination URL should load in when clicked. Possible values are _blank, _top, or any valid string (should it be just valid values for the target attribute).

title_alignment

string

How to orient the title text of the ad. Possible values are left, right, center.

content_alignment

string

How to orient the text ad's content. Possible values are left, right, center.

display_url_alignment

string

How to orient the displayed URL to the user. Possible values are left, right, center.

Returns

Returns a text_ad object if the request succeeded, or an error if something went terribly wrong.

Delete a text ad

Definition

DELETE https://api.adbutler.com/v1/text-ads/{TEXT-AD-ID}
\AdButler\TextAd->delete()
adbutler.textAds.delete()

Example Request

curl "https://api.adbutler.com/v1/text-ads/4623" \
  -H "Authorization: Basic {API_KEY}" \
  -X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$textAd = \AdButler\TextAd::retrieve( 4623 );
$textAd->delete();

echo $textAd;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.textAds.delete(4623, function(err, response) {
  console.log(response);
});

// using promises
adbutler.textAds.delete(4623).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "id": 4623,
  "delete": true
}
AdButler\TextAd JSON: {
  "id": 4623,
  "delete": true
}

Permanently deletes a text ad. if successful, this operation cannot be undone so be very sure when deleting one. Also immediately stops serving any ads belonging to this text ad account.

Returns

Returns a text ad ID if the request succeeded, or an error if something went terribly wrong.

List all text ads

Definition

GET https://api.adbutler.com/v1/text-ads
\AdButler\TextAd::retrieveAll()
adbutler.textAds.list()

Example Request

curl "https://api.adbutler.com/v1/text-ads?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$textAd = \AdButler\TextAd::retrieveAll(array(
  "limit" => 2
));

echo $textAd;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.textAds.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.textAds.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/text-ads",
  "data": [
    {
      "object": "text_ad",
      "self": "/v1/text-ads/4567",
      "id": 4567,
      "content": "Manage and serve online advertisements with our powerful and easy to use solution.",
      "content_alignment": "left",
      "destination_url": "https://www.adbutler.com",
      "display_url": "https://www.adbutler.com",
      "display_url_alignment": "left",
      "name": "Default Text Ad",
      "target_window": null,
      "title": "Ad serving software",
      "title_alignment": "left"
    },
    {
      "object": "text_ad",
      "self": "/v1/text-ads/4569",
      "id": 4569,
      "content": "hello",
      "content_alignment": "left",
      "destination_url": "http://www.calgaryflames.com",
      "display_url": "http://www.nhl.com",
      "display_url_alignment": "left",
      "name": "Justin's Ad",
      "target_window": "hello",
      "title": "Demo Text Ad",
      "title_alignment": "left"
    }
  ]
}
AdButler\TextAd JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/text-ads",
  "data": [
    {
      "object": "text_ad",
      "self": "/v1/text-ads/4567",
      "id": 4567,
      "content": "Manage and serve online advertisements with our powerful and easy to use solution.",
      "content_alignment": "left",
      "destination_url": "https://www.adbutler.com",
      "display_url": "https://www.adbutler.com",
      "display_url_alignment": "left",
      "name": "Default Text Ad",
      "target_window": null,
      "title": "Ad serving software",
      "title_alignment": "left"
    },
    {
      "object": "text_ad",
      "self": "/v1/text-ads/4569",
      "id": 4569,
      "content": "hello",
      "content_alignment": "left",
      "destination_url": "http://www.calgaryflames.com",
      "display_url": "http://www.nhl.com",
      "display_url_alignment": "left",
      "name": "Justin's Ad",
      "target_window": "hello",
      "title": "Demo Text Ad",
      "title_alignment": "left"
    }
  ]
}

Returns a list of all the text ad accounts. Most recent text ad accounts appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is a text_ad object, and if no objects were found the list will be empty.

Retrieve text-ad conversion tag

Definition

GET https://api.adbutler.com/v1/text-ads/{TEXT-ID}/conversion-tag
\AdButler\TextAdConvTag::retrieve()
adbutler.textAds.conversionTag.retrieve()

Example Request

curl "https://api.adbutler.com/v1/text-ads/ID/conversion-tag/4623" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$textAdConvTag = \AdButler\TextAdConvTag::retrieve( 4623 );

echo $textAdConvTag;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.textAds.conversionTag.read(4623, function(err, response) {
  console.log(response);
});

// using promises
adbutler.textAds.conversionTag.read(4623).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Retrieves an HTML tag which can be used to track conversions for the provided text ad.

Query Parameters

Parameter Description

protocol

Whether to use http or https protocol when serving the advertisements. Use https only if you are using secure pages because it does not support Custom Domains.

Returns

Example Response

{
  "object": "conv_tag",
  "url": "/v1/text-ads/4623/conversion-tag",
  "data": {
    "src": "https://servedbyadbutler.com.vm.test/convtrack.spark?MID=108607&TaID=4623",
    "html": "<img src='https://servedbyadbutler.com.vm.test/convtrack.spark?MID=108607&TaID=4623' width='1' height='1' border='0' />"
  }
}
AdButler\TextAdConvTag JSON: {
  "object": "conv_tag",
  "url": "/v1/text-ads/4623/conversion-tag",
  "data": {
    "src": "https://servedbyadbutler.com.vm.test/convtrack.spark?MID=108607&TaID=4623",
    "html": "<img src='https://servedbyadbutler.com.vm.test/convtrack.spark?MID=108607&TaID=4623' width='1' height='1' border='0' />"
  }
}
Field Type Description

object

string

A string denoting the object type which is always conv_tag for the current resource.

url

string

The relative URL of the current resource which is always of the form /v1/text-ads/{TEXT_ID}/conversion-tag.

data

array

The data object containing the conversion tag.

 

Returns a conv_tag object if the request succeeded, or an error if something went terribly wrong.


Popups

List all popups

Definition

GET https://api.adbutler.com/v1/popups
\AdButler\Popup::retrieveAll()
adbutler.popups.list()

Example Request

curl "https://api.adbutler.com/v1/popups?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$popup = \AdButler\Popup::retrieveAll(array(
  "limit" => 2
));

echo $popup;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.popups.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.popups.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/popups",
  "data": [
    {
      "object": "image_popup",
      "self": "/v1/popups/image/2222",
      "id": 2222,
      "creative": 234,
      "creative_url": "http://www.smartballoon/images/balloon.jpg",
      "height": 250,
      "html_alt_text": "A big balloon",
      "html_content_below": "",
      "location": "https://your-target-site.com",
      "name": "Demo Image Popup",
      "popup_style": "over",
      "title": "Ad Window",
      "tracking_pixel": "",
      "width": 300
    },
    {
      "object": "flash_popup",
      "self": "/v1/popups/flash/2223",
      "id": 2223,
      "creative": 45254,
      "creative_url": null,
      "flash_html": "<object width=\"300\" height=\"250\" id=\"movie_5474863\">\\r\\n<param name=\"wmode\" value=\"opaque\">\\r\\n<param name=\"quality\" value=\"high\">\\r\\n<param name=\"version\" value=\"7\">\\r\\n<param name=\"allowScriptAccess\" value=\"always\">\\r\\n<param name=\"movie\" value=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\">\\r\\n<embed width=\"300\" height=\"250\" src=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\" wmode=\"opaque\" quality=\"high\" version=\"7\" allowScriptAccess=\"always\" type=\"application/x-shockwave-flash\">\\r\\n</object>",
      "height": 250,
      "html_content_below": "",
      "location": "https://your-target-site.com",
      "mode": "opaque",
      "name": "Demo Flash Popup",
      "popup_style": "over",
      "quality": "high",
      "title": "Ad Window",
      "tracking_pixel": "",
      "version": 7,
      "width": 300
    }
  ]
}
AdButler\Popup JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/popups",
  "data": [
    {
      "object": "image_popup",
      "self": "/v1/popups/image/2222",
      "id": 2222,
      "creative": 234,
      "creative_url": "http://www.smartballoon/images/balloon.jpg",
      "height": 250,
      "html_alt_text": "A big balloon",
      "html_content_below": "",
      "location": "https://your-target-site.com",
      "name": "Demo Image Popup",
      "popup_style": "over",
      "title": "Ad Window",
      "tracking_pixel": "",
      "width": 300
    },
    {
      "object": "flash_popup",
      "self": "/v1/popups/flash/2223",
      "id": 2223,
      "creative": 45254,
      "creative_url": null,
      "flash_html": "<object width=\"300\" height=\"250\" id=\"movie_5474863\">\\r\\n<param name=\"wmode\" value=\"opaque\">\\r\\n<param name=\"quality\" value=\"high\">\\r\\n<param name=\"version\" value=\"7\">\\r\\n<param name=\"allowScriptAccess\" value=\"always\">\\r\\n<param name=\"movie\" value=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\">\\r\\n<embed width=\"300\" height=\"250\" src=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\" wmode=\"opaque\" quality=\"high\" version=\"7\" allowScriptAccess=\"always\" type=\"application/x-shockwave-flash\">\\r\\n</object>",
      "height": 250,
      "html_content_below": "",
      "location": "https://your-target-site.com",
      "mode": "opaque",
      "name": "Demo Flash Popup",
      "popup_style": "over",
      "quality": "high",
      "title": "Ad Window",
      "tracking_pixel": "",
      "version": 7,
      "width": 300
    }
  ]
}

You can retrieve a list of all the popups regardless of their type. You can optionally restrict the fields that you are interested in retrieving by using the fields query parameter.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is an object, and if no objects were found the list will be empty.


Image Popups

Introduction

A popup banner can catch your users attention by causing a separate window to appear with an advertisement in it. These ads can appear behind or in front of the content currently being browsed.

Popups require an option in the zone they belong to do be enabled to take effect.

The image_popup response object has the following fields.

Example Response

{
  "object": "image_popup",
  "self": "/v1/popups/image/2260",
  "id": 2260,
  "creative": 234,
  "creative_url": "http://www.smartballoon/images/balloon.jpg",
  "height": 250,
  "html_alt_text": "A big balloon",
  "html_content_below": "",
  "location": "https://your-target-site.com",
  "name": "Demo Image Popup",
  "popup_style": "over",
  "title": "Ad Window",
  "tracking_pixel": "",
  "width": 300
}
AdButler\ImagePopup JSON: {
  "object": "image_popup",
  "self": "/v1/popups/image/2260",
  "id": 2260,
  "creative": 234,
  "creative_url": "http://www.smartballoon/images/balloon.jpg",
  "height": 250,
  "html_alt_text": "A big balloon",
  "html_content_below": "",
  "location": "https://your-target-site.com",
  "name": "Demo Image Popup",
  "popup_style": "over",
  "title": "Ad Window",
  "tracking_pixel": "",
  "width": 300
}
Field Type Description

object

string

A string denoting the object type which is always image_popup for the current resource.

self

string

The relative URL of the current resource which is always of the form /v1/popups/image/{IMAGE_POPUP_ID}.

id

integer

The current resource identifier (ID).

creative

integer

The image creative identifier (ID)

creative_url

string

The image creative URL.

height

integer

Height of the popup

html_alt_text

string

The alternate text to appear if the image fails to load

html_content_below

string

HTML below the main HTML

location

string

The location to redirect to

name

string

Name of the Custom HTML Popup

popup_style

string

Where the popup should appear

title

string

Title of the popup

tracking_pixel

string

The pixel URL

width

integer

Width of the popup

Create an image popup

Definition

POST https://api.adbutler.com/v1/popups/image
\AdButler\ImagePopup::create()
adbutler.popups.images.create()

Example Request

curl "https://api.adbutler.com/v1/popups/image" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{  
        "creative": 234,
        "creative_url": "http://www.smartballoon/images/balloon.jpg",
        "height": 250,
        "html_alt_text": "A big balloon",
        "html_content_below": "",
        "location": "https://your-target-site.com",
        "name": "Demo Image Popup",
        "popup_style": "over",
        "title": "Ad Window",
        "tracking_pixel": "",
        "width": 300
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$imagePopup = \AdButler\ImagePopup::create(array(
  "creative" => 234,
  "creative_url" => "http://www.smartballoon/images/balloon.jpg",
  "height" => 250,
  "html_alt_text" => "A big balloon",
  "html_content_below" => "",
  "location" => "https://your-target-site.com",
  "name" => "Demo Image Popup",
  "popup_style" => "over",
  "title" => "Ad Window",
  "tracking_pixel" => "",
  "width" => 300
));

echo $imagePopup;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var postData = {
  "creative": 234,
  "creative_url": "http://www.smartballoon/images/balloon.jpg",
  "height": 250,
  "html_alt_text": "A big balloon",
  "html_content_below": "",
  "location": "https://your-target-site.com",
  "name": "Demo Image Popup",
  "popup_style": "over",
  "title": "Ad Window",
  "tracking_pixel": "",
  "width": 300
};

// using callbacks
adbutler.popups.images.create(postData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.popups.images.create(postData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "image_popup",
  "self": "/v1/popups/image/2260",
  "id": 2260,
  "creative": 234,
  "creative_url": "http://www.smartballoon/images/balloon.jpg",
  "height": 250,
  "html_alt_text": "A big balloon",
  "html_content_below": "",
  "location": "https://your-target-site.com",
  "name": "Demo Image Popup",
  "popup_style": "over",
  "title": "Ad Window",
  "tracking_pixel": "",
  "width": 300
}
AdButler\ImagePopup JSON: {
  "object": "image_popup",
  "self": "/v1/popups/image/2260",
  "id": 2260,
  "creative": 234,
  "creative_url": "http://www.smartballoon/images/balloon.jpg",
  "height": 250,
  "html_alt_text": "A big balloon",
  "html_content_below": "",
  "location": "https://your-target-site.com",
  "name": "Demo Image Popup",
  "popup_style": "over",
  "title": "Ad Window",
  "tracking_pixel": "",
  "width": 300
}

Creates a new image popup.

Field Type Description

name*

string

A descriptive name of the image popup. We recommend using a naming convention that is consistent, relevant, and clear.

title*

string

The user visible title that will appear on the frame of the popup window.

width*

integer

The width of the popup window containing the advertisement (typically the same width as the advertisement itself).

height*

integer

The height of the popup window containing the advertisement (typically the same height as the advertisement itself).

creative

integer

The image creative identifier (ID). It must be a valid ID if no creative_url is given.

creative_url

integer

Specify the URL of an image file (PNG, JPEG, or GIF). creative must be given if this is left empty.

location

string

A URL indicating where you want the user to go when they click on the popup. This field can be left blank.

tracking_pixel

string

A URL of an image, typically 1x1 pixel in size, intended for impression tracking purposes. It is loaded alongside the popup allowing an external system to monitor impressions.

html_content_below

string

The HTML content to appear below the image banner.

html_alt_text

string

Text to display if the image fails to load. This is intended for use by the Assistive Technologies.

popup_style

string

Whether this popup should appear in front of the page or behind it. Possible values are over or under.

* = required field

Returns

Returns an image_popup object if the request succeeded, or an error if something went terribly wrong.

Retrieve an image popup

Definition

GET https://api.adbutler.com/v1/popups/image/{IMAGE-POPUP-ID}
\AdButler\ImagePopup::retrieve()
adbutler.popups.images.retrieve()

Example Request

curl "https://api.adbutler.com/v1/popups/image/2260" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$imagePopup = \AdButler\ImagePopup::retrieve( 2260 );

echo $imagePopup;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.popups.images.read(2260, function(err, response) {
  console.log(response);
});

// using promises
adbutler.popups.images.read(2260).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "image_popup",
  "self": "/v1/popups/image/2260",
  "id": 2260,
  "creative": 234,
  "creative_url": "http://www.smartballoon/images/balloon.jpg",
  "height": 250,
  "html_alt_text": "A big balloon",
  "html_content_below": "",
  "location": "https://your-target-site.com",
  "name": "Demo Image Popup",
  "popup_style": "over",
  "title": "Ad Window",
  "tracking_pixel": "",
  "width": 300
}
AdButler\ImagePopup JSON: {
  "object": "image_popup",
  "self": "/v1/popups/image/2260",
  "id": 2260,
  "creative": 234,
  "creative_url": "http://www.smartballoon/images/balloon.jpg",
  "height": 250,
  "html_alt_text": "A big balloon",
  "html_content_below": "",
  "location": "https://your-target-site.com",
  "name": "Demo Image Popup",
  "popup_style": "over",
  "title": "Ad Window",
  "tracking_pixel": "",
  "width": 300
}

You can retrieve the information about an existing image popup by giving the image popup ID that was returned in the image popup object upon creation. You will see at the most 10 image popups in the response. You can change this default limit by appending ?limit=25 if you want this request to return 25 popups_image.

Returns

Returns an image_popup object if the request succeeded, or an error if something went terribly wrong.

Update an image popup

Definition

PUT https://api.adbutler.com/v1/popups/image/{IMAGE-POPUP-ID}
\AdButler\ImagePopup->save()
adbutler.popups.images.update()

Example Request

curl "https://api.adbutler.com/v1/popups/image/2260" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{  
        "creative": 234,
        "creative_url": "http://www.smartballoon/images/balloon.jpg",
        "height": 250,
        "html_alt_text": "A big balloon",
        "html_content_below": "",
        "location": "https://your-target-site.com",
        "name": "Demo Image Popup",
        "popup_style": "over",
        "title": "Ad Window",
        "tracking_pixel": "",
        "width": 300
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$imagePopup = \AdButler\ImagePopup::retrieve( 2260 );

$imagePopup->creative = 234;
$imagePopup->creative_url = "http://www.smartballoon/images/balloon.jpg";
$imagePopup->height = 250;
$imagePopup->html_alt_text = "A big balloon";
$imagePopup->html_content_below = "";
$imagePopup->location = "https://your-target-site.com";
$imagePopup->name = "Demo Image Popup";
$imagePopup->popup_style = "over";
$imagePopup->title = "Ad Window";
$imagePopup->tracking_pixel = "";
$imagePopup->width = 300;

$imagePopup->save();

echo $imagePopup;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var updateData = {
  "creative": 234,
  "creative_url": "http://www.smartballoon/images/balloon.jpg",
  "height": 250,
  "html_alt_text": "A big balloon",
  "html_content_below": "",
  "location": "https://your-target-site.com",
  "name": "Demo Image Popup",
  "popup_style": "over",
  "title": "Ad Window",
  "tracking_pixel": "",
  "width": 300
};

// using callbacks
adbutler.popups.images.update(2260, updateData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.popups.images.update(2260, updateData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "image_popup",
  "self": "/v1/popups/image/2260",
  "id": 2260,
  "creative": 234,
  "creative_url": "http://www.smartballoon/images/balloon.jpg",
  "height": 250,
  "html_alt_text": "A big balloon",
  "html_content_below": "",
  "location": "https://your-target-site.com",
  "name": "Demo Image Popup",
  "popup_style": "over",
  "title": "Ad Window",
  "tracking_pixel": "",
  "width": 300
}
AdButler\ImagePopup JSON: {
  "object": "image_popup",
  "self": "/v1/popups/image/2260",
  "id": 2260,
  "creative": 234,
  "creative_url": "http://www.smartballoon/images/balloon.jpg",
  "height": 250,
  "html_alt_text": "A big balloon",
  "html_content_below": "",
  "location": "https://your-target-site.com",
  "name": "Demo Image Popup",
  "popup_style": "over",
  "title": "Ad Window",
  "tracking_pixel": "",
  "width": 300
}

You can update a specific image popup account by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the image popup creation request.

Field Type Description

name

string

A descriptive name of the image popup. We recommend using a naming convention that is consistent, relevant, and clear.

title

string

The user visible title that will appear on the frame of the popup window.

width

integer

The width of the popup window containing the advertisement (typically the same width as the advertisement itself).

height

integer

The height of the popup window containing the advertisement (typically the same height as the advertisement itself).

creative

integer

The image creative identifier (ID). It must be a valid ID if no creative_url is given.

creative_url

integer

Specify the URL of an image file (PNG, JPEG, or GIF). creative must be given if this is left empty.

location

string

A URL indicating where you want the user to go when they click on the popup. This field can be left blank.

tracking_pixel

string

A URL of an image, typically 1x1 pixel in size, intended for impression tracking purposes. It is loaded alongside the popup allowing an external system to monitor impressions.

html_content_below

string

The HTML content to appear below the image banner.

html_alt_text

string

Text to display if the image fails to load. This is intended for use by the Assistive Technologies.

popup_style

string

Whether this popup should appear in front of the page or behind it. Possible values are over or under.

Returns

Returns an image_popup object if the request succeeded, or an error if something went terribly wrong.

Delete an image popup

Definition

DELETE https://api.adbutler.com/v1/popups/image/{IMAGE-POPUP-ID}
\AdButler\ImagePopup->delete()
adbutler.popups.images.delete()

Example Request

curl "https://api.adbutler.com/v1/popups/image/2260" \
  -H "Authorization: Basic {API_KEY}" \
  -X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$imagePopup = \AdButler\ImagePopup::retrieve( 2260 );
$imagePopup->delete();

echo $imagePopup;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.popups.images.delete(2260, function(err, response) {
  console.log(response);
});

// using promises
adbutler.popups.images.delete(2260).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "id": 2260,
  "delete": true
}
AdButler\ImagePopup JSON: {
  "id": 2260,
  "delete": true
}

Permanently deletes an image popup. if successful, this operation cannot be undone so be very sure when deleting one. Also immediately stops serving any ads belonging to this image popup account.

Returns

Returns an image popup ID if the request succeeded, or an error if something went terribly wrong.

List all image popups

Definition

GET https://api.adbutler.com/v1/popups/image
\AdButler\ImagePopup::retrieveAll()
adbutler.popups.images.list()

Example Request

curl "https://api.adbutler.com/v1/popups/image?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$imagePopup = \AdButler\ImagePopup::retrieveAll(array(
  "limit" => 2
));

echo $imagePopup;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.popups.images.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.popups.images.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/popups/image",
  "data": [
    {
      "object": "image_popup",
      "self": "/v1/popups/image/2222",
      "id": 2222,
      "creative": 234,
      "creative_url": "http://www.smartballoon/images/balloon.jpg",
      "height": 250,
      "html_alt_text": "A big balloon",
      "html_content_below": "",
      "location": "https://your-target-site.com",
      "name": "Demo Image Popup",
      "popup_style": "over",
      "title": "Ad Window",
      "tracking_pixel": "",
      "width": 300
    },
    {
      "object": "image_popup",
      "self": "/v1/popups/image/2225",
      "id": 2225,
      "creative": 234,
      "creative_url": "http://www.smartballoon/images/balloon.jpg",
      "height": 250,
      "html_alt_text": "A big balloon",
      "html_content_below": "",
      "location": "https://your-target-site.com",
      "name": "Demo Image Popup",
      "popup_style": "over",
      "title": "Ad Window",
      "tracking_pixel": "",
      "width": 300
    }
  ]
}
AdButler\ImagePopup JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/popups/image",
  "data": [
    {
      "object": "image_popup",
      "self": "/v1/popups/image/2222",
      "id": 2222,
      "creative": 234,
      "creative_url": "http://www.smartballoon/images/balloon.jpg",
      "height": 250,
      "html_alt_text": "A big balloon",
      "html_content_below": "",
      "location": "https://your-target-site.com",
      "name": "Demo Image Popup",
      "popup_style": "over",
      "title": "Ad Window",
      "tracking_pixel": "",
      "width": 300
    },
    {
      "object": "image_popup",
      "self": "/v1/popups/image/2225",
      "id": 2225,
      "creative": 234,
      "creative_url": "http://www.smartballoon/images/balloon.jpg",
      "height": 250,
      "html_alt_text": "A big balloon",
      "html_content_below": "",
      "location": "https://your-target-site.com",
      "name": "Demo Image Popup",
      "popup_style": "over",
      "title": "Ad Window",
      "tracking_pixel": "",
      "width": 300
    }
  ]
}

Returns a list of all the image popup accounts. Most recent image popup accounts appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is an image_popup object, and if no objects were found the list will be empty.


Flash Popups

Introduction

A popup banner can catch your users attention by causing a separate window to appear with an advertisement in it. These ads can appear behind or in front of the content currently being browsed.

Popups require an option in the zone they belong to do be enabled to take effect.

The flash_popup response object has the following fields.

Example Response

{
  "object": "flash_popup",
  "self": "/v1/popups/flash/2261",
  "id": 2261,
  "creative": 45254,
  "creative_url": null,
  "flash_html": "<object width=\"300\" height=\"250\" id=\"movie_5474863\">\\r\\n<param name=\"wmode\" value=\"opaque\">\\r\\n<param name=\"quality\" value=\"high\">\\r\\n<param name=\"version\" value=\"7\">\\r\\n<param name=\"allowScriptAccess\" value=\"always\">\\r\\n<param name=\"movie\" value=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\">\\r\\n<embed width=\"300\" height=\"250\" src=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\" wmode=\"opaque\" quality=\"high\" version=\"7\" allowScriptAccess=\"always\" type=\"application/x-shockwave-flash\">\\r\\n</object>",
  "height": 250,
  "html_content_below": "",
  "location": "https://your-target-site.com",
  "mode": "opaque",
  "name": "Demo Flash Popup",
  "popup_style": "over",
  "quality": "high",
  "title": "Ad Window",
  "tracking_pixel": "",
  "version": 7,
  "width": 300
}
AdButler\FlashPopup JSON: {
  "object": "flash_popup",
  "self": "/v1/popups/flash/2261",
  "id": 2261,
  "creative": 45254,
  "creative_url": null,
  "flash_html": "<object width=\"300\" height=\"250\" id=\"movie_5474863\">\\r\\n<param name=\"wmode\" value=\"opaque\">\\r\\n<param name=\"quality\" value=\"high\">\\r\\n<param name=\"version\" value=\"7\">\\r\\n<param name=\"allowScriptAccess\" value=\"always\">\\r\\n<param name=\"movie\" value=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\">\\r\\n<embed width=\"300\" height=\"250\" src=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\" wmode=\"opaque\" quality=\"high\" version=\"7\" allowScriptAccess=\"always\" type=\"application/x-shockwave-flash\">\\r\\n</object>",
  "height": 250,
  "html_content_below": "",
  "location": "https://your-target-site.com",
  "mode": "opaque",
  "name": "Demo Flash Popup",
  "popup_style": "over",
  "quality": "high",
  "title": "Ad Window",
  "tracking_pixel": "",
  "version": 7,
  "width": 300
}
Field Type Description

object

string

A string denoting the object type which is always popup_flash for the current resource.

self

string

The relative URL of the current resource which is always of the form /v1/popups-flash/{FLASH_POPUP_ID}.

id

integer

The current resource identifier (ID).

name

string

Name of the Custom HTML Popup

title

string

Title of the popup

location

string

The location to redirect to

width

integer

Width of the popup

height

integer

Height of the popup

tracking_pixel

string

The pixel URL

html_content_below

string

HTML below the main HTML

popup_style

string

Where the popup should appear

flash_html

string

The generated flash HTML

creative

integer

The creative ID

creative_url

NULL

The creative URL

mode

string

Flash mode

quality

string

Flash quality

version

integer

Flash version

Create a flash popup

Definition

POST https://api.adbutler.com/v1/popups/flash
\AdButler\FlashPopup::create()
adbutler.popups.flash.create()

Example Request

curl "https://api.adbutler.com/v1/popups/flash" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{  
        "creative": 45254,
        "creative_url": null,
        "height": 250,
        "html_content_below": "",
        "location": "https://your-target-site.com",
        "mode": "opaque",
        "name": "Demo Flash Popup",
        "popup_style": "over",
        "quality": "high",
        "title": "Ad Window",
        "tracking_pixel": "",
        "version": 7,
        "width": 300
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$flashPopup = \AdButler\FlashPopup::create(array(
  "creative" => 45254,
  "creative_url" => null,
  "height" => 250,
  "html_content_below" => "",
  "location" => "https://your-target-site.com",
  "mode" => "opaque",
  "name" => "Demo Flash Popup",
  "popup_style" => "over",
  "quality" => "high",
  "title" => "Ad Window",
  "tracking_pixel" => "",
  "version" => 7,
  "width" => 300
));

echo $flashPopup;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var postData = {
  "creative": 45254,
  "creative_url": null,
  "height": 250,
  "html_content_below": "",
  "location": "https://your-target-site.com",
  "mode": "opaque",
  "name": "Demo Flash Popup",
  "popup_style": "over",
  "quality": "high",
  "title": "Ad Window",
  "tracking_pixel": "",
  "version": 7,
  "width": 300
};

// using callbacks
adbutler.popups.flash.create(postData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.popups.flash.create(postData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "flash_popup",
  "self": "/v1/popups/flash/2261",
  "id": 2261,
  "creative": 45254,
  "creative_url": null,
  "flash_html": "<object width=\"300\" height=\"250\" id=\"movie_5474863\">\\r\\n<param name=\"wmode\" value=\"opaque\">\\r\\n<param name=\"quality\" value=\"high\">\\r\\n<param name=\"version\" value=\"7\">\\r\\n<param name=\"allowScriptAccess\" value=\"always\">\\r\\n<param name=\"movie\" value=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\">\\r\\n<embed width=\"300\" height=\"250\" src=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\" wmode=\"opaque\" quality=\"high\" version=\"7\" allowScriptAccess=\"always\" type=\"application/x-shockwave-flash\">\\r\\n</object>",
  "height": 250,
  "html_content_below": "",
  "location": "https://your-target-site.com",
  "mode": "opaque",
  "name": "Demo Flash Popup",
  "popup_style": "over",
  "quality": "high",
  "title": "Ad Window",
  "tracking_pixel": "",
  "version": 7,
  "width": 300
}
AdButler\FlashPopup JSON: {
  "object": "flash_popup",
  "self": "/v1/popups/flash/2261",
  "id": 2261,
  "creative": 45254,
  "creative_url": null,
  "flash_html": "<object width=\"300\" height=\"250\" id=\"movie_5474863\">\\r\\n<param name=\"wmode\" value=\"opaque\">\\r\\n<param name=\"quality\" value=\"high\">\\r\\n<param name=\"version\" value=\"7\">\\r\\n<param name=\"allowScriptAccess\" value=\"always\">\\r\\n<param name=\"movie\" value=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\">\\r\\n<embed width=\"300\" height=\"250\" src=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\" wmode=\"opaque\" quality=\"high\" version=\"7\" allowScriptAccess=\"always\" type=\"application/x-shockwave-flash\">\\r\\n</object>",
  "height": 250,
  "html_content_below": "",
  "location": "https://your-target-site.com",
  "mode": "opaque",
  "name": "Demo Flash Popup",
  "popup_style": "over",
  "quality": "high",
  "title": "Ad Window",
  "tracking_pixel": "",
  "version": 7,
  "width": 300
}

Creates a new flash popup.

Field Type Description

name*

string

A descriptive name of the flash popup. We recommend using a naming convention that is consistent, relevant, and clear.

title*

string

The user visible title that will appear on the frame of the popup window.

width*

string

The width of the popup window containing the advertisement (typically the same width as the advertisement itself).

height*

string

The height of the popup window containing the advertisement (typically the same height as the advertisement itself).

creative

string

The flash creative identifier (ID). It must be a valid ID if no creative_url is given.

creative_url

string

Specify the URL of a flash (SWF) file. creative must be given if this is left empty.

location

string

A URL indicating where you want the user to go when they click on the popup. This field can be left blank.

tracking_pixel

string

A URL of an image, typically 1x1 pixel in size, intended for impression tracking purposes. It is loaded alongside the popup allowing an external system to monitor impressions.

html_content_below

string

The HTML content to appear below the flash banner.

popup_style

string

Whether this popup should appear in front of the page or behind it. Possible values are over or under.

mode

string

Sets the window mode property of the SWF file for transparency, layering, positioning, and rendering in the browser. It can be one of window, opaque, or transparent.

  • Window: The SWF content plays in its own rectangle ("window") on a web page. You cannot explicitly specify if SWF content appears above or below other HTML elements on the page.
  • Opaque: The SWF content is layered together with other HTML elements on the page. The SWF file is opaque and hides everything layered behind it on the page. This option reduces playback performance compared to the window mode.
  • Transparent: The SWF content is layered together with other HTML elements on the page. The SWF file background color is transparent. HTML elements beneath the SWF file are visible through any transparent areas of the SWF. This option reduces playback performance compared to the window mode.

More information can be found here.

quality

string

Possible values are low, medium, or high.

  • Low favors playback speed over appearance and never uses anti-aliasing.
  • Medium applies some anti-aliasing and does not smooth bitmaps.
  • High favors appearance over playback speed and always applies anti-aliasing. If the movie has animation, bitmaps are not smoothed.

More information can be found here.

version

string

Flash player version number ranging between 5 and 100. Defaults to 7.

* = required field

Returns

Returns a flash_popup object if the request succeeded, or an error if something went terribly wrong.

Retrieve a flash popup

Definition

GET https://api.adbutler.com/v1/popups/flash/{FLASH-POPUP-ID}
\AdButler\FlashPopup::retrieve()
adbutler.popups.flash.retrieve()

Example Request

curl "https://api.adbutler.com/v1/popups/flash/2261" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$flashPopup = \AdButler\FlashPopup::retrieve( 2261 );

echo $flashPopup;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.popups.flash.read(2261, function(err, response) {
  console.log(response);
});

// using promises
adbutler.popups.flash.read(2261).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "flash_popup",
  "self": "/v1/popups/flash/2261",
  "id": 2261,
  "creative": 45254,
  "creative_url": null,
  "flash_html": "<object width=\"300\" height=\"250\" id=\"movie_5474863\">\\r\\n<param name=\"wmode\" value=\"opaque\">\\r\\n<param name=\"quality\" value=\"high\">\\r\\n<param name=\"version\" value=\"7\">\\r\\n<param name=\"allowScriptAccess\" value=\"always\">\\r\\n<param name=\"movie\" value=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\">\\r\\n<embed width=\"300\" height=\"250\" src=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\" wmode=\"opaque\" quality=\"high\" version=\"7\" allowScriptAccess=\"always\" type=\"application/x-shockwave-flash\">\\r\\n</object>",
  "height": 250,
  "html_content_below": "",
  "location": "https://your-target-site.com",
  "mode": "opaque",
  "name": "Demo Flash Popup",
  "popup_style": "over",
  "quality": "high",
  "title": "Ad Window",
  "tracking_pixel": "",
  "version": 7,
  "width": 300
}
AdButler\FlashPopup JSON: {
  "object": "flash_popup",
  "self": "/v1/popups/flash/2261",
  "id": 2261,
  "creative": 45254,
  "creative_url": null,
  "flash_html": "<object width=\"300\" height=\"250\" id=\"movie_5474863\">\\r\\n<param name=\"wmode\" value=\"opaque\">\\r\\n<param name=\"quality\" value=\"high\">\\r\\n<param name=\"version\" value=\"7\">\\r\\n<param name=\"allowScriptAccess\" value=\"always\">\\r\\n<param name=\"movie\" value=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\">\\r\\n<embed width=\"300\" height=\"250\" src=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\" wmode=\"opaque\" quality=\"high\" version=\"7\" allowScriptAccess=\"always\" type=\"application/x-shockwave-flash\">\\r\\n</object>",
  "height": 250,
  "html_content_below": "",
  "location": "https://your-target-site.com",
  "mode": "opaque",
  "name": "Demo Flash Popup",
  "popup_style": "over",
  "quality": "high",
  "title": "Ad Window",
  "tracking_pixel": "",
  "version": 7,
  "width": 300
}

You can retrieve the information about an existing flash popup by giving the flash popup ID that was returned in the flash popup object upon creation. You will see at the most 10 flash popups in the response. You can change this default limit by appending ?limit=25 if you want this request to return 25 popups_flash.

Returns

Returns a flash_popup object if the request succeeded, or an error if something went terribly wrong.

Update a flash popup

Definition

PUT https://api.adbutler.com/v1/popups/flash/{FLASH-POPUP-ID}
\AdButler\FlashPopup->save()
adbutler.popups.flash.update()

Example Request

curl "https://api.adbutler.com/v1/popups/flash/2261" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{  
        "creative": 45254,
        "creative_url": null,
        "height": 250,
        "html_content_below": "",
        "location": "https://your-target-site.com",
        "mode": "opaque",
        "name": "Demo Flash Popup",
        "popup_style": "over",
        "quality": "high",
        "title": "Ad Window",
        "tracking_pixel": "",
        "version": 7,
        "width": 300
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$flashPopup = \AdButler\FlashPopup::retrieve( 2261 );

$flashPopup->creative = 45254;
$flashPopup->creative_url = null;
$flashPopup->height = 250;
$flashPopup->html_content_below = "";
$flashPopup->location = "https://your-target-site.com";
$flashPopup->mode = "opaque";
$flashPopup->name = "Demo Flash Popup";
$flashPopup->popup_style = "over";
$flashPopup->quality = "high";
$flashPopup->title = "Ad Window";
$flashPopup->tracking_pixel = "";
$flashPopup->version = 7;
$flashPopup->width = 300;

$flashPopup->save();

echo $flashPopup;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var updateData = {
  "creative": 45254,
  "creative_url": null,
  "height": 250,
  "html_content_below": "",
  "location": "https://your-target-site.com",
  "mode": "opaque",
  "name": "Demo Flash Popup",
  "popup_style": "over",
  "quality": "high",
  "title": "Ad Window",
  "tracking_pixel": "",
  "version": 7,
  "width": 300
};

// using callbacks
adbutler.popups.flash.update(2261, updateData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.popups.flash.update(2261, updateData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "flash_popup",
  "self": "/v1/popups/flash/2261",
  "id": 2261,
  "creative": 45254,
  "creative_url": null,
  "flash_html": "<object width=\"300\" height=\"250\" id=\"movie_5474863\">\\r\\n<param name=\"wmode\" value=\"opaque\">\\r\\n<param name=\"quality\" value=\"high\">\\r\\n<param name=\"version\" value=\"7\">\\r\\n<param name=\"allowScriptAccess\" value=\"always\">\\r\\n<param name=\"movie\" value=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\">\\r\\n<embed width=\"300\" height=\"250\" src=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\" wmode=\"opaque\" quality=\"high\" version=\"7\" allowScriptAccess=\"always\" type=\"application/x-shockwave-flash\">\\r\\n</object>",
  "height": 250,
  "html_content_below": "",
  "location": "https://your-target-site.com",
  "mode": "opaque",
  "name": "Demo Flash Popup",
  "popup_style": "over",
  "quality": "high",
  "title": "Ad Window",
  "tracking_pixel": "",
  "version": 7,
  "width": 300
}
AdButler\FlashPopup JSON: {
  "object": "flash_popup",
  "self": "/v1/popups/flash/2261",
  "id": 2261,
  "creative": 45254,
  "creative_url": null,
  "flash_html": "<object width=\"300\" height=\"250\" id=\"movie_5474863\">\\r\\n<param name=\"wmode\" value=\"opaque\">\\r\\n<param name=\"quality\" value=\"high\">\\r\\n<param name=\"version\" value=\"7\">\\r\\n<param name=\"allowScriptAccess\" value=\"always\">\\r\\n<param name=\"movie\" value=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\">\\r\\n<embed width=\"300\" height=\"250\" src=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\" wmode=\"opaque\" quality=\"high\" version=\"7\" allowScriptAccess=\"always\" type=\"application/x-shockwave-flash\">\\r\\n</object>",
  "height": 250,
  "html_content_below": "",
  "location": "https://your-target-site.com",
  "mode": "opaque",
  "name": "Demo Flash Popup",
  "popup_style": "over",
  "quality": "high",
  "title": "Ad Window",
  "tracking_pixel": "",
  "version": 7,
  "width": 300
}

You can update a specific flash popup account by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the flash popup creation request.

Field Type Description

name

string

A descriptive name of the flash popup. We recommend using a naming convention that is consistent, relevant, and clear.

title

string

The user visible title that will appear on the frame of the popup window.

width

string

The width of the popup window containing the advertisement (typically the same width as the advertisement itself).

height

string

The height of the popup window containing the advertisement (typically the same height as the advertisement itself).

creative

string

The flash creative identifier (ID). It must be a valid ID if no creative_url is given.

creative_url

string

Specify the URL of a flash (SWF) file. creative must be given if this is left empty.

location

string

A URL indicating where you want the user to go when they click on the popup. This field can be left blank.

tracking_pixel

string

A URL of an image, typically 1x1 pixel in size, intended for impression tracking purposes. It is loaded alongside the popup allowing an external system to monitor impressions.

html_content_below

string

The HTML content to appear below the flash banner.

popup_style

string

Whether this popup should appear in front of the page or behind it. Possible values are over or under.

mode

string

Sets the window mode property of the SWF file for transparency, layering, positioning, and rendering in the browser. It can be one of window, opaque, or transparent.

  • Window: The SWF content plays in its own rectangle ("window") on a web page. You cannot explicitly specify if SWF content appears above or below other HTML elements on the page.
  • Opaque: The SWF content is layered together with other HTML elements on the page. The SWF file is opaque and hides everything layered behind it on the page. This option reduces playback performance compared to the window mode.
  • Transparent: The SWF content is layered together with other HTML elements on the page. The SWF file background color is transparent. HTML elements beneath the SWF file are visible through any transparent areas of the SWF. This option reduces playback performance compared to the window mode.

More information can be found here.

quality

string

Possible values are low, medium, or high.

  • Low favors playback speed over appearance and never uses anti-aliasing.
  • Medium applies some anti-aliasing and does not smooth bitmaps.
  • High favors appearance over playback speed and always applies anti-aliasing. If the movie has animation, bitmaps are not smoothed.

More information can be found here.

version

string

Flash player version number ranging between 5 and 100. Defaults to 7.

Returns

Returns a flash_popup object if the request succeeded, or an error if something went terribly wrong.

Delete a flash popup

Definition

DELETE https://api.adbutler.com/v1/popups/flash/{FLASH-POPUP-ID}
\AdButler\FlashPopup->delete()
adbutler.popups.flash.delete()

Example Request

curl "https://api.adbutler.com/v1/popups/flash/2261" \
  -H "Authorization: Basic {API_KEY}" \
  -X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$flashPopup = \AdButler\FlashPopup::retrieve( 2261 );
$flashPopup->delete();

echo $flashPopup;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.popups.flash.delete(2261, function(err, response) {
  console.log(response);
});

// using promises
adbutler.popups.flash.delete(2261).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "id": 2261,
  "delete": true
}
AdButler\FlashPopup JSON: {
  "id": 2261,
  "delete": true
}

Permanently deletes a flash popup. if successful, this operation cannot be undone so be very sure when deleting one. Also immediately stops serving any ads belonging to this flash popup account.

Returns

Returns a flash popup ID if the request succeeded, or an error if something went terribly wrong.

List all flash popups

Definition

GET https://api.adbutler.com/v1/popups/flash
\AdButler\FlashPopup::retrieveAll()
adbutler.popups.flash.list()

Example Request

curl "https://api.adbutler.com/v1/popups/flash?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$flashPopup = \AdButler\FlashPopup::retrieveAll(array(
  "limit" => 2
));

echo $flashPopup;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.popups.flash.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.popups.flash.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/popups/flash",
  "data": [
    {
      "object": "flash_popup",
      "self": "/v1/popups/flash/2223",
      "id": 2223,
      "creative": 45254,
      "creative_url": null,
      "flash_html": "<object width=\"300\" height=\"250\" id=\"movie_5474863\">\\r\\n<param name=\"wmode\" value=\"opaque\">\\r\\n<param name=\"quality\" value=\"high\">\\r\\n<param name=\"version\" value=\"7\">\\r\\n<param name=\"allowScriptAccess\" value=\"always\">\\r\\n<param name=\"movie\" value=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\">\\r\\n<embed width=\"300\" height=\"250\" src=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\" wmode=\"opaque\" quality=\"high\" version=\"7\" allowScriptAccess=\"always\" type=\"application/x-shockwave-flash\">\\r\\n</object>",
      "height": 250,
      "html_content_below": "",
      "location": "https://your-target-site.com",
      "mode": "opaque",
      "name": "Demo Flash Popup",
      "popup_style": "over",
      "quality": "high",
      "title": "Ad Window",
      "tracking_pixel": "",
      "version": 7,
      "width": 300
    },
    {
      "object": "flash_popup",
      "self": "/v1/popups/flash/2226",
      "id": 2226,
      "creative": 45254,
      "creative_url": null,
      "flash_html": "<object width=\"300\" height=\"250\" id=\"movie_5474863\">\\r\\n<param name=\"wmode\" value=\"opaque\">\\r\\n<param name=\"quality\" value=\"high\">\\r\\n<param name=\"version\" value=\"7\">\\r\\n<param name=\"allowScriptAccess\" value=\"always\">\\r\\n<param name=\"movie\" value=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\">\\r\\n<embed width=\"300\" height=\"250\" src=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\" wmode=\"opaque\" quality=\"high\" version=\"7\" allowScriptAccess=\"always\" type=\"application/x-shockwave-flash\">\\r\\n</object>",
      "height": 250,
      "html_content_below": "",
      "location": "https://your-target-site.com",
      "mode": "opaque",
      "name": "Demo Flash Popup",
      "popup_style": "over",
      "quality": "high",
      "title": "Ad Window",
      "tracking_pixel": "",
      "version": 7,
      "width": 300
    }
  ]
}
AdButler\FlashPopup JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/popups/flash",
  "data": [
    {
      "object": "flash_popup",
      "self": "/v1/popups/flash/2223",
      "id": 2223,
      "creative": 45254,
      "creative_url": null,
      "flash_html": "<object width=\"300\" height=\"250\" id=\"movie_5474863\">\\r\\n<param name=\"wmode\" value=\"opaque\">\\r\\n<param name=\"quality\" value=\"high\">\\r\\n<param name=\"version\" value=\"7\">\\r\\n<param name=\"allowScriptAccess\" value=\"always\">\\r\\n<param name=\"movie\" value=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\">\\r\\n<embed width=\"300\" height=\"250\" src=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\" wmode=\"opaque\" quality=\"high\" version=\"7\" allowScriptAccess=\"always\" type=\"application/x-shockwave-flash\">\\r\\n</object>",
      "height": 250,
      "html_content_below": "",
      "location": "https://your-target-site.com",
      "mode": "opaque",
      "name": "Demo Flash Popup",
      "popup_style": "over",
      "quality": "high",
      "title": "Ad Window",
      "tracking_pixel": "",
      "version": 7,
      "width": 300
    },
    {
      "object": "flash_popup",
      "self": "/v1/popups/flash/2226",
      "id": 2226,
      "creative": 45254,
      "creative_url": null,
      "flash_html": "<object width=\"300\" height=\"250\" id=\"movie_5474863\">\\r\\n<param name=\"wmode\" value=\"opaque\">\\r\\n<param name=\"quality\" value=\"high\">\\r\\n<param name=\"version\" value=\"7\">\\r\\n<param name=\"allowScriptAccess\" value=\"always\">\\r\\n<param name=\"movie\" value=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\">\\r\\n<embed width=\"300\" height=\"250\" src=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\" wmode=\"opaque\" quality=\"high\" version=\"7\" allowScriptAccess=\"always\" type=\"application/x-shockwave-flash\">\\r\\n</object>",
      "height": 250,
      "html_content_below": "",
      "location": "https://your-target-site.com",
      "mode": "opaque",
      "name": "Demo Flash Popup",
      "popup_style": "over",
      "quality": "high",
      "title": "Ad Window",
      "tracking_pixel": "",
      "version": 7,
      "width": 300
    }
  ]
}

Returns a list of all the flash popup accounts. Most recent flash popup accounts appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is a flash_popup object, and if no objects were found the list will be empty.


Custom HTML Popups

Introduction

A popup banner can catch your users attention by causing a separate window to appear with an advertisement in it. These ads can appear behind or in front of the content currently being browsed.

Popups require an option in the zone they belong to do be enabled to take effect.

The custom_html_popup response object has the following fields.

Example Response

{
  "object": "custom_html_popup",
  "self": "/v1/popups/custom-html/2262",
  "id": 2262,
  "name": "Demo Custom HTML Popup",
  "title": "Ad Window",
  "location": "https://your-target-site.com",
  "width": 300,
  "height": 250,
  "tracking_pixel": "",
  "html_content_below": "",
  "popup_style": "over",
  "custom_html": "<p>Hello world!</p>"
}
AdButler\CustomHTMLPopup JSON: {
  "object": "custom_html_popup",
  "self": "/v1/popups/custom-html/2262",
  "id": 2262,
  "name": "Demo Custom HTML Popup",
  "title": "Ad Window",
  "location": "https://your-target-site.com",
  "width": 300,
  "height": 250,
  "tracking_pixel": "",
  "html_content_below": "",
  "popup_style": "over",
  "custom_html": "<p>Hello world!</p>"
}
Field Type Description

object

string

A string denoting the object type which is always popup_custom_html for the current resource.

self

string

The relative URL of the current resource which is always of the form /v1/popups-custom-html/{CUSTOM_HTML_POPUP_ID}.

id

integer

The current resource identifier (ID).

name

string

Name of the Custom HTML Popup

title

string

Title of the popup

location

string

The location to redirect to

width

integer

Width of the popup

height

integer

Height of the popup

tracking_pixel

string

The pixel URL

html_content_below

string

HTML below the main HTML

popup_style

string

Where the popup should appear

custom_html

string

Custom HTML

Create a custom HTML popup

Definition

POST https://api.adbutler.com/v1/popups/custom-html
\AdButler\CustomHTMLPopup::create()
adbutler.popups.customHTML.create()

Example Request

curl "https://api.adbutler.com/v1/popups/custom-html" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{  
        "name": "Demo Custom HTML Popup",
        "title": "Ad Window",
        "location": "https://your-target-site.com",
        "width": 300,
        "height": 250,
        "tracking_pixel": "",
        "html_content_below": "",
        "popup_style": "over",
        "custom_html": "<p>Hello world!</p>"
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$customHTMLPopup = \AdButler\CustomHTMLPopup::create(array(
  "name" => "Demo Custom HTML Popup",
  "title" => "Ad Window",
  "location" => "https://your-target-site.com",
  "width" => 300,
  "height" => 250,
  "tracking_pixel" => "",
  "html_content_below" => "",
  "popup_style" => "over",
  "custom_html" => "<p>Hello world!</p>"
));

echo $customHTMLPopup;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var postData = {
  "name": "Demo Custom HTML Popup",
  "title": "Ad Window",
  "location": "https://your-target-site.com",
  "width": 300,
  "height": 250,
  "tracking_pixel": "",
  "html_content_below": "",
  "popup_style": "over",
  "custom_html": "<p>Hello world!</p>"
};

// using callbacks
adbutler.popups.customHTML.create(postData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.popups.customHTML.create(postData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "custom_html_popup",
  "self": "/v1/popups/custom-html/2262",
  "id": 2262,
  "name": "Demo Custom HTML Popup",
  "title": "Ad Window",
  "location": "https://your-target-site.com",
  "width": 300,
  "height": 250,
  "tracking_pixel": "",
  "html_content_below": "",
  "popup_style": "over",
  "custom_html": "<p>Hello world!</p>"
}
AdButler\CustomHTMLPopup JSON: {
  "object": "custom_html_popup",
  "self": "/v1/popups/custom-html/2262",
  "id": 2262,
  "name": "Demo Custom HTML Popup",
  "title": "Ad Window",
  "location": "https://your-target-site.com",
  "width": 300,
  "height": 250,
  "tracking_pixel": "",
  "html_content_below": "",
  "popup_style": "over",
  "custom_html": "<p>Hello world!</p>"
}

Creates a new custom HTML popup.

Field Type Description

name*

string

A descriptive name of the custom HTML popup. We recommend using a naming convention that is consistent, relevant, and clear.

title*

string

The user visible title that will appear on the frame of the popup window.

width*

integer

The width of the popup window containing the advertisement (typically the same width as the advertisement itself).

height*

integer

The height of the popup window containing the advertisement (typically the same height as the advertisement itself).

custom_html*

integer

The HTML content of the popup.

location

string

A URL indicating where you want the user to go when they click on the popup. This field can be left blank.

tracking_pixel

string

A URL of an image, typically 1x1 pixel in size, intended for impression tracking purposes. It is loaded alongside the popup allowing an external system to monitor impressions.

html_content_below

string

The HTML content to appear below the custom HTML popup.

popup_style

string

Whether this popup should appear in front of the page or behind it. Possible values are over or under.

* = required field

Returns

Returns a custom_html_popup object if the request succeeded, or an error if something went terribly wrong.

Retrieve a custom HTML popup

Definition

GET https://api.adbutler.com/v1/popups/custom-html/{CUSTOM-HTML-POPUP-ID}
\AdButler\CustomHTMLPopup::retrieve()
adbutler.popups.customHTML.retrieve()

Example Request

curl "https://api.adbutler.com/v1/popups/custom-html/2262" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$customHTMLPopup = \AdButler\CustomHTMLPopup::retrieve( 2262 );

echo $customHTMLPopup;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.popups.customHTML.read(2262, function(err, response) {
  console.log(response);
});

// using promises
adbutler.popups.customHTML.read(2262).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "custom_html_popup",
  "self": "/v1/popups/custom-html/2262",
  "id": 2262,
  "name": "Demo Custom HTML Popup",
  "title": "Ad Window",
  "location": "https://your-target-site.com",
  "width": 300,
  "height": 250,
  "tracking_pixel": "",
  "html_content_below": "",
  "popup_style": "over",
  "custom_html": "<p>Hello world!</p>"
}
AdButler\CustomHTMLPopup JSON: {
  "object": "custom_html_popup",
  "self": "/v1/popups/custom-html/2262",
  "id": 2262,
  "name": "Demo Custom HTML Popup",
  "title": "Ad Window",
  "location": "https://your-target-site.com",
  "width": 300,
  "height": 250,
  "tracking_pixel": "",
  "html_content_below": "",
  "popup_style": "over",
  "custom_html": "<p>Hello world!</p>"
}

You can retrieve the information about an existing custom HTML popup by giving the custom HTML popup ID that was returned in the custom HTML popup object upon creation. You will see at the most 10 custom HTML popups in the response. You can change this default limit by appending ?limit=25 if you want this request to return 25 popups_custom-html.

Returns

Returns a custom_html_popup object if the request succeeded, or an error if something went terribly wrong.

Update a custom HTML popup

Definition

PUT https://api.adbutler.com/v1/popups/custom-html/{CUSTOM-HTML-POPUP-ID}
\AdButler\CustomHTMLPopup->save()
adbutler.popups.customHTML.update()

Example Request

curl "https://api.adbutler.com/v1/popups/custom-html/2262" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{  
        "name": "Demo Custom HTML Popup",
        "title": "Ad Window",
        "location": "https://your-target-site.com",
        "width": 300,
        "height": 250,
        "tracking_pixel": "",
        "html_content_below": "",
        "popup_style": "over",
        "custom_html": "<p>Hello world!</p>"
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$customHTMLPopup = \AdButler\CustomHTMLPopup::retrieve( 2262 );

$customHTMLPopup->name = "Demo Custom HTML Popup";
$customHTMLPopup->title = "Ad Window";
$customHTMLPopup->location = "https://your-target-site.com";
$customHTMLPopup->width = 300;
$customHTMLPopup->height = 250;
$customHTMLPopup->tracking_pixel = "";
$customHTMLPopup->html_content_below = "";
$customHTMLPopup->popup_style = "over";
$customHTMLPopup->custom_html = "<p>Hello world!</p>";

$customHTMLPopup->save();

echo $customHTMLPopup;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var updateData = {
  "name": "Demo Custom HTML Popup",
  "title": "Ad Window",
  "location": "https://your-target-site.com",
  "width": 300,
  "height": 250,
  "tracking_pixel": "",
  "html_content_below": "",
  "popup_style": "over",
  "custom_html": "<p>Hello world!</p>"
};

// using callbacks
adbutler.popups.customHTML.update(2262, updateData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.popups.customHTML.update(2262, updateData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "custom_html_popup",
  "self": "/v1/popups/custom-html/2262",
  "id": 2262,
  "name": "Demo Custom HTML Popup",
  "title": "Ad Window",
  "location": "https://your-target-site.com",
  "width": 300,
  "height": 250,
  "tracking_pixel": "",
  "html_content_below": "",
  "popup_style": "over",
  "custom_html": "<p>Hello world!</p>"
}
AdButler\CustomHTMLPopup JSON: {
  "object": "custom_html_popup",
  "self": "/v1/popups/custom-html/2262",
  "id": 2262,
  "name": "Demo Custom HTML Popup",
  "title": "Ad Window",
  "location": "https://your-target-site.com",
  "width": 300,
  "height": 250,
  "tracking_pixel": "",
  "html_content_below": "",
  "popup_style": "over",
  "custom_html": "<p>Hello world!</p>"
}

You can update a specific custom HTML popup account by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the custom HTML popup creation request.

Field Type Description

name

string

A descriptive name of the custom HTML popup. We recommend using a naming convention that is consistent, relevant, and clear.

title

string

The user visible title that will appear on the frame of the popup window.

width

integer

The width of the popup window containing the advertisement (typically the same width as the advertisement itself).

height

integer

The height of the popup window containing the advertisement (typically the same height as the advertisement itself).

custom_html

integer

The HTML content of the popup.

location

string

A URL indicating where you want the user to go when they click on the popup. This field can be left blank.

tracking_pixel

string

A URL of an image, typically 1x1 pixel in size, intended for impression tracking purposes. It is loaded alongside the popup allowing an external system to monitor impressions.

html_content_below

string

The HTML content to appear below the custom HTML popup.

popup_style

string

Whether this popup should appear in front of the page or behind it. Possible values are over or under.

Returns

Returns a custom_html_popup object if the request succeeded, or an error if something went terribly wrong.

Delete a custom HTML popup

Definition

DELETE https://api.adbutler.com/v1/popups/custom-html/{CUSTOM-HTML-POPUP-ID}
\AdButler\CustomHTMLPopup->delete()
adbutler.popups.customHTML.delete()

Example Request

curl "https://api.adbutler.com/v1/popups/custom-html/2262" \
  -H "Authorization: Basic {API_KEY}" \
  -X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$customHTMLPopup = \AdButler\CustomHTMLPopup::retrieve( 2262 );
$customHTMLPopup->delete();

echo $customHTMLPopup;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.popups.customHTML.delete(2262, function(err, response) {
  console.log(response);
});

// using promises
adbutler.popups.customHTML.delete(2262).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "id": 2262,
  "delete": true
}
AdButler\CustomHTMLPopup JSON: {
  "id": 2262,
  "delete": true
}

Permanently deletes a custom HTML popup. if successful, this operation cannot be undone so be very sure when deleting one. Also immediately stops serving any ads belonging to this custom HTML popup account.

Returns

Returns a custom HTML popup ID if the request succeeded, or an error if something went terribly wrong.

List all custom HTML popups

Definition

GET https://api.adbutler.com/v1/popups/custom-html
\AdButler\CustomHTMLPopup::retrieveAll()
adbutler.popups.customHTML.list()

Example Request

curl "https://api.adbutler.com/v1/popups/custom-html?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$customHTMLPopup = \AdButler\CustomHTMLPopup::retrieveAll(array(
  "limit" => 2
));

echo $customHTMLPopup;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.popups.customHTML.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.popups.customHTML.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/popups/custom-html",
  "data": [
    {
      "object": "custom_html_popup",
      "self": "/v1/popups/custom-html/2224",
      "id": 2224,
      "name": "Demo Custom HTML Popup",
      "title": "Ad Window",
      "location": "https://your-target-site.com",
      "width": 300,
      "height": 250,
      "tracking_pixel": "",
      "html_content_below": "",
      "popup_style": "over",
      "custom_html": "<p>Hello world!</p>"
    },
    {
      "object": "custom_html_popup",
      "self": "/v1/popups/custom-html/2227",
      "id": 2227,
      "name": "Demo Custom HTML Popup",
      "title": "Ad Window",
      "location": "https://your-target-site.com",
      "width": 300,
      "height": 250,
      "tracking_pixel": "",
      "html_content_below": "",
      "popup_style": "over",
      "custom_html": "<p>Hello world!</p>"
    }
  ]
}
AdButler\CustomHTMLPopup JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/popups/custom-html",
  "data": [
    {
      "object": "custom_html_popup",
      "self": "/v1/popups/custom-html/2224",
      "id": 2224,
      "name": "Demo Custom HTML Popup",
      "title": "Ad Window",
      "location": "https://your-target-site.com",
      "width": 300,
      "height": 250,
      "tracking_pixel": "",
      "html_content_below": "",
      "popup_style": "over",
      "custom_html": "<p>Hello world!</p>"
    },
    {
      "object": "custom_html_popup",
      "self": "/v1/popups/custom-html/2227",
      "id": 2227,
      "name": "Demo Custom HTML Popup",
      "title": "Ad Window",
      "location": "https://your-target-site.com",
      "width": 300,
      "height": 250,
      "tracking_pixel": "",
      "html_content_below": "",
      "popup_style": "over",
      "custom_html": "<p>Hello world!</p>"
    }
  ]
}

Returns a list of all the custom HTML popup accounts. Most recent custom HTML popup accounts appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is a custom_html_popup object, and if no objects were found the list will be empty.


Media Groups

Introduction

Media groups allow you to group creatives together for easier organization and management in your account.

The media_group response object has the following fields.

Example Response

{
  "object": "media_group",
  "self": "/v1/media-groups/716",
  "id": 716,
  "name": "Default"
}
AdButler\MediaGroup JSON: {
  "object": "media_group",
  "self": "/v1/media-groups/716",
  "id": 716,
  "name": "Default"
}
Field Type Description

object

string

A string denoting the object type which is always media_group for the current resource.

self

string

The relative URL of the current resource which is always of the form /v1/media-groups/{MEDIA_GROUP_ID}.

id

integer

The current resource identifier (ID).

name

string

The name of the media group.

Create a media group

Definition

POST https://api.adbutler.com/v1/media-groups
\AdButler\MediaGroup::create()
adbutler.mediaGroups.create()

Example Request

curl "https://api.adbutler.com/v1/media-groups" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{  
        "name": "Default"
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$mediaGroup = \AdButler\MediaGroup::create(array(
  "name" => "Default"
));

echo $mediaGroup;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var postData = {
  "name": "Default"
};

// using callbacks
adbutler.mediaGroups.create(postData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.mediaGroups.create(postData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "media_group",
  "self": "/v1/media-groups/716",
  "id": 716,
  "name": "Default"
}
AdButler\MediaGroup JSON: {
  "object": "media_group",
  "self": "/v1/media-groups/716",
  "id": 716,
  "name": "Default"
}

Creates a new media group.

Field Type Description

name*

string

A descriptive name of the media group.

* = required field

Returns

Returns a media_group object if the request succeeded, or an error if something went terribly wrong.

Retrieve a media group

Definition

GET https://api.adbutler.com/v1/media-groups/{MEDIA-GROUP-ID}
\AdButler\MediaGroup::retrieve()
adbutler.mediaGroups.retrieve()

Example Request

curl "https://api.adbutler.com/v1/media-groups/716" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$mediaGroup = \AdButler\MediaGroup::retrieve( 716 );

echo $mediaGroup;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.mediaGroups.read(716, function(err, response) {
  console.log(response);
});

// using promises
adbutler.mediaGroups.read(716).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "media_group",
  "self": "/v1/media-groups/716",
  "id": 716,
  "name": "Default"
}
AdButler\MediaGroup JSON: {
  "object": "media_group",
  "self": "/v1/media-groups/716",
  "id": 716,
  "name": "Default"
}

You can retrieve the information about an existing media group by giving the media group ID that was returned in the media group object upon creation. You will see at the most 10 media groups in the response. You can change this default limit by appending ?limit=25 if you want this request to return 25 media-groups.

Returns

Returns a media_group object if the request succeeded, or an error if something went terribly wrong.

Update a media group

Definition

PUT https://api.adbutler.com/v1/media-groups/{MEDIA-GROUP-ID}
\AdButler\MediaGroup->save()
adbutler.mediaGroups.update()

Example Request

curl "https://api.adbutler.com/v1/media-groups/716" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{  
        "name": "Default"
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$mediaGroup = \AdButler\MediaGroup::retrieve( 716 );

$mediaGroup->name = "Default";

$mediaGroup->save();

echo $mediaGroup;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var updateData = {
  "name": "Default"
};

// using callbacks
adbutler.mediaGroups.update(716, updateData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.mediaGroups.update(716, updateData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "media_group",
  "self": "/v1/media-groups/716",
  "id": 716,
  "name": "Default"
}
AdButler\MediaGroup JSON: {
  "object": "media_group",
  "self": "/v1/media-groups/716",
  "id": 716,
  "name": "Default"
}

You can update a specific media group by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the media group creation request.

Field Type Description

name

string

A descriptive name of the media group.

Returns

Returns a media_group object if the request succeeded, or an error if something went terribly wrong.

Delete a media group

Definition

DELETE https://api.adbutler.com/v1/media-groups/{MEDIA-GROUP-ID}
\AdButler\MediaGroup->delete()
adbutler.mediaGroups.delete()

Example Request

curl "https://api.adbutler.com/v1/media-groups/716" \
  -H "Authorization: Basic {API_KEY}" \
  -X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$mediaGroup = \AdButler\MediaGroup::retrieve( 716 );
$mediaGroup->delete();

echo $mediaGroup;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.mediaGroups.delete(716, function(err, response) {
  console.log(response);
});

// using promises
adbutler.mediaGroups.delete(716).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "id": 716,
  "delete": true
}
AdButler\MediaGroup JSON: {
  "id": 716,
  "delete": true
}

Permanently deletes a media group. If successful, this operation cannot be undone so be very sure when deleting one.

Returns

Returns a media group ID if the request succeeded, or an error if something went terribly wrong.

List all media groups

Definition

GET https://api.adbutler.com/v1/media-groups
\AdButler\MediaGroup::retrieveAll()
adbutler.mediaGroups.list()

Example Request

curl "https://api.adbutler.com/v1/media-groups?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$mediaGroup = \AdButler\MediaGroup::retrieveAll(array(
  "limit" => 2
));

echo $mediaGroup;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.mediaGroups.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.mediaGroups.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/media-groups",
  "data": [
    {
      "object": "media_group",
      "self": "/v1/media-groups/693",
      "id": 693,
      "name": "Default"
    },
    {
      "object": "media_group",
      "self": "/v1/media-groups/694",
      "id": 694,
      "name": "Default"
    }
  ]
}
AdButler\MediaGroup JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/media-groups",
  "data": [
    {
      "object": "media_group",
      "self": "/v1/media-groups/693",
      "id": 693,
      "name": "Default"
    },
    {
      "object": "media_group",
      "self": "/v1/media-groups/694",
      "id": 694,
      "name": "Default"
    }
  ]
}

Returns a list of all the media groups. Most recent media groups appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is a media_group object, and if no objects were found the list will be empty.


Creatives

List all creatives

Definition

GET https://api.adbutler.com/v1/creatives
\AdButler\Creative::retrieveAll()
adbutler.creatives.list()

Example Request

curl "https://api.adbutler.com/v1/creatives?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$creative = \AdButler\Creative::retrieveAll(array(
  "limit" => 2
));

echo $creative;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.creatives.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.creatives.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/creatives",
  "data": [
    {
      "object": "image_creative",
      "self": "/v1/creatives/image/49981",
      "id": 49981,
      "description": "This is a demo image creative",
      "file_name": "image-ad.png",
      "file_size": 3696,
      "group": 228,
      "height": 250,
      "mime_type": "image/png",
      "name": "Demo Image Creative",
      "upload_time": "2016-04-29 09:17:43",
      "width": 300
    },
    {
      "object": "flash_creative",
      "self": "/v1/creatives/flash/49982",
      "id": 49982,
      "description": "This is a demo flash creative",
      "file_name": "flash-ad.swf",
      "file_size": 77587,
      "group": 228,
      "height": 250,
      "mime_type": "application/x-shockwave-flash",
      "name": "Demo Flash Creative",
      "upload_time": "2016-04-29 09:36:35",
      "width": 300
    }
  ]
}
AdButler\Creative JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/creatives",
  "data": [
    {
      "object": "image_creative",
      "self": "/v1/creatives/image/49981",
      "id": 49981,
      "description": "This is a demo image creative",
      "file_name": "image-ad.png",
      "file_size": 3696,
      "group": 228,
      "height": 250,
      "mime_type": "image/png",
      "name": "Demo Image Creative",
      "upload_time": "2016-04-29 09:17:43",
      "width": 300
    },
    {
      "object": "flash_creative",
      "self": "/v1/creatives/flash/49982",
      "id": 49982,
      "description": "This is a demo flash creative",
      "file_name": "flash-ad.swf",
      "file_size": 77587,
      "group": 228,
      "height": 250,
      "mime_type": "application/x-shockwave-flash",
      "name": "Demo Flash Creative",
      "upload_time": "2016-04-29 09:36:35",
      "width": 300
    }
  ]
}

You can retrieve a list of all the creatives regardless of their type. You can optionally restrict the fields that you are interested in retrieving by using the fields query parameter.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is an object, and if no objects were found the list will be empty.


Image Creatives

Introduction

The image file that makes up an advertisement is known as the image creative. You can create a new image creative, retrieve one or more image creatives, update an existing image creative, or delete the image creative.

The image_creative response object has the following fields.

Example Response

{
  "object": "image_creative",
  "self": "/v1/creatives/image/50645",
  "id": 50645,
  "description": "This is a demo image creative",
  "file_name": "image-ad.png",
  "file_size": 3696,
  "group": 228,
  "height": 250,
  "mime_type": "image/png",
  "name": "Demo Image Creative",
  "upload_time": "2016-04-29 09:17:43",
  "width": 300
}
AdButler\ImageCreative JSON: {
  "object": "image_creative",
  "self": "/v1/creatives/image/50645",
  "id": 50645,
  "description": "This is a demo image creative",
  "file_name": "image-ad.png",
  "file_size": 3696,
  "group": 228,
  "height": 250,
  "mime_type": "image/png",
  "name": "Demo Image Creative",
  "upload_time": "2016-04-29 09:17:43",
  "width": 300
}
Field Type Description

object

string

A string denoting the object type which is always image_creative for the current resource.

self

string

The relative URL of the current resource which is always of the form /v1/creatives/image/{IMAGE_CREATIVE_ID}.

id

integer

The current resource identifier (ID).

description

string

Description of the image creative.

file_name

string

Name of the uploaded image file.

file_size

integer

Size of the uploaded image file.

group

integer

Media group identifier (ID) the image creative belongs to.

height

integer

Height of the image creative.

mime_type

string

MIME type of the uploaded image creative.

name

string

Name of the image creative.

upload_time

string

The date and time when the image file was uploaded.

width

integer

Width of the image creative.

Create an image creative

Definition

POST https://api.adbutler.com/v1/creatives/image
\AdButler\ImageCreative::create()
adbutler.creatives.images.create()

Example Request

curl "https://api.adbutler.com/v1/creatives/image" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Expect:" \
  -X POST \
  -F file=@image-ad.png \
  -F attributes='{
       "description": "This is a demo image creative",
       "group": 228,
       "name": "Demo Image Creative"
     }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$imageCreative = \AdButler\ImageCreative::create(array(
  "description" => "This is a demo image creative",
  "group" => 228,
  "name" => "Demo Image Creative",
  "file" => "image-ad.png"
));

echo $imageCreative;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var postData = {
  "description": "This is a demo image creative",
  "group": 228,
  "name": "Demo Image Creative",
  "file": "image-ad.png"
};

// using callbacks
adbutler.creatives.images.create(postData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.creatives.images.create(postData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "image_creative",
  "self": "/v1/creatives/image/50645",
  "id": 50645,
  "description": "This is a demo image creative",
  "file_name": "image-ad.png",
  "file_size": 3696,
  "group": 228,
  "height": 250,
  "mime_type": "image/png",
  "name": "Demo Image Creative",
  "upload_time": "2016-04-29 09:17:43",
  "width": 300
}
AdButler\ImageCreative JSON: {
  "object": "image_creative",
  "self": "/v1/creatives/image/50645",
  "id": 50645,
  "description": "This is a demo image creative",
  "file_name": "image-ad.png",
  "file_size": 3696,
  "group": 228,
  "height": 250,
  "mime_type": "image/png",
  "name": "Demo Image Creative",
  "upload_time": "2016-04-29 09:17:43",
  "width": 300
}

Creates a new image creative.

Field Type Description

description

string

A short description about the image creative.

file*

string

The aboslute or relative path to the image (JPEG, PNG, or GIF) file.

group*

integer

The media group identifier (ID).

name

string

A descriptive name of the image creative.

* = required field

Returns

Returns an image_creative object if the request succeeded, or an error if something went terribly wrong.

Retrieve an image creative

Definition

GET https://api.adbutler.com/v1/creatives/image/{}
\AdButler\ImageCreative::retrieve()
adbutler.creatives.images.retrieve()

Example Request

curl "https://api.adbutler.com/v1/creatives/image/50645" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$imageCreative = \AdButler\ImageCreative::retrieve( 50645 );

echo $imageCreative;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.creatives.images.read(50645, function(err, response) {
  console.log(response);
});

// using promises
adbutler.creatives.images.read(50645).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "image_creative",
  "self": "/v1/creatives/image/50645",
  "id": 50645,
  "description": "This is a demo image creative",
  "file_name": "image-ad.png",
  "file_size": 3696,
  "group": 228,
  "height": 250,
  "mime_type": "image/png",
  "name": "Demo Image Creative",
  "upload_time": "2016-04-29 09:17:43",
  "width": 300
}
AdButler\ImageCreative JSON: {
  "object": "image_creative",
  "self": "/v1/creatives/image/50645",
  "id": 50645,
  "description": "This is a demo image creative",
  "file_name": "image-ad.png",
  "file_size": 3696,
  "group": 228,
  "height": 250,
  "mime_type": "image/png",
  "name": "Demo Image Creative",
  "upload_time": "2016-04-29 09:17:43",
  "width": 300
}

You can retrieve the information about an existing image creative by giving the image creative identifier that was returned in the creative_image object upon creation.

Returns

Returns an image_creative object if the request succeeded, or an error if something went terribly wrong.

Update an image creative

Definition

POST https://api.adbutler.com/v1/creatives/image/{}
\AdButler\ImageCreative->save()
adbutler.creatives.images.update()

Example Request

curl "https://api.adbutler.com/v1/creatives/image/50645" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Expect:" \
  -X POST \
  -F file=@image-ad.png \
  -F attributes='{
       "description": "This is a demo image creative",
       "group": 228,
       "name": "Demo Image Creative"
     }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$imageCreative = \AdButler\ImageCreative::retrieve( 50645 );

$imageCreative->description = "This is a demo image creative";
$imageCreative->group = 228;
$imageCreative->name = "Demo Image Creative";
$imageCreative->file = "image-ad.png";

$imageCreative->save();

echo $imageCreative;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var updateData = {
  "description": "This is a demo image creative",
  "group": 228,
  "name": "Demo Image Creative",
  "file": "image-ad.png"
};

// using callbacks
adbutler.creatives.images.update(50645, updateData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.creatives.images.update(50645, updateData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "image_creative",
  "self": "/v1/creatives/image/50645",
  "id": 50645,
  "description": "This is a demo image creative",
  "file_name": "image-ad.png",
  "file_size": 3696,
  "group": 228,
  "height": 250,
  "mime_type": "image/png",
  "name": "Demo Image Creative",
  "upload_time": "2016-04-29 09:17:43",
  "width": 300
}
AdButler\ImageCreative JSON: {
  "object": "image_creative",
  "self": "/v1/creatives/image/50645",
  "id": 50645,
  "description": "This is a demo image creative",
  "file_name": "image-ad.png",
  "file_size": 3696,
  "group": 228,
  "height": 250,
  "mime_type": "image/png",
  "name": "Demo Image Creative",
  "upload_time": "2016-04-29 09:17:43",
  "width": 300
}

You can update a specific image creative by setting the values of the fields you want to update. If you want the field to retain its old value, then just omit that field from the update request. The update request accepts mostly the same arguments as the image creative creation request.

Field Type Description

description

string

A short description about the image creative.

file

string

The aboslute or relative path to the image (JPEG, PNG, or GIF) file.

group

integer

The media group identifier (ID).

name

string

A descriptive name of the image creative.

Returns

Returns an image_creative object if the request succeeded, or an error if something went terribly wrong.

Delete an image creative

Definition

DELETE https://api.adbutler.com/v1/creatives/image/{}
\AdButler\ImageCreative->delete()
adbutler.creatives.images.delete()

Example Request

curl "https://api.adbutler.com/v1/creatives/image/50645" \
  -H "Authorization: Basic {API_KEY}" \
  -X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$imageCreative = \AdButler\ImageCreative::retrieve( 50645 );
$imageCreative->delete();

echo $imageCreative;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.creatives.images.delete(50645, function(err, response) {
  console.log(response);
});

// using promises
adbutler.creatives.images.delete(50645).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "id": 50645,
  "delete": true
}
AdButler\ImageCreative JSON: {
  "id": 50645,
  "delete": true
}

Permanently deletes an Image Creative. if successful, this operation cannot be undone so be very sure when deleting one.

Returns

Returns an image creative ID if the request succeeded, or an error if something went terribly wrong.

List all image creatives

Definition

GET https://api.adbutler.com/v1/creatives/image
\AdButler\ImageCreative::retrieveAll()
adbutler.creatives.images.list()

Example Request

curl "https://api.adbutler.com/v1/creatives/image?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$imageCreative = \AdButler\ImageCreative::retrieveAll(array(
  "limit" => 2
));

echo $imageCreative;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.creatives.images.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.creatives.images.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/creatives/image",
  "data": [
    {
      "object": "image_creative",
      "self": "/v1/creatives/image/49981",
      "id": 49981,
      "description": "This is a demo image creative",
      "file_name": "image-ad.png",
      "file_size": 3696,
      "group": 228,
      "height": 250,
      "mime_type": "image/png",
      "name": "Demo Image Creative",
      "upload_time": "2016-04-29 09:17:43",
      "width": 300
    },
    {
      "object": "image_creative",
      "self": "/v1/creatives/image/49985",
      "id": 49985,
      "description": "This is a demo image creative",
      "file_name": "image-ad.png",
      "file_size": 3696,
      "group": 228,
      "height": 250,
      "mime_type": "image/png",
      "name": "Demo Image Creative",
      "upload_time": "2016-04-29 09:17:43",
      "width": 300
    }
  ]
}
AdButler\ImageCreative JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/creatives/image",
  "data": [
    {
      "object": "image_creative",
      "self": "/v1/creatives/image/49981",
      "id": 49981,
      "description": "This is a demo image creative",
      "file_name": "image-ad.png",
      "file_size": 3696,
      "group": 228,
      "height": 250,
      "mime_type": "image/png",
      "name": "Demo Image Creative",
      "upload_time": "2016-04-29 09:17:43",
      "width": 300
    },
    {
      "object": "image_creative",
      "self": "/v1/creatives/image/49985",
      "id": 49985,
      "description": "This is a demo image creative",
      "file_name": "image-ad.png",
      "file_size": 3696,
      "group": 228,
      "height": 250,
      "mime_type": "image/png",
      "name": "Demo Image Creative",
      "upload_time": "2016-04-29 09:17:43",
      "width": 300
    }
  ]
}

Returns a list of all the image creatives. Most recent image creatives appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is a image_creative object, and if no objects were found the list will be empty.


Flash Creatives

Introduction

The flash file that makes up an advertisement is known as the flash creative. You can create a new flash creative, retrieve one or more flash creatives, update an existing flash creative, or delete the flash creative.

The flash_creative response object has the following fields.

Example Response

{
  "object": "flash_creative",
  "self": "/v1/creatives/flash/50646",
  "id": 50646,
  "description": "This is a demo flash creative",
  "file_name": "flash-ad.swf",
  "file_size": 77587,
  "group": 228,
  "height": 250,
  "mime_type": "application/x-shockwave-flash",
  "name": "Demo Flash Creative",
  "upload_time": "2016-04-29 09:36:35",
  "width": 300
}
AdButler\FlashCreative JSON: {
  "object": "flash_creative",
  "self": "/v1/creatives/flash/50646",
  "id": 50646,
  "description": "This is a demo flash creative",
  "file_name": "flash-ad.swf",
  "file_size": 77587,
  "group": 228,
  "height": 250,
  "mime_type": "application/x-shockwave-flash",
  "name": "Demo Flash Creative",
  "upload_time": "2016-04-29 09:36:35",
  "width": 300
}
Field Type Description

object

string

A string denoting the object type.

self

string

The URL string of the current resource.

id

integer

The current resource identifier (ID).

description

string

Description of the flash creative.

file_name

string

Name of the uploaded flash file.

file_size

integer

Size of the uploaded flash file.

group

integer

Media group identifier (ID) the flash creative belongs to.

height

integer

Height of the flash creative.

mime_type

string

MIME type of the uploaded flash creative.

name

string

Name of the flash creative.

upload_time

string

The date and time when the flash file was uploaded.

width

integer

Width of the flash creative.

Create a flash creative

Definition

POST https://api.adbutler.com/v1/creatives/flash
\AdButler\FlashCreative::create()
adbutler.creatives.flash.create()

Example Request

curl "https://api.adbutler.com/v1/creatives/flash" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Expect:" \
  -X POST \
  -F file=@flash-ad.swf \
  -F attributes='{
       "description": "This is a demo flash creative",
       "group": 228,
       "name": "Demo Flash Creative"
     }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$flashCreative = \AdButler\FlashCreative::create(array(
  "description" => "This is a demo flash creative",
  "group" => 228,
  "name" => "Demo Flash Creative",
  "file" => "flash-ad.swf"
));

echo $flashCreative;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var postData = {
  "description": "This is a demo flash creative",
  "group": 228,
  "name": "Demo Flash Creative",
  "file": "flash-ad.swf"
};

// using callbacks
adbutler.creatives.flash.create(postData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.creatives.flash.create(postData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "flash_creative",
  "self": "/v1/creatives/flash/50646",
  "id": 50646,
  "description": "This is a demo flash creative",
  "file_name": "flash-ad.swf",
  "file_size": 77587,
  "group": 228,
  "height": 250,
  "mime_type": "application/x-shockwave-flash",
  "name": "Demo Flash Creative",
  "upload_time": "2016-04-29 09:36:35",
  "width": 300
}
AdButler\FlashCreative JSON: {
  "object": "flash_creative",
  "self": "/v1/creatives/flash/50646",
  "id": 50646,
  "description": "This is a demo flash creative",
  "file_name": "flash-ad.swf",
  "file_size": 77587,
  "group": 228,
  "height": 250,
  "mime_type": "application/x-shockwave-flash",
  "name": "Demo Flash Creative",
  "upload_time": "2016-04-29 09:36:35",
  "width": 300
}

Creates a new flash creative.

Field Type Description

description

string

A short description about the flash creative.

file*

string

The aboslute or relative path to the flash (SWF) file.

group*

integer

The media group identifier (ID).

name

string

A descriptive name of the flash creative.

* = required field

Returns

Returns a flash_creative object if the request succeeded, or an error if something went terribly wrong.

Retrieve a flash creative

Definition

GET https://api.adbutler.com/v1/creatives/flash/{FLASH-CREATIVE-ID}
\AdButler\FlashCreative::retrieve()
adbutler.creatives.flash.retrieve()

Example Request

curl "https://api.adbutler.com/v1/creatives/flash/50646" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$flashCreative = \AdButler\FlashCreative::retrieve( 50646 );

echo $flashCreative;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.creatives.flash.read(50646, function(err, response) {
  console.log(response);
});

// using promises
adbutler.creatives.flash.read(50646).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "flash_creative",
  "self": "/v1/creatives/flash/50646",
  "id": 50646,
  "description": "This is a demo flash creative",
  "file_name": "flash-ad.swf",
  "file_size": 77587,
  "group": 228,
  "height": 250,
  "mime_type": "application/x-shockwave-flash",
  "name": "Demo Flash Creative",
  "upload_time": "2016-04-29 09:36:35",
  "width": 300
}
AdButler\FlashCreative JSON: {
  "object": "flash_creative",
  "self": "/v1/creatives/flash/50646",
  "id": 50646,
  "description": "This is a demo flash creative",
  "file_name": "flash-ad.swf",
  "file_size": 77587,
  "group": 228,
  "height": 250,
  "mime_type": "application/x-shockwave-flash",
  "name": "Demo Flash Creative",
  "upload_time": "2016-04-29 09:36:35",
  "width": 300
}

You can retrieve the information about an existing flash creative by giving the flash creative identifier that was returned in the creative_flash object upon creation.

Returns

Returns a flash_creative object if the request succeeded, or an error if something went terribly wrong.

Update a flash creative

Definition

POST https://api.adbutler.com/v1/creatives/flash/{FLASH-CREATIVE-ID}
\AdButler\FlashCreative->save()
adbutler.creatives.flash.update()

Example Request

curl "https://api.adbutler.com/v1/creatives/flash/50646" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Expect:" \
  -X POST \
  -F file=@flash-ad.swf \
  -F attributes='{
       "description": "This is a demo flash creative",
       "group": 228,
       "name": "Demo Flash Creative"
     }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$flashCreative = \AdButler\FlashCreative::retrieve( 50646 );

$flashCreative->description = "This is a demo flash creative";
$flashCreative->group = 228;
$flashCreative->name = "Demo Flash Creative";
$flashCreative->file = "flash-ad.swf";

$flashCreative->save();

echo $flashCreative;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var updateData = {
  "description": "This is a demo flash creative",
  "group": 228,
  "name": "Demo Flash Creative",
  "file": "flash-ad.swf"
};

// using callbacks
adbutler.creatives.flash.update(50646, updateData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.creatives.flash.update(50646, updateData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "flash_creative",
  "self": "/v1/creatives/flash/50646",
  "id": 50646,
  "description": "This is a demo flash creative",
  "file_name": "flash-ad.swf",
  "file_size": 77587,
  "group": 228,
  "height": 250,
  "mime_type": "application/x-shockwave-flash",
  "name": "Demo Flash Creative",
  "upload_time": "2016-04-29 09:36:35",
  "width": 300
}
AdButler\FlashCreative JSON: {
  "object": "flash_creative",
  "self": "/v1/creatives/flash/50646",
  "id": 50646,
  "description": "This is a demo flash creative",
  "file_name": "flash-ad.swf",
  "file_size": 77587,
  "group": 228,
  "height": 250,
  "mime_type": "application/x-shockwave-flash",
  "name": "Demo Flash Creative",
  "upload_time": "2016-04-29 09:36:35",
  "width": 300
}

You can update a specific flash creative by setting the values of the fields you want to update. If you want the field to retain its old value, then just omit that field from the update request. The update request accepts mostly the same arguments as the flash creative creation request.

Field Type Description

description

string

A short description about the flash creative.

file

string

The aboslute or relative path to the flash (SWF) file.

group

integer

The media group identifier (ID).

name

string

A descriptive name of the flash creative.

Returns

Returns a flash_creative object if the request succeeded, or an error if something went terribly wrong.

Delete a flash creative

Definition

DELETE https://api.adbutler.com/v1/creatives/flash/{FLASH-CREATIVE-ID}
\AdButler\FlashCreative->delete()
adbutler.creatives.flash.delete()

Example Request

curl "https://api.adbutler.com/v1/creatives/flash/50646" \
  -H "Authorization: Basic {API_KEY}" \
  -X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$flashCreative = \AdButler\FlashCreative::retrieve( 50646 );
$flashCreative->delete();

echo $flashCreative;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.creatives.flash.delete(50646, function(err, response) {
  console.log(response);
});

// using promises
adbutler.creatives.flash.delete(50646).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "id": 50646,
  "delete": true
}
AdButler\FlashCreative JSON: {
  "id": 50646,
  "delete": true
}

Permanently deletes a flash creative. if successful, this operation cannot be undone so be very sure when deleting one.

Returns

Returns a flash creative ID if the request succeeded, or an error if something went terribly wrong.

List all flash creatives

Definition

GET https://api.adbutler.com/v1/creatives/flash
\AdButler\FlashCreative::retrieveAll()
adbutler.creatives.flash.list()

Example Request

curl "https://api.adbutler.com/v1/creatives/flash?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$flashCreative = \AdButler\FlashCreative::retrieveAll(array(
  "limit" => 2
));

echo $flashCreative;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.creatives.flash.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.creatives.flash.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/creatives/flash",
  "data": [
    {
      "object": "flash_creative",
      "self": "/v1/creatives/flash/49982",
      "id": 49982,
      "description": "This is a demo flash creative",
      "file_name": "flash-ad.swf",
      "file_size": 77587,
      "group": 228,
      "height": 250,
      "mime_type": "application/x-shockwave-flash",
      "name": "Demo Flash Creative",
      "upload_time": "2016-04-29 09:36:35",
      "width": 300
    },
    {
      "object": "flash_creative",
      "self": "/v1/creatives/flash/49986",
      "id": 49986,
      "description": "This is a demo flash creative",
      "file_name": "flash-ad.swf",
      "file_size": 77587,
      "group": 228,
      "height": 250,
      "mime_type": "application/x-shockwave-flash",
      "name": "Demo Flash Creative",
      "upload_time": "2016-04-29 09:36:35",
      "width": 300
    }
  ]
}
AdButler\FlashCreative JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/creatives/flash",
  "data": [
    {
      "object": "flash_creative",
      "self": "/v1/creatives/flash/49982",
      "id": 49982,
      "description": "This is a demo flash creative",
      "file_name": "flash-ad.swf",
      "file_size": 77587,
      "group": 228,
      "height": 250,
      "mime_type": "application/x-shockwave-flash",
      "name": "Demo Flash Creative",
      "upload_time": "2016-04-29 09:36:35",
      "width": 300
    },
    {
      "object": "flash_creative",
      "self": "/v1/creatives/flash/49986",
      "id": 49986,
      "description": "This is a demo flash creative",
      "file_name": "flash-ad.swf",
      "file_size": 77587,
      "group": 228,
      "height": 250,
      "mime_type": "application/x-shockwave-flash",
      "name": "Demo Flash Creative",
      "upload_time": "2016-04-29 09:36:35",
      "width": 300
    }
  ]
}

Returns a list of all the flash creatives. Most recent flash creatives appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is a flash_creative object, and if no objects were found the list will be empty.


Video Creatives

Introduction

The video file that makes up an advertisement is known as the video creative. You can create a new video creative, retrieve one or more video creatives, update an existing video creative, or delete the video creative.

The video_creative response object has the following fields.

Example Response

{
  "object": "video_creative",
  "self": "/v1/creatives/video/50648",
  "id": 50648,
  "description": "This is a demo video creative",
  "duration": 6,
  "file_name": "video-ad.mp4",
  "file_size": 2107842,
  "group": 228,
  "height": 250,
  "mime_type": "video/mp4",
  "name": "Demo Video Creative",
  "upload_time": "2016-04-29 09:48:35",
  "video_data_rate": 329677,
  "width": 300
}
AdButler\VideoCreative JSON: {
  "object": "video_creative",
  "self": "/v1/creatives/video/50648",
  "id": 50648,
  "description": "This is a demo video creative",
  "duration": 6,
  "file_name": "video-ad.mp4",
  "file_size": 2107842,
  "group": 228,
  "height": 250,
  "mime_type": "video/mp4",
  "name": "Demo Video Creative",
  "upload_time": "2016-04-29 09:48:35",
  "video_data_rate": 329677,
  "width": 300
}
Field Type Description

object

string

A string denoting the object type which is always video_creative for the current resource.

self

string

The relative URL of the current resource which is always of the form /v1/creatives/video/{VIDEO_CREATIVE_ID}.

id

integer

The current resource identifier (ID).

description

string

Description of the video creative.

duration

integer

Duration of the video creative.

file_name

string

Name of the uploaded video file.

file_size

integer

Size of the uploaded video file.

group

integer

Media group identifier (ID) the video creative belongs to.

height

integer

Height of the video creative.

mime_type

string

MIME type of the uploaded video creative.

name

string

Name of the video creative.

upload_time

string

The date and time when the video file was uploaded.

width

integer

Width of the video creative.

video_data_rate

integer

Bitrate of the video creative.

Create a video creative

Definition

POST https://api.adbutler.com/v1/creatives/video
\AdButler\VideoCreative::create()
adbutler.creatives.videos.create()

Example Request

curl "https://api.adbutler.com/v1/creatives/video" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Expect:" \
  -X POST \
  -F file=@video-ad.mp4 \
  -F attributes='{
       "description": "This is a demo video creative",
       "group": 228,
       "name": "Demo Video Creative"
     }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$videoCreative = \AdButler\VideoCreative::create(array(
  "description" => "This is a demo video creative",
  "group" => 228,
  "name" => "Demo Video Creative",
  "file" => "video-ad.mp4"
));

echo $videoCreative;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var postData = {
  "description": "This is a demo video creative",
  "group": 228,
  "name": "Demo Video Creative",
  "file": "video-ad.mp4"
};

// using callbacks
adbutler.creatives.videos.create(postData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.creatives.videos.create(postData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "video_creative",
  "self": "/v1/creatives/video/50648",
  "id": 50648,
  "description": "This is a demo video creative",
  "duration": 6,
  "file_name": "video-ad.mp4",
  "file_size": 2107842,
  "group": 228,
  "height": 250,
  "mime_type": "video/mp4",
  "name": "Demo Video Creative",
  "upload_time": "2016-04-29 09:48:35",
  "video_data_rate": 329677,
  "width": 300
}
AdButler\VideoCreative JSON: {
  "object": "video_creative",
  "self": "/v1/creatives/video/50648",
  "id": 50648,
  "description": "This is a demo video creative",
  "duration": 6,
  "file_name": "video-ad.mp4",
  "file_size": 2107842,
  "group": 228,
  "height": 250,
  "mime_type": "video/mp4",
  "name": "Demo Video Creative",
  "upload_time": "2016-04-29 09:48:35",
  "video_data_rate": 329677,
  "width": 300
}

Creates a new video creative.

Field Type Description

description

string

A short description about the video creative.

file*

string

The aboslute or relative path to the video (FLV, MP4, OGV, or WEBM) file.

group*

integer

The media group identifier (ID).

name

string

A descriptive name of the video creative.

* = required field

Returns

Returns a video_creative object if the request succeeded, or an error if something went terribly wrong.

Retrieve a video creative

Definition

GET https://api.adbutler.com/v1/creatives/video/{VIDEO-CREATIVE-ID}
\AdButler\VideoCreative::retrieve()
adbutler.creatives.videos.retrieve()

Example Request

curl "https://api.adbutler.com/v1/creatives/video/50648" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$videoCreative = \AdButler\VideoCreative::retrieve( 50648 );

echo $videoCreative;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.creatives.videos.read(50648, function(err, response) {
  console.log(response);
});

// using promises
adbutler.creatives.videos.read(50648).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "video_creative",
  "self": "/v1/creatives/video/50648",
  "id": 50648,
  "description": "This is a demo video creative",
  "duration": 6,
  "file_name": "video-ad.mp4",
  "file_size": 2107842,
  "group": 228,
  "height": 250,
  "mime_type": "video/mp4",
  "name": "Demo Video Creative",
  "upload_time": "2016-04-29 09:48:35",
  "video_data_rate": 329677,
  "width": 300
}
AdButler\VideoCreative JSON: {
  "object": "video_creative",
  "self": "/v1/creatives/video/50648",
  "id": 50648,
  "description": "This is a demo video creative",
  "duration": 6,
  "file_name": "video-ad.mp4",
  "file_size": 2107842,
  "group": 228,
  "height": 250,
  "mime_type": "video/mp4",
  "name": "Demo Video Creative",
  "upload_time": "2016-04-29 09:48:35",
  "video_data_rate": 329677,
  "width": 300
}

You can retrieve the information about an existing video creative by giving the video creative identifier that was returned in the creative_video object upon creation.

Returns

Returns a video_creative object if the request succeeded, or an error if something went terribly wrong.

Update a video creative

Definition

POST https://api.adbutler.com/v1/creatives/video/{VIDEO-CREATIVE-ID}
\AdButler\VideoCreative->save()
adbutler.creatives.videos.update()

Example Request

curl "https://api.adbutler.com/v1/creatives/video/50648" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Expect:" \
  -X POST \
  -F file=@video-ad.mp4 \
  -F attributes='{
       "description": "This is a demo video creative",
       "group": 228,
       "name": "Demo Video Creative"
     }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$videoCreative = \AdButler\VideoCreative::retrieve( 50648 );

$videoCreative->description = "This is a demo video creative";
$videoCreative->group = 228;
$videoCreative->name = "Demo Video Creative";
$videoCreative->file = "video-ad.mp4";

$videoCreative->save();

echo $videoCreative;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var updateData = {
  "description": "This is a demo video creative",
  "group": 228,
  "name": "Demo Video Creative",
  "file": "video-ad.mp4"
};

// using callbacks
adbutler.creatives.videos.update(50648, updateData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.creatives.videos.update(50648, updateData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "video_creative",
  "self": "/v1/creatives/video/50648",
  "id": 50648,
  "description": "This is a demo video creative",
  "duration": 6,
  "file_name": "video-ad.mp4",
  "file_size": 2107842,
  "group": 228,
  "height": 250,
  "mime_type": "video/mp4",
  "name": "Demo Video Creative",
  "upload_time": "2016-04-29 09:48:35",
  "video_data_rate": 329677,
  "width": 300
}
AdButler\VideoCreative JSON: {
  "object": "video_creative",
  "self": "/v1/creatives/video/50648",
  "id": 50648,
  "description": "This is a demo video creative",
  "duration": 6,
  "file_name": "video-ad.mp4",
  "file_size": 2107842,
  "group": 228,
  "height": 250,
  "mime_type": "video/mp4",
  "name": "Demo Video Creative",
  "upload_time": "2016-04-29 09:48:35",
  "video_data_rate": 329677,
  "width": 300
}

You can update a specific video creative by setting the values of the fields you want to update. If you want the field to retain its old value, then just omit that field from the update request. The update request accepts mostly the same arguments as the video creative creation request.

Field Type Description

description

string

A short description about the video creative.

file

string

The aboslute or relative path to the video (FLV, MP4, OGV, or WEBM) file.

group

integer

The media group identifier (ID).

name

string

A descriptive name of the video creative.

Returns

Returns a video_creative object if the request succeeded, or an error if something went terribly wrong.

Delete a video creative

Definition

DELETE https://api.adbutler.com/v1/creatives/video/{VIDEO-CREATIVE-ID}
\AdButler\VideoCreative->delete()
adbutler.creatives.videos.delete()

Example Request

curl "https://api.adbutler.com/v1/creatives/video/50648" \
  -H "Authorization: Basic {API_KEY}" \
  -X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$videoCreative = \AdButler\VideoCreative::retrieve( 50648 );
$videoCreative->delete();

echo $videoCreative;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.creatives.videos.delete(50648, function(err, response) {
  console.log(response);
});

// using promises
adbutler.creatives.videos.delete(50648).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "id": 50648,
  "delete": true
}
AdButler\VideoCreative JSON: {
  "id": 50648,
  "delete": true
}

Permanently deletes a video creative. if successful, this operation cannot be undone so be very sure when deleting one.

Returns

Returns a video creative ID if the request succeeded, or an error if something went terribly wrong.

List all video creatives

Definition

GET https://api.adbutler.com/v1/creatives/video
\AdButler\VideoCreative::retrieveAll()
adbutler.creatives.videos.list()

Example Request

curl "https://api.adbutler.com/v1/creatives/video?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$videoCreative = \AdButler\VideoCreative::retrieveAll(array(
  "limit" => 2
));

echo $videoCreative;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.creatives.videos.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.creatives.videos.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/creatives/video",
  "data": [
    {
      "object": "video_creative",
      "self": "/v1/creatives/video/49984",
      "id": 49984,
      "description": "This is a demo video creative",
      "duration": 6,
      "file_name": "video-ad.mp4",
      "file_size": 2107842,
      "group": 228,
      "height": 250,
      "mime_type": "video/mp4",
      "name": "Demo Video Creative",
      "upload_time": "2016-04-29 09:48:35",
      "video_data_rate": 329677,
      "width": 300
    },
    {
      "object": "video_creative",
      "self": "/v1/creatives/video/49988",
      "id": 49988,
      "description": "This is a demo video creative",
      "duration": 6,
      "file_name": "video-ad.mp4",
      "file_size": 2107842,
      "group": 228,
      "height": 250,
      "mime_type": "video/mp4",
      "name": "Demo Video Creative",
      "upload_time": "2016-04-29 09:48:35",
      "video_data_rate": 329677,
      "width": 300
    }
  ]
}
AdButler\VideoCreative JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/creatives/video",
  "data": [
    {
      "object": "video_creative",
      "self": "/v1/creatives/video/49984",
      "id": 49984,
      "description": "This is a demo video creative",
      "duration": 6,
      "file_name": "video-ad.mp4",
      "file_size": 2107842,
      "group": 228,
      "height": 250,
      "mime_type": "video/mp4",
      "name": "Demo Video Creative",
      "upload_time": "2016-04-29 09:48:35",
      "video_data_rate": 329677,
      "width": 300
    },
    {
      "object": "video_creative",
      "self": "/v1/creatives/video/49988",
      "id": 49988,
      "description": "This is a demo video creative",
      "duration": 6,
      "file_name": "video-ad.mp4",
      "file_size": 2107842,
      "group": 228,
      "height": 250,
      "mime_type": "video/mp4",
      "name": "Demo Video Creative",
      "upload_time": "2016-04-29 09:48:35",
      "video_data_rate": 329677,
      "width": 300
    }
  ]
}

Returns a list of all the video creatives. Most recent video creatives appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is a video_creative object, and if no objects were found the list will be empty.


Rich Media Creatives

Introduction

The zip archive of HTML, CSS and JavaScript files that makes up an advertisement is known as the rich media creative. You can create a new rich media creative, retrieve one or more rich media creatives, update an existing rich media creative, or delete the rich media creative.

The rich_media_creative response object has the following fields.

Example Response

{
  "object": "rich_media_creative",
  "self": "/v1/creatives/rich-media/50647",
  "id": 50647,
  "description": "This is a demo rich media creative",
  "file_name": "rich-media-ad.zip",
  "file_size": 87587,
  "group": 228,
  "mime_type": "application/zip",
  "name": "Demo Rich Media Creative",
  "upload_time": "2016-04-29 09:45:35"
}
AdButler\RichMediaCreative JSON: {
  "object": "rich_media_creative",
  "self": "/v1/creatives/rich-media/50647",
  "id": 50647,
  "description": "This is a demo rich media creative",
  "file_name": "rich-media-ad.zip",
  "file_size": 87587,
  "group": 228,
  "mime_type": "application/zip",
  "name": "Demo Rich Media Creative",
  "upload_time": "2016-04-29 09:45:35"
}
Attributes Type Description

object

string

A string denoting the object type which is always rich_media_creative for the current resource.

self

string

The relative URL of the current resource which is always of the form /v1/creatives/rich‑media/{RICH_MEDIA_CREATIVE_ID}.

id

integer

The current resource identifier (ID).

description

string

The description of the rich media creative.

file_name

string

The name of the uploaded rich media archive.

file_size

integer

The size of the uploaded rich media archive.

group

integer

Media group identifier (ID) the rich media creative belongs to.

mime_type

string

MIME type of the uploaded rich media archive.

name

string

The name of the rich media creative.

upload_time

string

The date and time when the rich media archive was uploaded.

Create a rich media creative

Definition

POST https://api.adbutler.com/v1/creatives/rich-media
\AdButler\RichMediaCreative::create()
adbutler.creatives.richMedia.create()

Example Request

curl "https://api.adbutler.com/v1/creatives/rich-media" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Expect:" \
  -X POST \
  -F file=@rich-media-ad.zip \
  -F attributes='{
       "description": "This is a demo rich media creative",
       "group": 228,
       "name": "Demo Rich Media Creative"
     }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$richMediaCreative = \AdButler\RichMediaCreative::create(array(
  "description" => "This is a demo rich media creative",
  "group" => 228,
  "name" => "Demo Rich Media Creative",
  "file" => "rich-media-ad.zip"
));

echo $richMediaCreative;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var postData = {
  "description": "This is a demo rich media creative",
  "group": 228,
  "name": "Demo Rich Media Creative",
  "file": "rich-media-ad.zip"
};

// using callbacks
adbutler.creatives.richMedia.create(postData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.creatives.richMedia.create(postData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "rich_media_creative",
  "self": "/v1/creatives/rich-media/50647",
  "id": 50647,
  "description": "This is a demo rich media creative",
  "file_name": "rich-media-ad.zip",
  "file_size": 87587,
  "group": 228,
  "mime_type": "application/zip",
  "name": "Demo Rich Media Creative",
  "upload_time": "2016-04-29 09:45:35"
}
AdButler\RichMediaCreative JSON: {
  "object": "rich_media_creative",
  "self": "/v1/creatives/rich-media/50647",
  "id": 50647,
  "description": "This is a demo rich media creative",
  "file_name": "rich-media-ad.zip",
  "file_size": 87587,
  "group": 228,
  "mime_type": "application/zip",
  "name": "Demo Rich Media Creative",
  "upload_time": "2016-04-29 09:45:35"
}

Creates a new rich media creative.

Field Type Description

description

string

A short description about the rich media creative.

file*

string

The aboslute or relative path to the rich media archive (ZIP) file.

group*

integer

The media group identifier (ID).

name

string

A descriptive name of the rich media creative.

* = required field

Returns

Returns a rich_media_creative object if the request succeeded, or an error if something went terribly wrong.

Retrieve a rich media creative

Definition

GET https://api.adbutler.com/v1/creatives/rich-media/{RICH-MEDIA-CREATIVE-ID}
\AdButler\RichMediaCreative::retrieve()
adbutler.creatives.richMedia.retrieve()

Example Request

curl "https://api.adbutler.com/v1/creatives/rich-media/50647" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$richMediaCreative = \AdButler\RichMediaCreative::retrieve( 50647 );

echo $richMediaCreative;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.creatives.richMedia.read(50647, function(err, response) {
  console.log(response);
});

// using promises
adbutler.creatives.richMedia.read(50647).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "rich_media_creative",
  "self": "/v1/creatives/rich-media/50647",
  "id": 50647,
  "description": "This is a demo rich media creative",
  "file_name": "rich-media-ad.zip",
  "file_size": 87587,
  "group": 228,
  "mime_type": "application/zip",
  "name": "Demo Rich Media Creative",
  "upload_time": "2016-04-29 09:45:35"
}
AdButler\RichMediaCreative JSON: {
  "object": "rich_media_creative",
  "self": "/v1/creatives/rich-media/50647",
  "id": 50647,
  "description": "This is a demo rich media creative",
  "file_name": "rich-media-ad.zip",
  "file_size": 87587,
  "group": 228,
  "mime_type": "application/zip",
  "name": "Demo Rich Media Creative",
  "upload_time": "2016-04-29 09:45:35"
}

You can retrieve the information about an existing rich media creative by giving the rich media creative identifier that was returned in the creative_rich_media object upon creation.

Returns

Returns a rich_media_creative object if the request succeeded, or an error if something went terribly wrong.

Update a rich media creative

Definition

POST https://api.adbutler.com/v1/creatives/rich-media/{RICH-MEDIA-CREATIVE-ID}
\AdButler\RichMediaCreative->save()
adbutler.creatives.richMedia.update()

Example Request

curl "https://api.adbutler.com/v1/creatives/rich-media/50647" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Expect:" \
  -X POST \
  -F file=@rich-media-ad.zip \
  -F attributes='{
       "description": "This is a demo rich media creative",
       "group": 228,
       "name": "Demo Rich Media Creative"
     }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$richMediaCreative = \AdButler\RichMediaCreative::retrieve( 50647 );

$richMediaCreative->description = "This is a demo rich media creative";
$richMediaCreative->group = 228;
$richMediaCreative->name = "Demo Rich Media Creative";
$richMediaCreative->file = "rich-media-ad.zip";

$richMediaCreative->save();

echo $richMediaCreative;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var updateData = {
  "description": "This is a demo rich media creative",
  "group": 228,
  "name": "Demo Rich Media Creative",
  "file": "rich-media-ad.zip"
};

// using callbacks
adbutler.creatives.richMedia.update(50647, updateData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.creatives.richMedia.update(50647, updateData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "rich_media_creative",
  "self": "/v1/creatives/rich-media/50647",
  "id": 50647,
  "description": "This is a demo rich media creative",
  "file_name": "rich-media-ad.zip",
  "file_size": 87587,
  "group": 228,
  "mime_type": "application/zip",
  "name": "Demo Rich Media Creative",
  "upload_time": "2016-04-29 09:45:35"
}
AdButler\RichMediaCreative JSON: {
  "object": "rich_media_creative",
  "self": "/v1/creatives/rich-media/50647",
  "id": 50647,
  "description": "This is a demo rich media creative",
  "file_name": "rich-media-ad.zip",
  "file_size": 87587,
  "group": 228,
  "mime_type": "application/zip",
  "name": "Demo Rich Media Creative",
  "upload_time": "2016-04-29 09:45:35"
}

You can update a specific rich media creative by setting the values of the fields you want to update. If you want the field to retain its old value, then just omit that field from the update request. The update request accepts mostly the same arguments as the rich media creative creation request.

Field Type Description

description

string

A short description about the rich media creative.

file

string

The aboslute or relative path to the rich media archive (ZIP) file.

group

integer

The media group identifier (ID).

name

string

A descriptive name of the rich media creative.

Returns

Returns a rich_media_creative object if the request succeeded, or an error if something went terribly wrong.

Delete a rich media creative

Definition

DELETE https://api.adbutler.com/v1/creatives/rich-media/{RICH-MEDIA-CREATIVE-ID}
\AdButler\RichMediaCreative->delete()
adbutler.creatives.richMedia.delete()

Example Request

curl "https://api.adbutler.com/v1/creatives/rich-media/50647" \
  -H "Authorization: Basic {API_KEY}" \
  -X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$richMediaCreative = \AdButler\RichMediaCreative::retrieve( 50647 );
$richMediaCreative->delete();

echo $richMediaCreative;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.creatives.richMedia.delete(50647, function(err, response) {
  console.log(response);
});

// using promises
adbutler.creatives.richMedia.delete(50647).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "id": 50647,
  "delete": true
}
AdButler\RichMediaCreative JSON: {
  "id": 50647,
  "delete": true
}

Permanently deletes an Image Creative. if successful, this operation cannot be undone so be very sure when deleting one.

Returns

Returns a rich media creative ID if the request succeeded, or an error if something went terribly wrong.

List all rich media creatives

Definition

GET https://api.adbutler.com/v1/creatives/rich-media
\AdButler\RichMediaCreative::retrieveAll()
adbutler.creatives.richMedia.list()

Example Request

curl "https://api.adbutler.com/v1/creatives/rich-media?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$richMediaCreative = \AdButler\RichMediaCreative::retrieveAll(array(
  "limit" => 2
));

echo $richMediaCreative;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.creatives.richMedia.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.creatives.richMedia.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/creatives/rich-media",
  "data": [
    {
      "object": "rich_media_creative",
      "self": "/v1/creatives/rich-media/49983",
      "id": 49983,
      "description": "This is a demo rich media creative",
      "file_name": "rich-media-ad.zip",
      "file_size": 87587,
      "group": 228,
      "mime_type": "application/zip",
      "name": "Demo Rich Media Creative",
      "upload_time": "2016-04-29 09:45:35"
    },
    {
      "object": "rich_media_creative",
      "self": "/v1/creatives/rich-media/49987",
      "id": 49987,
      "description": "This is a demo rich media creative",
      "file_name": "rich-media-ad.zip",
      "file_size": 87587,
      "group": 228,
      "mime_type": "application/zip",
      "name": "Demo Rich Media Creative",
      "upload_time": "2016-04-29 09:45:35"
    }
  ]
}
AdButler\RichMediaCreative JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/creatives/rich-media",
  "data": [
    {
      "object": "rich_media_creative",
      "self": "/v1/creatives/rich-media/49983",
      "id": 49983,
      "description": "This is a demo rich media creative",
      "file_name": "rich-media-ad.zip",
      "file_size": 87587,
      "group": 228,
      "mime_type": "application/zip",
      "name": "Demo Rich Media Creative",
      "upload_time": "2016-04-29 09:45:35"
    },
    {
      "object": "rich_media_creative",
      "self": "/v1/creatives/rich-media/49987",
      "id": 49987,
      "description": "This is a demo rich media creative",
      "file_name": "rich-media-ad.zip",
      "file_size": 87587,
      "group": 228,
      "mime_type": "application/zip",
      "name": "Demo Rich Media Creative",
      "upload_time": "2016-04-29 09:45:35"
    }
  ]
}

Returns a list of all the rich media creatives. Most recent rich media creatives appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is a rich_media_creative object, and if no objects were found the list will be empty.


Schedules

Introduction

Schedules describe the conditions necessary for serving advertisements. Common conditions include start and end dates, and quotas.

You can also use the delivery methods to determine the expiration and pacing set up for advertisements.

Default delivery delivers the impressions as quickly as possible. Smooth delivery will evenly serve over the lifetime dates and quotas.

For example, with smooth delivery, if your campaign has a quota of 30,000 impression set over a period of 60 days, the system would serve the assignment 500 times per day. Smooth delivery assignments have the highest potential priority for serving within AdButler. If a quota has not been filled then that assignment will generally always serve as long as a targeting system does not interfere.

The schedule response object has the following fields.

Example Response

{
  "object": "schedule",
  "self": "/v1/schedules/22758",
  "id": 22758,
  "clicks": 0,
  "created_date": "2016-03-22 14:26:50",
  "day_cap_type": null,
  "day_cap_limit": null,
  "delivery_method": "default",
  "end_date": "2014-11-02 14:00:00",
  "per_user_view_limit": null,
  "per_user_view_period": null,
  "quota_lifetime": 5000,
  "quota_remaining": 5000,
  "quota_type": "views",
  "start_date": "2014-08-01 14:00:00",
  "under_delivery_behaviour": "endOnQuota",
  "views": 0
}
AdButler\Schedule JSON: {
  "object": "schedule",
  "self": "/v1/schedules/22758",
  "id": 22758,
  "clicks": 0,
  "created_date": "2016-03-22 14:26:50",
  "day_cap_type": null,
  "day_cap_limit": null,
  "delivery_method": "default",
  "end_date": "2014-11-02 14:00:00",
  "per_user_view_limit": null,
  "per_user_view_period": null,
  "quota_lifetime": 5000,
  "quota_remaining": 5000,
  "quota_type": "views",
  "start_date": "2014-08-01 14:00:00",
  "under_delivery_behaviour": "endOnQuota",
  "views": 0
}
Field Type Description

object

string

A string denoting the object type which is always schedule for the current resource.

self

string

The relative URL of the current resource which is always of the form /v1/schedules/{SCHEDULE_ID}.

id

integer

The current resource identifier (ID).

clicks

integer

The number of clicks recorded on far.

created_date

string

The date and time when the schedule was created.

day_cap_limit

NULL

The number of times an ad will be shown in a day.

day_cap_type

NULL

Whether day_cap_limit is imposed on the number of views or the number of clicks.

delivery_method

string

The type of ad delivery method.

end_date

string

The date and time when the ad serving should come to halt.

per_user_view_limit

NULL

The number of times the ad will be shown to a particular user in a time period given by per_user_view_period. The null value indicates frequency capping is disabled.

per_user_view_period

NULL

The number of days after which the per_user_view_limit counter will start over. The null value indicates frequency capping is disabled.

quota_lifetime

integer

The number of total impressions to serve.

quota_remaining

integer

The number of impressions remaining to be served.

quota_type

string

The type of quota.

start_date

string

The date and time when the ad serving should start.

under_delivery_behaviour

string

The ad serving behavior once the end date has been reached.

views

integer

The number of views recorded so far.

Create a schedule

Definition

POST https://api.adbutler.com/v1/schedules
\AdButler\Schedule::create()
adbutler.schedules.create()

Example Request

curl "https://api.adbutler.com/v1/schedules" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{  
        "delivery_method": "default",
        "end_date": "2014-11-02 14:00:00",
        "quota_lifetime": 5000,
        "quota_type": "views",
        "start_date": "2014-08-01 14:00:00",
        "under_delivery_behaviour": "endOnQuota"
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$schedule = \AdButler\Schedule::create(array(
  "delivery_method" => "default",
  "end_date" => "2014-11-02 14:00:00",
  "quota_lifetime" => 5000,
  "quota_type" => "views",
  "start_date" => "2014-08-01 14:00:00",
  "under_delivery_behaviour" => "endOnQuota"
));

echo $schedule;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var postData = {
  "delivery_method": "default",
  "end_date": "2014-11-02 14:00:00",
  "quota_lifetime": 5000,
  "quota_type": "views",
  "start_date": "2014-08-01 14:00:00",
  "under_delivery_behaviour": "endOnQuota"
};

// using callbacks
adbutler.schedules.create(postData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.schedules.create(postData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "schedule",
  "self": "/v1/schedules/22758",
  "id": 22758,
  "clicks": 0,
  "created_date": "2016-03-22 14:26:50",
  "day_cap_type": null,
  "day_cap_limit": null,
  "delivery_method": "default",
  "end_date": "2014-11-02 14:00:00",
  "per_user_view_limit": null,
  "per_user_view_period": null,
  "quota_lifetime": 5000,
  "quota_remaining": 5000,
  "quota_type": "views",
  "start_date": "2014-08-01 14:00:00",
  "under_delivery_behaviour": "endOnQuota",
  "views": 0
}
AdButler\Schedule JSON: {
  "object": "schedule",
  "self": "/v1/schedules/22758",
  "id": 22758,
  "clicks": 0,
  "created_date": "2016-03-22 14:26:50",
  "day_cap_type": null,
  "day_cap_limit": null,
  "delivery_method": "default",
  "end_date": "2014-11-02 14:00:00",
  "per_user_view_limit": null,
  "per_user_view_period": null,
  "quota_lifetime": 5000,
  "quota_remaining": 5000,
  "quota_type": "views",
  "start_date": "2014-08-01 14:00:00",
  "under_delivery_behaviour": "endOnQuota",
  "views": 0
}

Creates a new schedule.

Field Type Description

day_cap_limit

integer

The number of times an ad will be shown in a day. Defaults to 0.

day_cap_type

string

Whether to impose dialy limits on the amount of views (views) or the amount of clicks (clicks).

delivery_method

string

Whether to deliver the impressions as quickly as spossible ("default") or deliver it evenly ("smooth") over the specified duration (start_date and end_date) and quota (quota_lifetime and quota_type). Specify the pace of serving advertisements which can be either "default" or "smooth". Default delivery delivers the impressions as quickly as possible. Smooth delivery will evenly serve over the lifetime dates and quotas.

start_date

string

The time and date when AdButler should start serving your advertisement. You can delay serving of ads by setting a future start date. Defaults to midnight of the current date if not given.

end_date

string

The time and date when AdButler should stop serving your advertisement. The end date can be as far in the future as desired. This allows you to set time-based expiration for your ads and we guarantee accuracy to the hour. Leave this field empty if you want ad serving to never end.

per_user_view_limit

integer

The number of times the ad will be shown to a particular user in a time period given by per_user_view_period. An integer value enables frequency capping and must be specified along with per_user_view_period. Both fields default to null which means frequency capping is disabled.

per_user_view_period

integer

The number of days after which the per_user_view_limit counter will start over. This field must be specified along with per_user_view_limit. Both fields default to null which means frequency capping is disabled.

quota_lifetime

integer

The amount of quota when seeting up quota-based expiration which is a direct number (float or integer), not given per thousand. Just enter your desired total quota and we will calculate the remaining inventory available. A quota-based expiration method allowing you to impose a hard limit on the amount of clicks or views an assignment gets.

quota_type

string

The type of quota when setting up quota-based expiration which can be the number of clicks (clicks) or the number of views (views). A quota-based expiration method allowing you to impose a hard limit on the amount of clicks or views an assignment gets.

under_delivery_behaviour

string

Whether to keep serving ads until the quota is met (endOnQuota) or stop serving them right away (endOnDate) once the end date has been reached. Defaults to endOnDate if delivery_method is smooth. Defaults to null if delivery_method is defautl.

* = required field
† = must be given if delivery_method is smooth, otherwise defaults to the default value of the field

Returns

Returns a schedule object if the request succeeded, or an error if something went terribly wrong.

Retrieve a schedule

Definition

GET https://api.adbutler.com/v1/schedules/{SCHEDULE-ID}
\AdButler\Schedule::retrieve()
adbutler.schedules.retrieve()

Example Request

curl "https://api.adbutler.com/v1/schedules/22758" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$schedule = \AdButler\Schedule::retrieve( 22758 );

echo $schedule;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.schedules.read(22758, function(err, response) {
  console.log(response);
});

// using promises
adbutler.schedules.read(22758).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "schedule",
  "self": "/v1/schedules/22758",
  "id": 22758,
  "clicks": 0,
  "created_date": "2016-03-22 14:26:50",
  "day_cap_type": null,
  "day_cap_limit": null,
  "delivery_method": "default",
  "end_date": "2014-11-02 14:00:00",
  "per_user_view_limit": null,
  "per_user_view_period": null,
  "quota_lifetime": 5000,
  "quota_remaining": 5000,
  "quota_type": "views",
  "start_date": "2014-08-01 14:00:00",
  "under_delivery_behaviour": "endOnQuota",
  "views": 0
}
AdButler\Schedule JSON: {
  "object": "schedule",
  "self": "/v1/schedules/22758",
  "id": 22758,
  "clicks": 0,
  "created_date": "2016-03-22 14:26:50",
  "day_cap_type": null,
  "day_cap_limit": null,
  "delivery_method": "default",
  "end_date": "2014-11-02 14:00:00",
  "per_user_view_limit": null,
  "per_user_view_period": null,
  "quota_lifetime": 5000,
  "quota_remaining": 5000,
  "quota_type": "views",
  "start_date": "2014-08-01 14:00:00",
  "under_delivery_behaviour": "endOnQuota",
  "views": 0
}

You can retrieve the information about an existing schedule by giving the schedule ID that was returned in the schedule object upon creation. You will see at the most 10 schedules in the response. You can change this default limit by appending ?limit=25 if you want this request to return 25 schedules.

Returns

Returns a schedule object if the request succeeded, or an error if something went terribly wrong.

Update a schedule

Definition

PUT https://api.adbutler.com/v1/schedules/{SCHEDULE-ID}
\AdButler\Schedule->save()
adbutler.schedules.update()

Example Request

curl "https://api.adbutler.com/v1/schedules/22758" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{  
        "delivery_method": "default",
        "end_date": "2014-11-02 14:00:00",
        "quota_lifetime": 5000,
        "quota_type": "views",
        "start_date": "2014-08-01 14:00:00",
        "under_delivery_behaviour": "endOnQuota"
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$schedule = \AdButler\Schedule::retrieve( 22758 );

$schedule->delivery_method = "default";
$schedule->end_date = "2014-11-02 14:00:00";
$schedule->quota_lifetime = 5000;
$schedule->quota_type = "views";
$schedule->start_date = "2014-08-01 14:00:00";
$schedule->under_delivery_behaviour = "endOnQuota";

$schedule->save();

echo $schedule;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var updateData = {
  "delivery_method": "default",
  "end_date": "2014-11-02 14:00:00",
  "quota_lifetime": 5000,
  "quota_type": "views",
  "start_date": "2014-08-01 14:00:00",
  "under_delivery_behaviour": "endOnQuota"
};

// using callbacks
adbutler.schedules.update(22758, updateData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.schedules.update(22758, updateData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "schedule",
  "self": "/v1/schedules/22758",
  "id": 22758,
  "clicks": 0,
  "created_date": "2016-03-22 14:26:50",
  "day_cap_type": null,
  "day_cap_limit": null,
  "delivery_method": "default",
  "end_date": "2014-11-02 14:00:00",
  "per_user_view_limit": null,
  "per_user_view_period": null,
  "quota_lifetime": 5000,
  "quota_remaining": 5000,
  "quota_type": "views",
  "start_date": "2014-08-01 14:00:00",
  "under_delivery_behaviour": "endOnQuota",
  "views": 0
}
AdButler\Schedule JSON: {
  "object": "schedule",
  "self": "/v1/schedules/22758",
  "id": 22758,
  "clicks": 0,
  "created_date": "2016-03-22 14:26:50",
  "day_cap_type": null,
  "day_cap_limit": null,
  "delivery_method": "default",
  "end_date": "2014-11-02 14:00:00",
  "per_user_view_limit": null,
  "per_user_view_period": null,
  "quota_lifetime": 5000,
  "quota_remaining": 5000,
  "quota_type": "views",
  "start_date": "2014-08-01 14:00:00",
  "under_delivery_behaviour": "endOnQuota",
  "views": 0
}

You can update a specific schedule by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the schedule creation request.

Field Type Description

day_cap_limit

integer

The number of times an ad will be shown in a day. Defaults to 0.

day_cap_type

string

Whether to impose dialy limits on the amount of views (views) or the amount of clicks (clicks).

delivery_method

string

Whether to deliver the impressions as quickly as spossible ("default") or deliver it evenly ("smooth") over the specified duration (start_date and end_date) and quota (quota_lifetime and quota_type). Specify the pace of serving advertisements which can be either "default" or "smooth". Default delivery delivers the impressions as quickly as possible. Smooth delivery will evenly serve over the lifetime dates and quotas.

start_date

string

The time and date when AdButler should start serving your advertisement. You can delay serving of ads by setting a future start date. Defaults to midnight of the current date if not given.

end_date

string

The time and date when AdButler should stop serving your advertisement. The end date can be as far in the future as desired. This allows you to set time-based expiration for your ads and we guarantee accuracy to the hour. Leave this field empty if you want ad serving to never end.

per_user_view_limit

integer

The number of times the ad will be shown to a particular user in a time period given by per_user_view_period. An integer value enables frequency capping and must be specified along with per_user_view_period. Both fields default to null which means frequency capping is disabled.

per_user_view_period

integer

The number of days after which the per_user_view_limit counter will start over. This field must be specified along with per_user_view_limit. Both fields default to null which means frequency capping is disabled.

quota_lifetime

integer

The amount of quota when seeting up quota-based expiration which is a direct number (float or integer), not given per thousand. Just enter your desired total quota and we will calculate the remaining inventory available. A quota-based expiration method allowing you to impose a hard limit on the amount of clicks or views an assignment gets.

quota_type

string

The type of quota when setting up quota-based expiration which can be the number of clicks (clicks) or the number of views (views). A quota-based expiration method allowing you to impose a hard limit on the amount of clicks or views an assignment gets.

under_delivery_behaviour

string

Whether to keep serving ads until the quota is met (endOnQuota) or stop serving them right away (endOnDate) once the end date has been reached. Defaults to endOnDate if delivery_method is smooth. Defaults to null if delivery_method is defautl.

† = must be given if delivery_method is smooth, otherwise defaults to the default value of the field

Returns

Returns a schedule object if the request succeeded, or an error if something went terribly wrong.

Delete a schedule

Definition

DELETE https://api.adbutler.com/v1/schedules/{SCHEDULE-ID}
\AdButler\Schedule->delete()
adbutler.schedules.delete()

Example Request

curl "https://api.adbutler.com/v1/schedules/22758" \
  -H "Authorization: Basic {API_KEY}" \
  -X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$schedule = \AdButler\Schedule::retrieve( 22758 );
$schedule->delete();

echo $schedule;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.schedules.delete(22758, function(err, response) {
  console.log(response);
});

// using promises
adbutler.schedules.delete(22758).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "id": 22758,
  "delete": true
}
AdButler\Schedule JSON: {
  "id": 22758,
  "delete": true
}

Permanently deletes a schedule. if successful, this operation cannot be undone so be very sure when deleting one.

Returns

Returns a schedule ID if the request succeeded, or an error if something went terribly wrong.

List all schedules

Definition

GET https://api.adbutler.com/v1/schedules
\AdButler\Schedule::retrieveAll()
adbutler.schedules.list()

Example Request

curl "https://api.adbutler.com/v1/schedules?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$schedule = \AdButler\Schedule::retrieveAll(array(
  "limit" => 2
));

echo $schedule;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.schedules.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.schedules.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/schedules",
  "data": [
    {
      "object": "schedule",
      "self": "/v1/schedules/22512",
      "id": 22512,
      "clicks": 0,
      "created_date": "2018-06-28 09:48:12",
      "day_cap_type": "views",
      "day_cap_limit": null,
      "delivery_method": "default",
      "end_date": null,
      "per_user_view_limit": null,
      "per_user_view_period": null,
      "quota_lifetime": null,
      "quota_remaining": null,
      "quota_type": null,
      "start_date": null,
      "under_delivery_behaviour": "endOnDate",
      "views": 0
    },
    {
      "object": "schedule",
      "self": "/v1/schedules/22513",
      "id": 22513,
      "clicks": 0,
      "created_date": "2018-06-28 09:48:12",
      "day_cap_type": "views",
      "day_cap_limit": null,
      "delivery_method": "default",
      "end_date": null,
      "per_user_view_limit": null,
      "per_user_view_period": null,
      "quota_lifetime": null,
      "quota_remaining": null,
      "quota_type": null,
      "start_date": null,
      "under_delivery_behaviour": "endOnDate",
      "views": 0
    }
  ]
}
AdButler\Schedule JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/schedules",
  "data": [
    {
      "object": "schedule",
      "self": "/v1/schedules/22512",
      "id": 22512,
      "clicks": 0,
      "created_date": "2018-06-28 09:48:12",
      "day_cap_type": "views",
      "day_cap_limit": null,
      "delivery_method": "default",
      "end_date": null,
      "per_user_view_limit": null,
      "per_user_view_period": null,
      "quota_lifetime": null,
      "quota_remaining": null,
      "quota_type": null,
      "start_date": null,
      "under_delivery_behaviour": "endOnDate",
      "views": 0
    },
    {
      "object": "schedule",
      "self": "/v1/schedules/22513",
      "id": 22513,
      "clicks": 0,
      "created_date": "2018-06-28 09:48:12",
      "day_cap_type": "views",
      "day_cap_limit": null,
      "delivery_method": "default",
      "end_date": null,
      "per_user_view_limit": null,
      "per_user_view_period": null,
      "quota_lifetime": null,
      "quota_remaining": null,
      "quota_type": null,
      "start_date": null,
      "under_delivery_behaviour": "endOnDate",
      "views": 0
    }
  ]
}

Returns a list of all the schedules. Most recent schedule accounts appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is a schedule object, and if no objects were found the list will be empty.


Placements

Introduction

Assign an advertisement to a zone based on a set of scheduling criteria using the placements endpoint.

Each placement represents combination of criteria required to serve an advertisement. Prior to creating a placement, you will need to have created several other resources:

  • Advertisement (banner/campaign/text-ad/popup)
  • Zone
  • Schedule

You may also optionally create targeting options, keywords, and activity limits to further control the deliverability of your placements.

The placement response object has the following fields.

Example Response

{
  "object": "placement",
  "self": "/v1/placements/18597",
  "id": 18597,
  "active": true,
  "advertisement": {
    "id": 518889981,
    "type": "image_banner"
  },
  "channel": null,
  "cost": {
    "cpm": 0.05,
    "cpc": 0.1,
    "cpa": 0.05
  },
  "created_date": "2018-11-28 11:49:48",
  "day_cap_limit": 5000,
  "day_cap_type": null,
  "geo_target": null,
  "isp_target": null,
  "keywords": "",
  "keywords_match_method": "preferred",
  "payout_percent": 2,
  "per_user_view_limit": 500,
  "per_user_view_period": 3,
  "platform_target": null,
  "priority": "standard",
  "schedule": 22758,
  "weight": 2,
  "zone": {
    "id": 104144,
    "type": "banner_zone"
  }
}
AdButler\Placement JSON: {
  "object": "placement",
  "self": "/v1/placements/18597",
  "id": 18597,
  "active": true,
  "advertisement": {
    "id": 518889981,
    "type": "image_banner"
  },
  "channel": null,
  "cost": {
    "cpm": 0.05,
    "cpc": 0.1,
    "cpa": 0.05
  },
  "created_date": "2018-11-28 11:49:48",
  "day_cap_limit": 5000,
  "day_cap_type": null,
  "geo_target": null,
  "isp_target": null,
  "keywords": "",
  "keywords_match_method": "preferred",
  "payout_percent": 2,
  "per_user_view_limit": 500,
  "per_user_view_period": 3,
  "platform_target": null,
  "priority": "standard",
  "schedule": 22758,
  "weight": 2,
  "zone": {
    "id": 104144,
    "type": "banner_zone"
  }
}
Field Type Description

object

string

A string denoting the object type which is always placement for the current resource.

self

string

The relative URL of the current resource which is always of the form /v1/placements/{BANNER_PLACEMENT_ID}.

id

integer

The current resource identifier (ID).

active

boolean

The status of ad serving whether it is being served in the given zone or not.

advertisement

array

An object containing image banner, flash banner, rich media banner, custom HTML banner, banner campaign, text campaign, image popup, flash popup, custom HTML popup, or text ad identifier (ID) and type.

channel

NULL

The channel identifier (ID).

cost

array

The revenue details of the banner placement.

created_date

string

The date and time when the banner placement was created.

day_cap_limit

integer

The number of times an ad will be shown in a day.

This field has been moved to the schedule object and is now deprecated.

day_cap_type

NULL

Whether day_cap_limit is imposed on the number of views or the number of clicks.

This field has been moved to the schedule object and is now deprecated.

geo_target

NULL

The geotarget identifier (ID).

isp_target

NULL

The ISP target identifier (ID).

keywords

string

The list of comma separated words to determine whether the ad should or should not be served if word matches are found.

keywords_match_method

string

Whether to serve the ad only if a keyword match is found ("required") or just increase the serving priority of the ad whenever a keyword match is found ("preferred"). The Keyword match method indicates how important the keyword is.

payout_percent

integer

The percentage of the ad generated revenue paid out to the publisher.

per_user_view_limit

integer

The number of times the ad will be shown to a particular user in a time period given by per_user_view_period. The null value indicates frequency capping is disabled.

This field has been moved to the schedule object and is now deprecated.

per_user_view_period

integer

The number of days after which the per_user_view_limit counter will start over. The null value indicates frequency capping is disabled.

This field has been moved to the schedule object and is now deprecated.

platform_target

NULL

The platform target identifier (ID).

priority

string

A value specifying whether to prefer serving of some ads over others in a campaign or channel.

schedule

integer

The schedule identifier (ID).

weight

integer

A number used to compute the probability of serving a particular ad.

zone

array

An object containing banner, email, or text zone identifier (ID) and type.

Create a placement

Definition

POST https://api.adbutler.com/v1/placements
\AdButler\Placement::create()
adbutler.placements.create()

Example Request

curl "https://api.adbutler.com/v1/placements" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{  
        "active": true,
        "advertisement": 
                {
                        id: 518889981,
                        type: "image_banner"
                },
        "cost": 
                {
                        cpm: 0.05,
                        cpc: 0.1,
                        cpa: 0.05
                },
        "day_cap_limit": 5000,
        "day_cap_type": null,
        "geo_target": null,
        "isp_target": null,
        "keywords": "",
        "keywords_match_method": "preferred",
        "payout_percent": 2,
        "per_user_view_limit": 500,
        "per_user_view_period": 3,
        "platform_target": null,
        "priority": "standard",
        "schedule": 22758,
        "weight": 2,
        "zone": 
                {
                        id: 104144,
                        type: "banner_zone"
                }
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$placement = \AdButler\Placement::create(array(
  "active" => true,
  "advertisement" => 
    [
      id => 518889981,
      type => "image_banner"
    ],
  "cost" => 
    [
      cpm => 0.05,
      cpc => 0.1,
      cpa => 0.05
    ],
  "day_cap_limit" => 5000,
  "day_cap_type" => null,
  "geo_target" => null,
  "isp_target" => null,
  "keywords" => "",
  "keywords_match_method" => "preferred",
  "payout_percent" => 2,
  "per_user_view_limit" => 500,
  "per_user_view_period" => 3,
  "platform_target" => null,
  "priority" => "standard",
  "schedule" => 22758,
  "weight" => 2,
  "zone" => 
    [
      id => 104144,
      type => "banner_zone"
    ]
));

echo $placement;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var postData = {
  "active": true,
  "advertisement": 
    {
      id: 518889981,
      type: "image_banner"
    },
  "cost": 
    {
      cpm: 0.05,
      cpc: 0.1,
      cpa: 0.05
    },
  "day_cap_limit": 5000,
  "day_cap_type": null,
  "geo_target": null,
  "isp_target": null,
  "keywords": "",
  "keywords_match_method": "preferred",
  "payout_percent": 2,
  "per_user_view_limit": 500,
  "per_user_view_period": 3,
  "platform_target": null,
  "priority": "standard",
  "schedule": 22758,
  "weight": 2,
  "zone": 
    {
      id: 104144,
      type: "banner_zone"
    }
};

// using callbacks
adbutler.placements.create(postData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.placements.create(postData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "placement",
  "self": "/v1/placements/18597",
  "id": 18597,
  "active": true,
  "advertisement": {
    "id": 518889981,
    "type": "image_banner"
  },
  "channel": null,
  "cost": {
    "cpm": 0.05,
    "cpc": 0.1,
    "cpa": 0.05
  },
  "created_date": "2018-11-28 11:49:48",
  "day_cap_limit": 5000,
  "day_cap_type": null,
  "geo_target": null,
  "isp_target": null,
  "keywords": "",
  "keywords_match_method": "preferred",
  "payout_percent": 2,
  "per_user_view_limit": 500,
  "per_user_view_period": 3,
  "platform_target": null,
  "priority": "standard",
  "schedule": 22758,
  "weight": 2,
  "zone": {
    "id": 104144,
    "type": "banner_zone"
  }
}
AdButler\Placement JSON: {
  "object": "placement",
  "self": "/v1/placements/18597",
  "id": 18597,
  "active": true,
  "advertisement": {
    "id": 518889981,
    "type": "image_banner"
  },
  "channel": null,
  "cost": {
    "cpm": 0.05,
    "cpc": 0.1,
    "cpa": 0.05
  },
  "created_date": "2018-11-28 11:49:48",
  "day_cap_limit": 5000,
  "day_cap_type": null,
  "geo_target": null,
  "isp_target": null,
  "keywords": "",
  "keywords_match_method": "preferred",
  "payout_percent": 2,
  "per_user_view_limit": 500,
  "per_user_view_period": 3,
  "platform_target": null,
  "priority": "standard",
  "schedule": 22758,
  "weight": 2,
  "zone": {
    "id": 104144,
    "type": "banner_zone"
  }
}

Creates a new banner placement.

Field Type Description

schedule*

integer

The schedule identifier (ID).

advertisement*

object

An object containing image banner, flash banner, rich media banner, custom HTML banner, banner campaign, text campaign, image popup, flash popup, custom HTML popup, or text ad identifier (ID) and type.

zone*

integer

An object containing banner, email, or text zone identifier (ID) and type.

active

boolean

Whether to actively serve ads in the zones (true) or pause ad serving (false). Defaults to true.

weight

integer

A number used to determine the serving frequency of an advertisement. This number is used to compute the probability of an ad being served in a particular zone. Defaults to 1 which means every ad has an equal chance of being served. For example, consider three banners assigned to a zone with weights of 1, 4 and 5. The ratio works out to a corresponding probability of 10%, 40% and 50% chance of each banner being served.

priority

string

Priority allows you to prefer serving of some ads over others in a campaign or channel. Possible values in descending order are "sponsorship", "standard", "network", "bulk" and "house". Defaults to "standard".

day_cap_limit

integer

The number of times an ad will be shown in a day. Defaults to 0.

This field has been moved to the schedule object. Using this field is now deprecated.

day_cap_type

string

Whether to impose dialy limits on the amount of views (views) or the amount of clicks (clicks).

This field has been moved to the schedule object. Using this field is now deprecated.

per_user_view_limit

integer

The number of times the ad will be shown to a particular user in a time period given by per_user_view_period. An integer value enables frequency capping and must be specified along with 'per_user_view_period'. Both fields default to null which means frequency capping is disabled.

This field has been moved to the schedule object. Using this field is now deprecated.

per_user_view_period

integer

The number of days after which the per_user_view_limit counter will start over. This field must be specified along with 'per_user_view_limit'. Both fields default to null which means frequency capping is disabled.

This field has been moved to the schedule object. Using this field is now deprecated.

cost

object

An object associating a pricing model with the performance of your banner placement. This information will be used to calculate the revenue generated by your ad. You can either use a fixed cost or a rate based pricing model for your ad placements. Fixed cost is tied to the amount of quota and is given as { "fixed_cost": 0.00 } You can also use a rate based pricing model by specifying cpm, cpc, and cpa values as { "cpm": 0.00, "cpc": 0.00, "cpa": 0.00 }.

payout_percent

integer/float

The percentage of the ad generated revenue paid out to the publisher. Publisher payout is ideal for profit sharing where the revenue is split between money earned by the advertiser and money earned by the publisher. Defaults to 0.00 percent.

geo_target

integer

The geotarget identifier (ID) if you want your ads to be delivered to a particular location only. This will direct your audience to ads in their region. Defaults to null which means geographic targeting is not in effect.

platform_target

integer

The platform target identifier (ID) if you intend to restrict delivery of your ads to a certain device or a platform. Defaults to null which means platform targeting is not in effect.

keywords

string

Specify words separated by commas to determine if this ad should be served if a match is found. Use asterisk "*" character to represent a wildcard in a keyword e.g. "paint*" would match paint, painter, painting, paints etc. You can also stop the ad from being served in presence of a specific word by prepending a negative sign (-) to the word. For example, "-paint" would stop the ad from being delivered if the word "paint" is used.

keywords_match_method

string

Whether to serve the ad only if a match is found (required) or increase the serving priority of an ad whenever a match is found (preferred).

* = required field

Returns

Returns a placement object if the request succeeded, or an error if something went terribly wrong.

Retrieve a placement

Definition

GET https://api.adbutler.com/v1/placements/{PLACEMENT-ID}
\AdButler\Placement::retrieve()
adbutler.placements.retrieve()

Example Request

curl "https://api.adbutler.com/v1/placements/18597" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$placement = \AdButler\Placement::retrieve( 18597 );

echo $placement;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.placements.read(18597, function(err, response) {
  console.log(response);
});

// using promises
adbutler.placements.read(18597).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "placement",
  "self": "/v1/placements/18597",
  "id": 18597,
  "active": true,
  "advertisement": {
    "id": 518889981,
    "type": "image_banner"
  },
  "channel": null,
  "cost": {
    "cpm": 0.05,
    "cpc": 0.1,
    "cpa": 0.05
  },
  "created_date": "2018-11-28 11:49:48",
  "day_cap_limit": 5000,
  "day_cap_type": null,
  "geo_target": null,
  "isp_target": null,
  "keywords": "",
  "keywords_match_method": "preferred",
  "payout_percent": 2,
  "per_user_view_limit": 500,
  "per_user_view_period": 3,
  "platform_target": null,
  "priority": "standard",
  "schedule": 22758,
  "weight": 2,
  "zone": {
    "id": 104144,
    "type": "banner_zone"
  }
}
AdButler\Placement JSON: {
  "object": "placement",
  "self": "/v1/placements/18597",
  "id": 18597,
  "active": true,
  "advertisement": {
    "id": 518889981,
    "type": "image_banner"
  },
  "channel": null,
  "cost": {
    "cpm": 0.05,
    "cpc": 0.1,
    "cpa": 0.05
  },
  "created_date": "2018-11-28 11:49:48",
  "day_cap_limit": 5000,
  "day_cap_type": null,
  "geo_target": null,
  "isp_target": null,
  "keywords": "",
  "keywords_match_method": "preferred",
  "payout_percent": 2,
  "per_user_view_limit": 500,
  "per_user_view_period": 3,
  "platform_target": null,
  "priority": "standard",
  "schedule": 22758,
  "weight": 2,
  "zone": {
    "id": 104144,
    "type": "banner_zone"
  }
}

You can retrieve the information about an existing banner placement by giving the banner placement ID that was returned in the banner placement object upon creation. You will see at the most 10 banner placements in the response. You can change this default limit by appending ?limit=25 if you want this request to return 25 banner placements.

Returns

Returns a placement object if the request succeeded, or an error if something went terribly wrong.

Update a placement

Definition

PUT https://api.adbutler.com/v1/placements/{PLACEMENT-ID}
\AdButler\Placement->save()
adbutler.placements.update()

Example Request

curl "https://api.adbutler.com/v1/placements/18597" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{  
        "active": true,
        "advertisement": 
                {
                        id: 518889981,
                        type: "image_banner"
                },
        "cost": 
                {
                        cpm: 0.05,
                        cpc: 0.1,
                        cpa: 0.05
                },
        "day_cap_limit": 5000,
        "day_cap_type": null,
        "geo_target": null,
        "isp_target": null,
        "keywords": "",
        "keywords_match_method": "preferred",
        "payout_percent": 2,
        "per_user_view_limit": 500,
        "per_user_view_period": 3,
        "platform_target": null,
        "priority": "standard",
        "schedule": 22758,
        "weight": 2,
        "zone": 
                {
                        id: 104144,
                        type: "banner_zone"
                }
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$placement = \AdButler\Placement::retrieve( 18597 );

$placement->active = true;
$placement->advertisement = 
[
id = 518889981,
type = "image_banner"
];
$placement->cost = 
[
cpm = 0.05,
cpc = 0.1,
cpa = 0.05
];
$placement->day_cap_limit = 5000;
$placement->day_cap_type = null;
$placement->geo_target = null;
$placement->isp_target = null;
$placement->keywords = "";
$placement->keywords_match_method = "preferred";
$placement->payout_percent = 2;
$placement->per_user_view_limit = 500;
$placement->per_user_view_period = 3;
$placement->platform_target = null;
$placement->priority = "standard";
$placement->schedule = 22758;
$placement->weight = 2;
$placement->zone = 
[
id = 104144,
type = "banner_zone"
];

$placement->save();

echo $placement;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var updateData = {
  "active": true,
  "advertisement": 
    {
      id: 518889981,
      type: "image_banner"
    },
  "cost": 
    {
      cpm: 0.05,
      cpc: 0.1,
      cpa: 0.05
    },
  "day_cap_limit": 5000,
  "day_cap_type": null,
  "geo_target": null,
  "isp_target": null,
  "keywords": "",
  "keywords_match_method": "preferred",
  "payout_percent": 2,
  "per_user_view_limit": 500,
  "per_user_view_period": 3,
  "platform_target": null,
  "priority": "standard",
  "schedule": 22758,
  "weight": 2,
  "zone": 
    {
      id: 104144,
      type: "banner_zone"
    }
};

// using callbacks
adbutler.placements.update(18597, updateData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.placements.update(18597, updateData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "placement",
  "self": "/v1/placements/18597",
  "id": 18597,
  "active": true,
  "advertisement": {
    "id": 518889981,
    "type": "image_banner"
  },
  "channel": null,
  "cost": {
    "cpm": 0.05,
    "cpc": 0.1,
    "cpa": 0.05
  },
  "created_date": "2018-11-28 11:49:48",
  "day_cap_limit": 5000,
  "day_cap_type": null,
  "geo_target": null,
  "isp_target": null,
  "keywords": "",
  "keywords_match_method": "preferred",
  "payout_percent": 2,
  "per_user_view_limit": 500,
  "per_user_view_period": 3,
  "platform_target": null,
  "priority": "standard",
  "schedule": 22758,
  "weight": 2,
  "zone": {
    "id": 104144,
    "type": "banner_zone"
  }
}
AdButler\Placement JSON: {
  "object": "placement",
  "self": "/v1/placements/18597",
  "id": 18597,
  "active": true,
  "advertisement": {
    "id": 518889981,
    "type": "image_banner"
  },
  "channel": null,
  "cost": {
    "cpm": 0.05,
    "cpc": 0.1,
    "cpa": 0.05
  },
  "created_date": "2018-11-28 11:49:48",
  "day_cap_limit": 5000,
  "day_cap_type": null,
  "geo_target": null,
  "isp_target": null,
  "keywords": "",
  "keywords_match_method": "preferred",
  "payout_percent": 2,
  "per_user_view_limit": 500,
  "per_user_view_period": 3,
  "platform_target": null,
  "priority": "standard",
  "schedule": 22758,
  "weight": 2,
  "zone": {
    "id": 104144,
    "type": "banner_zone"
  }
}

You can update a specific banner placement by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the banner placement creation request.

Field Type Description

schedule

integer

The schedule identifier (ID).

advertisement

object

An object containing image banner, flash banner, rich media banner, custom HTML banner, banner campaign, text campaign, image popup, flash popup, custom HTML popup, or text ad identifier (ID) and type.

zone

integer

An object containing banner, email, or text zone identifier (ID) and type.

active

boolean

Whether to actively serve ads in the zones (true) or pause ad serving (false). Defaults to true.

weight

integer

A number used to determine the serving frequency of an advertisement. This number is used to compute the probability of an ad being served in a particular zone. Defaults to 1 which means every ad has an equal chance of being served. For example, consider three banners assigned to a zone with weights of 1, 4 and 5. The ratio works out to a corresponding probability of 10%, 40% and 50% chance of each banner being served.

priority

string

Priority allows you to prefer serving of some ads over others in a campaign or channel. Possible values in descending order are "sponsorship", "standard", "network", "bulk" and "house". Defaults to "standard".

day_cap_limit

integer

The number of times an ad will be shown in a day. Defaults to 0.

This field has been moved to the schedule object. Using this field is now deprecated.

day_cap_type

string

Whether to impose dialy limits on the amount of views (views) or the amount of clicks (clicks).

This field has been moved to the schedule object. Using this field is now deprecated.

per_user_view_limit

integer

The number of times the ad will be shown to a particular user in a time period given by per_user_view_period. An integer value enables frequency capping and must be specified along with 'per_user_view_period'. Both fields default to null which means frequency capping is disabled.

This field has been moved to the schedule object. Using this field is now deprecated.

per_user_view_period

integer

The number of days after which the per_user_view_limit counter will start over. This field must be specified along with 'per_user_view_limit'. Both fields default to null which means frequency capping is disabled.

This field has been moved to the schedule object. Using this field is now deprecated.

cost

object

An object associating a pricing model with the performance of your banner placement. This information will be used to calculate the revenue generated by your ad. You can either use a fixed cost or a rate based pricing model for your ad placements. Fixed cost is tied to the amount of quota and is given as { "fixed_cost": 0.00 } You can also use a rate based pricing model by specifying cpm, cpc, and cpa values as { "cpm": 0.00, "cpc": 0.00, "cpa": 0.00 }.

payout_percent

integer/float

The percentage of the ad generated revenue paid out to the publisher. Publisher payout is ideal for profit sharing where the revenue is split between money earned by the advertiser and money earned by the publisher. Defaults to 0.00 percent.

geo_target

integer

The geotarget identifier (ID) if you want your ads to be delivered to a particular location only. This will direct your audience to ads in their region. Defaults to null which means geographic targeting is not in effect.

platform_target

integer

The platform target identifier (ID) if you intend to restrict delivery of your ads to a certain device or a platform. Defaults to null which means platform targeting is not in effect.

keywords

string

Specify words separated by commas to determine if this ad should be served if a match is found. Use asterisk "*" character to represent a wildcard in a keyword e.g. "paint*" would match paint, painter, painting, paints etc. You can also stop the ad from being served in presence of a specific word by prepending a negative sign (-) to the word. For example, "-paint" would stop the ad from being delivered if the word "paint" is used.

keywords_match_method

string

Whether to serve the ad only if a match is found (required) or increase the serving priority of an ad whenever a match is found (preferred).

Returns

Returns a placement object if the request succeeded, or an error if something went terribly wrong.

Delete a placement

Definition

DELETE https://api.adbutler.com/v1/placements/{PLACEMENT-ID}
\AdButler\Placement->delete()
adbutler.placements.delete()

Example Request

curl "https://api.adbutler.com/v1/placements/18597" \
  -H "Authorization: Basic {API_KEY}" \
  -X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$placement = \AdButler\Placement::retrieve( 18597 );
$placement->delete();

echo $placement;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.placements.delete(18597, function(err, response) {
  console.log(response);
});

// using promises
adbutler.placements.delete(18597).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "id": 18597,
  "delete": true
}
AdButler\Placement JSON: {
  "id": 18597,
  "delete": true
}

Permanently deletes a banner placement. if successful, this operation cannot be undone so be very sure when deleting one.

Returns

Returns a placement ID if the request succeeded, or an error if something went terribly wrong.

List all placements

Definition

GET https://api.adbutler.com/v1/placements
\AdButler\Placement::retrieveAll()
adbutler.placements.list()

Example Request

curl "https://api.adbutler.com/v1/placements?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$placement = \AdButler\Placement::retrieveAll(array(
  "limit" => 2
));

echo $placement;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.placements.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.placements.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/placements",
  "data": [
    {
      "object": "placement",
      "self": "/v1/placements/18377",
      "id": 18377,
      "active": true,
      "advertisement": {
        "id": 518889708,
        "type": "image_banner"
      },
      "channel": null,
      "cost": [],
      "created_date": "2018-06-28 09:48:12",
      "day_cap_limit": null,
      "day_cap_type": null,
      "geo_target": null,
      "isp_target": null,
      "keywords": "",
      "keywords_match_method": "preferred",
      "payout_percent": null,
      "per_user_view_limit": null,
      "per_user_view_period": null,
      "platform_target": null,
      "priority": "standard",
      "schedule": 22512,
      "weight": 1,
      "zone": {
        "id": 104022,
        "type": "banner_zone"
      }
    },
    {
      "object": "placement",
      "self": "/v1/placements/18378",
      "id": 18378,
      "active": true,
      "advertisement": {
        "id": 4567,
        "type": "text_ad"
      },
      "channel": null,
      "cost": [],
      "created_date": "2018-06-28 09:48:12",
      "day_cap_limit": null,
      "day_cap_type": null,
      "geo_target": null,
      "isp_target": null,
      "keywords": "",
      "keywords_match_method": "preferred",
      "payout_percent": null,
      "per_user_view_limit": null,
      "per_user_view_period": null,
      "platform_target": null,
      "priority": "standard",
      "schedule": 22513,
      "weight": 1,
      "zone": {
        "id": 104023,
        "type": "text_zone"
      }
    }
  ]
}
AdButler\Placement JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/placements",
  "data": [
    {
      "object": "placement",
      "self": "/v1/placements/18377",
      "id": 18377,
      "active": true,
      "advertisement": {
        "id": 518889708,
        "type": "image_banner"
      },
      "channel": null,
      "cost": [],
      "created_date": "2018-06-28 09:48:12",
      "day_cap_limit": null,
      "day_cap_type": null,
      "geo_target": null,
      "isp_target": null,
      "keywords": "",
      "keywords_match_method": "preferred",
      "payout_percent": null,
      "per_user_view_limit": null,
      "per_user_view_period": null,
      "platform_target": null,
      "priority": "standard",
      "schedule": 22512,
      "weight": 1,
      "zone": {
        "id": 104022,
        "type": "banner_zone"
      }
    },
    {
      "object": "placement",
      "self": "/v1/placements/18378",
      "id": 18378,
      "active": true,
      "advertisement": {
        "id": 4567,
        "type": "text_ad"
      },
      "channel": null,
      "cost": [],
      "created_date": "2018-06-28 09:48:12",
      "day_cap_limit": null,
      "day_cap_type": null,
      "geo_target": null,
      "isp_target": null,
      "keywords": "",
      "keywords_match_method": "preferred",
      "payout_percent": null,
      "per_user_view_limit": null,
      "per_user_view_period": null,
      "platform_target": null,
      "priority": "standard",
      "schedule": 22513,
      "weight": 1,
      "zone": {
        "id": 104023,
        "type": "text_zone"
      }
    }
  ]
}

Returns a list of all the banner placements. Most recent banner placements appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is a placement object, and if no objects were found the list will be empty.

Retrieve placement conversion tag

Definition

GET https://api.adbutler.com/v1/placements/{PLACEMENT-ID}/conversion-tag
\AdButler\PlacementConvTag::retrieve()
adbutler.placements.conversionTag.retrieve()

Example Request

curl "https://api.adbutler.com/v1/placements/ID/conversion-tag/18597" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$placementConvTag = \AdButler\PlacementConvTag::retrieve( 18597 );

echo $placementConvTag;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.placements.conversionTag.read(18597, function(err, response) {
  console.log(response);
});

// using promises
adbutler.placements.conversionTag.read(18597).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Retrieves an HTML tag which can be used to track conversions for the provided placement.

Query Parameters

Parameter Description

protocol

Whether to use http or https protocol when serving the advertisements. Use https only if you are using secure pages because it does not support Custom Domains.

Returns

Example Response

{
  "object": "conv_tag",
  "url": "/v1/placements/18597/conversion-tag",
  "data": {
    "src": "https://servedbyadbutler.com.vm.test/convtrack.spark?MID=108607&placementID=18597",
    "html": "<img src='https://servedbyadbutler.com.vm.test/convtrack.spark?MID=108607&placementID=18597' width='1' height='1' border='0' />"
  }
}
AdButler\PlacementConvTag JSON: {
  "object": "conv_tag",
  "url": "/v1/placements/18597/conversion-tag",
  "data": {
    "src": "https://servedbyadbutler.com.vm.test/convtrack.spark?MID=108607&placementID=18597",
    "html": "<img src='https://servedbyadbutler.com.vm.test/convtrack.spark?MID=108607&placementID=18597' width='1' height='1' border='0' />"
  }
}
Field Type Description

object

string

A string denoting the object type which is always conv_tag for the current resource.

url

string

The relative URL of the current resource which is always of the form /v1/placements/{PLACEMENT_ID}/conversion-tag.

data

array

The data object containing the conversion tag.

 

Returns a conv_tag object if the request succeeded, or an error if something went terribly wrong.


Geo Targets

Introduction

Geo-targets enable you to deliver advertisements to users based on their geographic location. This is an effective way of reducing wasted impressions and increasing your return on investment.

You may inclusively or exclusively target by country, region and city, and additionally other cities found within a specified range.

The geo_target response object contains the following fields:

Example Response

{
  "object": "geo_target",
  "self": "/v1/geo-targets/1785",
  "id": 1785,
  "range": 3,
  "unit": "kilometers",
  "inclusive": true,
  "name": "Demo Geo Target",
  "areas": [
    {
      "country": "NZ",
      "region": "Ontago",
      "city": "Arrowtown"
    },
    {
      "country": "AU",
      "region": "New South Wales",
      "city": null
    },
    {
      "country": "GL",
      "region": null,
      "city": null
    },
    {
      "country": "UM",
      "region": null,
      "city": null
    },
    {
      "country": "BM",
      "region": null,
      "city": null
    },
    {
      "country": "CA",
      "region": null,
      "city": null
    },
    {
      "country": "US",
      "region": null,
      "city": null
    }
  ]
}
AdButler\GeoTarget JSON: {
  "object": "geo_target",
  "self": "/v1/geo-targets/1785",
  "id": 1785,
  "range": 3,
  "unit": "kilometers",
  "inclusive": true,
  "name": "Demo Geo Target",
  "areas": [
    {
      "country": "NZ",
      "region": "Ontago",
      "city": "Arrowtown"
    },
    {
      "country": "AU",
      "region": "New South Wales",
      "city": null
    },
    {
      "country": "GL",
      "region": null,
      "city": null
    },
    {
      "country": "UM",
      "region": null,
      "city": null
    },
    {
      "country": "BM",
      "region": null,
      "city": null
    },
    {
      "country": "CA",
      "region": null,
      "city": null
    },
    {
      "country": "US",
      "region": null,
      "city": null
    }
  ]
}
Field Type Description

object

string

A string denoting the object type which is always geo_target for the current resource.

self

string

The relative URL of the current resource which is always of the form /v1/geo-targets/{GEO_TARGET_ID}.

id

integer

The current resource identifier (ID).

range

integer

The additional distance around the selected locations to include in the target.

unit

string

The unit of distance for the range field.

inclusive

boolean

Whether it is an inclusion or an exclusion target.

name

string

The name of the geographic target.

areas

array

The list of the targeted locations.

Create a geo target

Definition

POST https://api.adbutler.com/v1/geo-targets
\AdButler\GeoTarget::create()
adbutler.targets.geo.create()

Example Request

curl "https://api.adbutler.com/v1/geo-targets" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{  
        "range": 3,
        "unit": "kilometers",
        "inclusive": true,
        "name": "Demo Geo Target",
        "areas": [
                {
                        country: "NZ",
                        region: "Ontago",
                        city: "Arrowtown"
                },
                {
                        country: "AU",
                        region: "New South Wales",
                        city: null
                },
                {
                        country: "GL",
                        region: null,
                        city: null
                },
                {
                        country: "UM",
                        region: null,
                        city: null
                },
                {
                        country: "BM",
                        region: null,
                        city: null
                },
                {
                        country: "CA",
                        region: null,
                        city: null
                },
                {
                        country: "US",
                        region: null,
                        city: null
                }
        ]
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$geoTarget = \AdButler\GeoTarget::create(array(
  "range" => 3,
  "unit" => "kilometers",
  "inclusive" => true,
  "name" => "Demo Geo Target",
  "areas" => [
    [
      country => "NZ",
      region => "Ontago",
      city => "Arrowtown"
    ],
    [
      country => "AU",
      region => "New South Wales",
      city => null
    ],
    [
      country => "GL",
      region => null,
      city => null
    ],
    [
      country => "UM",
      region => null,
      city => null
    ],
    [
      country => "BM",
      region => null,
      city => null
    ],
    [
      country => "CA",
      region => null,
      city => null
    ],
    [
      country => "US",
      region => null,
      city => null
    ]
  ]
));

echo $geoTarget;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var postData = {
  "range": 3,
  "unit": "kilometers",
  "inclusive": true,
  "name": "Demo Geo Target",
  "areas": [
    {
      country: "NZ",
      region: "Ontago",
      city: "Arrowtown"
    },
    {
      country: "AU",
      region: "New South Wales",
      city: null
    },
    {
      country: "GL",
      region: null,
      city: null
    },
    {
      country: "UM",
      region: null,
      city: null
    },
    {
      country: "BM",
      region: null,
      city: null
    },
    {
      country: "CA",
      region: null,
      city: null
    },
    {
      country: "US",
      region: null,
      city: null
    }
  ]
};

// using callbacks
adbutler.targets.geo.create(postData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.targets.geo.create(postData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "geo_target",
  "self": "/v1/geo-targets/1785",
  "id": 1785,
  "range": 3,
  "unit": "kilometers",
  "inclusive": true,
  "name": "Demo Geo Target",
  "areas": [
    {
      "country": "NZ",
      "region": "Ontago",
      "city": "Arrowtown"
    },
    {
      "country": "AU",
      "region": "New South Wales",
      "city": null
    },
    {
      "country": "GL",
      "region": null,
      "city": null
    },
    {
      "country": "UM",
      "region": null,
      "city": null
    },
    {
      "country": "BM",
      "region": null,
      "city": null
    },
    {
      "country": "CA",
      "region": null,
      "city": null
    },
    {
      "country": "US",
      "region": null,
      "city": null
    }
  ]
}
AdButler\GeoTarget JSON: {
  "object": "geo_target",
  "self": "/v1/geo-targets/1785",
  "id": 1785,
  "range": 3,
  "unit": "kilometers",
  "inclusive": true,
  "name": "Demo Geo Target",
  "areas": [
    {
      "country": "NZ",
      "region": "Ontago",
      "city": "Arrowtown"
    },
    {
      "country": "AU",
      "region": "New South Wales",
      "city": null
    },
    {
      "country": "GL",
      "region": null,
      "city": null
    },
    {
      "country": "UM",
      "region": null,
      "city": null
    },
    {
      "country": "BM",
      "region": null,
      "city": null
    },
    {
      "country": "CA",
      "region": null,
      "city": null
    },
    {
      "country": "US",
      "region": null,
      "city": null
    }
  ]
}

Creates a new geographic target.

Field Type Description

name*

string

A descriptive name of the geographic target.

range

integer

The additional distance around the selected areas for searching cities within to include in the target.

unit

string

The unit of distance for the range field which is either miles or kilometers.

inclusive

boolean

Whether it is an inclusion or an exclusion target.

areas*

boolean

A list of areas included in the current geo-target. Each area object represents some location on the map and may look like this: { "continent": "North America", "country": "CA", "region": "BC", "city": "Victoria" }. Possible values for the continent field are: "North America", "Europe", "Asia", "Oceania", "Central America", "South America", "Africa", or "Antarctica". The country field only accepts a two letter country code e.g. "CA" for Canada.

* = required field

Returns

Returns a geo_target object if the request succeeded, or an error if something went terribly wrong.

Retrieve a geo target

Definition

GET https://api.adbutler.com/v1/geo-targets/{GEO-TARGET-ID}
\AdButler\GeoTarget::retrieve()
adbutler.targets.geo.retrieve()

Example Request

curl "https://api.adbutler.com/v1/geo-targets/1785" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$geoTarget = \AdButler\GeoTarget::retrieve( 1785 );

echo $geoTarget;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.targets.geo.read(1785, function(err, response) {
  console.log(response);
});

// using promises
adbutler.targets.geo.read(1785).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "geo_target",
  "self": "/v1/geo-targets/1785",
  "id": 1785,
  "range": 3,
  "unit": "kilometers",
  "inclusive": true,
  "name": "Demo Geo Target",
  "areas": [
    {
      "country": "NZ",
      "region": "Ontago",
      "city": "Arrowtown"
    },
    {
      "country": "AU",
      "region": "New South Wales",
      "city": null
    },
    {
      "country": "GL",
      "region": null,
      "city": null
    },
    {
      "country": "UM",
      "region": null,
      "city": null
    },
    {
      "country": "BM",
      "region": null,
      "city": null
    },
    {
      "country": "CA",
      "region": null,
      "city": null
    },
    {
      "country": "US",
      "region": null,
      "city": null
    }
  ]
}
AdButler\GeoTarget JSON: {
  "object": "geo_target",
  "self": "/v1/geo-targets/1785",
  "id": 1785,
  "range": 3,
  "unit": "kilometers",
  "inclusive": true,
  "name": "Demo Geo Target",
  "areas": [
    {
      "country": "NZ",
      "region": "Ontago",
      "city": "Arrowtown"
    },
    {
      "country": "AU",
      "region": "New South Wales",
      "city": null
    },
    {
      "country": "GL",
      "region": null,
      "city": null
    },
    {
      "country": "UM",
      "region": null,
      "city": null
    },
    {
      "country": "BM",
      "region": null,
      "city": null
    },
    {
      "country": "CA",
      "region": null,
      "city": null
    },
    {
      "country": "US",
      "region": null,
      "city": null
    }
  ]
}

You can retrieve the information about an existing geo-target by giving the geo target ID that was returned in the geo-target object upon creation. You will see at the most 10 geo-targets in the response. You can change this default limit by appending ?limit=25 if you want this request to return 25 geo-targets.

Returns

Returns a geo_target object if the request succeeded, or an error if something went terribly wrong.

Update a geo target

Definition

PUT https://api.adbutler.com/v1/geo-targets/{GEO-TARGET-ID}
\AdButler\GeoTarget->save()
adbutler.targets.geo.update()

Example Request

curl "https://api.adbutler.com/v1/geo-targets/1785" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{  
        "range": 3,
        "unit": "kilometers",
        "inclusive": true,
        "name": "Demo Geo Target",
        "areas": [
                {
                        country: "NZ",
                        region: "Ontago",
                        city: "Arrowtown"
                },
                {
                        country: "AU",
                        region: "New South Wales",
                        city: null
                },
                {
                        country: "GL",
                        region: null,
                        city: null
                },
                {
                        country: "UM",
                        region: null,
                        city: null
                },
                {
                        country: "BM",
                        region: null,
                        city: null
                },
                {
                        country: "CA",
                        region: null,
                        city: null
                },
                {
                        country: "US",
                        region: null,
                        city: null
                }
        ]
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$geoTarget = \AdButler\GeoTarget::retrieve( 1785 );

$geoTarget->range = 3;
$geoTarget->unit = "kilometers";
$geoTarget->inclusive = true;
$geoTarget->name = "Demo Geo Target";
$geoTarget->areas = [
[
country = "NZ",
region = "Ontago",
city = "Arrowtown"
],
[
country = "AU",
region = "New South Wales",
city = null
],
[
country = "GL",
region = null,
city = null
],
[
country = "UM",
region = null,
city = null
],
[
country = "BM",
region = null,
city = null
],
[
country = "CA",
region = null,
city = null
],
[
country = "US",
region = null,
city = null
]
];

$geoTarget->save();

echo $geoTarget;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var updateData = {
  "range": 3,
  "unit": "kilometers",
  "inclusive": true,
  "name": "Demo Geo Target",
  "areas": [
    {
      country: "NZ",
      region: "Ontago",
      city: "Arrowtown"
    },
    {
      country: "AU",
      region: "New South Wales",
      city: null
    },
    {
      country: "GL",
      region: null,
      city: null
    },
    {
      country: "UM",
      region: null,
      city: null
    },
    {
      country: "BM",
      region: null,
      city: null
    },
    {
      country: "CA",
      region: null,
      city: null
    },
    {
      country: "US",
      region: null,
      city: null
    }
  ]
};

// using callbacks
adbutler.targets.geo.update(1785, updateData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.targets.geo.update(1785, updateData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "geo_target",
  "self": "/v1/geo-targets/1785",
  "id": 1785,
  "range": 3,
  "unit": "kilometers",
  "inclusive": true,
  "name": "Demo Geo Target",
  "areas": [
    {
      "country": "NZ",
      "region": "Ontago",
      "city": "Arrowtown"
    },
    {
      "country": "AU",
      "region": "New South Wales",
      "city": null
    },
    {
      "country": "GL",
      "region": null,
      "city": null
    },
    {
      "country": "UM",
      "region": null,
      "city": null
    },
    {
      "country": "BM",
      "region": null,
      "city": null
    },
    {
      "country": "CA",
      "region": null,
      "city": null
    },
    {
      "country": "US",
      "region": null,
      "city": null
    }
  ]
}
AdButler\GeoTarget JSON: {
  "object": "geo_target",
  "self": "/v1/geo-targets/1785",
  "id": 1785,
  "range": 3,
  "unit": "kilometers",
  "inclusive": true,
  "name": "Demo Geo Target",
  "areas": [
    {
      "country": "NZ",
      "region": "Ontago",
      "city": "Arrowtown"
    },
    {
      "country": "AU",
      "region": "New South Wales",
      "city": null
    },
    {
      "country": "GL",
      "region": null,
      "city": null
    },
    {
      "country": "UM",
      "region": null,
      "city": null
    },
    {
      "country": "BM",
      "region": null,
      "city": null
    },
    {
      "country": "CA",
      "region": null,
      "city": null
    },
    {
      "country": "US",
      "region": null,
      "city": null
    }
  ]
}

You can update a specific geo-target account by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the geo-target creation request.

Field Type Description

name

string

A descriptive name of the geographic target.

range

integer

The additional distance around the selected areas for searching cities within to include in the target.

unit

string

The unit of distance for the range field which is either miles or kilometers.

inclusive

boolean

Whether it is an inclusion or an exclusion target.

areas

boolean

A list of areas included in the current geo-target. Each area object represents some location on the map and may look like this: { "continent": "North America", "country": "CA", "region": "BC", "city": "Victoria" }. Possible values for the continent field are: "North America", "Europe", "Asia", "Oceania", "Central America", "South America", "Africa", or "Antarctica". The country field only accepts a two letter country code e.g. "CA" for Canada.

Returns

Returns a geo_target object if the request succeeded, or an error if something went terribly wrong.

Delete a geo target

Definition

DELETE https://api.adbutler.com/v1/geo-targets/{GEO-TARGET-ID}
\AdButler\GeoTarget->delete()
adbutler.targets.geo.delete()

Example Request

curl "https://api.adbutler.com/v1/geo-targets/1785" \
  -H "Authorization: Basic {API_KEY}" \
  -X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$geoTarget = \AdButler\GeoTarget::retrieve( 1785 );
$geoTarget->delete();

echo $geoTarget;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.targets.geo.delete(1785, function(err, response) {
  console.log(response);
});

// using promises
adbutler.targets.geo.delete(1785).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/geo-targets",
  "data": [
    {
      "object": "geo_target",
      "self": "/v1/geo-targets/1426",
      "id": 1426,
      "range": 200,
      "unit": "miles",
      "inclusive": true,
      "name": "Adbutler API Test Target (Wasif)",
      "areas": [
        {
          "country": "CA",
          "region": "British Columbia",
          "city": "Vancouver"
        },
        {
          "country": "CA",
          "region": "British Columbia",
          "city": ""
        },
        {
          "country": "US",
          "region": "Washington",
          "city": ""
        },
        {
          "country": "CA",
          "region": "British Columbia",
          "city": "100 Mile House"
        },
        {
          "country": "US",
          "region": "Washington",
          "city": "Noon"
        }
      ]
    },
    {
      "object": "geo_target",
      "self": "/v1/geo-targets/1454",
      "id": 1454,
      "range": 10,
      "unit": "miles",
      "inclusive": false,
      "name": "Adbutler API Test Target (Wasif)",
      "areas": [
        {
          "country": "US",
          "region": null,
          "city": null
        },
        {
          "country": "CA",
          "region": null,
          "city": null
        },
        {
          "country": "AU",
          "region": "New South Wales",
          "city": null
        },
        {
          "country": "NZ",
          "region": "Otago",
          "city": "Arrowtown"
        },
        {
          "country": "NZ",
          "region": "Otago",
          "city": "Wharehuanui"
        }
      ]
    }
  ]
}
AdButler\Collection JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/geo-targets",
  "data": [
    AdButler\GeoTarget JSON: {
      "object": "geo_target",
      "self": "/v1/geo-targets/1426",
      "id": 1426,
      "range": 200,
      "unit": "miles",
      "inclusive": true,
      "name": "Adbutler API Test Target (Wasif)",
      "areas": [
        {
          "country": "CA",
          "region": "British Columbia",
          "city": "Vancouver"
        },
        {
          "country": "CA",
          "region": "British Columbia",
          "city": ""
        },
        {
          "country": "US",
          "region": "Washington",
          "city": ""
        },
        {
          "country": "CA",
          "region": "British Columbia",
          "city": "100 Mile House"
        },
        {
          "country": "US",
          "region": "Washington",
          "city": "Noon"
        }
      ]
    },
    AdButler\GeoTarget JSON: {
      "object": "geo_target",
      "self": "/v1/geo-targets/1454",
      "id": 1454,
      "range": 10,
      "unit": "miles",
      "inclusive": false,
      "name": "Adbutler API Test Target (Wasif)",
      "areas": [
        {
          "country": "US",
          "region": null,
          "city": null
        },
        {
          "country": "CA",
          "region": null,
          "city": null
        },
        {
          "country": "AU",
          "region": "New South Wales",
          "city": null
        },
        {
          "country": "NZ",
          "region": "Otago",
          "city": "Arrowtown"
        },
        {
          "country": "NZ",
          "region": "Otago",
          "city": "Wharehuanui"
        }
      ]
    }
  ]
}

Permanently deletes a geo-target. if successful, this operation cannot be undone so be very sure when deleting one.

Returns

Returns a geo-target ID if the request succeeded, or an error if something went terribly wrong.

List all geo targets

Definition

GET https://api.adbutler.com/v1/geo-targets
\AdButler\GeoTarget::retrieveAll()
adbutler.targets.geo.list()

Example Request

curl "https://api.adbutler.com/v1/geo-targets?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$geoTarget = \AdButler\GeoTarget::retrieveAll(array(
  "limit" => 2
));

echo $geoTarget;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.targets.geo.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.targets.geo.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/geo-targets",
  "data": [
    {
      "object": "geo_target",
      "self": "/v1/geo-targets/1770",
      "id": 1770,
      "range": 3,
      "unit": "kilometers",
      "inclusive": true,
      "name": "Demo Geo Target",
      "areas": [
        {
          "country": "US",
          "region": null,
          "city": null
        },
        {
          "country": "CA",
          "region": null,
          "city": null
        },
        {
          "country": "BM",
          "region": null,
          "city": null
        },
        {
          "country": "UM",
          "region": null,
          "city": null
        },
        {
          "country": "GL",
          "region": null,
          "city": null
        },
        {
          "country": "AU",
          "region": "New South Wales",
          "city": null
        },
        {
          "country": "NZ",
          "region": "Ontago",
          "city": "Arrowtown"
        }
      ]
    },
    {
      "object": "geo_target",
      "self": "/v1/geo-targets/1785",
      "id": 1785,
      "range": 3,
      "unit": "kilometers",
      "inclusive": true,
      "name": "Demo Geo Target",
      "areas": [
        {
          "country": "NZ",
          "region": "Ontago",
          "city": "Arrowtown"
        },
        {
          "country": "AU",
          "region": "New South Wales",
          "city": null
        },
        {
          "country": "GL",
          "region": null,
          "city": null
        },
        {
          "country": "UM",
          "region": null,
          "city": null
        },
        {
          "country": "BM",
          "region": null,
          "city": null
        },
        {
          "country": "CA",
          "region": null,
          "city": null
        },
        {
          "country": "US",
          "region": null,
          "city": null
        }
      ]
    }
  ]
}
AdButler\GeoTarget JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/geo-targets",
  "data": [
    {
      "object": "geo_target",
      "self": "/v1/geo-targets/1770",
      "id": 1770,
      "range": 3,
      "unit": "kilometers",
      "inclusive": true,
      "name": "Demo Geo Target",
      "areas": [
        {
          "country": "US",
          "region": null,
          "city": null
        },
        {
          "country": "CA",
          "region": null,
          "city": null
        },
        {
          "country": "BM",
          "region": null,
          "city": null
        },
        {
          "country": "UM",
          "region": null,
          "city": null
        },
        {
          "country": "GL",
          "region": null,
          "city": null
        },
        {
          "country": "AU",
          "region": "New South Wales",
          "city": null
        },
        {
          "country": "NZ",
          "region": "Ontago",
          "city": "Arrowtown"
        }
      ]
    },
    {
      "object": "geo_target",
      "self": "/v1/geo-targets/1785",
      "id": 1785,
      "range": 3,
      "unit": "kilometers",
      "inclusive": true,
      "name": "Demo Geo Target",
      "areas": [
        {
          "country": "NZ",
          "region": "Ontago",
          "city": "Arrowtown"
        },
        {
          "country": "AU",
          "region": "New South Wales",
          "city": null
        },
        {
          "country": "GL",
          "region": null,
          "city": null
        },
        {
          "country": "UM",
          "region": null,
          "city": null
        },
        {
          "country": "BM",
          "region": null,
          "city": null
        },
        {
          "country": "CA",
          "region": null,
          "city": null
        },
        {
          "country": "US",
          "region": null,
          "city": null
        }
      ]
    }
  ]
}

Returns a list of all the geo-targets. Most recent geo-targets appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is a geo_target object, and if no objects were found the list will be empty.


ISP Targets

Introduction

Direct users to ads relevant to them using ISP Targets, which help filter your audience by specific Internet Service Providers using Autonomous System Numbers (ASNs) ASN is a number which uniquely identifies each network on the Internet.

The isp_target response object has the following fields.

Example Response

{
  "object": "isp_target",
  "self": "/v1/isp-targets/412",
  "id": 412,
  "name": "Demo ISP Target",
  "asn_list": [
    {
      "asn": "24",
      "isp": "National Aeronautics and Space Administration"
    },
    {
      "asn": "1234",
      "isp": "Fortum"
    },
    {
      "asn": "2345",
      "isp": "France Telecom"
    }
  ]
}
AdButler\ISPTarget JSON: {
  "object": "isp_target",
  "self": "/v1/isp-targets/412",
  "id": 412,
  "name": "Demo ISP Target",
  "asn_list": [
    {
      "asn": 24,
      "isp": "National Aeronautics and Space Administration"
    },
    {
      "asn": 1234,
      "isp": "Fortum"
    },
    {
      "asn": 2345,
      "isp": "France Telecom"
    }
  ]
}
Field Type Description

object

string

A string denoting the object type which is always isp_target for the current resource.

self

string

The relative URL of the current resource which is always of the form /v1/isp-targets/{ISP_TARGET_ID}.

id

integer

The current resource identifier (ID).

name

string

A descriptive name of the ISP Target.

asn_list

array

A list of targeted Autonomous System Numbers (ASNs).

Create an ISP target

Definition

POST https://api.adbutler.com/v1/isp-targets
\AdButler\ISPTarget::create()
adbutler.targets.isp.create()

Example Request

curl "https://api.adbutler.com/v1/isp-targets" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{  
        "name": "Demo ISP Target",
        "asn_list": [
                {
                        asn: "24",
                        isp: "National Aeronautics and Space Administration"
                },
                {
                        asn: "1234",
                        isp: "Fortum"
                },
                {
                        asn: "2345",
                        isp: "France Telecom"
                }
        ]
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$iSPTarget = \AdButler\ISPTarget::create(array(
  "name" => "Demo ISP Target",
  "asn_list" => [
    [
      asn => "24",
      isp => "National Aeronautics and Space Administration"
    ],
    [
      asn => "1234",
      isp => "Fortum"
    ],
    [
      asn => "2345",
      isp => "France Telecom"
    ]
  ]
));

echo $iSPTarget;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var postData = {
  "name": "Demo ISP Target",
  "asn_list": [
    {
      asn: "24",
      isp: "National Aeronautics and Space Administration"
    },
    {
      asn: "1234",
      isp: "Fortum"
    },
    {
      asn: "2345",
      isp: "France Telecom"
    }
  ]
};

// using callbacks
adbutler.targets.isp.create(postData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.targets.isp.create(postData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "isp_target",
  "self": "/v1/isp-targets/412",
  "id": 412,
  "name": "Demo ISP Target",
  "asn_list": [
    {
      "asn": "24",
      "isp": "National Aeronautics and Space Administration"
    },
    {
      "asn": "1234",
      "isp": "Fortum"
    },
    {
      "asn": "2345",
      "isp": "France Telecom"
    }
  ]
}
AdButler\ISPTarget JSON: {
  "object": "isp_target",
  "self": "/v1/isp-targets/412",
  "id": 412,
  "name": "Demo ISP Target",
  "asn_list": [
    {
      "asn": 24,
      "isp": "National Aeronautics and Space Administration"
    },
    {
      "asn": 1234,
      "isp": "Fortum"
    },
    {
      "asn": 2345,
      "isp": "France Telecom"
    }
  ]
}

Creates a new ISP target.

Field Type Description

name*

string

A descriptive name of the ISP target.

asn_list*

array

The list of Autonomous System Numbers (ASNs) to include in the target. The list can be found here.

* = required field

Returns

Returns an isp_target object if the request succeeded, or an error if something went terribly wrong.

Retrieve an ISP target

Definition

GET https://api.adbutler.com/v1/isp-targets/{ISP-TARGET-ID}
\AdButler\ISPTarget::retrieve()
adbutler.targets.isp.retrieve()

Example Request

curl "https://api.adbutler.com/v1/isp-targets/412" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$iSPTarget = \AdButler\ISPTarget::retrieve( 412 );

echo $iSPTarget;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.targets.isp.read(412, function(err, response) {
  console.log(response);
});

// using promises
adbutler.targets.isp.read(412).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "isp_target",
  "self": "/v1/isp-targets/412",
  "id": 412,
  "name": "Demo ISP Target",
  "asn_list": [
    {
      "asn": "24",
      "isp": "National Aeronautics and Space Administration"
    },
    {
      "asn": "1234",
      "isp": "Fortum"
    },
    {
      "asn": "2345",
      "isp": "France Telecom"
    }
  ]
}
AdButler\ISPTarget JSON: {
  "object": "isp_target",
  "self": "/v1/isp-targets/412",
  "id": 412,
  "name": "Demo ISP Target",
  "asn_list": [
    {
      "asn": 24,
      "isp": "National Aeronautics and Space Administration"
    },
    {
      "asn": 1234,
      "isp": "Fortum"
    },
    {
      "asn": 2345,
      "isp": "France Telecom"
    }
  ]
}

You can retrieve the information about an existing ISP target by giving the ISP target ID that was returned in the ISP target object upon creation. You will see at the most 10 ISP targets in the response. You can change this default limit by appending ?limit=25 if you want this request to return 25 ISP targets.

Returns

Returns an isp_target object if the request succeeded, or an error if something went terribly wrong.

Update an ISP target

Definition

PUT https://api.adbutler.com/v1/isp-targets/{ISP-TARGET-ID}
\AdButler\ISPTarget->save()
adbutler.targets.isp.update()

Example Request

curl "https://api.adbutler.com/v1/isp-targets/412" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{  
        "name": "Demo ISP Target",
        "asn_list": [
                {
                        asn: "24",
                        isp: "National Aeronautics and Space Administration"
                },
                {
                        asn: "1234",
                        isp: "Fortum"
                },
                {
                        asn: "2345",
                        isp: "France Telecom"
                }
        ]
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$iSPTarget = \AdButler\ISPTarget::retrieve( 412 );

$iSPTarget->name = "Demo ISP Target";
$iSPTarget->asn_list = [
[
asn = "24",
isp = "National Aeronautics and Space Administration"
],
[
asn = "1234",
isp = "Fortum"
],
[
asn = "2345",
isp = "France Telecom"
]
];

$iSPTarget->save();

echo $iSPTarget;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var updateData = {
  "name": "Demo ISP Target",
  "asn_list": [
    {
      asn: "24",
      isp: "National Aeronautics and Space Administration"
    },
    {
      asn: "1234",
      isp: "Fortum"
    },
    {
      asn: "2345",
      isp: "France Telecom"
    }
  ]
};

// using callbacks
adbutler.targets.isp.update(412, updateData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.targets.isp.update(412, updateData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "isp_target",
  "self": "/v1/isp-targets/412",
  "id": 412,
  "name": "Demo ISP Target",
  "asn_list": [
    {
      "asn": "24",
      "isp": "National Aeronautics and Space Administration"
    },
    {
      "asn": "1234",
      "isp": "Fortum"
    },
    {
      "asn": "2345",
      "isp": "France Telecom"
    }
  ]
}
AdButler\ISPTarget JSON: {
  "object": "isp_target",
  "self": "/v1/isp-targets/412",
  "id": 412,
  "name": "Demo ISP Target",
  "asn_list": [
    {
      "asn": 24,
      "isp": "National Aeronautics and Space Administration"
    },
    {
      "asn": 1234,
      "isp": "Fortum"
    },
    {
      "asn": 2345,
      "isp": "France Telecom"
    }
  ]
}

You can update a specific ISP target account by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the ISP target creation request.

Field Type Description

name

string

A descriptive name of the ISP target.

asn_list

array

The list of Autonomous System Numbers (ASNs) to include in the target. The list can be found here.

Returns

Returns an isp_target object if the request succeeded, or an error if something went terribly wrong.

Delete an ISP target

Definition

DELETE https://api.adbutler.com/v1/isp-targets/{ISP-TARGET-ID}
\AdButler\ISPTarget->delete()
adbutler.targets.isp.delete()

Example Request

curl "https://api.adbutler.com/v1/isp-targets/412" \
  -H "Authorization: Basic {API_KEY}" \
  -X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$iSPTarget = \AdButler\ISPTarget::retrieve( 412 );
$iSPTarget->delete();

echo $iSPTarget;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.targets.isp.delete(412, function(err, response) {
  console.log(response);
});

// using promises
adbutler.targets.isp.delete(412).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "id": 412,
  "delete": true
}
AdButler\ISPTarget JSON: {
  "id": 412,
  "delete": true
}

Permanently deletes an ISP target. if successful, this operation cannot be undone so be very sure when deleting one.

Returns

Returns an ISP target ID if the request succeeded, or an error if something went terribly wrong.

List all ISP targets

Definition

GET https://api.adbutler.com/v1/isp-targets
\AdButler\ISPTarget::retrieveAll()
adbutler.targets.isp.list()

Example Request

curl "https://api.adbutler.com/v1/isp-targets?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$iSPTarget = \AdButler\ISPTarget::retrieveAll(array(
  "limit" => 2
));

echo $iSPTarget;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.targets.isp.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.targets.isp.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/isp-targets",
  "data": [
    {
      "object": "isp_target",
      "self": "/v1/isp-targets/400",
      "id": 400,
      "name": "Demo ISP Target",
      "asn_list": [
        {
          "asn": "24",
          "isp": "National Aeronautics and Space Administration"
        },
        {
          "asn": "1234",
          "isp": "Fortum"
        },
        {
          "asn": "2345",
          "isp": "France Telecom"
        }
      ]
    },
    {
      "object": "isp_target",
      "self": "/v1/isp-targets/401",
      "id": 401,
      "name": "Demo ISP Target",
      "asn_list": [
        {
          "asn": "24",
          "isp": "National Aeronautics and Space Administration"
        },
        {
          "asn": "1234",
          "isp": "Fortum"
        },
        {
          "asn": "2345",
          "isp": "France Telecom"
        }
      ]
    }
  ]
}
AdButler\ISPTarget JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/isp-targets",
  "data": [
    {
      "object": "isp_target",
      "self": "/v1/isp-targets/400",
      "id": 400,
      "name": "Demo ISP Target",
      "asn_list": [
        {
          "asn": 24,
          "isp": "National Aeronautics and Space Administration"
        },
        {
          "asn": 1234,
          "isp": "Fortum"
        },
        {
          "asn": 2345,
          "isp": "France Telecom"
        }
      ]
    },
    {
      "object": "isp_target",
      "self": "/v1/isp-targets/401",
      "id": 401,
      "name": "Demo ISP Target",
      "asn_list": [
        {
          "asn": 24,
          "isp": "National Aeronautics and Space Administration"
        },
        {
          "asn": 1234,
          "isp": "Fortum"
        },
        {
          "asn": 2345,
          "isp": "France Telecom"
        }
      ]
    }
  ]
}

Returns a list of all the ISP targets. Most recent ISP targets appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is an isp_target object, and if no objects were found the list will be empty.


Platform Targets

Introduction

Target your advertisements to specific mobile/tablet/notebook/desktop devices, or to specific browsers and operating systems to help ensure users get the best ads for their platform. You can also target specific mobile phones or tablets, such as the iPhones or Samsung devices using device targeting filters.

The platform_target response object has the following fields.

Example Response

{
  "object": "platform_target",
  "self": "/v1/platform-targets/1636",
  "id": 1636,
  "name": "Demo Platform Target",
  "platform": "mobile",
  "desktop_browser_targets": [],
  "mobile_browser_targets": [
    "chrome",
    "opera",
    "safari"
  ],
  "desktop_os_targets": [],
  "mobile_os_targets": [
    "android",
    "blackberry",
    "ios",
    "windows_phone"
  ],
  "device_targets": [
    "Nexus*",
    "Apple*"
  ]
}
AdButler\PlatformTarget JSON: {
  "object": "platform_target",
  "self": "/v1/platform-targets/1636",
  "id": 1636,
  "name": "Demo Platform Target",
  "platform": "mobile",
  "desktop_browser_targets": [],
  "mobile_browser_targets": [
    "chrome",
    "opera",
    "safari"
  ],
  "desktop_os_targets": [],
  "mobile_os_targets": [
    "android",
    "blackberry",
    "ios",
    "windows_phone"
  ],
  "device_targets": [
    "Nexus*",
    "Apple*"
  ]
}
Field Type Description

object

string

A string denoting the object type which is always platform_target for the current resource.

self

string

The relative URL of the current resource which is always of the form /v1/platform-targets/{PLATFORM_TARGET_ID}.

id

integer

The current resource identifier (ID).

name

string

A descriptive name of the platform target.

platform

string

A preset grouping of the platform target.

desktop_browser_targets

array

The list of desktop internet browser included in the platform target.

mobile_browser_targets

array

The list of mobile internet browsers included in the platform target.

desktop_os_targets

array

The list of desktop Operating Systems included in the platform target.

mobile_os_targets

array

The list of mobile Operating Systems included in the platform target.

device_targets

array

The list of device patterns included in the platform target.

Create a platform target

Definition

POST https://api.adbutler.com/v1/platform-targets
\AdButler\PlatformTarget::create()
adbutler.targets.platform.create()

Example Request

curl "https://api.adbutler.com/v1/platform-targets" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{  
        "name": "Demo Platform Target",
        "platform": "mobile"
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$platformTarget = \AdButler\PlatformTarget::create(array(
  "name" => "Demo Platform Target",
  "platform" => "mobile"
));

echo $platformTarget;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var postData = {
  "name": "Demo Platform Target",
  "platform": "mobile"
};

// using callbacks
adbutler.targets.platform.create(postData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.targets.platform.create(postData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "platform_target",
  "self": "/v1/platform-targets/1636",
  "id": 1636,
  "name": "Demo Platform Target",
  "platform": "mobile",
  "desktop_browser_targets": [],
  "mobile_browser_targets": [
    "chrome",
    "opera",
    "safari"
  ],
  "desktop_os_targets": [],
  "mobile_os_targets": [
    "android",
    "blackberry",
    "ios",
    "windows_phone"
  ],
  "device_targets": [
    "Nexus*",
    "Apple*"
  ]
}
AdButler\PlatformTarget JSON: {
  "object": "platform_target",
  "self": "/v1/platform-targets/1636",
  "id": 1636,
  "name": "Demo Platform Target",
  "platform": "mobile",
  "desktop_browser_targets": [],
  "mobile_browser_targets": [
    "chrome",
    "opera",
    "safari"
  ],
  "desktop_os_targets": [],
  "mobile_os_targets": [
    "android",
    "blackberry",
    "ios",
    "windows_phone"
  ],
  "device_targets": [
    "Nexus*",
    "Apple*"
  ]
}

Creates a new platform target.

Field Type Description

name*

string

A descriptive name of the platform target.

platform

string

A preset platform target including devices of a certain form factor. Possible values are mobile, tablet, desktop, or any.

desktop_browser_targets

array

The list of desktop internet browsers to target. Disabled if null. The list may include any combination of chrome, edge, firefox, ie, opera, or safari as values.

mobile_browser_targets

array

The list of mobile internet browsers to target. Disabled if null. The list may include any combination of android, blackberry, chrome, opera, safari, or uc as values.

desktop_os_targets

array

The list of desktop operating systems to target. Disabled if null. The list may include any combination of linux, mac, windows, or ubuntu as values.

mobile_os_targets

array

The list of mobile operating systems to target. Disabled if null. The list may include any combination of blackberry, ios, series40, symbian, or windows_phoneas values.

device_targets

array

A list of device specific patterns used only if platform is any, mobile, or tablet. Defaults to null. For example, "Apple*" will target iOS devices and "Nexus*" will target nexus devices.

* = required field

Returns

Returns a platform_target object if the request succeeded, or an error if something went terribly wrong.

Retrieve a platform target

Definition

GET https://api.adbutler.com/v1/platform-targets/{PLATFORM-TARGET-ID}
\AdButler\PlatformTarget::retrieve()
adbutler.targets.platform.retrieve()

Example Request

curl "https://api.adbutler.com/v1/platform-targets/1636" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$platformTarget = \AdButler\PlatformTarget::retrieve( 1636 );

echo $platformTarget;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.targets.platform.read(1636, function(err, response) {
  console.log(response);
});

// using promises
adbutler.targets.platform.read(1636).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "platform_target",
  "self": "/v1/platform-targets/1636",
  "id": 1636,
  "name": "Demo Platform Target",
  "platform": "mobile",
  "desktop_browser_targets": [],
  "mobile_browser_targets": [
    "chrome",
    "opera",
    "safari"
  ],
  "desktop_os_targets": [],
  "mobile_os_targets": [
    "android",
    "blackberry",
    "ios",
    "windows_phone"
  ],
  "device_targets": [
    "Nexus*",
    "Apple*"
  ]
}
AdButler\PlatformTarget JSON: {
  "object": "platform_target",
  "self": "/v1/platform-targets/1636",
  "id": 1636,
  "name": "Demo Platform Target",
  "platform": "mobile",
  "desktop_browser_targets": [],
  "mobile_browser_targets": [
    "chrome",
    "opera",
    "safari"
  ],
  "desktop_os_targets": [],
  "mobile_os_targets": [
    "android",
    "blackberry",
    "ios",
    "windows_phone"
  ],
  "device_targets": [
    "Nexus*",
    "Apple*"
  ]
}

You can retrieve the information about an existing platform target by giving the platform target ID that was returned in the platform target object upon creation. You will see at the most 10 platform targets in the response. You can change this default limit by appending ?limit=25 if you want this request to return 25 platform targets.

Returns

Returns a platform_target object if the request succeeded, or an error if something went terribly wrong.

Update a platform target

Definition

PUT https://api.adbutler.com/v1/platform-targets/{PLATFORM-TARGET-ID}
\AdButler\PlatformTarget->save()
adbutler.targets.platform.update()

Example Request

curl "https://api.adbutler.com/v1/platform-targets/1636" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{  
        "name": "Demo Platform Target",
        "platform": "mobile"
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$platformTarget = \AdButler\PlatformTarget::retrieve( 1636 );

$platformTarget->name = "Demo Platform Target";
$platformTarget->platform = "mobile";

$platformTarget->save();

echo $platformTarget;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var updateData = {
  "name": "Demo Platform Target",
  "platform": "mobile"
};

// using callbacks
adbutler.targets.platform.update(1636, updateData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.targets.platform.update(1636, updateData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "platform_target",
  "self": "/v1/platform-targets/1636",
  "id": 1636,
  "name": "Demo Platform Target",
  "platform": "mobile",
  "desktop_browser_targets": [],
  "mobile_browser_targets": [
    "chrome",
    "opera",
    "safari"
  ],
  "desktop_os_targets": [],
  "mobile_os_targets": [
    "android",
    "blackberry",
    "ios",
    "windows_phone"
  ],
  "device_targets": [
    "Nexus*",
    "Apple*"
  ]
}
AdButler\PlatformTarget JSON: {
  "object": "platform_target",
  "self": "/v1/platform-targets/1636",
  "id": 1636,
  "name": "Demo Platform Target",
  "platform": "mobile",
  "desktop_browser_targets": [],
  "mobile_browser_targets": [
    "chrome",
    "opera",
    "safari"
  ],
  "desktop_os_targets": [],
  "mobile_os_targets": [
    "android",
    "blackberry",
    "ios",
    "windows_phone"
  ],
  "device_targets": [
    "Nexus*",
    "Apple*"
  ]
}

You can update a specific platform target by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the platform target creation request.

Field Type Description

name

string

A descriptive name of the platform target.

platform

string

A preset platform target including devices of a certain form factor. Possible values are mobile, tablet, desktop, or any.

desktop_browser_targets

array

The list of desktop internet browsers to target. Disabled if null. The list may include any combination of chrome, edge, firefox, ie, opera, or safari as values.

mobile_browser_targets

array

The list of mobile internet browsers to target. Disabled if null. The list may include any combination of android, blackberry, chrome, opera, safari, or uc as values.

desktop_os_targets

array

The list of desktop operating systems to target. Disabled if null. The list may include any combination of linux, mac, windows, or ubuntu as values.

mobile_os_targets

array

The list of mobile operating systems to target. Disabled if null. The list may include any combination of blackberry, ios, series40, symbian, or windows_phoneas values.

device_targets

array

A list of device specific patterns used only if platform is any, mobile, or tablet. Defaults to null. For example, "Apple*" will target iOS devices and "Nexus*" will target nexus devices.

Returns

Returns a platform_target object if the request succeeded, or an error if something went terribly wrong.

Delete a platform target

Definition

DELETE https://api.adbutler.com/v1/platform-targets/{PLATFORM-TARGET-ID}
\AdButler\PlatformTarget->delete()
adbutler.targets.platform.delete()

Example Request

curl "https://api.adbutler.com/v1/platform-targets/1636" \
  -H "Authorization: Basic {API_KEY}" \
  -X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$platformTarget = \AdButler\PlatformTarget::retrieve( 1636 );
$platformTarget->delete();

echo $platformTarget;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.targets.platform.delete(1636, function(err, response) {
  console.log(response);
});

// using promises
adbutler.targets.platform.delete(1636).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "id": 1636,
  "delete": true
}
AdButler\PlatformTarget JSON: {
  "id": 1636,
  "delete": true
}

Permanently deletes a platform target. If successful, this operation cannot be undone so be very sure when deleting one.

Returns

Returns a platform target ID if the request succeeded, or an error if something went terribly wrong.

List all platform targets

Definition

GET https://api.adbutler.com/v1/platform-targets
\AdButler\PlatformTarget::retrieveAll()
adbutler.targets.platform.list()

Example Request

curl "https://api.adbutler.com/v1/platform-targets?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$platformTarget = \AdButler\PlatformTarget::retrieveAll(array(
  "limit" => 2
));

echo $platformTarget;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.targets.platform.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.targets.platform.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/platform-targets",
  "data": [
    {
      "object": "platform_target",
      "self": "/v1/platform-targets/1635",
      "id": 1635,
      "name": "Demo Platform Target",
      "platform": "mobile",
      "desktop_browser_targets": [],
      "mobile_browser_targets": [
        "chrome",
        "opera",
        "safari"
      ],
      "desktop_os_targets": [],
      "mobile_os_targets": [
        "android",
        "blackberry",
        "ios",
        "windows_phone"
      ],
      "device_targets": [
        "Nexus*",
        "Apple*"
      ]
    },
    {
      "object": "platform_target",
      "self": "/v1/platform-targets/1636",
      "id": 1636,
      "name": "Demo Platform Target",
      "platform": "mobile",
      "desktop_browser_targets": [],
      "mobile_browser_targets": [
        "chrome",
        "opera",
        "safari"
      ],
      "desktop_os_targets": [],
      "mobile_os_targets": [
        "android",
        "blackberry",
        "ios",
        "windows_phone"
      ],
      "device_targets": [
        "Nexus*",
        "Apple*"
      ]
    }
  ]
}
AdButler\PlatformTarget JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/platform-targets",
  "data": [
    {
      "object": "platform_target",
      "self": "/v1/platform-targets/1635",
      "id": 1635,
      "name": "Demo Platform Target",
      "platform": "mobile",
      "desktop_browser_targets": [],
      "mobile_browser_targets": [
        "chrome",
        "opera",
        "safari"
      ],
      "desktop_os_targets": [],
      "mobile_os_targets": [
        "android",
        "blackberry",
        "ios",
        "windows_phone"
      ],
      "device_targets": [
        "Nexus*",
        "Apple*"
      ]
    },
    {
      "object": "platform_target",
      "self": "/v1/platform-targets/1636",
      "id": 1636,
      "name": "Demo Platform Target",
      "platform": "mobile",
      "desktop_browser_targets": [],
      "mobile_browser_targets": [
        "chrome",
        "opera",
        "safari"
      ],
      "desktop_os_targets": [],
      "mobile_os_targets": [
        "android",
        "blackberry",
        "ios",
        "windows_phone"
      ],
      "device_targets": [
        "Nexus*",
        "Apple*"
      ]
    }
  ]
}

Returns a list of all the platform targets. Most recent platform targets appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is a platform_target object, and if no objects were found the list will be empty.


Keyword Targets

Introduction

Keyword targeting is another powerful targeting technique available within AdButler. They are configured in the placements resource. You can specify the relevant keywords in the keywords field. You can specify the keywords match method by specifying either "required" or "preferred" as value to the keywords_match_method field. You will need to modify the zone tag in order to deploy keyword targeting.


Reports

Introduction

Reporting is the new interface to Statistics. It serves to quantify the serving of your advertisements across price and performance related metrics. They are updated in real time. We go to great lengths to give you detailed and accurate data about the performance of your advertisements, to help you make informed decisions. This endpoint enables you to build your own reporting dashboard should you feel the need to.

The report response object has the following fields.

Example Response

{
  "object": "report",
  "url": "/v1/reports",
  "data": [
    {
      "type": "overview",
      "id": 107870,
      "summary": {
        "responses": 222,
        "impressions": 222,
        "clicks": 0,
        "conversions": 0,
        "cost": 5.51,
        "payout": 0,
        "revenue": 5.51,
        "e_cpm": 24.821,
        "e_cpc": 0,
        "e_cpa": 0,
        "breakdown": [
          {
            "placement": 16778,
            "banner": {
              "type": "image_banner",
              "id": 518887977
            },
            "text_ad": null,
            "popup": null,
            "campaign": {
              "type": "banner_campaign",
              "id": 9415
            },
            "zone": {
              "type": "banner_zone",
              "id": 103294
            },
            "responses": 129,
            "impressions": 129,
            "clicks": 0,
            "conversions": 0,
            "cost": 5.509,
            "payout": 0.003,
            "revenue": 5.507,
            "e_cpm": 42.709,
            "e_cpc": 0,
            "e_cpa": 0
          },
          {
            "placement": 16779,
            "banner": {
              "type": "image_banner",
              "id": 518887978
            },
            "text_ad": null,
            "popup": null,
            "campaign": {
              "type": "banner_campaign",
              "id": 9416
            },
            "zone": {
              "type": "banner_zone",
              "id": 103295
            },
            "responses": 93,
            "impressions": 93,
            "clicks": 0,
            "conversions": 0,
            "cost": 0.001,
            "payout": 0,
            "revenue": 0.001,
            "e_cpm": 0.01,
            "e_cpc": 0,
            "e_cpa": 0
          }
        ]
      },
      "details": [
        {
          "start_date": "2017-08-09T00:00:00-07:00",
          "responses": 222,
          "impressions": 222,
          "clicks": 0,
          "conversions": 0,
          "cost": 5.51,
          "payout": 0,
          "revenue": 5.51,
          "e_cpm": 24.821,
          "e_cpc": 0,
          "e_cpa": 0,
          "breakdown": [
            {
              "placement": 16778,
              "banner": {
                "type": "image_banner",
                "id": 518887977
              },
              "text_ad": null,
              "popup": null,
              "campaign": {
                "type": "banner_campaign",
                "id": 9415
              },
              "zone": {
                "type": "banner_zone",
                "id": 103294
              },
              "responses": 129,
              "impressions": 129,
              "clicks": 0,
              "conversions": 0,
              "cost": 5.509,
              "payout": 0.003,
              "revenue": 5.507,
              "e_cpm": 42.709,
              "e_cpc": 0,
              "e_cpa": 0
            },
            {
              "placement": 16779,
              "banner": {
                "type": "image_banner",
                "id": 518887978
              },
              "text_ad": null,
              "popup": null,
              "campaign": {
                "type": "banner_campaign",
                "id": 9416
              },
              "zone": {
                "type": "banner_zone",
                "id": 103295
              },
              "responses": 93,
              "impressions": 93,
              "clicks": 0,
              "conversions": 0,
              "cost": 0.001,
              "payout": 0,
              "revenue": 0.001,
              "e_cpm": 0.01,
              "e_cpc": 0,
              "e_cpa": 0
            }
          ]
        }
      ]
    }
  ],
  "meta": {
    "type": "overview",
    "period": "day",
    "from": "2017-08-07T00:00:00-07:00",
    "to": "2017-08-10T00:00:00-07:00",
    "timezone": "America/Los_Angeles"
  }
}
AdButler\Report JSON: {
  "object": "report",
  "url": "/v1/reports",
  "data": [
    {
      "type": "overview",
      "id": 107870,
      "summary": {
        "responses": 222,
        "impressions": 222,
        "clicks": 0,
        "conversions": 0,
        "cost": 5.51,
        "payout": 0,
        "revenue": 5.51,
        "e_cpm": 24.821,
        "e_cpc": 0,
        "e_cpa": 0,
        "breakdown": [
          {
            "placement": 16778,
            "banner": {
              "type": "image_banner",
              "id": 518887977
            },
            "text_ad": null,
            "popup": null,
            "campaign": {
              "type": "banner_campaign",
              "id": 9415
            },
            "zone": {
              "type": "banner_zone",
              "id": 103294
            },
            "responses": 129,
            "impressions": 129,
            "clicks": 0,
            "conversions": 0,
            "cost": 5.509,
            "payout": 0.003,
            "revenue": 5.507,
            "e_cpm": 42.709,
            "e_cpc": 0,
            "e_cpa": 0
          },
          {
            "placement": 16779,
            "banner": {
              "type": "image_banner",
              "id": 518887978
            },
            "text_ad": null,
            "popup": null,
            "campaign": {
              "type": "banner_campaign",
              "id": 9416
            },
            "zone": {
              "type": "banner_zone",
              "id": 103295
            },
            "responses": 93,
            "impressions": 93,
            "clicks": 0,
            "conversions": 0,
            "cost": 0.001,
            "payout": 0,
            "revenue": 0.001,
            "e_cpm": 0.01,
            "e_cpc": 0,
            "e_cpa": 0
          }
        ]
      },
      "details": [
        {
          "start_date": "2017-08-09T00:00:00-07:00",
          "responses": 222,
          "impressions": 222,
          "clicks": 0,
          "conversions": 0,
          "cost": 5.51,
          "payout": 0,
          "revenue": 5.51,
          "e_cpm": 24.821,
          "e_cpc": 0,
          "e_cpa": 0,
          "breakdown": [
            {
              "placement": 16778,
              "banner": {
                "type": "image_banner",
                "id": 518887977
              },
              "text_ad": null,
              "popup": null,
              "campaign": {
                "type": "banner_campaign",
                "id": 9415
              },
              "zone": {
                "type": "banner_zone",
                "id": 103294
              },
              "responses": 129,
              "impressions": 129,
              "clicks": 0,
              "conversions": 0,
              "cost": 5.509,
              "payout": 0.003,
              "revenue": 5.507,
              "e_cpm": 42.709,
              "e_cpc": 0,
              "e_cpa": 0
            },
            {
              "placement": 16779,
              "banner": {
                "type": "image_banner",
                "id": 518887978
              },
              "text_ad": null,
              "popup": null,
              "campaign": {
                "type": "banner_campaign",
                "id": 9416
              },
              "zone": {
                "type": "banner_zone",
                "id": 103295
              },
              "responses": 93,
              "impressions": 93,
              "clicks": 0,
              "conversions": 0,
              "cost": 0.001,
              "payout": 0,
              "revenue": 0.001,
              "e_cpm": 0.01,
              "e_cpc": 0,
              "e_cpa": 0
            }
          ]
        }
      ]
    }
  ],
  "meta": {
    "type": "overview",
    "period": "day",
    "from": "2017-08-07T00:00:00-07:00",
    "to": "2017-08-10T00:00:00-07:00",
    "timezone": "America/Los_Angeles" 
  }
}
Field Type Description

object

string

A string denoting the object type which is always report for the current resource.

url

string

The relative URL of the current resource which is always of the form /v1/reports.

data

array

The data retrieved given the criteria in the URL.

meta

array

Additional information about the request.

Retrieve reports

Definition

GET https://api.adbutler.com/v1/reports
\AdButler\Report::retrieve()
adbutler.reports.retrieve()

Example Request

curl "https://api.adbutler.com/v1/reports?type=overview&from=2017-08-07T16:30:00-07:00&to=2017-08-10T18:00:00-07:00&period=day&timezone=America/Los_Angeles&summary=true&details=true&breakdown=true&financials=true" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$report = \AdButler\Report::retrieve( array(
    'type' => 'overview'
    'from' => '2017-08-07T16:30:00-07:00'
    'to' => '2017-08-10T18:00:00-07:00'
    'period' => 'day'
    'timezone' => 'America/Los_Angeles'
    'summary' => true
    'details' => true
    'breakdown' => true
    'financials' => true
));

echo $report;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.reports.read({
  type: 'overview',
  from: '2017-08-07T16:30:00-07:00',
  to: 2017-08-10T18:00:00-07:00,
  period: 'day',
  timezone: America/Los_Angeles,
  summary: true,
  details: true,
  breakdown: true,
  financials: true
}, function(response) {
  console.log(response);
});

// using promises
adbutler.reports.read({
  type: 'overview',
  from: 2017-08-07T16:30:00-07:00,
  to: '2017-08-10T18:00:00-07:00',
  period: 'day',
  timezone: America/Los_Angeles,
  summary: true,
  details: true,
  breakdown: true,
  financials: true
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "report",
  "url": "/v1/reports",
  "data": [
    {
      "type": "overview",
      "id": 107870,
      "summary": {
        "responses": 222,
        "impressions": 222,
        "clicks": 0,
        "conversions": 0,
        "cost": 5.51,
        "payout": 0,
        "revenue": 5.51,
        "e_cpm": 24.821,
        "e_cpc": 0,
        "e_cpa": 0,
        "breakdown": [
          {
            "placement": 16778,
            "banner": {
              "type": "image_banner",
              "id": 518887977
            },
            "text_ad": null,
            "popup": null,
            "campaign": {
              "type": "banner_campaign",
              "id": 9415
            },
            "zone": {
              "type": "banner_zone",
              "id": 103294
            },
            "responses": 129,
            "impressions": 129,
            "clicks": 0,
            "conversions": 0,
            "cost": 5.509,
            "payout": 0.003,
            "revenue": 5.507,
            "e_cpm": 42.709,
            "e_cpc": 0,
            "e_cpa": 0
          },
          {
            "placement": 16779,
            "banner": {
              "type": "image_banner",
              "id": 518887978
            },
            "text_ad": null,
            "popup": null,
            "campaign": {
              "type": "banner_campaign",
              "id": 9416
            },
            "zone": {
              "type": "banner_zone",
              "id": 103295
            },
            "responses": 93,
            "impressions": 93,
            "clicks": 0,
            "conversions": 0,
            "cost": 0.001,
            "payout": 0,
            "revenue": 0.001,
            "e_cpm": 0.01,
            "e_cpc": 0,
            "e_cpa": 0
          }
        ]
      },
      "details": [
        {
          "start_date": "2017-08-09T00:00:00-07:00",
          "responses": 222,
          "impressions": 222,
          "clicks": 0,
          "conversions": 0,
          "cost": 5.51,
          "payout": 0,
          "revenue": 5.51,
          "e_cpm": 24.821,
          "e_cpc": 0,
          "e_cpa": 0,
          "breakdown": [
            {
              "placement": 16778,
              "banner": {
                "type": "image_banner",
                "id": 518887977
              },
              "text_ad": null,
              "popup": null,
              "campaign": {
                "type": "banner_campaign",
                "id": 9415
              },
              "zone": {
                "type": "banner_zone",
                "id": 103294
              },
              "responses": 129,
              "impressions": 129,
              "clicks": 0,
              "conversions": 0,
              "cost": 5.509,
              "payout": 0.003,
              "revenue": 5.507,
              "e_cpm": 42.709,
              "e_cpc": 0,
              "e_cpa": 0
            },
            {
              "placement": 16779,
              "banner": {
                "type": "image_banner",
                "id": 518887978
              },
              "text_ad": null,
              "popup": null,
              "campaign": {
                "type": "banner_campaign",
                "id": 9416
              },
              "zone": {
                "type": "banner_zone",
                "id": 103295
              },
              "responses": 93,
              "impressions": 93,
              "clicks": 0,
              "conversions": 0,
              "cost": 0.001,
              "payout": 0,
              "revenue": 0.001,
              "e_cpm": 0.01,
              "e_cpc": 0,
              "e_cpa": 0
            }
          ]
        }
      ]
    }
  ],
  "meta": {
    "type": "overview",
    "period": "day",
    "from": "2017-08-07T00:00:00-07:00",
    "to": "2017-08-10T00:00:00-07:00",
    "timezone": "America/Los_Angeles"
  }
}
AdButler\Report JSON: {
  "object": "report",
  "url": "/v1/reports",
  "data": [
    {
      "type": "overview",
      "id": 107870,
      "summary": {
        "responses": 222,
        "impressions": 222,
        "clicks": 0,
        "conversions": 0,
        "cost": 5.51,
        "payout": 0,
        "revenue": 5.51,
        "e_cpm": 24.821,
        "e_cpc": 0,
        "e_cpa": 0,
        "breakdown": [
          {
            "placement": 16778,
            "banner": {
              "type": "image_banner",
              "id": 518887977
            },
            "text_ad": null,
            "popup": null,
            "campaign": {
              "type": "banner_campaign",
              "id": 9415
            },
            "zone": {
              "type": "banner_zone",
              "id": 103294
            },
            "responses": 129,
            "impressions": 129,
            "clicks": 0,
            "conversions": 0,
            "cost": 5.509,
            "payout": 0.003,
            "revenue": 5.507,
            "e_cpm": 42.709,
            "e_cpc": 0,
            "e_cpa": 0
          },
          {
            "placement": 16779,
            "banner": {
              "type": "image_banner",
              "id": 518887978
            },
            "text_ad": null,
            "popup": null,
            "campaign": {
              "type": "banner_campaign",
              "id": 9416
            },
            "zone": {
              "type": "banner_zone",
              "id": 103295
            },
            "responses": 93,
            "impressions": 93,
            "clicks": 0,
            "conversions": 0,
            "cost": 0.001,
            "payout": 0,
            "revenue": 0.001,
            "e_cpm": 0.01,
            "e_cpc": 0,
            "e_cpa": 0
          }
        ]
      },
      "details": [
        {
          "start_date": "2017-08-09T00:00:00-07:00",
          "responses": 222,
          "impressions": 222,
          "clicks": 0,
          "conversions": 0,
          "cost": 5.51,
          "payout": 0,
          "revenue": 5.51,
          "e_cpm": 24.821,
          "e_cpc": 0,
          "e_cpa": 0,
          "breakdown": [
            {
              "placement": 16778,
              "banner": {
                "type": "image_banner",
                "id": 518887977
              },
              "text_ad": null,
              "popup": null,
              "campaign": {
                "type": "banner_campaign",
                "id": 9415
              },
              "zone": {
                "type": "banner_zone",
                "id": 103294
              },
              "responses": 129,
              "impressions": 129,
              "clicks": 0,
              "conversions": 0,
              "cost": 5.509,
              "payout": 0.003,
              "revenue": 5.507,
              "e_cpm": 42.709,
              "e_cpc": 0,
              "e_cpa": 0
            },
            {
              "placement": 16779,
              "banner": {
                "type": "image_banner",
                "id": 518887978
              },
              "text_ad": null,
              "popup": null,
              "campaign": {
                "type": "banner_campaign",
                "id": 9416
              },
              "zone": {
                "type": "banner_zone",
                "id": 103295
              },
              "responses": 93,
              "impressions": 93,
              "clicks": 0,
              "conversions": 0,
              "cost": 0.001,
              "payout": 0,
              "revenue": 0.001,
              "e_cpm": 0.01,
              "e_cpc": 0,
              "e_cpa": 0
            }
          ]
        }
      ]
    }
  ],
  "meta": {
    "type": "overview",
    "period": "day",
    "from": "2017-08-07T00:00:00-07:00",
    "to": "2017-08-10T00:00:00-07:00",
    "timezone": "America/Los_Angeles" 
  }
}

You can retrieve overview of all the information or about a specific publisher, advertiser, zone, campaign, or banner in specified periods.

Query Parameters

Parameter Description

type*

Specifies the focus of the statistics you are interested in viewing. The value must be one of overview, publisher, advertiser, zone, campaign, banner, or geo-target.

period*

The range of time you are interested in viewing. The value must be one of hour, day, week, month, or year.

preset

Frequently used time frames for reporting statistics are bundled as presets You can pick a value from the presets instead of creating your own custom date range using the from and to fields. A preset range value must be one of the following: today, yesterday, this-week, last-week, this-month, last-month, year-to-date, last-7-days, last-14-days, last-30-days, last-3-months, last-6-months, or all-time.

timezone*

Timezone for the preset field e.g. America/Los_Angeles. A complete list of acceptable timezones by country is given here.

from

A valid ISO 8601 formatted date denoting the start of the period, e.g. 2016-09-01T00:00:00+00:00. This field along with the to field lets you specify a custom date and time interval if none suits your needs from the preset. The timezone offsets must match in the specified from and to fields.

to

A valid ISO 8601 formatted date denoting the end of the period, e.g. 2016-10-15T16:00:00+00:00. This field along with the from field lets you specify a custom date and time interval if none suits your needs from the preset. The timezone offsets must match the specified to and from fields.

summary

Whether to show a summary (true) or not (false).

details

Whether to show details (true) or not (false).

breakdown

Whether to show breakdown of summary and details (true) or not (false).

financials

Whether to show financial data (true) or not (false). When true, you will see additional fields like cost, payout, revenue, e_cpm, e_cpc, and e_cpa in the response.

publishers

Submit this parameter to filter your report by a list of publisher IDs. The IDs must be submitted as a comma-separated list.

zones

Submit this parameter to filter your report by a list of zone IDs. The IDs must be submitted as a comma-separated list.

advertisers

Submit this parameter to filter your report by a list of advertiser IDs. The IDs must be submitted as a comma-separated list.

campaigns

Submit this parameter to filter your report by a list of campaign IDs. The IDs must be submitted as a comma-separated list.

banners

Submit this parameter to filter your report by a list of banner IDs. The IDs must be submitted as a comma-separated list.

textads

Submit this parameter to filter your report by a list of text ad IDs. The IDs must be submitted as a comma-separated list.

popups

Submit this parameter to filter your report by a list of popup IDs. The IDs must be submitted as a comma-separated list.

* = required field
✝ = Either preset or specific to and from dates must be specified
‡ = Either summary or details must be specified

Returns

Returns a report object if the request succeeded, or an error if something went terribly wrong.


VAST Reports

Introduction

Reporting is the new interface to Statistics. It serves to quantify the serving of your advertisements across price and performance related metrics. They are updated in real time. We go to great lengths to give you detailed and accurate data about the performance of your advertisements, to help you make informed decisions. This endpoint enables you to build your own reporting dashboard should you feel the need to.

The vast_report response object has the following fields.

Example Response

{
  "object": "vast-report",
  "url": "/v1/vast-reports",
  "data": [
     {
         "type": "overview",
         "id": 108508,
         "summary": {
             "requests": 4668,
             "impressions": 4717,
             "clicks": 425,
             "companionClicks1": 51,
             "companionClicks2": 46,
             "companionClicks3": 38,
             "companionClicks4": 38,
             "companionClicks5": 46,
             "companionViews1": 43,
             "companionViews2": 52,
             "companionViews3": 49,
             "companionViews4": 43,
             "companionViews5": 43,
             "start": 3777,
             "firstQuartile": 2882,
             "midpoint": 2081,
             "thirdQuartile": 1225,
             "complete": 621,
             "mute": 219,
             "unmute": 196,
             "pause": 211,
             "rewind": 218,
             "resume": 214,
             "fullscreen": 808,
             "exitFullscreen": 221,
             "expand": 38,
             "collapse": 49,
             "acceptInvitationLinear": 55,
             "closeLinear": 32,
             "skip": 1422,
             "conversions": 0,
             "cost": 0,
             "payout": 0,
             "revenue": 0,
             "e_cpm": 0,
             "e_cpc": 0,
             "e_cpa": 0
         },
         "details": [
             {
                 "start_date": "2018-01-01T00:00:00-08:00",
                 "requests": 2445,
                 "impressions": 2493,
                 "clicks": 244,
                 "companionClicks1": 26,
                 "companionClicks2": 26,
                 "companionClicks3": 17,
                 "companionClicks4": 18,
                 "companionClicks5": 26,
                 "companionViews1": 26,
                 "companionViews2": 31,
                 "companionViews3": 27,
                 "companionViews4": 21,
                 "companionViews5": 26,
                 "start": 1969,
                 "firstQuartile": 1507,
                 "midpoint": 1094,
                 "thirdQuartile": 641,
                 "complete": 306,
                 "mute": 107,
                 "unmute": 106,
                 "pause": 106,
                 "rewind": 109,
                 "resume": 115,
                 "fullscreen": 425,
                 "exitFullscreen": 120,
                 "expand": 26,
                 "collapse": 28,
                 "acceptInvitationLinear": 30,
                 "closeLinear": 14,
                 "skip": 737,
                 "conversions": 0,
                 "cost": 0,
                 "payout": 0,
                 "revenue": 0,
                 "e_cpm": 0,
                 "e_cpc": 0,
                 "e_cpa": 0
             },
             {
                 "start_date": "2018-02-01T00:00:00-08:00",
                 "requests": 2223,
                 "impressions": 2224,
                 "clicks": 181,
                 "companionClicks1": 25,
                 "companionClicks2": 20,
                 "companionClicks3": 21,
                 "companionClicks4": 20,
                 "companionClicks5": 20,
                 "companionViews1": 17,
                 "companionViews2": 21,
                 "companionViews3": 22,
                 "companionViews4": 22,
                 "companionViews5": 17,
                 "start": 1808,
                 "firstQuartile": 1375,
                 "midpoint": 987,
                 "thirdQuartile": 584,
                 "complete": 315,
                 "mute": 112,
                 "unmute": 90,
                 "pause": 105,
                 "rewind": 109,
                 "resume": 99,
                 "fullscreen": 383,
                 "exitFullscreen": 101,
                 "expand": 12,
                 "collapse": 21,
                 "acceptInvitationLinear": 25,
                 "closeLinear": 18,
                 "skip": 685,
                 "conversions": 0,
                 "cost": 0,
                 "payout": 0,
                 "revenue": 0,
                 "e_cpm": 0,
                 "e_cpc": 0,
                 "e_cpa": 0
             }
         ]
     }
  ],
  "meta": {
     "type": "overview",
     "period": "month",
     "from": "2018-01-01T00:00:00-08:00",
     "to": "2018-03-01T00:00:00-08:00",
     "timezone": "America/Los_Angeles"
  }
  }
AdButler\VASTReport JSON: {
  "object": "vast_report",
  "url": "/v1/vast-reports",
  "data": [
     {
         "type": "overview",
         "id": 108508,
         "summary": {
             "requests": 4668,
             "impressions": 4717,
             "clicks": 425,
             "companionClicks1": 51,
             "companionClicks2": 46,
             "companionClicks3": 38,
             "companionClicks4": 38,
             "companionClicks5": 46,
             "companionViews1": 43,
             "companionViews2": 52,
             "companionViews3": 49,
             "companionViews4": 43,
             "companionViews5": 43,
             "start": 3777,
             "firstQuartile": 2882,
             "midpoint": 2081,
             "thirdQuartile": 1225,
             "complete": 621,
             "mute": 219,
             "unmute": 196,
             "pause": 211,
             "rewind": 218,
             "resume": 214,
             "fullscreen": 808,
             "exitFullscreen": 221,
             "expand": 38,
             "collapse": 49,
             "acceptInvitationLinear": 55,
             "closeLinear": 32,
             "skip": 1422,
             "conversions": 0,
             "cost": 0,
             "payout": 0,
             "revenue": 0,
             "e_cpm": 0,
             "e_cpc": 0,
             "e_cpa": 0
         },
         "details": [
             {
                 "start_date": "2018-01-01T00:00:00-08:00",
                 "requests": 2445,
                 "impressions": 2493,
                 "clicks": 244,
                 "companionClicks1": 26,
                 "companionClicks2": 26,
                 "companionClicks3": 17,
                 "companionClicks4": 18,
                 "companionClicks5": 26,
                 "companionViews1": 26,
                 "companionViews2": 31,
                 "companionViews3": 27,
                 "companionViews4": 21,
                 "companionViews5": 26,
                 "start": 1969,
                 "firstQuartile": 1507,
                 "midpoint": 1094,
                 "thirdQuartile": 641,
                 "complete": 306,
                 "mute": 107,
                 "unmute": 106,
                 "pause": 106,
                 "rewind": 109,
                 "resume": 115,
                 "fullscreen": 425,
                 "exitFullscreen": 120,
                 "expand": 26,
                 "collapse": 28,
                 "acceptInvitationLinear": 30,
                 "closeLinear": 14,
                 "skip": 737,
                 "conversions": 0,
                 "cost": 0,
                 "payout": 0,
                 "revenue": 0,
                 "e_cpm": 0,
                 "e_cpc": 0,
                 "e_cpa": 0
             },
             {
                 "start_date": "2018-02-01T00:00:00-08:00",
                 "requests": 2223,
                 "impressions": 2224,
                 "clicks": 181,
                 "companionClicks1": 25,
                 "companionClicks2": 20,
                 "companionClicks3": 21,
                 "companionClicks4": 20,
                 "companionClicks5": 20,
                 "companionViews1": 17,
                 "companionViews2": 21,
                 "companionViews3": 22,
                 "companionViews4": 22,
                 "companionViews5": 17,
                 "start": 1808,
                 "firstQuartile": 1375,
                 "midpoint": 987,
                 "thirdQuartile": 584,
                 "complete": 315,
                 "mute": 112,
                 "unmute": 90,
                 "pause": 105,
                 "rewind": 109,
                 "resume": 99,
                 "fullscreen": 383,
                 "exitFullscreen": 101,
                 "expand": 12,
                 "collapse": 21,
                 "acceptInvitationLinear": 25,
                 "closeLinear": 18,
                 "skip": 685,
                 "conversions": 0,
                 "cost": 0,
                 "payout": 0,
                 "revenue": 0,
                 "e_cpm": 0,
                 "e_cpc": 0,
                 "e_cpa": 0
             }
         ]
     }
  ],
  "meta": {
     "type": "overview",
     "period": "month",
     "from": "2018-01-01T00:00:00-08:00",
     "to": "2018-03-01T00:00:00-08:00",
     "timezone": "America/Los_Angeles"
  }
  }
Field Type Description

object

string

A string denoting the object type which is always vast_report for the current resource.

url

string

The relative URL of the current resource which is always of the form /v1/vast_reports.

data

array

The data retrieved given the criteria in the URL.

meta

array

Additional information about the request.

Retrieve VAST Reports

Definition

GET https://api.adbutler.com/v1/vast-reports
\AdButler\VASTReport::retrieve()
adbutler.vast-reports.retrieve()

Example Request

curl "https://api.adbutler.com/v1/vast-reports?type=overview&from=2018-01-01T00:00:00-08:00&to=2018-02-01T12:00:00-08:00&period=month&timezone=America/Los_Angeles&summary=true&details=true&breakdown=false&financials=true" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$report = \AdButler\VASTReport::retrieve( array(
    'type' => 'overview'
    'from' => '2017-08-07T16:30:00-07:00'
    'to' => '2017-08-10T18:00:00-07:00'
    'period' => 'day'
    'timezone' => 'America/Los_Angeles'
    'summary' => true
    'details' => true
    'breakdown' => true
    'financials' => true
));

echo $report;
var AdButler = require("adbutler");

var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vast-reports.read({
  type: overview,
  from: 2017-08-07T16:30:00-07:00,
  to: 2017-08-10T18:00:00-07:00,
  period: day,
  timezone: America/Los_Angeles,
  summary: true,
  details: true,
  breakdown: true,
  financials: true
}, function(response) {
  console.log(response);
});

// using promises
adbutler.vast-reports.read({
  type: overview,
  from: 2017-08-07T16:30:00-07:00,
  to: 2017-08-10T18:00:00-07:00,
  period: day,
  timezone: America/Los_Angeles,
  summary: true,
  details: true,
  breakdown: true,
  financials: true
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "vast-report",
  "url": "/v1/vast-reports",
  "data": [
     {
         "type": "overview",
         "id": 108508,
         "summary": {
             "requests": 4668,
             "impressions": 4717,
             "clicks": 425,
             "companionClicks1": 51,
             "companionClicks2": 46,
             "companionClicks3": 38,
             "companionClicks4": 38,
             "companionClicks5": 46,
             "companionViews1": 43,
             "companionViews2": 52,
             "companionViews3": 49,
             "companionViews4": 43,
             "companionViews5": 43,
             "start": 3777,
             "firstQuartile": 2882,
             "midpoint": 2081,
             "thirdQuartile": 1225,
             "complete": 621,
             "mute": 219,
             "unmute": 196,
             "pause": 211,
             "rewind": 218,
             "resume": 214,
             "fullscreen": 808,
             "exitFullscreen": 221,
             "expand": 38,
             "collapse": 49,
             "acceptInvitationLinear": 55,
             "closeLinear": 32,
             "skip": 1422,
             "conversions": 0,
             "cost": 0,
             "payout": 0,
             "revenue": 0,
             "e_cpm": 0,
             "e_cpc": 0,
             "e_cpa": 0
         },
         "details": [
             {
                 "start_date": "2018-01-01T00:00:00-08:00",
                 "requests": 2445,
                 "impressions": 2493,
                 "clicks": 244,
                 "companionClicks1": 26,
                 "companionClicks2": 26,
                 "companionClicks3": 17,
                 "companionClicks4": 18,
                 "companionClicks5": 26,
                 "companionViews1": 26,
                 "companionViews2": 31,
                 "companionViews3": 27,
                 "companionViews4": 21,
                 "companionViews5": 26,
                 "start": 1969,
                 "firstQuartile": 1507,
                 "midpoint": 1094,
                 "thirdQuartile": 641,
                 "complete": 306,
                 "mute": 107,
                 "unmute": 106,
                 "pause": 106,
                 "rewind": 109,
                 "resume": 115,
                 "fullscreen": 425,
                 "exitFullscreen": 120,
                 "expand": 26,
                 "collapse": 28,
                 "acceptInvitationLinear": 30,
                 "closeLinear": 14,
                 "skip": 737,
                 "conversions": 0,
                 "cost": 0,
                 "payout": 0,
                 "revenue": 0,
                 "e_cpm": 0,
                 "e_cpc": 0,
                 "e_cpa": 0
             },
             {
                 "start_date": "2018-02-01T00:00:00-08:00",
                 "requests": 2223,
                 "impressions": 2224,
                 "clicks": 181,
                 "companionClicks1": 25,
                 "companionClicks2": 20,
                 "companionClicks3": 21,
                 "companionClicks4": 20,
                 "companionClicks5": 20,
                 "companionViews1": 17,
                 "companionViews2": 21,
                 "companionViews3": 22,
                 "companionViews4": 22,
                 "companionViews5": 17,
                 "start": 1808,
                 "firstQuartile": 1375,
                 "midpoint": 987,
                 "thirdQuartile": 584,
                 "complete": 315,
                 "mute": 112,
                 "unmute": 90,
                 "pause": 105,
                 "rewind": 109,
                 "resume": 99,
                 "fullscreen": 383,
                 "exitFullscreen": 101,
                 "expand": 12,
                 "collapse": 21,
                 "acceptInvitationLinear": 25,
                 "closeLinear": 18,
                 "skip": 685,
                 "conversions": 0,
                 "cost": 0,
                 "payout": 0,
                 "revenue": 0,
                 "e_cpm": 0,
                 "e_cpc": 0,
                 "e_cpa": 0
             }
         ]
     }
  ],
  "meta": {
     "type": "overview",
     "period": "month",
     "from": "2018-01-01T00:00:00-08:00",
     "to": "2018-03-01T00:00:00-08:00",
     "timezone": "America/Los_Angeles"
  }
  }
AdButler\VASTReport JSON: {
  "object": "vast_report",
  "url": "/v1/vast-reports",
  "data": [
     {
         "type": "overview",
         "id": 108508,
         "summary": {
             "requests": 4668,
             "impressions": 4717,
             "clicks": 425,
             "companionClicks1": 51,
             "companionClicks2": 46,
             "companionClicks3": 38,
             "companionClicks4": 38,
             "companionClicks5": 46,
             "companionViews1": 43,
             "companionViews2": 52,
             "companionViews3": 49,
             "companionViews4": 43,
             "companionViews5": 43,
             "start": 3777,
             "firstQuartile": 2882,
             "midpoint": 2081,
             "thirdQuartile": 1225,
             "complete": 621,
             "mute": 219,
             "unmute": 196,
             "pause": 211,
             "rewind": 218,
             "resume": 214,
             "fullscreen": 808,
             "exitFullscreen": 221,
             "expand": 38,
             "collapse": 49,
             "acceptInvitationLinear": 55,
             "closeLinear": 32,
             "skip": 1422,
             "conversions": 0,
             "cost": 0,
             "payout": 0,
             "revenue": 0,
             "e_cpm": 0,
             "e_cpc": 0,
             "e_cpa": 0
         },
         "details": [
             {
                 "start_date": "2018-01-01T00:00:00-08:00",
                 "requests": 2445,
                 "impressions": 2493,
                 "clicks": 244,
                 "companionClicks1": 26,
                 "companionClicks2": 26,
                 "companionClicks3": 17,
                 "companionClicks4": 18,
                 "companionClicks5": 26,
                 "companionViews1": 26,
                 "companionViews2": 31,
                 "companionViews3": 27,
                 "companionViews4": 21,
                 "companionViews5": 26,
                 "start": 1969,
                 "firstQuartile": 1507,
                 "midpoint": 1094,
                 "thirdQuartile": 641,
                 "complete": 306,
                 "mute": 107,
                 "unmute": 106,
                 "pause": 106,
                 "rewind": 109,
                 "resume": 115,
                 "fullscreen": 425,
                 "exitFullscreen": 120,
                 "expand": 26,
                 "collapse": 28,
                 "acceptInvitationLinear": 30,
                 "closeLinear": 14,
                 "skip": 737,
                 "conversions": 0,
                 "cost": 0,
                 "payout": 0,
                 "revenue": 0,
                 "e_cpm": 0,
                 "e_cpc": 0,
                 "e_cpa": 0
             },
             {
                 "start_date": "2018-02-01T00:00:00-08:00",
                 "requests": 2223,
                 "impressions": 2224,
                 "clicks": 181,
                 "companionClicks1": 25,
                 "companionClicks2": 20,
                 "companionClicks3": 21,
                 "companionClicks4": 20,
                 "companionClicks5": 20,
                 "companionViews1": 17,
                 "companionViews2": 21,
                 "companionViews3": 22,
                 "companionViews4": 22,
                 "companionViews5": 17,
                 "start": 1808,
                 "firstQuartile": 1375,
                 "midpoint": 987,
                 "thirdQuartile": 584,
                 "complete": 315,
                 "mute": 112,
                 "unmute": 90,
                 "pause": 105,
                 "rewind": 109,
                 "resume": 99,
                 "fullscreen": 383,
                 "exitFullscreen": 101,
                 "expand": 12,
                 "collapse": 21,
                 "acceptInvitationLinear": 25,
                 "closeLinear": 18,
                 "skip": 685,
                 "conversions": 0,
                 "cost": 0,
                 "payout": 0,
                 "revenue": 0,
                 "e_cpm": 0,
                 "e_cpc": 0,
                 "e_cpa": 0
             }
         ]
     }
  ],
  "meta": {
     "type": "overview",
     "period": "month",
     "from": "2018-01-01T00:00:00-08:00",
     "to": "2018-03-01T00:00:00-08:00",
     "timezone": "America/Los_Angeles"
  }
  }

You can retrieve overview of all the information or about a specific publisher, advertiser, zone, campaign, or banner in specified periods.

Query Parameters

Parameter Description

type*

Specifies the focus of the statistics you are interested in viewing. The value must be one of overview, publisher, advertiser, zone, campaign, or banner.

period*

The range of time you are interested in viewing. The value must be one of hour, day, week, month, or year.

preset

Frequently used time frames for reporting statistics are bundled as presets You can pick a value from the presets instead of creating your own custom date range using the from and to fields. A preset range value must be one of the following: today, yesterday, this-week, last-week, this-month, last-month, year-to-date, last-7-days, last-14-days, last-30-days, last-3-months, last-6-months, or all-time.

timezone*

Timezone for the preset field e.g. America/Los_Angeles. A complete list of acceptable timezones by country is given here.

from

A valid ISO 8601 formatted date denoting the start of the period, e.g. 2016-09-01T00:00:00+00:00. This field along with the to field lets you specify a custom date and time interval if none suits your needs from the preset. The timezone offsets must match in the specified from and to fields.

to

A valid ISO 8601 formatted date denoting the end of the period, e.g. 2016-10-15T16:00:00+00:00. This field along with the from field lets you specify a custom date and time interval if none suits your needs from the preset. The timezone offsets must match the specified to and from fields.

summary

Whether to show a summary (true) or not (false).

details

Whether to show details (true) or not (false).

breakdown

Whether to show breakdown of summary and details (true) or not (false).

financials

Whether to show financial data (true) or not (false). When true, you will see additional fields like cost, payout, revenue, e_cpm, e_cpc, and e_cpa in the response.

* = required field
✝ = Either preset or specific to and from dates must be specified
‡ = Either summary or details must be specified

Returns

Returns a vast_report object if the request succeeded, or an error if something went terribly wrong.


Click Details

Introduction

This endpoint will allow you to get detailed breakdown of clicks in your account. Please note that we only keep the latest 3 months of click-through data.

The click_detail_report response object has the following fields.

Example Response

{
  "object": "click_detail_report",
  "url": "/v1/reports/click-details",
  "data": [
      {
          "zone": 86133,
          "campaign": 5053,
          "advertisement": {
              "type": "banner",
              "id": 518881649
          },
          "click_date": "2018-09-10 22:35:39",
          "ip": "192.168.10.xxx",
          "country": null,
          "region": null,
          "city": null,
          "custom_param_1": null,
          "custom_param_2": null,
          "custom_param_3": null,
          "custom_param_4": null,
          "custom_param_5": null
      }
  ],
  "meta": {
      "limit": "1",
      "offset": "10",
      "has_more": true,
      "from": "2018-09-01T00:00:00-07:00",
      "to": "2018-10-01T00:00:00-07:00",
      "timezone": "America/Los_Angeles"
  }
}
AdButler\Report JSON: {
    "object": "click_detail_report",
    "url": "/v1/reports/click-details",
    "data": [
        {
            "zone": 86133,
            "campaign": 5053,
            "advertisement": {
                "type": "banner",
                "id": 518881649
            },
            "click_date": "2018-09-10 22:35:39",
            "ip": "192.168.10.xxx",
            "country": null,
            "region": null,
            "city": null,
            "custom_param_1": null,
            "custom_param_2": null,
            "custom_param_3": null,
            "custom_param_4": null,
            "custom_param_5": null
        }
    ],
    "meta": {
        "limit": "1",
        "offset": "10",
        "has_more": true,
        "from": "2018-09-01T00:00:00-07:00",
        "to": "2018-10-01T00:00:00-07:00",
        "timezone": "America/Los_Angeles"
    }
}
Field Type Description

object

string

A string denoting the object type which is always click_detail_report for the current resource.

url

string

The relative URL of the current resource which is always of the form /v1/reports/click-details.

data

array

The data retrieved given the criteria in the URL.

meta

array

Additional information about the request.

Retrieve Click Details

Definition

GET https://api.adbutler.com/v1/reports/click-details
\AdButler\ClickDetails::retrieve()
adbutler.clickDetails.retrieve()

Example Request

curl "https://api.adbutler.com/v1/reports/click-details?vast=false&from=2018-09-01T00:00:00-07:00&to=2018-10-01T00:00:00-07:00&limit=1&offset=10" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$report = \AdButler\ClickDetails::retrieve( array(
    'vast' => 'false',
    'from' => '2018-09-01T00:00:00-07:00',
    'to' => '2018-10-01T00:00:00-07:00',
    'limit' => 1,
    'offset' => 10,
));

echo $report;
var AdButler = require("adbutler");

var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.clickDetails.read({
  vast: false,
  from: 2018-09-01T00:00:00-07:00,
  to: 2018-10-01T00:00:00-07:00,
  limit: 1,
  offset: 10,
}, function(response) {
  console.log(response);
});

// using promises
adbutler.reports.read({
  vast: false,
  from: 2018-09-01T00:00:00-07:00,
  to: 2018-10-01T00:00:00-07:00,
  limit: 1,
  offset: 10,
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "click_detail_report",
  "url": "/v1/reports/click-details",
  "data": [
      {
          "zone": 86133,
          "campaign": 5053,
          "advertisement": {
              "type": "banner",
              "id": 518881649
          },
          "click_date": "2018-09-10 22:35:39",
          "ip": "192.168.10.xxx",
          "country": null,
          "region": null,
          "city": null,
          "custom_param_1": null,
          "custom_param_2": null,
          "custom_param_3": null,
          "custom_param_4": null,
          "custom_param_5": null
      }
  ],
  "meta": {
      "limit": "1",
      "offset": "10",
      "has_more": true,
      "from": "2018-09-01T00:00:00-07:00",
      "to": "2018-10-01T00:00:00-07:00",
      "timezone": "America/Los_Angeles"
  }
}
AdButler\Report JSON: {
    "object": "click_detail_report",
    "url": "/v1/reports/click-details",
    "data": [
        {
            "zone": 86133,
            "campaign": 5053,
            "advertisement": {
                "type": "banner",
                "id": 518881649
            },
            "click_date": "2018-09-10 22:35:39",
            "ip": "192.168.10.xxx",
            "country": null,
            "region": null,
            "city": null,
            "custom_param_1": null,
            "custom_param_2": null,
            "custom_param_3": null,
            "custom_param_4": null,
            "custom_param_5": null
        }
    ],
    "meta": {
        "limit": "1",
        "offset": "10",
        "has_more": true,
        "from": "2018-09-01T00:00:00-07:00",
        "to": "2018-10-01T00:00:00-07:00",
        "timezone": "America/Los_Angeles"
    }
}

You can retrieve a report of clicks on your account.

Query Parameters

Parameter Description

vast

Whether this report will return display or VAST clicks. true for VAST, false for display.

filter_type

Describes how you would like to filter the report. Either by zone or by campaign. Leave this field blank if you don't want to filter.

filter_ids

A comma-separated list of IDs to filter the report by. If 'filter_type' is omitted, omit this field as well.

custom_filter_params

If your account is set up to use Custom Parameters, you can filter your clicks based on those parameters. This field is a comma-separated list of custom parameters you'd like to filter this report by.

preset

Frequently used time frames for reporting statistics are bundled as presets You can pick a value from the presets instead of creating your own custom date range using the from and to fields. A preset range value must be one of the following: today, yesterday, this-week, last-week, this-month, last-month, last-7-days, last-14-days, last-30-days, or last-3-months.

timezone*

Timezone for the preset field e.g. America/Los_Angeles. A complete list of acceptable timezones by country is given here.

from

A valid ISO 8601 formatted date denoting the start of the period, e.g. 2016-09-01T00:00:00+00:00. This field along with the to field lets you specify a custom date and time interval if none suits your needs from the preset. The timezone offsets must match in the specified from and to fields.

to

A valid ISO 8601 formatted date denoting the end of the period, e.g. 2016-10-15T16:00:00+00:00. This field along with the from field lets you specify a custom date and time interval if none suits your needs from the preset. The timezone offsets must match the specified to and from fields.

limit

A non-negative integer that indicates the number of records you'd like returned in the response.

offset

A non-negative integer that indicates how many records to skip when compiling the response.

✝ = Either preset or specific to and from dates must be specified

Returns

Returns a click_detail_report object if the request succeeded, or an error if something went terribly wrong.


Conversion Details

Introduction

If you are tracking conversions, this endpoint can be a great way to get a more detailed breakdown of how they are performing. You can get reports on conversions for specific zones, campaigns, and date ranges.

NOTE: This endpoint is not available by default. Please contact our support team to get it enabled for your account.

The conversion_detail_report response object has the following fields.

Example Response

{
  "object": "conversion_detail_report",
  "url": "/v1/reports/conversion-details",
  "data": [
      {
          "zone": 86133,
          "campaign": 5053,
          "advertisement": {
              "type": "banner",
              "id": 518881680
          },
          "conversion_date": "2018-09-10 22:35:39",
          "referrer": "adbutler.com",
          "ip": "192.168.10.xxx",
          "country": null,
          "region": null,
          "city": null,
          "value": 35.75,
          "transaction_id": "abcd-1234",
          "product_id": null
      }
  ],
  "meta": {
      "limit": "1",
      "offset": "10",
      "has_more": true,
      "from": "2018-09-01T00:00:00-07:00",
      "to": "2018-10-01T00:00:00-07:00",
      "timezone": "America/Los_Angeles"
  }
}
AdButler\Report JSON: {
    "object": "conversion_detail_report",
    "url": "/v1/reports/conversion-details",
    "data": [
        {
            "zone": 86133,
            "campaign": 5053,
            "advertisement": {
                "type": "banner",
                "id": 518881680
            },
            "conversion_date": "2018-09-10 22:35:39",
            "referrer": "adbutler.com",
            "ip": "192.168.10.xxx",
            "country": null,
            "region": null,
            "city": null,
            "value": 35.75,
            "transaction_id": "abcd-1234",
            "product_id": null
        }
    ],
    "meta": {
        "limit": "1",
        "offset": "10",
        "has_more": true,
        "from": "2018-09-01T00:00:00-07:00",
        "to": "2018-10-01T00:00:00-07:00",
        "timezone": "America/Los_Angeles"
    }
}
Field Type Description

object

string

A string denoting the object type which is always report for the current resource.

url

string

The relative URL of the current resource which is always of the form /v1/reports.

data

array

The data retrieved given the criteria in the URL.

meta

array

Additional information about the request.

Retrieve Conversion Details

Definition

GET https://api.adbutler.com/v1/reports/conversion-details
\AdButler\ConversionDetails::retrieve()
adbutler.conversionDetails.retrieve()

Example Request

curl "https://api.adbutler.com/v1/reports/conversion-details?vast=false&from=2018-09-01T00:00:00-07:00&to=2018-10-01T00:00:00-07:00&limit=1&offset=10" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$report = \AdButler\ConversionDetails::retrieve( array(
    'vast' => 'false',
    'from' => '2018-09-01T00:00:00-07:00',
    'to' => '2018-10-01T00:00:00-07:00',
    'limit' => 1,
    'offset' => 10,
));

echo $report;
var AdButler = require("adbutler");

var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.conversionDetails.read({
  vast: false,
  from: 2018-09-01T00:00:00-07:00,
  to: 2018-10-01T00:00:00-07:00,
  limit: 1,
  offset: 10,
}, function(response) {
  console.log(response);
});

// using promises
adbutler.reports.read({
  vast: false,
  from: 2018-09-01T00:00:00-07:00,
  to: 2018-10-01T00:00:00-07:00,
  limit: 1,
  offset: 10,
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "conversion_detail_report",
  "url": "/v1/reports/conversion-details",
  "data": [
      {
          "zone": 86133,
          "campaign": 5053,
          "advertisement": {
              "type": "banner",
              "id": 518881680
          },
          "conversion_date": "2018-09-10 22:35:39",
          "referrer": "adbutler.com",
          "ip": "192.168.10.xxx",
          "country": null,
          "region": null,
          "city": null,
          "value": 35.75,
          "transaction_id": "abcd-1234",
          "product_id": null
      }
  ],
  "meta": {
      "limit": "1",
      "offset": "10",
      "has_more": true,
      "from": "2018-09-01T00:00:00-07:00",
      "to": "2018-10-01T00:00:00-07:00",
      "timezone": "America/Los_Angeles"
  }
}
AdButler\Report JSON: {
    "object": "conversion_detail_report",
    "url": "/v1/reports/conversion-details",
    "data": [
        {
            "zone": 86133,
            "campaign": 5053,
            "advertisement": {
                "type": "banner",
                "id": 518881680
            },
            "conversion_date": "2018-09-10 22:35:39",
            "referrer": "adbutler.com",
            "ip": "192.168.10.xxx",
            "country": null,
            "region": null,
            "city": null,
            "value": 35.75,
            "transaction_id": "abcd-1234",
            "product_id": null
        }
    ],
    "meta": {
        "limit": "1",
        "offset": "10",
        "has_more": true,
        "from": "2018-09-01T00:00:00-07:00",
        "to": "2018-10-01T00:00:00-07:00",
        "timezone": "America/Los_Angeles"
    }
}

You can retrieve a report of conversions on your account.

Query Parameters

Parameter Description

vast

Whether this report will return display or VAST conversions. true for VAST, false for display.

filter_type

Describes how you would like to filter the report. Either by zone or by campaign. Leave this field blank if you don't want to filter.

filter_ids

A comma-separated list of IDs to filter the report by. If 'filter_type' is omitted, omit this field as well.

preset

Frequently used time frames for reporting statistics are bundled as presets You can pick a value from the presets instead of creating your own custom date range using the from and to fields. A preset range value must be one of the following: today, yesterday, this-week, last-week, this-month, last-month, year-to-date, last-7-days, last-14-days, last-30-days, last-3-months, last-6-months, or all-time.

timezone*

Timezone for the preset field e.g. America/Los_Angeles. A complete list of acceptable timezones by country is given here.

from

A valid ISO 8601 formatted date denoting the start of the period, e.g. 2016-09-01T00:00:00+00:00. This field along with the to field lets you specify a custom date and time interval if none suits your needs from the preset. The timezone offsets must match in the specified from and to fields.

to

A valid ISO 8601 formatted date denoting the end of the period, e.g. 2016-10-15T16:00:00+00:00. This field along with the from field lets you specify a custom date and time interval if none suits your needs from the preset. The timezone offsets must match the specified to and from fields.

limit

A non-negative integer that indicates the number of records you'd like returned in the response.

offset

A non-negative integer that indicates how many records to skip when compiling the response.

✝ = Either preset or specific to and from dates must be specified

Returns

Returns a conversion_detail_report object if the request succeeded, or an error if something went terribly wrong.


Stats

Introduction

Statistics quantify the serving of your advertisements across price and performance related metrics. They are updated in real time. We go to great lengths to give you detailed and accurate data about the performance of your advertisements, to help you make informed decisions. This endpoint enables you to build your own reporting dashboard should you feel the need to.

The stats response object has the following fields.

Example Response

{
  "object": "stats",
  "url": "/v1/stats",
  "data": {
    "1770": [
      {
        "start_date": "2016-01-01T00:00:00+00:00",
        "responses": 2399,
        "impressions": 2399,
        "clicks": 2399,
        "conversions": 2399,
        "cost": 0,
        "payout": 0,
        "revenue": 0,
        "e_cpm": 0,
        "e_cpc": 0,
        "e_cpa": 0
      }
    ]
  },
  "meta": {
    "type": "publisher",
    "period": "year",
    "from": "2016-01-01T00:00:00+00:00",
    "to": "2016-12-31T23:00:00+00:00"
  }
}
AdButler\Stats JSON: {
  "object": "stats",
  "url": "/v1/stats",
  "data": {
    "1770": [
      {
        "start_date": "2016-01-01T00:00:00+00:00",
        "responses": 2399,
        "impressions": 2399,
        "clicks": 2399,
        "conversions": 2399,
        "cost": 0,
        "payout": 0,
        "revenue": 0,
        "e_cpm": 0,
        "e_cpc": 0,
        "e_cpa": 0
      }
    ]
  },
  "meta": {
    "type": "publisher",
    "period": "year",
    "from": "2016-01-01T00:00:00+00:00",
    "to": "2016-12-31T23:00:00+00:00"
  }
}
Field Type Description

object

string

A string denoting the object type which is always stats for the current resource.

url

string

The relative URL of the current resource which is always of the form /v1/stats.

data

array

The data retrieved given the criteria in the URL.

meta

array

Additional information about the request.

Retrieve statistics

Definition

GET https://api.adbutler.com/v1/stats
\AdButler\Stats::retrieve()
adbutler.stats.retrieve()

Example Request

curl "https://api.adbutler.com/v1/stats?type=publisher" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$stat = \AdButler\Stats::retrieve( array(
    'type' => 'publisher',
    'from' => '2016-09-01T00:00:00+00:00',
    'to' => '2016-10-15T16:00:00+00:00',
    'period' => 'year',
    'show_financial_data' => true
));

echo $stat;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.stats.read(3199, function(response) {
  console.log(response);
});

// using promises
adbutler.stats.read(3199).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "stats",
  "url": "/v1/stats",
  "data": {
    "1770": [
      {
        "start_date": "2016-01-01T00:00:00+00:00",
        "responses": 2399,
        "impressions": 2399,
        "clicks": 2399,
        "conversions": 2399,
        "cost": 0,
        "payout": 0,
        "revenue": 0,
        "e_cpm": 0,
        "e_cpc": 0,
        "e_cpa": 0
      }
    ]
  },
  "meta": {
    "type": "publisher",
    "period": "year",
    "from": "2016-01-01T00:00:00+00:00",
    "to": "2016-12-31T23:00:00+00:00"
  }
}
AdButler\Stats JSON: {
  "object": "stats",
  "url": "/v1/stats",
  "data": {
    "1770": [
      {
        "start_date": "2016-01-01T00:00:00+00:00",
        "responses": 2399,
        "impressions": 2399,
        "clicks": 2399,
        "conversions": 2399,
        "cost": 0,
        "payout": 0,
        "revenue": 0,
        "e_cpm": 0,
        "e_cpc": 0,
        "e_cpa": 0
      }
    ]
  },
  "meta": {
    "type": "publisher",
    "period": "year",
    "from": "2016-01-01T00:00:00+00:00",
    "to": "2016-12-31T23:00:00+00:00"
  }
}

You can retrieve overview of all the information or about a specific publisher, advertiser, zone, campaign, or banner in specified periods.

Query Parameters

Parameter Description

type*

Specifies the focus of the statistics you are interested in viewing. The value must be one of overview, publisher, advertiser, zone, campaign, or banner.

period*

The range of time you are interested in viewing. The value must be one of hour, day, week, month, or year.

preset

Frequently used time frames for reporting statistics are bundled as presets You can pick a value from the presets instead of creating your own custom date range using the from and to fields. A preset range value must be one of the following: today, yesterday, this-week, last-week, this-month, last-month, year-to-date, last-7-days, last-14-days, last-30-days, last-3-months, last-6-months, or all-time.

timezone*

Timezone for the preset field e.g. America/Los_Angeles. A complete list of acceptable timezones by country is given here.

from

A valid ISO 8601 formatted date denoting the start of the period, e.g. 2016-09-01T00:00:00+00:00. This field along with the to field lets you specify a custom date and time interval if none suits your needs from the preset. The timezone offsets must match in the specified from and to fields.

to

A valid ISO 8601 formatted date denoting the end of the period, e.g. 2016-10-15T16:00:00+00:00. This field along with the from field lets you specify a custom date and time interval if none suits your needs from the preset. The timezone offsets must match the specified to and from fields.

show_financial_data

A flag to indicate whether to show financial data in the response or not. When true you will see cost, payout, revenue, e_cpm, e_cpc, and e_cpa in the response.

* = required field
✝ = Either preset or specific to and from dates must be specified

Returns

Returns a stats object if the request succeeded, or an error if something went terribly wrong.

Retrieve summary statistics

Definition

GET https://api.adbutler.com/v1/stats
\AdButler\Stats::retrieve()
adbutler.stats.retrieve()

Example Request

curl "https://api.adbutler.com/v1/stats?type=publisher" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$stat = \AdButler\Stats::retrieve( array(
    'type' => 'publisher'
));

echo $stat;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.stats.read(3199, function(response) {
  console.log(response);
});

// using promises
adbutler.stats.read(3199).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "stats",
  "url": "/v1/stats/summary",
  "data": {
    "1520": {
      "responses": 2778043,
      "impressions": 2778094,
      "clicks": 11,
      "conversions": 8,
      "cost": 2399.22634,
      "payout": 287.9071608,
      "revenue": 2111.3191792,
      "e_cpm": 0.864,
      "e_cpc": 218.111,
      "e_cpa": 299.903
    },
    "1747": {
      "responses": 922621,
      "impressions": 922611,
      "clicks": 0,
      "conversions": 0,
      "cost": 0,
      "payout": 0,
      "revenue": 0,
      "e_cpm": 0,
      "e_cpc": 0,
      "e_cpa": 0
    }
  },
  "meta": {
    "type": "publisher",
    "period": "total",
    "from": "2016-06-01T00:00:00-07:00",
    "to": "2016-11-10T13:00:00-08:00"
  }
}
AdButler\Stats JSON: {
    "object": "stats",
    "url": "/v1/stats/summary",
    "data": {
      "1520": {
        "responses": 2778043,
        "impressions": 2778094,
        "clicks": 11,
        "conversions": 8,
        "cost": 2399.22634,
        "payout": 287.9071608,
        "revenue": 2111.3191792,
        "e_cpm": 0.864,
        "e_cpc": 218.111,
        "e_cpa": 299.903
      },
      "1747": {
        "responses": 922621,
        "impressions": 922611,
        "clicks": 0,
        "conversions": 0,
        "cost": 0,
        "payout": 0,
        "revenue": 0,
        "e_cpm": 0,
        "e_cpc": 0,
        "e_cpa": 0
      }
    },
    "meta": {
    "type": "publisher",
    "period": "total",
    "from": "2016-06-01T00:00:00-07:00",
    "to": "2016-11-10T13:00:00-08:00"
  }
}

Summary statistics present the overall performance metrics. You can retrieve an overview of all the information or about a specific publisher, advertiser, zone, campaign, or banner.

Query Parameters

Parameter Description

type*

Specifies the focus of the statistics you are interested in viewing. The value must be one of overview, publisher, advertiser, zone, campaign, or banner.

period*

The range of time you are interested in viewing. The value must be one of hour, day, week, month, or year.

preset

Frequently used time frames for reporting statistics are bundled as presets You can pick a value from the presets instead of creating your own custom date range using the from and to fields. A preset range value must be one of the following: today, yesterday, this-week, last-week, this-month, last-month, year-to-date, last-7-days, last-14-days, last-30-days, last-3-months, last-6-months, or all-time.

preset_tz

Timezone for the preset field e.g. America/Los_angeles. A complete list of acceptable timezones by country is given here.

from

A valid ISO 8601 formatted date denoting the start of the period, e.g. 2016-09-01T00:00:00+00:00. This field along with the to field lets you specify a custom date and time interval if none suits your needs from the preset. The timezone offsets must match in the specified from and to fields.

to

A valid ISO 8601 formatted date denoting the end of the period, e.g. 2016-10-15T16:00:00+00:00. This field along with the from field lets you specify a custom date and time interval if none suits your needs from the preset. The timezone offsets must match in the specified to and from fields.

show_financial_data

A flag to indicate whether to show financial data in the response or not. When true you will see cost, payout, revenue, e_cpm, e_cpc, and e_cpa in the response.

* = required field
✝ = Either preset or specific to and from dates must be specified

Returns

Returns a stats object if the request succeeded, or an error if something went terribly wrong.


VAST Banners

Introduction

A VAST banner is a collection of creatives to be served before, during, or after video content. The banner can consist of linear, non-linear, and companion creatives, and complies with the VAST specification set out by the IAB.

The vast_banner response object has the following fields.

Example Response

{
  "object": "vast_banner",
  "self": "/v1/vast-banners/2579",
  "id": "2579",
  "name": "demo-account-banner",
  "location": null,
  "ad_parameters": null,
  "encode_parameters": "none",
  "companion_display": "",
  "skippable": false,
  "skip_duration": "0",
  "duration": "00:01",
  "use_wrapper": false,
  "wrapper_url": null,
  "companions": [
    1416
  ]
}
AdButler\VASTBanner JSON: {
  "object": "vast_banner",
  "self": "/v1/vast-banners/2579",
  "id": 2579,
  "name": "demo-account-banner",
  "location": null,
  "ad_parameters": null,
  "encode_parameters": "none",
  "companion_display": "",
  "skippable": false,
  "skip_duration": 0,
  "duration": "00:01",
  "use_wrapper": false,
  "wrapper_url": null,
  "companions": [
    1416
  ]
}
Field Type Description

object

string

A string denoting the object type which is always vast_banner for the current resource.

self

string

The relative URL of the current resource which is always of the form /v1/vast-banners/{BANNER_ID}.

id

integer

The resource identifier (ID).

name

string

Name of the banner.

location

string

A URL indicating where you want the user to go when they click on the banner. This refers to either the linear or non-linear media. Companion ads will have their own click destinations. This field can be left blank.

ad_parameters

string

Custom parameters for executable media or API frameworks (such as VPAID).

encode_parameters

string

How the ad_parameters field has been escaped. One of: "none", "xml", "xml_reencode".

companion_display

string

The method by which the video player should try to display companion ads. One of: "any", "all", "none".

skippable

boolean

Whether the ad is skippable.

skip_duration

string

The percentage (integer), or length of time ('mm:ss') before the ad can be skipped.

duration

string

The length of the ad. (mm:ss)

use_wrapper

boolean

Whether this banner is going to serve a wrapper ad.

wrapper_url

string

URL of a VAST wrapper ad for this banner to serve.

companions

array

An array of IDs that refer to all the VAST companions associated with this banner.

Create a VAST Banner

Definition

POST https://api.adbutler.com/v1/vast-banners
\AdButler\VASTBanner::create()
adbutler.vastBanners.create()

Example Request

curl "https://api.adbutler.com/v1/vast-banners" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{  
        "name": "demo-account-banner",
        "ad_parameters": null,
        "encode_parameters": "none",
        "companion_display": "",
        "skippable": false,
        "skip_duration": "0",
        "duration": "00:01",
        "use_wrapper": false,
        "wrapper_url": null
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTBanner = \AdButler\VASTBanner::create(array(
  "name" => "demo-account-banner",
  "ad_parameters" => null,
  "encode_parameters" => "none",
  "companion_display" => "",
  "skippable" => false,
  "skip_duration" => "0",
  "duration" => "00:01",
  "use_wrapper" => false,
  "wrapper_url" => null
));

echo $vASTBanner;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var postData = {
  "name": "demo-account-banner",
  "ad_parameters": null,
  "encode_parameters": "none",
  "companion_display": "",
  "skippable": false,
  "skip_duration": "0",
  "duration": "00:01",
  "use_wrapper": false,
  "wrapper_url": null
};

// using callbacks
adbutler.vastBanners.create(postData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastBanners.create(postData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "vast_banner",
  "self": "/v1/vast-banners/2579",
  "id": "2579",
  "name": "demo-account-banner",
  "location": null,
  "ad_parameters": null,
  "encode_parameters": "none",
  "companion_display": "",
  "skippable": false,
  "skip_duration": "0",
  "duration": "00:01",
  "use_wrapper": false,
  "wrapper_url": null,
  "companions": [
    1416
  ]
}
AdButler\VASTBanner JSON: {
  "object": "vast_banner",
  "self": "/v1/vast-banners/2579",
  "id": 2579,
  "name": "demo-account-banner",
  "location": null,
  "ad_parameters": null,
  "encode_parameters": "none",
  "companion_display": "",
  "skippable": false,
  "skip_duration": 0,
  "duration": "00:01",
  "use_wrapper": false,
  "wrapper_url": null,
  "companions": [
    1416
  ]
}

Creates a new VAST Banner.

Field Type Description

name*

string

Name of the banner.

location*

string

A URL indicating where you want the user to go when they click on the banner. This refers to either the linear or non-linear media. Companion ads will have their own click destinations. This field can be left blank.

ad_parameters

string

Custom parameters for executable media or API frameworks (such as VPAID).

encode_parameters

string

How the ad_parameters field has been escaped. One of: "none", "xml", "xml_reencode".

companion_display

string

The method by which the video player should try to display companion ads. One of: "any", "all", "none".

skippable

boolean

Whether the ad is skippable.

skip_duration

string

The percentage (integer), or length of time ('mm:ss') before the ad can be skipped.

duration

string

The length of the ad. (mm:ss)

use_wrapper

boolean

Whether this banner is going to serve a wrapper ad.

wrapper_url

string

URL of a VAST wrapper ad for this banner to serve.

* = required field

Returns

Returns a vast_banner object if the request succeeded, or an error if something went terribly wrong.

Retrieve a VAST Banner

Definition

GET https://api.adbutler.com/v1/vast-banners/{BANNER-ID}
\AdButler\VASTBanner::retrieve()
adbutler.vastBanners.retrieve()

Example Request

curl "https://api.adbutler.com/v1/vast-banners/2579" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTBanner = \AdButler\VASTBanner::retrieve( 2579 );

echo $vASTBanner;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastBanners.read(2579, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastBanners.read(2579).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "vast_banner",
  "self": "/v1/vast-banners/2579",
  "id": "2579",
  "name": "demo-account-banner",
  "location": null,
  "ad_parameters": null,
  "encode_parameters": "none",
  "companion_display": "",
  "skippable": false,
  "skip_duration": "0",
  "duration": "00:01",
  "use_wrapper": false,
  "wrapper_url": null,
  "companions": [
    1416
  ]
}
AdButler\VASTBanner JSON: {
  "object": "vast_banner",
  "self": "/v1/vast-banners/2579",
  "id": 2579,
  "name": "demo-account-banner",
  "location": null,
  "ad_parameters": null,
  "encode_parameters": "none",
  "companion_display": "",
  "skippable": false,
  "skip_duration": 0,
  "duration": "00:01",
  "use_wrapper": false,
  "wrapper_url": null,
  "companions": [
    1416
  ]
}

You can retrieve the information about an existing VAST banner by giving the banner ID that was returned in the VAST banner object upon creation.

Returns

Returns a vast_banner object if the request succeeded, or an error if something went terribly wrong.

Update a VAST Banner

Definition

PUT https://api.adbutler.com/v1/vast-banners/{BANNER-ID}
\AdButler\VASTBanner->save()
adbutler.vastBanners.update()

Example Request

curl "https://api.adbutler.com/v1/vast-banners/2579" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{  
        "name": "demo-account-banner",
        "ad_parameters": null,
        "encode_parameters": "none",
        "companion_display": "",
        "skippable": false,
        "skip_duration": "0",
        "duration": "00:01",
        "use_wrapper": false,
        "wrapper_url": null
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTBanner = \AdButler\VASTBanner::retrieve( 2579 );

$vASTBanner->name = "demo-account-banner";
$vASTBanner->ad_parameters = null;
$vASTBanner->encode_parameters = "none";
$vASTBanner->companion_display = "";
$vASTBanner->skippable = false;
$vASTBanner->skip_duration = "0";
$vASTBanner->duration = "00:01";
$vASTBanner->use_wrapper = false;
$vASTBanner->wrapper_url = null;

$vASTBanner->save();

echo $vASTBanner;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var updateData = {
  "name": "demo-account-banner",
  "ad_parameters": null,
  "encode_parameters": "none",
  "companion_display": "",
  "skippable": false,
  "skip_duration": "0",
  "duration": "00:01",
  "use_wrapper": false,
  "wrapper_url": null
};

// using callbacks
adbutler.vastBanners.update(2579, updateData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastBanners.update(2579, updateData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "vast_banner",
  "self": "/v1/vast-banners/2579",
  "id": "2579",
  "name": "demo-account-banner",
  "location": null,
  "ad_parameters": null,
  "encode_parameters": "none",
  "companion_display": "",
  "skippable": false,
  "skip_duration": "0",
  "duration": "00:01",
  "use_wrapper": false,
  "wrapper_url": null,
  "companions": [
    1416
  ]
}
AdButler\VASTBanner JSON: {
  "object": "vast_banner",
  "self": "/v1/vast-banners/2579",
  "id": 2579,
  "name": "demo-account-banner",
  "location": null,
  "ad_parameters": null,
  "encode_parameters": "none",
  "companion_display": "",
  "skippable": false,
  "skip_duration": 0,
  "duration": "00:01",
  "use_wrapper": false,
  "wrapper_url": null,
  "companions": [
    1416
  ]
}

You can update a specific VAST banner by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the VAST banner creation request.

Field Type Description

name

string

Name of the banner.

location

string

A URL indicating where you want the user to go when they click on the banner. This refers to either the linear or non-linear media. Companion ads will have their own click destinations. This field can be left blank.

ad_parameters

string

Custom parameters for executable media or API frameworks (such as VPAID).

encode_parameters

string

How the ad_parameters field has been escaped. One of: "none", "xml", "xml_reencode".

companion_display

string

The method by which the video player should try to display companion ads. One of: "any", "all", "none".

skippable

boolean

Whether the ad is skippable.

skip_duration

string

The percentage (integer), or length of time ('mm:ss') before the ad can be skipped.

duration

string

The length of the ad. (mm:ss)

use_wrapper

boolean

Whether this banner is going to serve a wrapper ad.

wrapper_url

string

URL of a VAST wrapper ad for this banner to serve.

Returns

Returns a vast_banner object if the request succeeded, or an error if something went terribly wrong.

Delete a VAST Banner

Definition

DELETE https://api.adbutler.com/v1/vast-banners/{BANNER-ID}
\AdButler\VASTBanner->delete()
adbutler.vastBanners.delete()

Example Request

curl "https://api.adbutler.com/v1/vast-banners/2579" \
  -H "Authorization: Basic {API_KEY}" \
  -X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTBanner = \AdButler\VASTBanner::retrieve( 2579 );
$vASTBanner->delete();

echo $vASTBanner;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastBanners.delete(2579, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastBanners.delete(2579).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "id": 2579,
  "delete": true
}
AdButler\VASTBanner JSON: {
  "id": 2579,
  "delete": true
}

Permanently deletes a VAST banner. if successful, this operation cannot be undone so be very sure when deleting one.

Returns

Returns a VAST banner ID if the request succeeded, or an error if something went terribly wrong.

List all VAST Banners

Definition

GET https://api.adbutler.com/v1/vast-banners
\AdButler\VASTBanner::retrieveAll()
adbutler.vastBanners.list()

Example Request

curl "https://api.adbutler.com/v1/vast-banners?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTBanner = \AdButler\VASTBanner::retrieveAll(array(
  "limit" => 2
));

echo $vASTBanner;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastBanners.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastBanners.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/vast-banners",
  "data": [
    {
      "object": "vast_banner",
      "self": "/v1/vast-banners/2553",
      "id": "2553",
      "name": "demo-account-banner",
      "location": null,
      "ad_parameters": null,
      "encode_parameters": "none",
      "companion_display": "",
      "skippable": false,
      "skip_duration": "0",
      "duration": "00:01",
      "use_wrapper": false,
      "wrapper_url": null,
      "companions": [
        1402
      ]
    },
    {
      "object": "vast_banner",
      "self": "/v1/vast-banners/2554",
      "id": "2554",
      "name": "demo-account-banner",
      "location": null,
      "ad_parameters": null,
      "encode_parameters": "none",
      "companion_display": "",
      "skippable": false,
      "skip_duration": "0",
      "duration": "00:01",
      "use_wrapper": false,
      "wrapper_url": null,
      "companions": [
        1403
      ]
    }
  ]
}
AdButler\VASTBanner JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/vast-banners",
  "data": [
    {
      "object": "vast_banner",
      "self": "/v1/vast-banners/2553",
      "id": 2553,
      "name": "demo-account-banner",
      "location": null,
      "ad_parameters": null,
      "encode_parameters": "none",
      "companion_display": "",
      "skippable": false,
      "skip_duration": 0,
      "duration": "00:01",
      "use_wrapper": false,
      "wrapper_url": null,
      "companions": [
        1402
      ]
    },
    {
      "object": "vast_banner",
      "self": "/v1/vast-banners/2554",
      "id": 2554,
      "name": "demo-account-banner",
      "location": null,
      "ad_parameters": null,
      "encode_parameters": "none",
      "companion_display": "",
      "skippable": false,
      "skip_duration": 0,
      "duration": "00:01",
      "use_wrapper": false,
      "wrapper_url": null,
      "companions": [
        1403
      ]
    }
  ]
}

Returns a list of all the VAST banners. Most recent VAST banners appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is a vast_banner object, and if no objects were found the list will be empty.

Retrieve VAST banner conversion tag

Definition

GET https://api.adbutler.com/v1/vast-banners/{BANNER-ID}/conversion-tag
\AdButler\VASTBannerConvTag::retrieve()
adbutler.vastBanners.conversionTag.retrieve()

Example Request

curl "https://api.adbutler.com/v1/vast-banners/ID/conversion-tag/2579" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTBannerConvTag = \AdButler\VASTBannerConvTag::retrieve( 2579 );

echo $vASTBannerConvTag;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastBanners.conversionTag.read(2579, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastBanners.conversionTag.read(2579).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Retrieves an HTML tag which can be used to track conversions for the provided VAST banner.

Query Parameters

Parameter Description

protocol

Whether to use http or https protocol when serving the advertisements. Use https only if you are using secure pages because it does not support Custom Domains.

Returns

Example Response

{
  "object": "conv_tag",
  "url": "/v1/vast-banners/2579/conversion-tag",
  "data": {
    "src": "https://servedbyadbutler.com.vm.test/vconvtrack.spark?MID=108607&vastBannerID=2579",
    "html": "<img src='https://servedbyadbutler.com.vm.test/vconvtrack.spark?MID=108607&vastBannerID=2579' width='1' height='1' border='0' />"
  }
}
AdButler\VASTBannerConvTag JSON: {
  "object": "conv_tag",
  "url": "/v1/vast-banners/2579/conversion-tag",
  "data": {
    "src": "https://servedbyadbutler.com.vm.test/vconvtrack.spark?MID=108607&vastBannerID=2579",
    "html": "<img src='https://servedbyadbutler.com.vm.test/vconvtrack.spark?MID=108607&vastBannerID=2579' width='1' height='1' border='0' />"
  }
}
Field Type Description

object

string

A string denoting the object type which is always conv_tag for the current resource.

url

string

The relative URL of the current resource which is always of the form /v1/vast-banners/{BANNER_ID}/conversion-tag.

data

array

The data object containing the conversion tag.

 

Returns a conv_tag object if the request succeeded, or an error if something went terribly wrong.


VAST Schedules

Introduction

VAST Schedules describe the conditions necessary for serving VAST ads. Common conditions include start and end dates, and quotas.

If a quota has not been filled then that assignment will generally always serve as long as a targeting system does not interfere.

The vast_schedule response object has the following fields.

Example Response

{
  "object": "vast_schedule",
  "self": "/v1/vast-schedules/12209",
  "id": 12209,
  "delivery_method": "default",
  "quota_lifetime": 0,
  "quota_type": null,
  "start_date": "0000-00-00 00:00:00",
  "end_date": "9999-01-01 00:00:00",
  "views": 0,
  "clicks": 0,
  "geo_target": 0
}
AdButler\VASTSchedule JSON: {
  "object": "vast_schedule",
  "self": "/v1/vast-schedules/12209",
  "id": 12209,
  "delivery_method": "default",
  "quota_lifetime": 0,
  "quota_type": null,
  "start_date": "0000-00-00 00:00:00",
  "end_date": "9999-01-01 00:00:00",
  "views": 0,
  "clicks": 0,
  "geo_target": 0
}
Field Type Description

object

string

A string denoting the object type which is always vast_schedule for the current resource.

self

string

The relative URL of the current resource which is always of the form /v1/vast-schedules/{SCHEDULE_ID}.

id

integer

The resource identifier (ID).

delivery_method

string

Whether to deliver the impressions as quickly as possible ("default") or deliver it evenly ("smooth") over the specified duration (start_date and end_date) and quota (quota_lifetime and quota_type). Specify the pace of serving advertisements which can be either "default" or "smooth". Default delivery delivers the impressions as quickly as possible. Smooth delivery will evenly serve over the lifetime dates and quotas.

quota_lifetime

integer

The amount of quota when setting up quota-based expiration which is a direct number (float or integer), not given per thousand. Just enter your desired total quota and we will calculate the remaining inventory available. A quota-based expiration method allowing you to impose a hard limit on the amount of clicks or views an assignment gets.

quota_type

string

The type of quota when setting up quota-based expiration which can be the number of clicks (clicks) or the number of views (views). A quota-based expiration method allowing you to impose a hard limit on the amount of clicks or views an assignment gets.

start_date

datetime

The time and date when AdButler should start serving your advertisement. You can delay serving of ads by setting a future start date. Defaults to midnight of the current date if not given.

end_date

datetime

The time and date when AdButler should stop serving your advertisement. The end date can be as far in the future as desired. This allows you to set time-based expiration for your ads and we guarantee accuracy to the hour. Leave this field empty if you want ad serving to never end.

views

integer

The number of views recorded so far.

clicks

integer

The number of clicks recorded so far.

geo_target

integer

The geotarget identifier (ID) if you want your ads to be delivered to a particular location only. This will direct your audience to ads in their region. Defaults to null which means geographic targeting is not in effect.

Create a VAST Schedule

Definition

POST https://api.adbutler.com/v1/vast-schedules
\AdButler\VASTSchedule::create()
adbutler.vastSchedules.create()

Example Request

curl "https://api.adbutler.com/v1/vast-schedules" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{  
        "quota_lifetime": 0,
        "quota_type": null,
        "start_date": "0000-00-00 00:00:00",
        "end_date": "9999-01-01 00:00:00"
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTSchedule = \AdButler\VASTSchedule::create(array(
  "quota_lifetime" => 0,
  "quota_type" => null,
  "start_date" => "0000-00-00 00:00:00",
  "end_date" => "9999-01-01 00:00:00"
));

echo $vASTSchedule;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var postData = {
  "quota_lifetime": 0,
  "quota_type": null,
  "start_date": "0000-00-00 00:00:00",
  "end_date": "9999-01-01 00:00:00"
};

// using callbacks
adbutler.vastSchedules.create(postData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastSchedules.create(postData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "vast_schedule",
  "self": "/v1/vast-schedules/12209",
  "id": 12209,
  "delivery_method": "default",
  "quota_lifetime": 0,
  "quota_type": null,
  "start_date": "0000-00-00 00:00:00",
  "end_date": "9999-01-01 00:00:00",
  "views": 0,
  "clicks": 0,
  "geo_target": 0
}
AdButler\VASTSchedule JSON: {
  "object": "vast_schedule",
  "self": "/v1/vast-schedules/12209",
  "id": 12209,
  "delivery_method": "default",
  "quota_lifetime": 0,
  "quota_type": null,
  "start_date": "0000-00-00 00:00:00",
  "end_date": "9999-01-01 00:00:00",
  "views": 0,
  "clicks": 0,
  "geo_target": 0
}

Creates a new VAST schedule.

Field Type Description

delivery_method

string

Whether to deliver the impressions as quickly as possible ("default") or deliver it evenly ("smooth") over the specified duration (start_date and end_date) and quota (quota_lifetime and quota_type). Specify the pace of serving advertisements which can be either "default" or "smooth". Default delivery delivers the impressions as quickly as possible. Smooth delivery will evenly serve over the lifetime dates and quotas.

quota_lifetime

integer

The amount of quota when setting up quota-based expiration which is a direct number (float or integer), not given per thousand. Just enter your desired total quota and we will calculate the remaining inventory available. A quota-based expiration method allowing you to impose a hard limit on the amount of clicks or views an assignment gets.

quota_type

string

The type of quota when setting up quota-based expiration which can be the number of clicks (clicks) or the number of views (views). A quota-based expiration method allowing you to impose a hard limit on the amount of clicks or views an assignment gets.

start_date

datetime

The time and date when AdButler should start serving your advertisement. You can delay serving of ads by setting a future start date. Defaults to midnight of the current date if not given.

end_date

datetime

The time and date when AdButler should stop serving your advertisement. The end date can be as far in the future as desired. This allows you to set time-based expiration for your ads and we guarantee accuracy to the hour. Leave this field empty if you want ad serving to never end.

geo_target

integer

The geotarget identifier (ID) if you want your ads to be delivered to a particular location only. This will direct your audience to ads in their region. Defaults to null which means geographic targeting is not in effect.

* = required field
† = must be given if delivery_method is smooth, otherwise defaults to the default value of the field

Returns

Returns a vast_schedule object if the request succeeded, or an error if something went terribly wrong.

Retrieve a VAST Schedule

Definition

GET https://api.adbutler.com/v1/vast-schedules/{SCHEDULE-ID}
\AdButler\VASTSchedule::retrieve()
adbutler.vastSchedules.retrieve()

Example Request

curl "https://api.adbutler.com/v1/vast-schedules/12209" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTSchedule = \AdButler\VASTSchedule::retrieve( 12209 );

echo $vASTSchedule;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastSchedules.read(12209, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastSchedules.read(12209).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "vast_schedule",
  "self": "/v1/vast-schedules/12209",
  "id": 12209,
  "delivery_method": "default",
  "quota_lifetime": 0,
  "quota_type": null,
  "start_date": "0000-00-00 00:00:00",
  "end_date": "9999-01-01 00:00:00",
  "views": 0,
  "clicks": 0,
  "geo_target": 0
}
AdButler\VASTSchedule JSON: {
  "object": "vast_schedule",
  "self": "/v1/vast-schedules/12209",
  "id": 12209,
  "delivery_method": "default",
  "quota_lifetime": 0,
  "quota_type": null,
  "start_date": "0000-00-00 00:00:00",
  "end_date": "9999-01-01 00:00:00",
  "views": 0,
  "clicks": 0,
  "geo_target": 0
}

You can retrieve the information about an existing VAST schedule by giving the schedule ID that was returned in the VAST schedule object upon creation. You will see at the most 10 VAST schedules in the response. You can change this default limit by appending ?limit=25 if you want this request to return 25 VAST schedules.

Returns

Returns a vast_schedule object if the request succeeded, or an error if something went terribly wrong.

Update a VAST Schedule

Definition

PUT https://api.adbutler.com/v1/vast-schedules/{SCHEDULE-ID}
\AdButler\VASTSchedule->save()
adbutler.vastSchedules.update()

Example Request

curl "https://api.adbutler.com/v1/vast-schedules/12209" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{  
        "quota_lifetime": 0,
        "quota_type": null,
        "start_date": "0000-00-00 00:00:00",
        "end_date": "9999-01-01 00:00:00"
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTSchedule = \AdButler\VASTSchedule::retrieve( 12209 );

$vASTSchedule->quota_lifetime = 0;
$vASTSchedule->quota_type = null;
$vASTSchedule->start_date = "0000-00-00 00:00:00";
$vASTSchedule->end_date = "9999-01-01 00:00:00";

$vASTSchedule->save();

echo $vASTSchedule;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var updateData = {
  "quota_lifetime": 0,
  "quota_type": null,
  "start_date": "0000-00-00 00:00:00",
  "end_date": "9999-01-01 00:00:00"
};

// using callbacks
adbutler.vastSchedules.update(12209, updateData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastSchedules.update(12209, updateData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "vast_schedule",
  "self": "/v1/vast-schedules/12209",
  "id": 12209,
  "delivery_method": "default",
  "quota_lifetime": 0,
  "quota_type": null,
  "start_date": "0000-00-00 00:00:00",
  "end_date": "9999-01-01 00:00:00",
  "views": 0,
  "clicks": 0,
  "geo_target": 0
}
AdButler\VASTSchedule JSON: {
  "object": "vast_schedule",
  "self": "/v1/vast-schedules/12209",
  "id": 12209,
  "delivery_method": "default",
  "quota_lifetime": 0,
  "quota_type": null,
  "start_date": "0000-00-00 00:00:00",
  "end_date": "9999-01-01 00:00:00",
  "views": 0,
  "clicks": 0,
  "geo_target": 0
}

You can update a specific VAST schedule by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the VAST schedule creation request.

Field Type Description

delivery_method

string

Whether to deliver the impressions as quickly as possible ("default") or deliver it evenly ("smooth") over the specified duration (start_date and end_date) and quota (quota_lifetime and quota_type). Specify the pace of serving advertisements which can be either "default" or "smooth". Default delivery delivers the impressions as quickly as possible. Smooth delivery will evenly serve over the lifetime dates and quotas.

quota_lifetime

integer

The amount of quota when setting up quota-based expiration which is a direct number (float or integer), not given per thousand. Just enter your desired total quota and we will calculate the remaining inventory available. A quota-based expiration method allowing you to impose a hard limit on the amount of clicks or views an assignment gets.

quota_type

string

The type of quota when setting up quota-based expiration which can be the number of clicks (clicks) or the number of views (views). A quota-based expiration method allowing you to impose a hard limit on the amount of clicks or views an assignment gets.

start_date

datetime

The time and date when AdButler should start serving your advertisement. You can delay serving of ads by setting a future start date. Defaults to midnight of the current date if not given.

end_date

datetime

The time and date when AdButler should stop serving your advertisement. The end date can be as far in the future as desired. This allows you to set time-based expiration for your ads and we guarantee accuracy to the hour. Leave this field empty if you want ad serving to never end.

geo_target

integer

The geotarget identifier (ID) if you want your ads to be delivered to a particular location only. This will direct your audience to ads in their region. Defaults to null which means geographic targeting is not in effect.

† = must be given if delivery_method is smooth, otherwise defaults to the default value of the field

Returns

Returns a vast_schedule object if the request succeeded, or an error if something went terribly wrong.

Delete a VAST Schedule

Definition

DELETE https://api.adbutler.com/v1/vast-schedules/{SCHEDULE-ID}
\AdButler\VASTSchedule->delete()
adbutler.vastSchedules.delete()

Example Request

curl "https://api.adbutler.com/v1/vast-schedules/12209" \
  -H "Authorization: Basic {API_KEY}" \
  -X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTSchedule = \AdButler\VASTSchedule::retrieve( 12209 );
$vASTSchedule->delete();

echo $vASTSchedule;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastSchedules.delete(12209, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastSchedules.delete(12209).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "id": 12209,
  "delete": true
}
AdButler\VASTSchedule JSON: {
  "id": 12209,
  "delete": true
}

Permanently deletes a VAST schedule. if successful, this operation cannot be undone so be very sure when deleting one.

Returns

Returns a VAST schedule ID if the request succeeded, or an error if something went terribly wrong.

List all VAST Schedules

Definition

GET https://api.adbutler.com/v1/vast-schedules
\AdButler\VASTSchedule::retrieveAll()
adbutler.vastSchedules.list()

Example Request

curl "https://api.adbutler.com/v1/vast-schedules?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTSchedule = \AdButler\VASTSchedule::retrieveAll(array(
  "limit" => 2
));

echo $vASTSchedule;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastSchedules.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastSchedules.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/vast-schedules",
  "data": [
    {
      "object": "vast_schedule",
      "self": "/v1/vast-schedules/12153",
      "id": 12153,
      "delivery_method": "default",
      "quota_lifetime": 0,
      "quota_type": null,
      "start_date": "0000-00-00 00:00:00",
      "end_date": "9999-01-01 00:00:00",
      "views": 0,
      "clicks": 0,
      "geo_target": 0
    },
    {
      "object": "vast_schedule",
      "self": "/v1/vast-schedules/12154",
      "id": 12154,
      "delivery_method": "default",
      "quota_lifetime": 0,
      "quota_type": null,
      "start_date": "0000-00-00 00:00:00",
      "end_date": "9999-01-01 00:00:00",
      "views": 0,
      "clicks": 0,
      "geo_target": 0
    }
  ]
}
AdButler\VASTSchedule JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/vast-schedules",
  "data": [
    {
      "object": "vast_schedule",
      "self": "/v1/vast-schedules/12153",
      "id": 12153,
      "delivery_method": "default",
      "quota_lifetime": 0,
      "quota_type": null,
      "start_date": "0000-00-00 00:00:00",
      "end_date": "9999-01-01 00:00:00",
      "views": 0,
      "clicks": 0,
      "geo_target": 0
    },
    {
      "object": "vast_schedule",
      "self": "/v1/vast-schedules/12154",
      "id": 12154,
      "delivery_method": "default",
      "quota_lifetime": 0,
      "quota_type": null,
      "start_date": "0000-00-00 00:00:00",
      "end_date": "9999-01-01 00:00:00",
      "views": 0,
      "clicks": 0,
      "geo_target": 0
    }
  ]
}

Returns a list of all the VAST schedules. Most recent VAST schedules appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is a vast_schedule object, and if no objects were found the list will be empty.


VAST Zones

Introduction

A VAST zone is a collection of VAST placements that you wish to serve. Each VAST zone has its own VAST ad tag you can use to retrieve ads.

The vast_zone response object has the following fields.

Example Response

{
  "object": "vast_zone",
  "self": "/v1/vast-zones/85772",
  "id": 85772,
  "name": "demo-account-zone",
  "publisher": 123,
  "default_vast_banner": 2579,
  "default_vast_campaign": 0
}
AdButler\VASTZone JSON: {
  "object": "vast_zone",
  "self": "/v1/vast-zones/85772",
  "id": 85772,
  "name": "demo-account-zone",
  "publisher": 123,
  "default_vast_banner": 2579,
  "default_vast_campaign": 0
}
Field Type Description

object

string

A string denoting the object type which is always vast_zone for the current resource.

self

string

The relative URL of the current resource which is always of the form /v1/vast-zones/{ZONE_ID}.

id

integer

The resource identifier (ID).

name

string

Name of the zone.

publisher

integer

The publisher identifier (ID) the banner zone belongs to. You can create zones without a publisher but you cannot use them unless you associate them with a publisher first.

default_vast_banner

integer

The default VAST banner identifier (ID). A default banner will show if there is nothing else available in the zone.

default_vast_campaign

integer

The default VAST campaign identifier (ID). A default campaign will show if there is nothing else available in the zone.

Create a VAST Zone

Definition

POST https://api.adbutler.com/v1/vast-zones
\AdButler\VASTZone::create()
adbutler.vastZones.create()

Example Request

curl "https://api.adbutler.com/v1/vast-zones" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{  
        "name": "demo-account-zone",
        "publisher": 123,
        "default_vast_banner": 2579,
        "default_vast_campaign": 0
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTZone = \AdButler\VASTZone::create(array(
  "name" => "demo-account-zone",
  "publisher" => 123,
  "default_vast_banner" => 2579,
  "default_vast_campaign" => 0
));

echo $vASTZone;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var postData = {
  "name": "demo-account-zone",
  "publisher": 123,
  "default_vast_banner": 2579,
  "default_vast_campaign": 0
};

// using callbacks
adbutler.vastZones.create(postData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastZones.create(postData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "vast_zone",
  "self": "/v1/vast-zones/85772",
  "id": 85772,
  "name": "demo-account-zone",
  "publisher": 123,
  "default_vast_banner": 2579,
  "default_vast_campaign": 0
}
AdButler\VASTZone JSON: {
  "object": "vast_zone",
  "self": "/v1/vast-zones/85772",
  "id": 85772,
  "name": "demo-account-zone",
  "publisher": 123,
  "default_vast_banner": 2579,
  "default_vast_campaign": 0
}

Creates a new VAST Zone.

Field Type Description

name*

string

Name of the zone.

publisher

integer

The publisher identifier (ID) the banner zone belongs to. You can create zones without a publisher but you cannot use them unless you associate them with a publisher first.

default_vast_banner

integer

The default VAST banner identifier (ID). A default banner will show if there is nothing else available in the zone.

default_vast_campaign

integer

The default VAST campaign identifier (ID). A default campaign will show if there is nothing else available in the zone.

* = required field
† = only one of default_vast_banner or default_vast_campaign may be submitted

Returns

Returns a vast_zone object if the request succeeded, or an error if something went terribly wrong.

Retrieve a VAST Zone

Definition

GET https://api.adbutler.com/v1/vast-zones/{ZONE-ID}
\AdButler\VASTZone::retrieve()
adbutler.vastZones.retrieve()

Example Request

curl "https://api.adbutler.com/v1/vast-zones/85772" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTZone = \AdButler\VASTZone::retrieve( 85772 );

echo $vASTZone;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastZones.read(85772, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastZones.read(85772).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "vast_zone",
  "self": "/v1/vast-zones/85772",
  "id": 85772,
  "name": "demo-account-zone",
  "publisher": 123,
  "default_vast_banner": 2579,
  "default_vast_campaign": 0
}
AdButler\VASTZone JSON: {
  "object": "vast_zone",
  "self": "/v1/vast-zones/85772",
  "id": 85772,
  "name": "demo-account-zone",
  "publisher": 123,
  "default_vast_banner": 2579,
  "default_vast_campaign": 0
}

You can retrieve the information about an existing VAST zone by giving the zone ID that was returned in the VAST zone object upon creation. You will see at the most 10 VAST zones in the response. You can change this default limit by appending ?limit=25 if you want this request to return 25 VAST zones.

Returns

Returns a vast_zone object if the request succeeded, or an error if something went terribly wrong.

Update a VAST Zone

Definition

PUT https://api.adbutler.com/v1/vast-zones/{ZONE-ID}
\AdButler\VASTZone->save()
adbutler.vastZones.update()

Example Request

curl "https://api.adbutler.com/v1/vast-zones/85772" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{  
        "name": "demo-account-zone",
        "publisher": 123,
        "default_vast_banner": 2579,
        "default_vast_campaign": 0
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTZone = \AdButler\VASTZone::retrieve( 85772 );

$vASTZone->name = "demo-account-zone";
$vASTZone->publisher = 123;
$vASTZone->default_vast_banner = 2579;
$vASTZone->default_vast_campaign = 0;

$vASTZone->save();

echo $vASTZone;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var updateData = {
  "name": "demo-account-zone",
  "publisher": 123,
  "default_vast_banner": 2579,
  "default_vast_campaign": 0
};

// using callbacks
adbutler.vastZones.update(85772, updateData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastZones.update(85772, updateData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "vast_zone",
  "self": "/v1/vast-zones/85772",
  "id": 85772,
  "name": "demo-account-zone",
  "publisher": 123,
  "default_vast_banner": 2579,
  "default_vast_campaign": 0
}
AdButler\VASTZone JSON: {
  "object": "vast_zone",
  "self": "/v1/vast-zones/85772",
  "id": 85772,
  "name": "demo-account-zone",
  "publisher": 123,
  "default_vast_banner": 2579,
  "default_vast_campaign": 0
}

You can update a specific VAST zone by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the VAST zone creation request.

Field Type Description

name

string

Name of the zone.

publisher

integer

The publisher identifier (ID) the banner zone belongs to. You can create zones without a publisher but you cannot use them unless you associate them with a publisher first.

default_vast_banner

integer

The default VAST banner identifier (ID). A default banner will show if there is nothing else available in the zone.

default_vast_campaign

integer

The default VAST campaign identifier (ID). A default campaign will show if there is nothing else available in the zone.

† = only one of default_vast_banner or default_vast_campaign may be submitted

Returns

Returns a vast_zone object if the request succeeded, or an error if something went terribly wrong.

Delete a VAST Zone

Definition

DELETE https://api.adbutler.com/v1/vast-zones/{ZONE-ID}
\AdButler\VASTZone->delete()
adbutler.vastZones.delete()

Example Request

curl "https://api.adbutler.com/v1/vast-zones/85772" \
  -H "Authorization: Basic {API_KEY}" \
  -X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTZone = \AdButler\VASTZone::retrieve( 85772 );
$vASTZone->delete();

echo $vASTZone;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastZones.delete(85772, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastZones.delete(85772).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "id": 85772,
  "delete": true
}
AdButler\VASTZone JSON: {
  "id": 85772,
  "delete": true
}

Permanently deletes a VAST zone. if successful, this operation cannot be undone so be very sure when deleting one.

Returns

Returns a VAST zone ID if the request succeeded, or an error if something went terribly wrong.

List all VAST Zones

Definition

GET https://api.adbutler.com/v1/vast-zones
\AdButler\VASTZone::retrieveAll()
adbutler.vastZones.list()

Example Request

curl "https://api.adbutler.com/v1/vast-zones?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTZone = \AdButler\VASTZone::retrieveAll(array(
  "limit" => 2
));

echo $vASTZone;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastZones.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastZones.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/vast-zones",
  "data": [
    {
      "object": "vast_zone",
      "self": "/v1/vast-zones/85756",
      "id": 85756,
      "name": "demo-account-zone",
      "publisher": 123,
      "default_vast_banner": 2553,
      "default_vast_campaign": 0
    },
    {
      "object": "vast_zone",
      "self": "/v1/vast-zones/85757",
      "id": 85757,
      "name": "demo-account-zone",
      "publisher": 123,
      "default_vast_banner": 2554,
      "default_vast_campaign": 0
    }
  ]
}
AdButler\VASTZone JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/vast-zones",
  "data": [
    {
      "object": "vast_zone",
      "self": "/v1/vast-zones/85756",
      "id": 85756,
      "name": "demo-account-zone",
      "publisher": 123,
      "default_vast_banner": 2553,
      "default_vast_campaign": 0
    },
    {
      "object": "vast_zone",
      "self": "/v1/vast-zones/85757",
      "id": 85757,
      "name": "demo-account-zone",
      "publisher": 123,
      "default_vast_banner": 2554,
      "default_vast_campaign": 0
    }
  ]
}

Returns a list of all the VAST zones. Most recent VAST zones appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is a vast_zone object, and if no objects were found the list will be empty.

Retrieve VAST zone conversion tag

Definition

GET https://api.adbutler.com/v1/vast-zones/{ZONE-ID}/conversion-tag
\AdButler\VASTZoneConvTag::retrieve()
adbutler.vastZones.conversionTag.retrieve()

Example Request

curl "https://api.adbutler.com/v1/vast-zones/ID/conversion-tag/85772" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTZoneConvTag = \AdButler\VASTZoneConvTag::retrieve( 85772 );

echo $vASTZoneConvTag;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastZones.conversionTag.read(85772, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastZones.conversionTag.read(85772).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Retrieves an HTML tag which can be used to track conversions for the provided VAST zone.

Query Parameters

Parameter Description

protocol

Whether to use http or https protocol when serving the advertisements. Use https only if you are using secure pages because it does not support Custom Domains.

Returns

Example Response

{
  "object": "conv_tag",
  "url": "/v1/vast-zones/85772/conversion-tag",
  "data": {
    "src": "https://servedbyadbutler.com.vm.test/vconvtrack.spark?MID=108607&vastZoneID=85772",
    "html": "<img src='https://servedbyadbutler.com.vm.test/vconvtrack.spark?MID=108607&vastZoneID=85772' width='1' height='1' border='0' />"
  }
}
AdButler\VASTZoneConvTag JSON: {
  "object": "conv_tag",
  "url": "/v1/vast-zones/85772/conversion-tag",
  "data": {
    "src": "https://servedbyadbutler.com.vm.test/vconvtrack.spark?MID=108607&vastZoneID=85772",
    "html": "<img src='https://servedbyadbutler.com.vm.test/vconvtrack.spark?MID=108607&vastZoneID=85772' width='1' height='1' border='0' />"
  }
}
Field Type Description

object

string

A string denoting the object type which is always conv_tag for the current resource.

url

string

The relative URL of the current resource which is always of the form /v1/vast-zones/{ZONE_ID}/conversion-tag.

data

array

The data object containing the conversion tag.

 

Returns a conv_tag object if the request succeeded, or an error if something went terribly wrong.


VAST Campaigns

Introduction

VAST campaigns are an effective way for you to organize your ads under an Advertiser for purposes of clarity and reporting.

The vast_campaign response object has the following fields.

Example Response

{
  "object": "vast_campaign",
  "self": "/v1/vast-campaigns/4449",
  "id": 4449,
  "name": "demo-account-zone",
  "advertiser": 123
}
AdButler\VASTCampaign JSON: {
  "object": "vast_campaign",
  "self": "/v1/vast-campaigns/4449",
  "id": 4449,
  "name": "demo-account-zone",
  "advertiser": 123
}
Field Type Description

object

string

A string denoting the object type which is always vast_campaign for the current resource.

self

string

The relative URL of the current resource which is always of the form /v1/vast-campaigns/{CAMPAIGN-ID}.

id

integer

The resource identifier (ID).

name

string

Name of the campaign.

advertiser

integer

The advertiser resource identifier (ID).

Create a VAST Campaign

Definition

POST https://api.adbutler.com/v1/vast-campaigns
\AdButler\VASTCampaign::create()
adbutler.vastCampaigns.create()

Example Request

curl "https://api.adbutler.com/v1/vast-campaigns" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{  
        "name": "demo-account-zone",
        "advertiser": 123
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTCampaign = \AdButler\VASTCampaign::create(array(
  "name" => "demo-account-zone",
  "advertiser" => 123
));

echo $vASTCampaign;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var postData = {
  "name": "demo-account-zone",
  "advertiser": 123
};

// using callbacks
adbutler.vastCampaigns.create(postData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastCampaigns.create(postData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "vast_campaign",
  "self": "/v1/vast-campaigns/4449",
  "id": 4449,
  "name": "demo-account-zone",
  "advertiser": 123
}
AdButler\VASTCampaign JSON: {
  "object": "vast_campaign",
  "self": "/v1/vast-campaigns/4449",
  "id": 4449,
  "name": "demo-account-zone",
  "advertiser": 123
}

Creates a new VAST campaign.

Field Type Description

name*

string

Name of the campaign.

advertiser

integer

The advertiser resource identifier (ID).

* = required field

Returns

Returns a vast_campaign object if the request succeeded, or an error if something went terribly wrong.

Retrieve a VAST Campaign

Definition

GET https://api.adbutler.com/v1/vast-campaigns/{CAMPAIGN-ID}
\AdButler\VASTCampaign::retrieve()
adbutler.vastCampaigns.retrieve()

Example Request

curl "https://api.adbutler.com/v1/vast-campaigns/4449" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTCampaign = \AdButler\VASTCampaign::retrieve( 4449 );

echo $vASTCampaign;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastCampaigns.read(4449, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastCampaigns.read(4449).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "vast_campaign",
  "self": "/v1/vast-campaigns/4449",
  "id": 4449,
  "name": "demo-account-zone",
  "advertiser": 123
}
AdButler\VASTCampaign JSON: {
  "object": "vast_campaign",
  "self": "/v1/vast-campaigns/4449",
  "id": 4449,
  "name": "demo-account-zone",
  "advertiser": 123
}

You can retrieve the information about an existing VAST campaign by giving the campaign ID that was returned in the VAST campaign object upon creation. You will see at the most 10 VAST campaigns in the response. You can change this default limit by appending ?limit=25 if you want this request to return 25 VAST campaigns.

Returns

Returns a vast_campaign object if the request succeeded, or an error if something went terribly wrong.

Update a VAST Campaign

Definition

PUT https://api.adbutler.com/v1/vast-campaigns/{CAMPAIGN-ID}
\AdButler\VASTCampaign->save()
adbutler.vastCampaigns.update()

Example Request

curl "https://api.adbutler.com/v1/vast-campaigns/4449" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{  
        "name": "demo-account-zone",
        "advertiser": 123
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTCampaign = \AdButler\VASTCampaign::retrieve( 4449 );

$vASTCampaign->name = "demo-account-zone";
$vASTCampaign->advertiser = 123;

$vASTCampaign->save();

echo $vASTCampaign;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var updateData = {
  "name": "demo-account-zone",
  "advertiser": 123
};

// using callbacks
adbutler.vastCampaigns.update(4449, updateData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastCampaigns.update(4449, updateData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "vast_campaign",
  "self": "/v1/vast-campaigns/4449",
  "id": 4449,
  "name": "demo-account-zone",
  "advertiser": 123
}
AdButler\VASTCampaign JSON: {
  "object": "vast_campaign",
  "self": "/v1/vast-campaigns/4449",
  "id": 4449,
  "name": "demo-account-zone",
  "advertiser": 123
}

You can update a specific VAST campaign by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the VAST campaign creation request.

Field Type Description

name

string

Name of the campaign.

advertiser

integer

The advertiser resource identifier (ID).

Returns

Returns a vast_campaign object if the request succeeded, or an error if something went terribly wrong.

Delete a VAST Campaign

Definition

DELETE https://api.adbutler.com/v1/vast-campaigns/{CAMPAIGN-ID}
\AdButler\VASTCampaign->delete()
adbutler.vastCampaigns.delete()

Example Request

curl "https://api.adbutler.com/v1/vast-campaigns/4449" \
  -H "Authorization: Basic {API_KEY}" \
  -X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTCampaign = \AdButler\VASTCampaign::retrieve( 4449 );
$vASTCampaign->delete();

echo $vASTCampaign;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastCampaigns.delete(4449, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastCampaigns.delete(4449).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "id": 4449,
  "delete": true
}
AdButler\VASTCampaign JSON: {
  "id": 4449,
  "delete": true
}

Permanently deletes a VAST campaign. if successful, this operation cannot be undone so be very sure when deleting one.

Returns

Returns a VAST campaign ID if the request succeeded, or an error if something went terribly wrong.

List all VAST campaigns

Definition

GET https://api.adbutler.com/v1/vast-campaigns
\AdButler\VASTCampaign::retrieveAll()
adbutler.vastCampaigns.list()

Example Request

curl "https://api.adbutler.com/v1/vast-campaigns?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTCampaign = \AdButler\VASTCampaign::retrieveAll(array(
  "limit" => 2
));

echo $vASTCampaign;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastCampaigns.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastCampaigns.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/vast-campaigns",
  "data": [
    {
      "object": "vast_campaign",
      "self": "/v1/vast-campaigns/4436",
      "id": 4436,
      "name": "demo-account-zone",
      "advertiser": 123
    },
    {
      "object": "vast_campaign",
      "self": "/v1/vast-campaigns/4435",
      "id": 4435,
      "name": "demo-account-zone",
      "advertiser": 123
    }
  ]
}
AdButler\VASTCampaign JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/vast-campaigns",
  "data": [
    {
      "object": "vast_campaign",
      "self": "/v1/vast-campaigns/4436",
      "id": 4436,
      "name": "demo-account-zone",
      "advertiser": 123
    },
    {
      "object": "vast_campaign",
      "self": "/v1/vast-campaigns/4435",
      "id": 4435,
      "name": "demo-account-zone",
      "advertiser": 123
    }
  ]
}

Returns a list of all the VAST campaigns. Most recent VAST campaigns appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is a vast_campaign object, and if no objects were found the list will be empty.

Retrieve VAST campaign conversion tag

Definition

GET https://api.adbutler.com/v1/vast-campaigns/{CAMPAIGN-ID}/conversion-tag
\AdButler\VASTCampaignConvTag::retrieve()
adbutler.vastCampaigns.conversionTag.retrieve()

Example Request

curl "https://api.adbutler.com/v1/vast-campaigns/ID/conversion-tag/4449" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTCampaignConvTag = \AdButler\VASTCampaignConvTag::retrieve( 4449 );

echo $vASTCampaignConvTag;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastCampaigns.conversionTag.read(4449, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastCampaigns.conversionTag.read(4449).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Retrieves an HTML tag which can be used to track conversions for the provided VAST campaign.

Query Parameters

Parameter Description

protocol

Whether to use http or https protocol when serving the advertisements. Use https only if you are using secure pages because it does not support Custom Domains.

Returns

Example Response

{
  "object": "conv_tag",
  "url": "/v1/vast-campaigns/4449/conversion-tag",
  "data": {
    "src": "https://servedbyadbutler.com.vm.test/vconvtrack.spark?MID=108607&vastCampaignID=4449",
    "html": "<img src='https://servedbyadbutler.com.vm.test/vconvtrack.spark?MID=108607&vastCampaignID=4449' width='1' height='1' border='0' />"
  }
}
AdButler\VASTCampaignConvTag JSON: {
  "object": "conv_tag",
  "url": "/v1/vast-campaigns/4449/conversion-tag",
  "data": {
    "src": "https://servedbyadbutler.com.vm.test/vconvtrack.spark?MID=108607&vastCampaignID=4449",
    "html": "<img src='https://servedbyadbutler.com.vm.test/vconvtrack.spark?MID=108607&vastCampaignID=4449' width='1' height='1' border='0' />"
  }
}
Field Type Description

object

string

A string denoting the object type which is always conv_tag for the current resource.

url

string

The relative URL of the current resource which is always of the form /v1/vast-campaigns/{CAMPAIGN_ID}/conversion-tag.

data

array

The data object containing the conversion tag.

 

Returns a conv_tag object if the request succeeded, or an error if something went terribly wrong.


VAST Campaign Assignments

Introduction

A VAST campaign assignment represents the relationship between a VAST banner and a VAST campaign.

The vast_campaign_assignment response object has the following fields.

Example Response

{
  "object": "vast_campaign_assignment",
  "self": "/v1/vast_campaign_assignments/7697",
  "id": 7697,
  "active": true,
  "banner": 2579,
  "campaign": 4449
}
AdButler\VASTCampaignAssignment JSON: {
  "object": "vast_campaign_assignment",
  "self": "/v1/vast_campaign_assignments/7697",
  "id": 7697,
  "active": true,
  "banner": 2579,
  "campaign": 4449
}
Field Type Description

object

string

A string denoting the object type which is always vast_campaign_assignment for the current resource.

self

string

The relative URL of the current resource which is always of the form /v1/vast-campaign‑assignments/{CAMPAIGN_ASSIGNMENT_ID}.

id

integer

The current resource identifier (ID).

active

boolean

The status of ad serving whether it is being served in the given zone or not.

banner

integer

The VAST banner resource identifier (ID).

campaign

integer

The VAST campaign resource identifier (ID).

Create a VAST campaign assignment

Definition

POST https://api.adbutler.com/v1/vast-campaign-assignments
\AdButler\VASTCampaignAssignment::create()
adbutler.vastCampaignAssignments.create()

Example Request

curl "https://api.adbutler.com/v1/vast-campaign-assignments" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{  
        "active": true,
        "banner": 2579,
        "campaign": 4449
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTCampaignAssignment = \AdButler\VASTCampaignAssignment::create(array(
  "active" => true,
  "banner" => 2579,
  "campaign" => 4449
));

echo $vASTCampaignAssignment;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var postData = {
  "active": true,
  "banner": 2579,
  "campaign": 4449
};

// using callbacks
adbutler.vastCampaignAssignments.create(postData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastCampaignAssignments.create(postData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "vast_campaign_assignment",
  "self": "/v1/vast_campaign_assignments/7697",
  "id": 7697,
  "active": true,
  "banner": 2579,
  "campaign": 4449
}
AdButler\VASTCampaignAssignment JSON: {
  "object": "vast_campaign_assignment",
  "self": "/v1/vast_campaign_assignments/7697",
  "id": 7697,
  "active": true,
  "banner": 2579,
  "campaign": 4449
}

Creates a new VAST campaign assignment.

Field Type Description

campaign*

integer

The VAST campaign resource identifier (ID).

banner*

integer

The VAST banner resource identifier (ID).

active

boolean

Whether to actively serve ads in the zones (true) or pause ad serving (false). Defaults to true.

* = required field

Returns

Returns a vast_campaign_assignment object if the request succeeded, or an error if something went terribly wrong.

Retrieve a VAST campaign assignment

Definition

GET https://api.adbutler.com/v1/vast-campaign-assignments/{CAMPAIGN-ASSIGNMENT-ID}
\AdButler\VASTCampaignAssignment::retrieve()
adbutler.vastCampaignAssignments.retrieve()

Example Request

curl "https://api.adbutler.com/v1/vast-campaign-assignments/7697" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTCampaignAssignment = \AdButler\VASTCampaignAssignment::retrieve( 7697 );

echo $vASTCampaignAssignment;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastCampaignAssignments.read(7697, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastCampaignAssignments.read(7697).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "vast_campaign_assignment",
  "self": "/v1/vast_campaign_assignments/7697",
  "id": 7697,
  "active": true,
  "banner": 2579,
  "campaign": 4449
}
AdButler\VASTCampaignAssignment JSON: {
  "object": "vast_campaign_assignment",
  "self": "/v1/vast_campaign_assignments/7697",
  "id": 7697,
  "active": true,
  "banner": 2579,
  "campaign": 4449
}

You can retrieve the information about an existing VAST campaign assignment by giving the VAST campaign assignment ID that was returned in the vast_campaign_assignment object upon creation. You will see at the most 10 VAST campaign assignments in the response. You can change this default limit by appending ?limit=25 if you want this request to return 25 campaign assignments.

Returns

Returns a vast_campaign_assignment object if the request succeeded, or an error if something went terribly wrong.

Update a VAST campaign assignment

Definition

PUT https://api.adbutler.com/v1/vast-campaign-assignments/{CAMPAIGN-ASSIGNMENT-ID}
\AdButler\VASTCampaignAssignment->save()
adbutler.vastCampaignAssignments.update()

Example Request

curl "https://api.adbutler.com/v1/vast-campaign-assignments/7697" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{  
        "active": true,
        "banner": 2579,
        "campaign": 4449
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTCampaignAssignment = \AdButler\VASTCampaignAssignment::retrieve( 7697 );

$vASTCampaignAssignment->active = true;
$vASTCampaignAssignment->banner = 2579;
$vASTCampaignAssignment->campaign = 4449;

$vASTCampaignAssignment->save();

echo $vASTCampaignAssignment;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var updateData = {
  "active": true,
  "banner": 2579,
  "campaign": 4449
};

// using callbacks
adbutler.vastCampaignAssignments.update(7697, updateData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastCampaignAssignments.update(7697, updateData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "vast_campaign_assignment",
  "self": "/v1/vast_campaign_assignments/7697",
  "id": 7697,
  "active": true,
  "banner": 2579,
  "campaign": 4449
}
AdButler\VASTCampaignAssignment JSON: {
  "object": "vast_campaign_assignment",
  "self": "/v1/vast_campaign_assignments/7697",
  "id": 7697,
  "active": true,
  "banner": 2579,
  "campaign": 4449
}

You can update a specific VAST campaign assignment by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the campaign assignment creation request.

Field Type Description

campaign

integer

The VAST campaign resource identifier (ID).

banner

integer

The VAST banner resource identifier (ID).

active

boolean

Whether to actively serve ads in the zones (true) or pause ad serving (false). Defaults to true.

Returns

Returns a vast_campaign_assignment object if the request succeeded, or an error if something went terribly wrong.

Delete a VAST campaign assignment

Definition

DELETE https://api.adbutler.com/v1/vast-campaign-assignments/{CAMPAIGN-ASSIGNMENT-ID}
\AdButler\VASTCampaignAssignment->delete()
adbutler.vastCampaignAssignments.delete()

Example Request

curl "https://api.adbutler.com/v1/vast-campaign-assignments/7697" \
  -H "Authorization: Basic {API_KEY}" \
  -X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTCampaignAssignment = \AdButler\VASTCampaignAssignment::retrieve( 7697 );
$vASTCampaignAssignment->delete();

echo $vASTCampaignAssignment;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastCampaignAssignments.delete(7697, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastCampaignAssignments.delete(7697).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "id": 7697,
  "delete": true
}
AdButler\VASTCampaignAssignment JSON: {
  "id": 7697,
  "delete": true
}

Permanently deletes a VAST campaign assignment. If successful, this operation cannot be undone so be very sure when deleting one.

Returns

Returns a vast_campaign_assignment ID if the request succeeded, or an error if something went terribly wrong.

List all VAST campaign assignments

Definition

GET https://api.adbutler.com/v1/vast-campaign-assignments
\AdButler\VASTCampaignAssignment::retrieveAll()
adbutler.vastCampaignAssignments.list()

Example Request

curl "https://api.adbutler.com/v1/vast-campaign-assignments?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTCampaignAssignment = \AdButler\VASTCampaignAssignment::retrieveAll(array(
  "limit" => 2
));

echo $vASTCampaignAssignment;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastCampaignAssignments.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastCampaignAssignments.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/vast-campaign-assignments",
  "data": [
    {
      "object": "vast_campaign_assignment",
      "self": "/v1/vast_campaign_assignments/7692",
      "id": 7692,
      "active": true,
      "banner": 2576,
      "campaign": 4447
    },
    {
      "object": "vast_campaign_assignment",
      "self": "/v1/vast_campaign_assignments/7695",
      "id": 7695,
      "active": true,
      "banner": 2578,
      "campaign": 4448
    }
  ]
}
AdButler\VASTCampaignAssignment JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/vast-campaign-assignments",
  "data": [
    {
      "object": "vast_campaign_assignment",
      "self": "/v1/vast_campaign_assignments/7692",
      "id": 7692,
      "active": true,
      "banner": 2576,
      "campaign": 4447
    },
    {
      "object": "vast_campaign_assignment",
      "self": "/v1/vast_campaign_assignments/7695",
      "id": 7695,
      "active": true,
      "banner": 2578,
      "campaign": 4448
    }
  ]
}

Returns a list of all the VAST campaign assignments. Most recent campaign assignments appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is a vast_campaign_assignment object, and if no objects were found the list will be empty.


VAST Channels

Introduction

VAST channels provide an easy way to assign your VAST campaigns to multiple zones usually having a particular focus and perhaps owned by different publishers. This is desirable when a campaign with the same assignment settings is to be assigned to a large number of zones.

The vast_channel response object has the following fields.

Example Response

{
  "object": "vast_channel",
  "self": "/v1/vast-channels/1053",
  "id": 1053,
  "name": "demo-account-zone",
  "priority": "standard",
  "vast_zones": [
    {
      "id": 85772,
      "name": "demo-account-zone",
      "type": "VAST Zone"
    }
  ]
}
AdButler\VASTChannel JSON: {
  "object": "vast_channel",
  "self": "/v1/vast-channels/1053",
  "id": 1053,
  "name": "demo-account-zone",
  "priority": "standard",
  "vast_zones": [
    {
      "id": 85772,
      "name": "demo-account-zone",
      "type": "VAST Zone"
    }
  ]
}
Field Type Description

object

string

A string denoting the object type which is always vast_channel for the current resource.

self

string

The relative URL of the current resource which is always of the form /v1/vast-channels/{CHANNEL_ID}.

id

integer

The resource identifier (ID).

name

string

Name of the channel.

priority

string

Priority allows you to prefer serving of some ads over others in a channel.

Possible values in descending order are "sponsorship", "standard", "network", "bulk" and "house". Defaults to "standard".

vast_zones

array

An array of VAST zones assigned to the current resource.

Create a VAST Channel

Definition

POST https://api.adbutler.com/v1/vast-channels
\AdButler\VASTChannel::create()
adbutler.vastChannels.create()

Example Request

curl "https://api.adbutler.com/v1/vast-channels" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{  
        "name": "demo-account-zone",
        "priority": "standard",
        "vast_zones": [
                {
                        id: 85772,
                        name: "demo-account-zone",
                        type: "VAST Zone"
                }
        ]
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTChannel = \AdButler\VASTChannel::create(array(
  "name" => "demo-account-zone",
  "priority" => "standard",
  "vast_zones" => [
    [
      id => 85772,
      name => "demo-account-zone",
      type => "VAST Zone"
    ]
  ]
));

echo $vASTChannel;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var postData = {
  "name": "demo-account-zone",
  "priority": "standard",
  "vast_zones": [
    {
      id: 85772,
      name: "demo-account-zone",
      type: "VAST Zone"
    }
  ]
};

// using callbacks
adbutler.vastChannels.create(postData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastChannels.create(postData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "vast_channel",
  "self": "/v1/vast-channels/1053",
  "id": 1053,
  "name": "demo-account-zone",
  "priority": "standard",
  "vast_zones": [
    {
      "id": 85772,
      "name": "demo-account-zone",
      "type": "VAST Zone"
    }
  ]
}
AdButler\VASTChannel JSON: {
  "object": "vast_channel",
  "self": "/v1/vast-channels/1053",
  "id": 1053,
  "name": "demo-account-zone",
  "priority": "standard",
  "vast_zones": [
    {
      "id": 85772,
      "name": "demo-account-zone",
      "type": "VAST Zone"
    }
  ]
}

Creates a new VAST Channel.

Field Type Description

name*

string

Name of the channel.

priority

string

Priority allows you to prefer serving of some ads over others in a channel.

Possible values in descending order are "sponsorship", "standard", "network", "bulk" and "house". Defaults to "standard".

* = required field

Returns

Returns a vast_channel object if the request succeeded, or an error if something went terribly wrong.

Retrieve a VAST Channel

Definition

GET https://api.adbutler.com/v1/vast-channels/{CHANNEL-ID}
\AdButler\VASTChannel::retrieve()
adbutler.vastChannels.retrieve()

Example Request

curl "https://api.adbutler.com/v1/vast-channels/1053" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTChannel = \AdButler\VASTChannel::retrieve( 1053 );

echo $vASTChannel;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastChannels.read(1053, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastChannels.read(1053).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "vast_channel",
  "self": "/v1/vast-channels/1053",
  "id": 1053,
  "name": "demo-account-zone",
  "priority": "standard",
  "vast_zones": [
    {
      "id": 85772,
      "name": "demo-account-zone",
      "type": "VAST Zone"
    }
  ]
}
AdButler\VASTChannel JSON: {
  "object": "vast_channel",
  "self": "/v1/vast-channels/1053",
  "id": 1053,
  "name": "demo-account-zone",
  "priority": "standard",
  "vast_zones": [
    {
      "id": 85772,
      "name": "demo-account-zone",
      "type": "VAST Zone"
    }
  ]
}

You can retrieve the information about an existing VAST channel by giving the channel ID that was returned in the VAST channel object upon creation. You will see at the most 10 VAST channels in the response. You can change this default limit by appending ?limit=25 if you want this request to return 25 VAST channels.

Returns

Returns a vast_channel object if the request succeeded, or an error if something went terribly wrong.

Update a VAST Channel

Definition

PUT https://api.adbutler.com/v1/vast-channels/{CHANNEL-ID}
\AdButler\VASTChannel->save()
adbutler.vastChannels.update()

Example Request

curl "https://api.adbutler.com/v1/vast-channels/1053" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{  
        "name": "demo-account-zone",
        "priority": "standard",
        "vast_zones": [
                {
                        id: 85772,
                        name: "demo-account-zone",
                        type: "VAST Zone"
                }
        ]
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTChannel = \AdButler\VASTChannel::retrieve( 1053 );

$vASTChannel->name = "demo-account-zone";
$vASTChannel->priority = "standard";
$vASTChannel->vast_zones = [
[
id = 85772,
name = "demo-account-zone",
type = "VAST Zone"
]
];

$vASTChannel->save();

echo $vASTChannel;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var updateData = {
  "name": "demo-account-zone",
  "priority": "standard",
  "vast_zones": [
    {
      id: 85772,
      name: "demo-account-zone",
      type: "VAST Zone"
    }
  ]
};

// using callbacks
adbutler.vastChannels.update(1053, updateData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastChannels.update(1053, updateData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "vast_channel",
  "self": "/v1/vast-channels/1053",
  "id": 1053,
  "name": "demo-account-zone",
  "priority": "standard",
  "vast_zones": [
    {
      "id": 85772,
      "name": "demo-account-zone",
      "type": "VAST Zone"
    }
  ]
}
AdButler\VASTChannel JSON: {
  "object": "vast_channel",
  "self": "/v1/vast-channels/1053",
  "id": 1053,
  "name": "demo-account-zone",
  "priority": "standard",
  "vast_zones": [
    {
      "id": 85772,
      "name": "demo-account-zone",
      "type": "VAST Zone"
    }
  ]
}

You can update a specific VAST channel by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the VAST channel creation request.

Field Type Description

name

string

Name of the channel.

priority

string

Priority allows you to prefer serving of some ads over others in a channel.

Possible values in descending order are "sponsorship", "standard", "network", "bulk" and "house". Defaults to "standard".

Returns

Returns a vast_channel object if the request succeeded, or an error if something went terribly wrong.

Delete a VAST Channel

Definition

DELETE https://api.adbutler.com/v1/vast-channels/{CHANNEL-ID}
\AdButler\VASTChannel->delete()
adbutler.vastChannels.delete()

Example Request

curl "https://api.adbutler.com/v1/vast-channels/1053" \
  -H "Authorization: Basic {API_KEY}" \
  -X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTChannel = \AdButler\VASTChannel::retrieve( 1053 );
$vASTChannel->delete();

echo $vASTChannel;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastChannels.delete(1053, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastChannels.delete(1053).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "id": 1053,
  "delete": true
}
AdButler\VASTChannel JSON: {
  "id": 1053,
  "delete": true
}

Permanently deletes a VAST channel. if successful, this operation cannot be undone so be very sure when deleting one.

Returns

Returns a VAST channel ID if the request succeeded, or an error if something went terribly wrong.

List all VAST Channels

Definition

GET https://api.adbutler.com/v1/vast-channels
\AdButler\VASTChannel::retrieveAll()
adbutler.vastChannels.list()

Example Request

curl "https://api.adbutler.com/v1/vast-channels?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTChannel = \AdButler\VASTChannel::retrieveAll(array(
  "limit" => 2
));

echo $vASTChannel;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastChannels.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastChannels.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/vast-channels",
  "data": [
    {
      "object": "vast_channel",
      "self": "/v1/vast-channels/1042",
      "id": 1042,
      "name": "demo-account-zone",
      "priority": "standard",
      "vast_zones": [
        {
          "id": 85756,
          "name": "demo-account-zone",
          "type": "VAST Zone"
        }
      ]
    },
    {
      "object": "vast_channel",
      "self": "/v1/vast-channels/1043",
      "id": 1043,
      "name": "demo-account-zone",
      "priority": "standard",
      "vast_zones": [
        {
          "id": 85757,
          "name": "demo-account-zone",
          "type": "VAST Zone"
        }
      ]
    }
  ]
}
AdButler\VASTChannel JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/vast-channels",
  "data": [
    {
      "object": "vast_channel",
      "self": "/v1/vast-channels/1042",
      "id": 1042,
      "name": "demo-account-zone",
      "priority": "standard",
      "vast_zones": [
        {
          "id": 85756,
          "name": "demo-account-zone",
          "type": "VAST Zone"
        }
      ]
    },
    {
      "object": "vast_channel",
      "self": "/v1/vast-channels/1043",
      "id": 1043,
      "name": "demo-account-zone",
      "priority": "standard",
      "vast_zones": [
        {
          "id": 85757,
          "name": "demo-account-zone",
          "type": "VAST Zone"
        }
      ]
    }
  ]
}

Returns a list of all the VAST channels. Most recent VAST channels appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is a vast_channel object, and if no objects were found the list will be empty.


VAST Channel Zone Assignments

Introduction

A VAST channel zone assignment represents the relationship between a VAST channel and a VAST zone.

The vast_channel_zone_assignment response object has the following fields.

Example Response

{
  "object": "vast_channel_zone_assignment",
  "self": "/v1/vast-channel-zone-assignments/58",
  "id": 58,
  "vast_channel": 1053,
  "vast_zone": {
    "id": 85772,
    "type": "VAST Zone"
  }
}
AdButler\VASTChannelZoneAssignment JSON: {
  "object": "vast_channel_zone_assignment",
  "self": "/v1/vast-channel-zone-assignments/58",
  "id": 58,
  "vast_channel": 1053,
  "vast_zone": {
    "id": 85772,
    "type": "VAST Zone"
  }
}
Field Type Description

object

string

A string denoting the object type which is always vast_channel_zone_assignment for the current resource.

self

string

The relative URL of the current resource which is always of the form /v1/vast-channel-zone-assignments/{CHANNEL-ZONE-ASSIGNMENT-ID}.

id

integer

The resource identifier (ID).

vast_channel

integer

The VAST channel identifier (ID) that you want the zone assigned to.

vast_zone

object

An object containing a VAST zone identifier (ID) and type.

Create a VAST Channel Zone Assignment

Definition

POST https://api.adbutler.com/v1/vast-channel-zone-assignments
\AdButler\VASTChannelZoneAssignment::create()
adbutler.vastChannelZoneAssignments.create()

Example Request

curl "https://api.adbutler.com/v1/vast-channel-zone-assignments" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{  

      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTChannelZoneAssignment = \AdButler\VASTChannelZoneAssignment::create(array(

));

echo $vASTChannelZoneAssignment;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var postData = {

};

// using callbacks
adbutler.vastChannelZoneAssignments.create(postData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastChannelZoneAssignments.create(postData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "vast_channel_zone_assignment",
  "self": "/v1/vast-channel-zone-assignments/58",
  "id": 58,
  "vast_channel": 1053,
  "vast_zone": {
    "id": 85772,
    "type": "VAST Zone"
  }
}
AdButler\VASTChannelZoneAssignment JSON: {
  "object": "vast_channel_zone_assignment",
  "self": "/v1/vast-channel-zone-assignments/58",
  "id": 58,
  "vast_channel": 1053,
  "vast_zone": {
    "id": 85772,
    "type": "VAST Zone"
  }
}

Creates a new VAST Channel Zone Assignment.

Field Type Description

vast_channel*

integer

The VAST channel identifier (ID) that you want the zone assigned to.

vast_zone*

object

An object containing a VAST zone identifier (ID) and type.

* = required field

Returns

Returns a vast_channel_zone_assignment object if the request succeeded, or an error if something went terribly wrong.

Retrieve a VAST Channel Zone Assignment

Definition

GET https://api.adbutler.com/v1/vast-channel-zone-assignments/{CHANNEL-ZONE-ASSIGNMENT-ID}
\AdButler\VASTChannelZoneAssignment::retrieve()
adbutler.vastChannelZoneAssignments.retrieve()

Example Request

curl "https://api.adbutler.com/v1/vast-channel-zone-assignments/58" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTChannelZoneAssignment = \AdButler\VASTChannelZoneAssignment::retrieve( 58 );

echo $vASTChannelZoneAssignment;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastChannelZoneAssignments.read(58, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastChannelZoneAssignments.read(58).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "vast_channel_zone_assignment",
  "self": "/v1/vast-channel-zone-assignments/58",
  "id": 58,
  "vast_channel": 1053,
  "vast_zone": {
    "id": 85772,
    "type": "VAST Zone"
  }
}
AdButler\VASTChannelZoneAssignment JSON: {
  "object": "vast_channel_zone_assignment",
  "self": "/v1/vast-channel-zone-assignments/58",
  "id": 58,
  "vast_channel": 1053,
  "vast_zone": {
    "id": 85772,
    "type": "VAST Zone"
  }
}

You can retrieve the information about an existing VAST channel assignment by giving the channel zone assignment ID that was returned in the VAST channel object upon creation. You will see at the most 10 VAST channel-zone-assignments in the response. You can change this default limit by appending ?limit=25 if you want this request to return 25 VAST channel-zone-assignments.

Returns

Returns a vast_channel_zone_assignment object if the request succeeded, or an error if something went terribly wrong.

Update a VAST Channel Zone Assignment

Definition

PUT https://api.adbutler.com/v1/vast-channel-zone-assignments/{CHANNEL-ZONE-ASSIGNMENT-ID}
\AdButler\VASTChannelZoneAssignment->save()
adbutler.vastChannelZoneAssignments.update()

Example Request

curl "https://api.adbutler.com/v1/vast-channel-zone-assignments/58" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{  

      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTChannelZoneAssignment = \AdButler\VASTChannelZoneAssignment::retrieve( 58 );



$vASTChannelZoneAssignment->save();

echo $vASTChannelZoneAssignment;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var updateData = {

};

// using callbacks
adbutler.vastChannelZoneAssignments.update(58, updateData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastChannelZoneAssignments.update(58, updateData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "vast_channel_zone_assignment",
  "self": "/v1/vast-channel-zone-assignments/58",
  "id": 58,
  "vast_channel": 1053,
  "vast_zone": {
    "id": 85772,
    "type": "VAST Zone"
  }
}
AdButler\VASTChannelZoneAssignment JSON: {
  "object": "vast_channel_zone_assignment",
  "self": "/v1/vast-channel-zone-assignments/58",
  "id": 58,
  "vast_channel": 1053,
  "vast_zone": {
    "id": 85772,
    "type": "VAST Zone"
  }
}

You can update a specific VAST channel zone assignment by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the VAST channel zone assignment creation request.

Field Type Description

vast_channel

integer

The VAST channel identifier (ID) that you want the zone assigned to.

vast_zone

object

An object containing a VAST zone identifier (ID) and type.

Returns

Returns a vast_channel_zone_assignment object if the request succeeded, or an error if something went terribly wrong.

Delete a VAST Channel Zone Assignment

Definition

DELETE https://api.adbutler.com/v1/vast-channel-zone-assignments/{CHANNEL-ZONE-ASSIGNMENT-ID}
\AdButler\VASTChannelZoneAssignment->delete()
adbutler.vastChannelZoneAssignments.delete()

Example Request

curl "https://api.adbutler.com/v1/vast-channel-zone-assignments/58" \
  -H "Authorization: Basic {API_KEY}" \
  -X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTChannelZoneAssignment = \AdButler\VASTChannelZoneAssignment::retrieve( 58 );
$vASTChannelZoneAssignment->delete();

echo $vASTChannelZoneAssignment;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastChannelZoneAssignments.delete(58, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastChannelZoneAssignments.delete(58).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "id": 58,
  "delete": true
}
AdButler\VASTChannelZoneAssignment JSON: {
  "id": 58,
  "delete": true
}

Permanently deletes a VAST channel zone assignment. if successful, this operation cannot be undone so be very sure when deleting one.

Returns

Returns a VAST channel zone assignment ID if the request succeeded, or an error if something went terribly wrong.

List all VAST Channel Zone Assignments

Definition

GET https://api.adbutler.com/v1/vast-channel-zone-assignments
\AdButler\VASTChannelZoneAssignment::retrieveAll()
adbutler.vastChannelZoneAssignments.list()

Example Request

curl "https://api.adbutler.com/v1/vast-channel-zone-assignments?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTChannelZoneAssignment = \AdButler\VASTChannelZoneAssignment::retrieveAll(array(
  "limit" => 2
));

echo $vASTChannelZoneAssignment;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastChannelZoneAssignments.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastChannelZoneAssignments.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/vast-channel-zone-assignments",
  "data": [
    {
      "object": "vast_channel_zone_assignment",
      "self": "/v1/vast-channel-zone-assignments/45",
      "id": 45,
      "vast_channel": 1042,
      "vast_zone": {
        "id": 85756,
        "type": "VAST Zone"
      }
    },
    {
      "object": "vast_channel_zone_assignment",
      "self": "/v1/vast-channel-zone-assignments/46",
      "id": 46,
      "vast_channel": 1043,
      "vast_zone": {
        "id": 85757,
        "type": "VAST Zone"
      }
    }
  ]
}
AdButler\VASTChannelZoneAssignment JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/vast-channel-zone-assignments",
  "data": [
    {
      "object": "vast_channel_zone_assignment",
      "self": "/v1/vast-channel-zone-assignments/45",
      "id": 45,
      "vast_channel": 1042,
      "vast_zone": {
        "id": 85756,
        "type": "VAST Zone"
      }
    },
    {
      "object": "vast_channel_zone_assignment",
      "self": "/v1/vast-channel-zone-assignments/46",
      "id": 46,
      "vast_channel": 1043,
      "vast_zone": {
        "id": 85757,
        "type": "VAST Zone"
      }
    }
  ]
}

Returns a list of all the VAST channel zone assignments. Most recent VAST channel zone assignments appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is a vast_channel_zone_assignment object, and if no objects were found the list will be empty.


VAST Companions

Introduction

A VAST companion is a display banner that will be rendered in a container that is connected to the video player, usually close by. A VAST companion is part of a VAST banner just like a linear or non-linear ad and is usually related to the content of the main creative.

The vast_companion response object has the following fields.

Example Response

{
  "object": "vast_companion",
  "self": "/v1/vast_companions/1416",
  "id": 1416,
  "banner": 2579,
  "resource_type": "static",
  "type": "image/png",
  "width": 100,
  "height": 100,
  "asset_width": 0,
  "asset_height": 0,
  "scalable": false,
  "expanded_width": 0,
  "expanded_height": 0,
  "api_framework": null,
  "content": null,
  "alt_text": null,
  "dom_element_id": null,
  "sequence": "1",
  "creative": 0,
  "location": null,
  "encode_parameters": "none",
  "ad_parameters": null
}
AdButler\VASTCompanion JSON: {
  "object": "vast_companion",
  "self": "/v1/vast_companions/1416",
  "id": 1416,
  "banner": 2579,
  "resource_type": "static",
  "type": "image/png",
  "width": 100,
  "height": 100,
  "asset_width": 0,
  "asset_height": 0,
  "scalable": false,
  "expanded_width": 0,
  "expanded_height": 0,
  "api_framework": null,
  "content": null,
  "alt_text": null,
  "dom_element_id": null,
  "sequence": 1,
  "creative": 0,
  "location": null,
  "encode_parameters": "none",
  "ad_parameters": null
}
Field Type Description

object

string

A string denoting the object type which is always vast_companion for the current resource.

self

string

The relative URL of the current resource which is always of the form /v1/vast-companions/{COMPANION-ID}.

id

integer

The resource identifier (ID).

banner

integer

The ID of the VAST banner, for which this is a companion.

resource_type

string

The type of resource. One of : "static", "iframe", or "html".

type

string

MIME type of the resource.

width

integer

The width, in pixels, of the ad slot for which the companion ad is intended.

height

integer

The height, in pixels, of the ad slot for which the companion ad is intended.

asset_width

integer

The width, in pixels, of the creative.

asset_height

integer

The height, in pixels, of the creative.

scalable

boolean

Whether the companion is scalable.

expanded_width

integer

The maximum pixel width of the creative in its expanded state.

expanded_height

integer

The maximum pixel height of the creative in its expanded state.

api_framework

string

The API necessary to communicate with the creative, if available.

content

string

If resource_type is "static", this would be a URL that points to where the creative is hosted. Otherwise, this is the code that will be rendered as the content for the creative.

alt_text

string

Alt text of the resource.

dom_element_id

string

The HTML DOM element ID where the creative will be served.

sequence

integer

The sequence number of the companion. An integer between 1 and 5.

creative

integer

The image creative identifier (ID).

location

string

A URL indicating where you want the user to go when they click on the banner. This field can be left blank.

ad_parameters

string

Custom parameters for executable media or API frameworks.

encode_parameters

integer

How the ad_parameters field has been escaped. One of: "none", "xml", "xml_reencode".

Create a VAST Companion

Definition

POST https://api.adbutler.com/v1/vast-companions
\AdButler\VASTCompanion::create()
adbutler.vastCompanions.create()

Example Request

curl "https://api.adbutler.com/v1/vast-companions" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{  
        "resource_type": "static",
        "type": "image/png",
        "width": 100,
        "height": 100,
        "sequence": "1"
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTCompanion = \AdButler\VASTCompanion::create(array(
  "resource_type" => "static",
  "type" => "image/png",
  "width" => 100,
  "height" => 100,
  "sequence" => "1"
));

echo $vASTCompanion;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var postData = {
  "resource_type": "static",
  "type": "image/png",
  "width": 100,
  "height": 100,
  "sequence": "1"
};

// using callbacks
adbutler.vastCompanions.create(postData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastCompanions.create(postData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "vast_companion",
  "self": "/v1/vast_companions/1416",
  "id": 1416,
  "banner": 2579,
  "resource_type": "static",
  "type": "image/png",
  "width": 100,
  "height": 100,
  "asset_width": 0,
  "asset_height": 0,
  "scalable": false,
  "expanded_width": 0,
  "expanded_height": 0,
  "api_framework": null,
  "content": null,
  "alt_text": null,
  "dom_element_id": null,
  "sequence": "1",
  "creative": 0,
  "location": null,
  "encode_parameters": "none",
  "ad_parameters": null
}
AdButler\VASTCompanion JSON: {
  "object": "vast_companion",
  "self": "/v1/vast_companions/1416",
  "id": 1416,
  "banner": 2579,
  "resource_type": "static",
  "type": "image/png",
  "width": 100,
  "height": 100,
  "asset_width": 0,
  "asset_height": 0,
  "scalable": false,
  "expanded_width": 0,
  "expanded_height": 0,
  "api_framework": null,
  "content": null,
  "alt_text": null,
  "dom_element_id": null,
  "sequence": 1,
  "creative": 0,
  "location": null,
  "encode_parameters": "none",
  "ad_parameters": null
}

Creates a new VAST Companion.

Field Type Description

banner*

integer

The ID of the VAST banner, for which this is a companion.

resource_type*

string

The type of resource. One of : "static", "iframe", or "html".

type*

string

MIME type of the resource.

width*

integer

The width, in pixels, of the ad slot for which the companion ad is intended.

height*

integer

The height, in pixels, of the ad slot for which the companion ad is intended.

sequence*

integer

The sequence number of the companion. An integer between 1 and 5.

scalable

integer

The height, in pixels, of the ad slot for which the companion ad is intended.

expanded_width

integer

The maximum pixel width of the creative in its expanded state.

expanded_height

integer

The maximum pixel height of the creative in its expanded state.

api_framework

string

The API necessary to communicate with the creative, if available.

content

string

If resource_type is "static", this would be a URL that points to where the creative is hosted. Otherwise, this is the code that will be rendered as the content for the creative.

alt_text

string

Alt text of the resource.

dom_element_id

string

The HTML DOM element ID where the creative will be served.

creative

integer

The image creative identifier (ID).

location

string

A URL indicating where you want the user to go when they click on the banner. This field can be left blank.

ad_parameters

string

Custom parameters for executable media or API frameworks.

encode_parameters

integer

How the ad_parameters field has been escaped. One of: "none", "xml", "xml_reencode".

* = required field

Returns

Returns a vast_companion object if the request succeeded, or an error if something went terribly wrong.

Retrieve a VAST Companion

Definition

GET https://api.adbutler.com/v1/vast-companions/{COMPANION-ID}
\AdButler\VASTCompanion::retrieve()
adbutler.vastCompanions.retrieve()

Example Request

curl "https://api.adbutler.com/v1/vast-companions/1416" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTCompanion = \AdButler\VASTCompanion::retrieve( 1416 );

echo $vASTCompanion;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastCompanions.read(1416, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastCompanions.read(1416).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "vast_companion",
  "self": "/v1/vast_companions/1416",
  "id": 1416,
  "banner": 2579,
  "resource_type": "static",
  "type": "image/png",
  "width": 100,
  "height": 100,
  "asset_width": 0,
  "asset_height": 0,
  "scalable": false,
  "expanded_width": 0,
  "expanded_height": 0,
  "api_framework": null,
  "content": null,
  "alt_text": null,
  "dom_element_id": null,
  "sequence": "1",
  "creative": 0,
  "location": null,
  "encode_parameters": "none",
  "ad_parameters": null
}
AdButler\VASTCompanion JSON: {
  "object": "vast_companion",
  "self": "/v1/vast_companions/1416",
  "id": 1416,
  "banner": 2579,
  "resource_type": "static",
  "type": "image/png",
  "width": 100,
  "height": 100,
  "asset_width": 0,
  "asset_height": 0,
  "scalable": false,
  "expanded_width": 0,
  "expanded_height": 0,
  "api_framework": null,
  "content": null,
  "alt_text": null,
  "dom_element_id": null,
  "sequence": 1,
  "creative": 0,
  "location": null,
  "encode_parameters": "none",
  "ad_parameters": null
}

You can retrieve the information about an existing VAST companion by giving the companion ID that was returned in the VAST companion object upon creation. You will see at the most 10 VAST companions in the response. You can change this default limit by appending ?limit=25 if you want this request to return 25 VAST companions.

Returns

Returns a vast_companion object if the request succeeded, or an error if something went terribly wrong.

Update a VAST Companion

Definition

PUT https://api.adbutler.com/v1/vast-companions/{COMPANION-ID}
\AdButler\VASTCompanion->save()
adbutler.vastCompanions.update()

Example Request

curl "https://api.adbutler.com/v1/vast-companions/1416" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{  
        "resource_type": "static",
        "type": "image/png",
        "width": 100,
        "height": 100,
        "sequence": "1"
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTCompanion = \AdButler\VASTCompanion::retrieve( 1416 );

$vASTCompanion->resource_type = "static";
$vASTCompanion->type = "image/png";
$vASTCompanion->width = 100;
$vASTCompanion->height = 100;
$vASTCompanion->sequence = "1";

$vASTCompanion->save();

echo $vASTCompanion;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var updateData = {
  "resource_type": "static",
  "type": "image/png",
  "width": 100,
  "height": 100,
  "sequence": "1"
};

// using callbacks
adbutler.vastCompanions.update(1416, updateData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastCompanions.update(1416, updateData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "vast_companion",
  "self": "/v1/vast_companions/1416",
  "id": 1416,
  "banner": 2579,
  "resource_type": "static",
  "type": "image/png",
  "width": 100,
  "height": 100,
  "asset_width": 0,
  "asset_height": 0,
  "scalable": false,
  "expanded_width": 0,
  "expanded_height": 0,
  "api_framework": null,
  "content": null,
  "alt_text": null,
  "dom_element_id": null,
  "sequence": "1",
  "creative": 0,
  "location": null,
  "encode_parameters": "none",
  "ad_parameters": null
}
AdButler\VASTCompanion JSON: {
  "object": "vast_companion",
  "self": "/v1/vast_companions/1416",
  "id": 1416,
  "banner": 2579,
  "resource_type": "static",
  "type": "image/png",
  "width": 100,
  "height": 100,
  "asset_width": 0,
  "asset_height": 0,
  "scalable": false,
  "expanded_width": 0,
  "expanded_height": 0,
  "api_framework": null,
  "content": null,
  "alt_text": null,
  "dom_element_id": null,
  "sequence": 1,
  "creative": 0,
  "location": null,
  "encode_parameters": "none",
  "ad_parameters": null
}

You can update a specific VAST companion by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the VAST companion creation request.

Field Type Description

banner

integer

The ID of the VAST banner, for which this is a companion.

resource_type

string

The type of resource. One of : "static", "iframe", or "html".

type

string

MIME type of the resource.

width

integer

The width, in pixels, of the ad slot for which the companion ad is intended.

height

integer

The height, in pixels, of the ad slot for which the companion ad is intended.

sequence

integer

The sequence number of the companion. An integer between 1 and 5.

scalable

integer

The height, in pixels, of the ad slot for which the companion ad is intended.

expanded_width

integer

The maximum pixel width of the creative in its expanded state.

expanded_height

integer

The maximum pixel height of the creative in its expanded state.

api_framework

string

The API necessary to communicate with the creative, if available.

content

string

If resource_type is "static", this would be a URL that points to where the creative is hosted. Otherwise, this is the code that will be rendered as the content for the creative.

alt_text

string

Alt text of the resource.

dom_element_id

string

The HTML DOM element ID where the creative will be served.

creative

integer

The image creative identifier (ID).

location

string

A URL indicating where you want the user to go when they click on the banner. This field can be left blank.

ad_parameters

string

Custom parameters for executable media or API frameworks.

encode_parameters

integer

How the ad_parameters field has been escaped. One of: "none", "xml", "xml_reencode".

Returns

Returns a vast_companion object if the request succeeded, or an error if something went terribly wrong.

Delete a VAST Companion

Definition

DELETE https://api.adbutler.com/v1/vast-companions/{COMPANION-ID}
\AdButler\VASTCompanion->delete()
adbutler.vastCompanions.delete()

Example Request

curl "https://api.adbutler.com/v1/vast-companions/1416" \
  -H "Authorization: Basic {API_KEY}" \
  -X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTCompanion = \AdButler\VASTCompanion::retrieve( 1416 );
$vASTCompanion->delete();

echo $vASTCompanion;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastCompanions.delete(1416, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastCompanions.delete(1416).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "id": 1416,
  "delete": true
}
AdButler\VASTCompanion JSON: {
  "id": 1416,
  "delete": true
}

Permanently deletes a VAST companion. if successful, this operation cannot be undone so be very sure when deleting one.

Returns

Returns a VAST companion ID if the request succeeded, or an error if something went terribly wrong.

List all VAST Companions

Definition

GET https://api.adbutler.com/v1/vast-companions
\AdButler\VASTCompanion::retrieveAll()
adbutler.vastCompanions.list()

Example Request

curl "https://api.adbutler.com/v1/vast-companions?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTCompanion = \AdButler\VASTCompanion::retrieveAll(array(
  "limit" => 2
));

echo $vASTCompanion;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastCompanions.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastCompanions.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/vast-companions",
  "data": [
    {
      "object": "vast_companion",
      "self": "/v1/vast_companions/1402",
      "id": 1402,
      "banner": 2553,
      "resource_type": "static",
      "type": "image/png",
      "width": 100,
      "height": 100,
      "asset_width": 0,
      "asset_height": 0,
      "scalable": false,
      "expanded_width": 0,
      "expanded_height": 0,
      "api_framework": null,
      "content": null,
      "alt_text": null,
      "dom_element_id": null,
      "sequence": "1",
      "creative": 0,
      "location": null,
      "encode_parameters": "none",
      "ad_parameters": null
    },
    {
      "object": "vast_companion",
      "self": "/v1/vast_companions/1403",
      "id": 1403,
      "banner": 2554,
      "resource_type": "static",
      "type": "image/png",
      "width": 100,
      "height": 100,
      "asset_width": 0,
      "asset_height": 0,
      "scalable": false,
      "expanded_width": 0,
      "expanded_height": 0,
      "api_framework": null,
      "content": null,
      "alt_text": null,
      "dom_element_id": null,
      "sequence": "1",
      "creative": 0,
      "location": null,
      "encode_parameters": "none",
      "ad_parameters": null
    }
  ]
}
AdButler\VASTCompanion JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/vast-companions",
  "data": [
    {
      "object": "vast_companion",
      "self": "/v1/vast_companions/1402",
      "id": 1402,
      "banner": 2553,
      "resource_type": "static",
      "type": "image/png",
      "width": 100,
      "height": 100,
      "asset_width": 0,
      "asset_height": 0,
      "scalable": false,
      "expanded_width": 0,
      "expanded_height": 0,
      "api_framework": null,
      "content": null,
      "alt_text": null,
      "dom_element_id": null,
      "sequence": 1,
      "creative": 0,
      "location": null,
      "encode_parameters": "none",
      "ad_parameters": null
    },
    {
      "object": "vast_companion",
      "self": "/v1/vast_companions/1403",
      "id": 1403,
      "banner": 2554,
      "resource_type": "static",
      "type": "image/png",
      "width": 100,
      "height": 100,
      "asset_width": 0,
      "asset_height": 0,
      "scalable": false,
      "expanded_width": 0,
      "expanded_height": 0,
      "api_framework": null,
      "content": null,
      "alt_text": null,
      "dom_element_id": null,
      "sequence": 1,
      "creative": 0,
      "location": null,
      "encode_parameters": "none",
      "ad_parameters": null
    }
  ]
}

Returns a list of all the VAST companions. Most recent VAST companions appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is a vast_companion object, and if no objects were found the list will be empty.


VAST Media

List all VAST Media

Definition

GET https://api.adbutler.com/v1/vast-medias
\AdButler\VASTMedia::retrieveAll()
adbutler.vastMedia.list()

Example Request

curl "https://api.adbutler.com/v1/vast-media?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTMedia = \AdButler\VASTMedia::retrieveAll(array(
  "limit" => 2
));

echo $vASTMedia;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastMedia.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastMedia.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/vast-media",
  "data": [
    {
      "object": "vast_media_non_linear",
      "self": "/v1/vast-media/non-linear/5964",
      "id": 5964,
      "banner": 2554,
      "type": null,
      "maintain_aspect_ratio": false,
      "is_linear": false,
      "creative": {
        "type": "image_url",
        "source": null
      },
      "scalable": false,
      "expanded_width": 0,
      "expanded_height": 0,
      "ad_parameters": null,
      "min_suggested_duration": 0,
      "width": 100,
      "height": 100,
      "encode_parameters": "none"
    },
    {
      "object": "vast_media_linear",
      "self": "/v1/vast-media/linear/5963",
      "id": 5963,
      "banner": 2554,
      "maintain_aspect_ratio": false,
      "is_linear": true,
      "creative": 0,
      "scalable": false,
      "delivery": "progressive",
      "codec": null,
      "api_framework": null,
      "min_bitrate": 0,
      "max_bitrate": 0,
      "creative_url": null,
      "width": 100,
      "height": 100,
      "type": null
    }
  ]
}
AdButler\VASTMedia JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/vast-media",
  "data": [
    {
      "object": "vast_media_non_linear",
      "self": "/v1/vast-media/non-linear/5964",
      "id": 5964,
      "banner": 2554,
      "type": null,
      "maintain_aspect_ratio": false,
      "is_linear": false,
      "creative": {
        "type": "image_url",
        "source": null
      },
      "scalable": false,
      "expanded_width": 0,
      "expanded_height": 0,
      "ad_parameters": null,
      "min_suggested_duration": 0,
      "width": 100,
      "height": 100,
      "encode_parameters": "none"
    },
    {
      "object": "vast_media_linear",
      "self": "/v1/vast-media/linear/5963",
      "id": 5963,
      "banner": 2554,
      "maintain_aspect_ratio": false,
      "is_linear": true,
      "creative": 0,
      "scalable": false,
      "delivery": "progressive",
      "codec": null,
      "api_framework": null,
      "min_bitrate": 0,
      "max_bitrate": 0,
      "creative_url": null,
      "width": 100,
      "height": 100,
      "type": null
    }
  ]
}

Returns a list of all the VAST medias. Most recent VAST medias appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is a vast-media object, and if no objects were found the list will be empty.


VAST Media Linear

Introduction

The VAST Linear Media object is a reference to a linear creative that will be served in a VAST Banner. A linear creative is one that is video-based and plays pre-roll, mid-roll or post-roll in relation to the video content.

The vast_media_linear response object has the following fields.

Example Response

{
  "object": "vast_media_linear",
  "self": "/v1/vast-media/linear/6015",
  "id": 6015,
  "banner": 2579,
  "maintain_aspect_ratio": false,
  "creative": 0,
  "scalable": false,
  "delivery": "progressive",
  "codec": null,
  "api_framework": null,
  "min_bitrate": 0,
  "max_bitrate": 0,
  "creative_url": null,
  "width": 100,
  "height": 100,
  "type": null
}
AdButler\VASTMediaLinear JSON: {
  "object": "vast_media_linear",
  "self": "/v1/vast-media/linear/6015",
  "id": 6015,
  "banner": 2579,
  "maintain_aspect_ratio": false,
  "creative": 0,
  "scalable": false,
  "delivery": "progressive",
  "codec": null,
  "api_framework": null,
  "min_bitrate": 0,
  "max_bitrate": 0,
  "creative_url": null,
  "width": 100,
  "height": 100,
  "type": null
}
Field Type Description

object

string

A string denoting the object type which is always vast-media for the current resource.

self

string

The relative URL of the current resource which is always of the form /v1/vast-medias/{MEDIA-ID}.

id

integer

The resource identifier (ID).

banner

string

The ID of the VAST banner that this object belongs to.

type

string

MIME type of the resource.

delivery

string

The method that the media is delivered. One of: "progressive" or "streaming".

width

integer

Width of the media.

height

integer

Height of the media.

scalable

boolean

Whether the video file can scale to a larger size.

maintain_aspect_ratio

boolean

Whether the video file will be forced to maintain it's native aspect ratio when scaled.

creative

integer

The video creative identifier (ID).

creative_url

string

The URL of a video file.

codec

string

The codec used to encode the file, as specific by RFC 4281.

min_bitrate

integer

The minimum bitrate for the file.

max_bitrate

integer

The maximum bitrate for the file.

api_framework

string

The API necessary to communicate with the creative, if available.

Create a VAST Linear Media

Definition

POST https://api.adbutler.com/v1/vast-media-linear
\AdButler\VASTMediaLinear::create()
adbutler.vastMedia.linear.create()

Example Request

curl "https://api.adbutler.com/v1/vast-media/linear" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{  
        "delivery": "progressive",
        "width": 100,
        "height": 100
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTMediaLinear = \AdButler\VASTMediaLinear::create(array(
  "delivery" => "progressive",
  "width" => 100,
  "height" => 100
));

echo $vASTMediaLinear;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var postData = {
  "delivery": "progressive",
  "width": 100,
  "height": 100
};

// using callbacks
adbutler.vastMedia.linear.create(postData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastMedia.linear.create(postData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "vast_media_linear",
  "self": "/v1/vast-media/linear/6015",
  "id": 6015,
  "banner": 2579,
  "maintain_aspect_ratio": false,
  "creative": 0,
  "scalable": false,
  "delivery": "progressive",
  "codec": null,
  "api_framework": null,
  "min_bitrate": 0,
  "max_bitrate": 0,
  "creative_url": null,
  "width": 100,
  "height": 100,
  "type": null
}
AdButler\VASTMediaLinear JSON: {
  "object": "vast_media_linear",
  "self": "/v1/vast-media/linear/6015",
  "id": 6015,
  "banner": 2579,
  "maintain_aspect_ratio": false,
  "creative": 0,
  "scalable": false,
  "delivery": "progressive",
  "codec": null,
  "api_framework": null,
  "min_bitrate": 0,
  "max_bitrate": 0,
  "creative_url": null,
  "width": 100,
  "height": 100,
  "type": null
}

Creates a new VAST Linear Media.

Field Type Description

banner*

string

The ID of the VAST banner that this object belongs to.

type

string

MIME type of the resource. Required if creative_url is given.

delivery*

string

The method that the media is delivered. One of: "progressive" or "streaming".

width

integer

Width of the media. Required if creative_url is given.

height

integer

Height of the media. Required if creative_url is given.

scalable

boolean

Whether the video file can scale to a larger size.

maintain_aspect_ratio

boolean

Whether the video file will be forced to maintain it's native aspect ratio when scaled.

creative

integer

The video creative identifier (ID). Must be a valid ID if no creative_url is given.

creative_url

string

The URL of a video file. creative must be given if this is left empty.

codec

string

The codec used to encode the file, as specific by RFC 4281.

min_bitrate

integer

The minimum bitrate for the file. Only include this field if creative_url is given.

max_bitrate

integer

The maximum bitrate for the file. Only include this field if creative_url is given.

api_framework

string

The API necessary to communicate with the creative, if available.

* = required field

Returns

Returns a vast-media-linear object if the request succeeded, or an error if something went terribly wrong.

Retrieve a VAST Linear Media

Definition

GET https://api.adbutler.com/v1/vast-media-linear/{MEDIA-ID}
\AdButler\VASTMediaLinear::retrieve()
adbutler.vastMedia.linear.retrieve()

Example Request

curl "https://api.adbutler.com/v1/vast-media/linear/6015" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTMediaLinear = \AdButler\VASTMediaLinear::retrieve( 6015 );

echo $vASTMediaLinear;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastMedia.linear.read(6015, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastMedia.linear.read(6015).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "vast_media_linear",
  "self": "/v1/vast-media/linear/6015",
  "id": 6015,
  "banner": 2579,
  "maintain_aspect_ratio": false,
  "creative": 0,
  "scalable": false,
  "delivery": "progressive",
  "codec": null,
  "api_framework": null,
  "min_bitrate": 0,
  "max_bitrate": 0,
  "creative_url": null,
  "width": 100,
  "height": 100,
  "type": null
}
AdButler\VASTMediaLinear JSON: {
  "object": "vast_media_linear",
  "self": "/v1/vast-media/linear/6015",
  "id": 6015,
  "banner": 2579,
  "maintain_aspect_ratio": false,
  "creative": 0,
  "scalable": false,
  "delivery": "progressive",
  "codec": null,
  "api_framework": null,
  "min_bitrate": 0,
  "max_bitrate": 0,
  "creative_url": null,
  "width": 100,
  "height": 100,
  "type": null
}

You can retrieve the information about an existing VAST media by giving the media ID that was returned in the VAST media object upon creation. You will see at the most 10 VAST medias in the response. You can change this default limit by appending ?limit=25 if you want this request to return 25 VAST linear media.

Returns

Returns a vast-media-linear object if the request succeeded, or an error if something went terribly wrong.

Update a VAST Linear Media

Definition

PUT https://api.adbutler.com/v1/vast-media-linear/{MEDIA-ID}
\AdButler\VASTMediaLinear->save()
adbutler.vastMedia.linear.update()

Example Request

curl "https://api.adbutler.com/v1/vast-media/linear/6015" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{  
        "delivery": "progressive",
        "width": 100,
        "height": 100
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTMediaLinear = \AdButler\VASTMediaLinear::retrieve( 6015 );

$vASTMediaLinear->delivery = "progressive";
$vASTMediaLinear->width = 100;
$vASTMediaLinear->height = 100;

$vASTMediaLinear->save();

echo $vASTMediaLinear;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var updateData = {
  "delivery": "progressive",
  "width": 100,
  "height": 100
};

// using callbacks
adbutler.vastMedia.linear.update(6015, updateData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastMedia.linear.update(6015, updateData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "vast_media_linear",
  "self": "/v1/vast-media/linear/6015",
  "id": 6015,
  "banner": 2579,
  "maintain_aspect_ratio": false,
  "creative": 0,
  "scalable": false,
  "delivery": "progressive",
  "codec": null,
  "api_framework": null,
  "min_bitrate": 0,
  "max_bitrate": 0,
  "creative_url": null,
  "width": 100,
  "height": 100,
  "type": null
}
AdButler\VASTMediaLinear JSON: {
  "object": "vast_media_linear",
  "self": "/v1/vast-media/linear/6015",
  "id": 6015,
  "banner": 2579,
  "maintain_aspect_ratio": false,
  "creative": 0,
  "scalable": false,
  "delivery": "progressive",
  "codec": null,
  "api_framework": null,
  "min_bitrate": 0,
  "max_bitrate": 0,
  "creative_url": null,
  "width": 100,
  "height": 100,
  "type": null
}

You can update a specific VAST linear media by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the VAST media creation request.

Field Type Description

banner

string

The ID of the VAST banner that this object belongs to.

type

string

MIME type of the resource. Required if creative_url is given.

delivery

string

The method that the media is delivered. One of: "progressive" or "streaming".

width

integer

Width of the media. Required if creative_url is given.

height

integer

Height of the media. Required if creative_url is given.

scalable

boolean

Whether the video file can scale to a larger size.

maintain_aspect_ratio

boolean

Whether the video file will be forced to maintain it's native aspect ratio when scaled.

creative

integer

The video creative identifier (ID). Must be a valid ID if no creative_url is given.

creative_url

string

The URL of a video file. creative must be given if this is left empty.

codec

string

The codec used to encode the file, as specific by RFC 4281.

min_bitrate

integer

The minimum bitrate for the file. Only include this field if creative_url is given.

max_bitrate

integer

The maximum bitrate for the file. Only include this field if creative_url is given.

api_framework

string

The API necessary to communicate with the creative, if available.

To change a vast_media_linear object from using a library creative to an external one (or vice-versa), you'll need set the old value to null.

Returns

Returns a vast-media-linear object if the request succeeded, or an error if something went terribly wrong.

Delete a VAST Linear Media

Definition

DELETE https://api.adbutler.com/v1/vast-media-linear/{MEDIA-ID}
\AdButler\VASTMediaLinear->delete()
adbutler.vastMedia.linear.delete()

Example Request

curl "https://api.adbutler.com/v1/vast-media/linear/6015" \
  -H "Authorization: Basic {API_KEY}" \
  -X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTMediaLinear = \AdButler\VASTMediaLinear::retrieve( 6015 );
$vASTMediaLinear->delete();

echo $vASTMediaLinear;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastMedia.linear.delete(6015, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastMedia.linear.delete(6015).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "id": 6015,
  "delete": true
}
AdButler\VASTMediaLinear JSON: {
  "id": 6015,
  "delete": true
}

Permanently deletes a VAST linear media. if successful, this operation cannot be undone so be very sure when deleting one.

Returns

Returns a VAST media ID if the request succeeded, or an error if something went terribly wrong.

List all VAST Linear Media

Definition

GET https://api.adbutler.com/v1/vast-media-linear
\AdButler\VASTMediaLinear::retrieveAll()
adbutler.vastMedia.linear.list()

Example Request

curl "https://api.adbutler.com/v1/vast-media/linear?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTMediaLinear = \AdButler\VASTMediaLinear::retrieveAll(array(
  "limit" => 2
));

echo $vASTMediaLinear;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastMedia.linear.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastMedia.linear.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/vast-media/linear",
  "data": [
    {
      "object": "vast_media_linear",
      "self": "/v1/vast-media/linear/5963",
      "id": 5963,
      "banner": 2554,
      "maintain_aspect_ratio": false,
      "creative": 0,
      "scalable": false,
      "delivery": "progressive",
      "codec": null,
      "api_framework": null,
      "min_bitrate": 0,
      "max_bitrate": 0,
      "creative_url": null,
      "width": 100,
      "height": 100,
      "type": null
    },
    {
      "object": "vast_media_linear",
      "self": "/v1/vast-media/linear/5961",
      "id": 5961,
      "banner": 2553,
      "maintain_aspect_ratio": false,
      "creative": 0,
      "scalable": false,
      "delivery": "progressive",
      "codec": null,
      "api_framework": null,
      "min_bitrate": 0,
      "max_bitrate": 0,
      "creative_url": null,
      "width": 100,
      "height": 100,
      "type": null
    }
  ]
}
AdButler\VASTMediaLinear JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/vast-media/linear",
  "data": [
    {
      "object": "vast_media_linear",
      "self": "/v1/vast-media/linear/5963",
      "id": 5963,
      "banner": 2554,
      "maintain_aspect_ratio": false,
      "creative": 0,
      "scalable": false,
      "delivery": "progressive",
      "codec": null,
      "api_framework": null,
      "min_bitrate": 0,
      "max_bitrate": 0,
      "creative_url": null,
      "width": 100,
      "height": 100,
      "type": null
    },
    {
      "object": "vast_media_linear",
      "self": "/v1/vast-media/linear/5961",
      "id": 5961,
      "banner": 2553,
      "maintain_aspect_ratio": false,
      "creative": 0,
      "scalable": false,
      "delivery": "progressive",
      "codec": null,
      "api_framework": null,
      "min_bitrate": 0,
      "max_bitrate": 0,
      "creative_url": null,
      "width": 100,
      "height": 100,
      "type": null
    }
  ]
}

Returns a list of all the VAST linear medias. Most recent VAST medias appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is a vast-media object, and if no objects were found the list will be empty.


VAST Media Non-Linear

Introduction

The VAST Linear Media object is a reference to a linear creative that will be served in a VAST Banner. A linear creative is one that is video-based and plays pre-roll, mid-roll or post-roll in relation to the video content.

The vast_media_non_linear response object has the following fields.

Example Response

{
  "object": "vast_media_non_linear",
  "self": "/v1/vast-media/non-linear/6016",
  "id": 6016,
  "banner": 2579,
  "type": "image/png",
  "maintain_aspect_ratio": false,
  "creative": {
    "type": "image_url",
    "source": "https://admin.adbutler.com/assets/icons/adbutler_logo_inapp@2x.png"
  },
  "scalable": false,
  "expanded_width": 0,
  "expanded_height": 0,
  "ad_parameters": null,
  "min_suggested_duration": 0,
  "width": 325,
  "height": 100,
  "encode_parameters": "none"
}
AdButler\VASTMediaNonLinear JSON: {
  "object": "vast_media_non_linear",
  "self": "/v1/vast-media/non-linear/6016",
  "id": 6016,
  "banner": 2579,
  "type": "image/png",
  "maintain_aspect_ratio": false,
  "creative": {
    "type": "image_url",
    "source": "https://admin.adbutler.com/assets/icons/adbutler_logo_inapp@2x.png"
  },
  "scalable": false,
  "expanded_width": 0,
  "expanded_height": 0,
  "ad_parameters": null,
  "min_suggested_duration": 0,
  "width": 325,
  "height": 100,
  "encode_parameters": "none"
}
Field Type Description

object

string

A string denoting the object type which is always vast-media for the current resource.

self

string

The relative URL of the current resource which is always of the form /v1/vast-medias/{MEDIA-ID}.

id

integer

The resource identifier (ID).

banner

string

The ID of the VAST banner that this object belongs to.

creative

object

An object that describes the type of creative this object will contain. It contains the type of creative, one of: "image_library", "image_url", "html", "iframe". It also contains the source of the creative. If type is "image_library", then source is the ID of an Image Creative. If type is "image_url", then source is a URL that links to an image file. If type is "html" or "iframe", then source is a string containing the HTML code to be displayed.

type

string

Describes the type of creative. If it is an image, this will be the MIME type or image format.

width

integer

Width of the media.

height

integer

Height of the media.

expanded_width

integer

The width of the media if it is scaled up.

expanded_height

integer

The height of the media if it is scaled up.

scalable

boolean

Whether the video file can scale to a larger size.

maintain_aspect_ratio

boolean

Whether the video file will be forced to maintain it's native aspect ratio when scaled.

min_suggested_duration

integer

The minimum amount of time, in seconds, that this media file should be displayed in the player.

ad_parameters

string

Any custom parameters for executable media or API frameworks that might be required by the creative.

encode_parameters

string

Specifies whether the entities in ad_parameters have been escaped. One of "none", "xml", or "xml_reencode".

Create a VAST Non-Linear Media

Definition

POST https://api.adbutler.com/v1/vast-media-non-linear
\AdButler\VASTMediaNonLinear::create()
adbutler.vastMedia.nonLinear.create()

Example Request

curl "https://api.adbutler.com/v1/vast-media/non-linear" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{  
        "width": 325,
        "height": 100
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTMediaNonLinear = \AdButler\VASTMediaNonLinear::create(array(
  "width" => 325,
  "height" => 100
));

echo $vASTMediaNonLinear;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var postData = {
  "width": 325,
  "height": 100
};

// using callbacks
adbutler.vastMedia.nonLinear.create(postData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastMedia.nonLinear.create(postData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "vast_media_non_linear",
  "self": "/v1/vast-media/non-linear/6016",
  "id": 6016,
  "banner": 2579,
  "type": "image/png",
  "maintain_aspect_ratio": false,
  "creative": {
    "type": "image_url",
    "source": "https://admin.adbutler.com/assets/icons/adbutler_logo_inapp@2x.png"
  },
  "scalable": false,
  "expanded_width": 0,
  "expanded_height": 0,
  "ad_parameters": null,
  "min_suggested_duration": 0,
  "width": 325,
  "height": 100,
  "encode_parameters": "none"
}
AdButler\VASTMediaNonLinear JSON: {
  "object": "vast_media_non_linear",
  "self": "/v1/vast-media/non-linear/6016",
  "id": 6016,
  "banner": 2579,
  "type": "image/png",
  "maintain_aspect_ratio": false,
  "creative": {
    "type": "image_url",
    "source": "https://admin.adbutler.com/assets/icons/adbutler_logo_inapp@2x.png"
  },
  "scalable": false,
  "expanded_width": 0,
  "expanded_height": 0,
  "ad_parameters": null,
  "min_suggested_duration": 0,
  "width": 325,
  "height": 100,
  "encode_parameters": "none"
}

Creates a new VAST Non-Linear Media.

Field Type Description

banner*

string

The ID of the VAST banner that this object belongs to.

creative*

object

An object that describes the type of creative this object will contain. It contains the type of creative, one of: "image_library", "image_url", "html", "iframe". It also contains the source of the creative. If type is "image_library", then source is the ID of an Image Creative. If type is "image_url", then source is a URL that links to an image file. If type is "html" or "iframe", then source is a string containing the HTML code to be displayed.

width

integer

Width of the media. This field is required if the creative type is anything other than "image_library".

height

integer

Height of the media. This field is required if the creative type is anything other than "image_library".

expanded_width

integer

The width of the media if it is scaled up.

expanded_height

integer

The height of the media if it is scaled up.

scalable

boolean

Whether the video file can scale to a larger size.

maintain_aspect_ratio

boolean

Whether the video file will be forced to maintain it's native aspect ratio when scaled.

min_suggested_duration

integer

The minimum amount of time, in seconds, that this media file should be displayed in the player.

ad_parameters

string

Any custom parameters for executable media or API frameworks that might be required by the creative.

encode_parameters

string

Specifies whether the entities in ad_parameters have been escaped. One of "none", "xml", or "xml_reencode".

* = required field

Returns

Returns a vast-media-non-linear object if the request succeeded, or an error if something went terribly wrong.

Retrieve a VAST Non-Linear Media

Definition

GET https://api.adbutler.com/v1/vast-media-non-linear/{MEDIA-ID}
\AdButler\VASTMediaNonLinear::retrieve()
adbutler.vastMedia.nonLinear.retrieve()

Example Request

curl "https://api.adbutler.com/v1/vast-media/non-linear/6016" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTMediaNonLinear = \AdButler\VASTMediaNonLinear::retrieve( 6016 );

echo $vASTMediaNonLinear;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastMedia.nonLinear.read(6016, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastMedia.nonLinear.read(6016).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "vast_media_non_linear",
  "self": "/v1/vast-media/non-linear/6016",
  "id": 6016,
  "banner": 2579,
  "type": "image/png",
  "maintain_aspect_ratio": false,
  "creative": {
    "type": "image_url",
    "source": "https://admin.adbutler.com/assets/icons/adbutler_logo_inapp@2x.png"
  },
  "scalable": false,
  "expanded_width": 0,
  "expanded_height": 0,
  "ad_parameters": null,
  "min_suggested_duration": 0,
  "width": 325,
  "height": 100,
  "encode_parameters": "none"
}
AdButler\VASTMediaNonLinear JSON: {
  "object": "vast_media_non_linear",
  "self": "/v1/vast-media/non-linear/6016",
  "id": 6016,
  "banner": 2579,
  "type": "image/png",
  "maintain_aspect_ratio": false,
  "creative": {
    "type": "image_url",
    "source": "https://admin.adbutler.com/assets/icons/adbutler_logo_inapp@2x.png"
  },
  "scalable": false,
  "expanded_width": 0,
  "expanded_height": 0,
  "ad_parameters": null,
  "min_suggested_duration": 0,
  "width": 325,
  "height": 100,
  "encode_parameters": "none"
}

You can retrieve the information about an existing VAST media by giving the media ID that was returned in the VAST media object upon creation. You will see at the most 10 VAST medias in the response. You can change this default limit by appending ?limit=25 if you want this request to return 25 VAST linear media.

Returns

Returns a vast-media-non-linear object if the request succeeded, or an error if something went terribly wrong.

Update a VAST Non-Linear Media

Definition

PUT https://api.adbutler.com/v1/vast-media-non-linear/{MEDIA-ID}
\AdButler\VASTMediaNonLinear->save()
adbutler.vastMedia.nonLinear.update()

Example Request

curl "https://api.adbutler.com/v1/vast-media/non-linear/6016" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{  
        "width": 325,
        "height": 100
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTMediaNonLinear = \AdButler\VASTMediaNonLinear::retrieve( 6016 );

$vASTMediaNonLinear->width = 325;
$vASTMediaNonLinear->height = 100;

$vASTMediaNonLinear->save();

echo $vASTMediaNonLinear;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var updateData = {
  "width": 325,
  "height": 100
};

// using callbacks
adbutler.vastMedia.nonLinear.update(6016, updateData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastMedia.nonLinear.update(6016, updateData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "vast_media_non_linear",
  "self": "/v1/vast-media/non-linear/6016",
  "id": 6016,
  "banner": 2579,
  "type": "image/png",
  "maintain_aspect_ratio": false,
  "creative": {
    "type": "image_url",
    "source": "https://admin.adbutler.com/assets/icons/adbutler_logo_inapp@2x.png"
  },
  "scalable": false,
  "expanded_width": 0,
  "expanded_height": 0,
  "ad_parameters": null,
  "min_suggested_duration": 0,
  "width": 325,
  "height": 100,
  "encode_parameters": "none"
}
AdButler\VASTMediaNonLinear JSON: {
  "object": "vast_media_non_linear",
  "self": "/v1/vast-media/non-linear/6016",
  "id": 6016,
  "banner": 2579,
  "type": "image/png",
  "maintain_aspect_ratio": false,
  "creative": {
    "type": "image_url",
    "source": "https://admin.adbutler.com/assets/icons/adbutler_logo_inapp@2x.png"
  },
  "scalable": false,
  "expanded_width": 0,
  "expanded_height": 0,
  "ad_parameters": null,
  "min_suggested_duration": 0,
  "width": 325,
  "height": 100,
  "encode_parameters": "none"
}

You can update a specific VAST non-linear media by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the VAST media creation request.

Field Type Description

banner

string

The ID of the VAST banner that this object belongs to.

creative

object

An object that describes the type of creative this object will contain. It contains the type of creative, one of: "image_library", "image_url", "html", "iframe". It also contains the source of the creative. If type is "image_library", then source is the ID of an Image Creative. If type is "image_url", then source is a URL that links to an image file. If type is "html" or "iframe", then source is a string containing the HTML code to be displayed.

width

integer

Width of the media. This field is required if the creative type is anything other than "image_library".

height

integer

Height of the media. This field is required if the creative type is anything other than "image_library".

expanded_width

integer

The width of the media if it is scaled up.

expanded_height

integer

The height of the media if it is scaled up.

scalable

boolean

Whether the video file can scale to a larger size.

maintain_aspect_ratio

boolean

Whether the video file will be forced to maintain it's native aspect ratio when scaled.

min_suggested_duration

integer

The minimum amount of time, in seconds, that this media file should be displayed in the player.

ad_parameters

string

Any custom parameters for executable media or API frameworks that might be required by the creative.

encode_parameters

string

Specifies whether the entities in ad_parameters have been escaped. One of "none", "xml", or "xml_reencode".

Returns

Returns a vast-media-non-linear object if the request succeeded, or an error if something went terribly wrong.

Delete a VAST Non-Linear Media

Definition

DELETE https://api.adbutler.com/v1/vast-media-non-linear/{MEDIA-ID}
\AdButler\VASTMediaNonLinear->delete()
adbutler.vastMedia.nonLinear.delete()

Example Request

curl "https://api.adbutler.com/v1/vast-media/non-linear/6016" \
  -H "Authorization: Basic {API_KEY}" \
  -X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTMediaNonLinear = \AdButler\VASTMediaNonLinear::retrieve( 6016 );
$vASTMediaNonLinear->delete();

echo $vASTMediaNonLinear;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastMedia.nonLinear.delete(6016, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastMedia.nonLinear.delete(6016).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "id": 6016,
  "delete": true
}
AdButler\VASTMediaNonLinear JSON: {
  "id": 6016,
  "delete": true
}

Permanently deletes a VAST non-linear media. if successful, this operation cannot be undone so be very sure when deleting one.

Returns

Returns a VAST media ID if the request succeeded, or an error if something went terribly wrong.

List all VAST Non-Linear Media

Definition

GET https://api.adbutler.com/v1/vast-media-non-linear
\AdButler\VASTMediaNonLinear::retrieveAll()
adbutler.vastMedia.nonLinear.list()

Example Request

curl "https://api.adbutler.com/v1/vast-media/non-linear?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTMediaNonLinear = \AdButler\VASTMediaNonLinear::retrieveAll(array(
  "limit" => 2
));

echo $vASTMediaNonLinear;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastMedia.nonLinear.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastMedia.nonLinear.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/vast-media/non-linear",
  "data": [
    {
      "object": "vast_media_non_linear",
      "self": "/v1/vast-media/non-linear/5964",
      "id": 5964,
      "banner": 2554,
      "type": null,
      "maintain_aspect_ratio": false,
      "creative": {
        "type": "image_url",
        "source": null
      },
      "scalable": false,
      "expanded_width": 0,
      "expanded_height": 0,
      "ad_parameters": null,
      "min_suggested_duration": 0,
      "width": 100,
      "height": 100,
      "encode_parameters": "none"
    },
    {
      "object": "vast_media_non_linear",
      "self": "/v1/vast-media/non-linear/5962",
      "id": 5962,
      "banner": 2553,
      "type": null,
      "maintain_aspect_ratio": false,
      "creative": {
        "type": "image_url",
        "source": null
      },
      "scalable": false,
      "expanded_width": 0,
      "expanded_height": 0,
      "ad_parameters": null,
      "min_suggested_duration": 0,
      "width": 100,
      "height": 100,
      "encode_parameters": "none"
    }
  ]
}
AdButler\VASTMediaNonLinear JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/vast-media/non-linear",
  "data": [
    {
      "object": "vast_media_non_linear",
      "self": "/v1/vast-media/non-linear/5964",
      "id": 5964,
      "banner": 2554,
      "type": null,
      "maintain_aspect_ratio": false,
      "creative": {
        "type": "image_url",
        "source": null
      },
      "scalable": false,
      "expanded_width": 0,
      "expanded_height": 0,
      "ad_parameters": null,
      "min_suggested_duration": 0,
      "width": 100,
      "height": 100,
      "encode_parameters": "none"
    },
    {
      "object": "vast_media_non_linear",
      "self": "/v1/vast-media/non-linear/5962",
      "id": 5962,
      "banner": 2553,
      "type": null,
      "maintain_aspect_ratio": false,
      "creative": {
        "type": "image_url",
        "source": null
      },
      "scalable": false,
      "expanded_width": 0,
      "expanded_height": 0,
      "ad_parameters": null,
      "min_suggested_duration": 0,
      "width": 100,
      "height": 100,
      "encode_parameters": "none"
    }
  ]
}

Returns a list of all the VAST non-linear medias. Most recent VAST medias appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is a vast-media object, and if no objects were found the list will be empty.


VAST Placement

Introduction

A VAST placement represents the relationship between a VAST banner or VAST campaign and a VAST zone or VAST channel. A VAST placement will also have a schedule that outlines its serving behaviour

The vast_placement response object has the following fields.

Example Response

{
  "object": "vast_placement",
  "self": "/v1/vast_placements/7698",
  "id": 7698,
  "zone": 85772,
  "channel": 0,
  "schedule": 12209,
  "advertisement": {
    "id": 2579,
    "type": "vast_banner"
  },
  "active": true,
  "cpm": 2,
  "cpc": 0,
  "cpa": 0,
  "fixed_cost": 0,
  "payout_percent": 0,
  "use_channel_priority": true,
  "priority": "standard",
  "max_frequency": 0,
  "max_frequency_period": 0,
  "max_frequency_type": "start"
}
AdButler\VASTPlacement JSON: {
  "object": "vast_placement",
  "self": "/v1/vast_placements/7698",
  "id": 7698,
  "zone": 85772,
  "channel": 0,
  "schedule": 12209,
  "advertisement": {
    "id": 2579,
    "type": "vast_banner"
  },
  "active": true,
  "cpm": 2,
  "cpc": 0,
  "cpa": 0,
  "fixed_cost": 0,
  "payout_percent": 0,
  "use_channel_priority": true,
  "priority": "standard",
  "max_frequency": 0,
  "max_frequency_period": 0,
  "max_frequency_type": "start"
}
Field Type Description

object

string

A string denoting the object type which is always vast_placement for the current resource.

self

string

The relative URL of the current resource which is always of the form /v1/vast-placements/{PlACEMENT_ID}.

id

integer

The resource identifier (ID).

advertisement

object

An object containing vast_banner or vast_campaign identifier (ID) and type.

zone

integer

If assigned to a zone, this is the VAST zone ID.

channel

integer

If assiged to a channel, this is the VAST channel ID.

schedule

integer

The VAST schedule identifier (ID).

active

boolean

Whether to actively serve ads in the zones (true) or pause ad serving (false). Defaults to true.

cpm

decimal

CPM of the placement.

cpc

decimal

CPC of the placement.

cpa

decimal

CPA of the placement.

fixed_cost

decimal

Fixed cost of the placement.

payout_percent

decimal

The percentage of the ad generated revenue paid out to the publisher. Publisher payout is ideal for profit sharing where the revenue is split between money earned by the advertiser and money earned by the publisher. Defaults to 0.00 percent.

use_channel_priority

boolean

Whether to use the priority of the channel or set a specific priority.

priority

integer

Priority allows you to prefer serving of some ads over others in a campaign or channel. Possible values in descending order are "sponsorship", "standard", "network", "bulk" and "house". Defaults to "standard".

max_frequency

integer

A limit to the number of times a user is allowed to trigger a specific event, given by max_frequency_type, over a period of time, given by max_frequency_period. An integer value enables frequency capping and must be specified alongside

max_frequency_period

integer

The number of days after which the max_frequency counter will start over. This field must be specified along with max_frequency.

max_frequency_type

string

The specific event that will be counted by the frequency capping. One of: "start", "view", "firstQuartile", "midpoint", "thirdQuartile", "complete".

Create a VAST Placement

Definition

POST https://api.adbutler.com/v1/vast-placements
\AdButler\VASTPlacement::create()
adbutler.vastPlacements.create()

Example Request

curl "https://api.adbutler.com/v1/vast-placements" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{  

      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTPlacement = \AdButler\VASTPlacement::create(array(

));

echo $vASTPlacement;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var postData = {

};

// using callbacks
adbutler.vastPlacements.create(postData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastPlacements.create(postData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "vast_placement",
  "self": "/v1/vast_placements/7698",
  "id": 7698,
  "zone": 85772,
  "channel": 0,
  "schedule": 12209,
  "advertisement": {
    "id": 2579,
    "type": "vast_banner"
  },
  "active": true,
  "cpm": 2,
  "cpc": 0,
  "cpa": 0,
  "fixed_cost": 0,
  "payout_percent": 0,
  "use_channel_priority": true,
  "priority": "standard",
  "max_frequency": 0,
  "max_frequency_period": 0,
  "max_frequency_type": "start"
}
AdButler\VASTPlacement JSON: {
  "object": "vast_placement",
  "self": "/v1/vast_placements/7698",
  "id": 7698,
  "zone": 85772,
  "channel": 0,
  "schedule": 12209,
  "advertisement": {
    "id": 2579,
    "type": "vast_banner"
  },
  "active": true,
  "cpm": 2,
  "cpc": 0,
  "cpa": 0,
  "fixed_cost": 0,
  "payout_percent": 0,
  "use_channel_priority": true,
  "priority": "standard",
  "max_frequency": 0,
  "max_frequency_period": 0,
  "max_frequency_type": "start"
}

Creates a new VAST Placement.

Field Type Description

advertisement*

object

An object containing vast_banner or vast_campaign identifier (ID) and type.

schedule*

integer

The VAST schedule identifier (ID).

zone

integer

If assigned to a zone, this is the VAST zone ID.

channel

integer

If assiged to a channel, this is the VAST channel ID.

active

boolean

Whether to actively serve ads in the zones (true) or pause ad serving (false). Defaults to true.

cpm

decimal

CPM of the placement.

cpc

decimal

CPC of the placement.

cpa

decimal

CPA of the placement.

fixed_cost

decimal

Fixed cost of the placement.

payout_percent

decimal

The percentage of the ad generated revenue paid out to the publisher. Publisher payout is ideal for profit sharing where the revenue is split between money earned by the advertiser and money earned by the publisher. Defaults to 0.00 percent.

use_channel_priority

boolean

Whether to use the priority of the channel or set a specific priority.

priority

integer

Priority allows you to prefer serving of some ads over others in a campaign or channel. Possible values in descending order are "sponsorship", "standard", "network", "bulk" and "house". Defaults to "standard".

max_frequency

integer

A limit to the number of times a user is allowed to trigger a specific event, given by max_frequency_type, over a period of time, given by max_frequency_period. An integer value enables frequency capping and must be specified alongside

max_frequency_period

integer

The number of days after which the max_frequency counter will start over. This field must be specified along with max_frequency.

max_frequency_type

string

The specific event that will be counted by the frequency capping. One of: "start", "view", "firstQuartile", "midpoint", "thirdQuartile", "complete".

* = required field

Returns

Returns a vast_placement object if the request succeeded, or an error if something went terribly wrong.

Retrieve a VAST Placement

Definition

GET https://api.adbutler.com/v1/vast-placements/{PLACEMENT-ID}
\AdButler\VASTPlacement::retrieve()
adbutler.vastPlacements.retrieve()

Example Request

curl "https://api.adbutler.com/v1/vast-placements/7698" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTPlacement = \AdButler\VASTPlacement::retrieve( 7698 );

echo $vASTPlacement;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastPlacements.read(7698, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastPlacements.read(7698).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "vast_placement",
  "self": "/v1/vast_placements/7698",
  "id": 7698,
  "zone": 85772,
  "channel": 0,
  "schedule": 12209,
  "advertisement": {
    "id": 2579,
    "type": "vast_banner"
  },
  "active": true,
  "cpm": 2,
  "cpc": 0,
  "cpa": 0,
  "fixed_cost": 0,
  "payout_percent": 0,
  "use_channel_priority": true,
  "priority": "standard",
  "max_frequency": 0,
  "max_frequency_period": 0,
  "max_frequency_type": "start"
}
AdButler\VASTPlacement JSON: {
  "object": "vast_placement",
  "self": "/v1/vast_placements/7698",
  "id": 7698,
  "zone": 85772,
  "channel": 0,
  "schedule": 12209,
  "advertisement": {
    "id": 2579,
    "type": "vast_banner"
  },
  "active": true,
  "cpm": 2,
  "cpc": 0,
  "cpa": 0,
  "fixed_cost": 0,
  "payout_percent": 0,
  "use_channel_priority": true,
  "priority": "standard",
  "max_frequency": 0,
  "max_frequency_period": 0,
  "max_frequency_type": "start"
}

You can retrieve the information about an existing VAST placement by giving the placement ID that was returned in the VAST placement object upon creation. You will see at the most 10 VAST placements in the response. You can change this default limit by appending ?limit=25 if you want this request to return 25 VAST placements.

Returns

Returns a vast_placement object if the request succeeded, or an error if something went terribly wrong.

Update a VAST Placement

Definition

PUT https://api.adbutler.com/v1/vast-placements/{PLACEMENT-ID}
\AdButler\VASTPlacement->save()
adbutler.vastPlacements.update()

Example Request

curl "https://api.adbutler.com/v1/vast-placements/7698" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{  

      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTPlacement = \AdButler\VASTPlacement::retrieve( 7698 );



$vASTPlacement->save();

echo $vASTPlacement;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var updateData = {

};

// using callbacks
adbutler.vastPlacements.update(7698, updateData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastPlacements.update(7698, updateData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "vast_placement",
  "self": "/v1/vast_placements/7698",
  "id": 7698,
  "zone": 85772,
  "channel": 0,
  "schedule": 12209,
  "advertisement": {
    "id": 2579,
    "type": "vast_banner"
  },
  "active": true,
  "cpm": 2,
  "cpc": 0,
  "cpa": 0,
  "fixed_cost": 0,
  "payout_percent": 0,
  "use_channel_priority": true,
  "priority": "standard",
  "max_frequency": 0,
  "max_frequency_period": 0,
  "max_frequency_type": "start"
}
AdButler\VASTPlacement JSON: {
  "object": "vast_placement",
  "self": "/v1/vast_placements/7698",
  "id": 7698,
  "zone": 85772,
  "channel": 0,
  "schedule": 12209,
  "advertisement": {
    "id": 2579,
    "type": "vast_banner"
  },
  "active": true,
  "cpm": 2,
  "cpc": 0,
  "cpa": 0,
  "fixed_cost": 0,
  "payout_percent": 0,
  "use_channel_priority": true,
  "priority": "standard",
  "max_frequency": 0,
  "max_frequency_period": 0,
  "max_frequency_type": "start"
}

You can update a specific VAST placement by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the VAST placement creation request.

Field Type Description

advertisement

object

An object containing vast_banner or vast_campaign identifier (ID) and type.

schedule

integer

The VAST schedule identifier (ID).

zone

integer

If assigned to a zone, this is the VAST zone ID.

channel

integer

If assiged to a channel, this is the VAST channel ID.

active

boolean

Whether to actively serve ads in the zones (true) or pause ad serving (false). Defaults to true.

cpm

decimal

CPM of the placement.

cpc

decimal

CPC of the placement.

cpa

decimal

CPA of the placement.

fixed_cost

decimal

Fixed cost of the placement.

payout_percent

decimal

The percentage of the ad generated revenue paid out to the publisher. Publisher payout is ideal for profit sharing where the revenue is split between money earned by the advertiser and money earned by the publisher. Defaults to 0.00 percent.

use_channel_priority

boolean

Whether to use the priority of the channel or set a specific priority.

priority

integer

Priority allows you to prefer serving of some ads over others in a campaign or channel. Possible values in descending order are "sponsorship", "standard", "network", "bulk" and "house". Defaults to "standard".

max_frequency

integer

A limit to the number of times a user is allowed to trigger a specific event, given by max_frequency_type, over a period of time, given by max_frequency_period. An integer value enables frequency capping and must be specified alongside

max_frequency_period

integer

The number of days after which the max_frequency counter will start over. This field must be specified along with max_frequency.

max_frequency_type

string

The specific event that will be counted by the frequency capping. One of: "start", "view", "firstQuartile", "midpoint", "thirdQuartile", "complete".

Returns

Returns a vast_placement object if the request succeeded, or an error if something went terribly wrong.

Delete a VAST Placement

Definition

DELETE https://api.adbutler.com/v1/vast-placements/{PLACEMENT-ID}
\AdButler\VASTPlacement->delete()
adbutler.vastPlacements.delete()

Example Request

curl "https://api.adbutler.com/v1/vast-placements/7698" \
  -H "Authorization: Basic {API_KEY}" \
  -X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTPlacement = \AdButler\VASTPlacement::retrieve( 7698 );
$vASTPlacement->delete();

echo $vASTPlacement;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastPlacements.delete(7698, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastPlacements.delete(7698).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "id": 7698,
  "delete": true
}
AdButler\VASTPlacement JSON: {
  "id": 7698,
  "delete": true
}

Permanently deletes a VAST placement. if successful, this operation cannot be undone so be very sure when deleting one.

Returns

Returns a VAST placement ID if the request succeeded, or an error if something went terribly wrong.

List all VAST Placements

Definition

GET https://api.adbutler.com/v1/vast-placements
\AdButler\VASTPlacement::retrieveAll()
adbutler.vastPlacements.list()

Example Request

curl "https://api.adbutler.com/v1/vast-placements?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTPlacement = \AdButler\VASTPlacement::retrieveAll(array(
  "limit" => 2
));

echo $vASTPlacement;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastPlacements.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastPlacements.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/vast-placements",
  "data": [
    {
      "object": "vast_placement",
      "self": "/v1/vast_placements/7658",
      "id": 7658,
      "zone": 85756,
      "channel": 0,
      "schedule": 12153,
      "advertisement": {
        "id": 2553,
        "type": "vast_banner"
      },
      "active": true,
      "cpm": 2,
      "cpc": 0,
      "cpa": 0,
      "fixed_cost": 0,
      "payout_percent": 0,
      "use_channel_priority": true,
      "priority": "standard",
      "max_frequency": 0,
      "max_frequency_period": 0,
      "max_frequency_type": "start"
    },
    {
      "object": "vast_placement",
      "self": "/v1/vast_placements/7659",
      "id": 7659,
      "zone": 85757,
      "channel": 0,
      "schedule": 12154,
      "advertisement": {
        "id": 2554,
        "type": "vast_banner"
      },
      "active": true,
      "cpm": 2,
      "cpc": 0,
      "cpa": 0,
      "fixed_cost": 0,
      "payout_percent": 0,
      "use_channel_priority": true,
      "priority": "standard",
      "max_frequency": 0,
      "max_frequency_period": 0,
      "max_frequency_type": "start"
    }
  ]
}
AdButler\VASTPlacement JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/vast-placements",
  "data": [
    {
      "object": "vast_placement",
      "self": "/v1/vast_placements/7658",
      "id": 7658,
      "zone": 85756,
      "channel": 0,
      "schedule": 12153,
      "advertisement": {
        "id": 2553,
        "type": "vast_banner"
      },
      "active": true,
      "cpm": 2,
      "cpc": 0,
      "cpa": 0,
      "fixed_cost": 0,
      "payout_percent": 0,
      "use_channel_priority": true,
      "priority": "standard",
      "max_frequency": 0,
      "max_frequency_period": 0,
      "max_frequency_type": "start"
    },
    {
      "object": "vast_placement",
      "self": "/v1/vast_placements/7659",
      "id": 7659,
      "zone": 85757,
      "channel": 0,
      "schedule": 12154,
      "advertisement": {
        "id": 2554,
        "type": "vast_banner"
      },
      "active": true,
      "cpm": 2,
      "cpc": 0,
      "cpa": 0,
      "fixed_cost": 0,
      "payout_percent": 0,
      "use_channel_priority": true,
      "priority": "standard",
      "max_frequency": 0,
      "max_frequency_period": 0,
      "max_frequency_type": "start"
    }
  ]
}

Returns a list of all the VAST placements. Most recent VAST placements appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is a vast_placement object, and if no objects were found the list will be empty.

Retrieve VAST placement conversion tag

Definition

GET https://api.adbutler.com/v1/vast-placements/{PLACEMENT-ID}/conversion-tag
\AdButler\VASTPlacementConvTag::retrieve()
adbutler.vastPlacements.conversionTag.retrieve()

Example Request

curl "https://api.adbutler.com/v1/vast-placements/ID/conversion-tag/7698" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTPlacementConvTag = \AdButler\VASTPlacementConvTag::retrieve( 7698 );

echo $vASTPlacementConvTag;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastPlacements.conversionTag.read(7698, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastPlacements.conversionTag.read(7698).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Retrieves an HTML tag which can be used to track conversions for the provided VAST placement.

Query Parameters

Parameter Description

protocol

Whether to use http or https protocol when serving the advertisements. Use https only if you are using secure pages because it does not support Custom Domains.

Returns

Example Response

{
  "object": "conv_tag",
  "url": "/v1/vast-placements/7698/conversion-tag",
  "data": {
    "src": "https://servedbyadbutler.com.vm.test/vconvtrack.spark?MID=108607&vastPlacementID=7698",
    "html": "<img src='https://servedbyadbutler.com.vm.test/vconvtrack.spark?MID=108607&vastPlacementID=7698' width='1' height='1' border='0' />"
  }
}
AdButler\VASTPlacementConvTag JSON: {
  "object": "conv_tag",
  "url": "/v1/vast-placements/7698/conversion-tag",
  "data": {
    "src": "https://servedbyadbutler.com.vm.test/vconvtrack.spark?MID=108607&vastPlacementID=7698",
    "html": "<img src='https://servedbyadbutler.com.vm.test/vconvtrack.spark?MID=108607&vastPlacementID=7698' width='1' height='1' border='0' />"
  }
}
Field Type Description

object

string

A string denoting the object type which is always conv_tag for the current resource.

url

string

The relative URL of the current resource which is always of the form /v1/vast-placements/{PLACEMENT_ID}/conversion-tag.

data

array

The data object containing the conversion tag.

 

Returns a conv_tag object if the request succeeded, or an error if something went terribly wrong.


VAST Tracking

Introduction

The VAST Tracking endpoint allows you to bind your own custom tracking links to different VAST events. When these are active the video player will fire both our tracking and your custom tracking at the same time the event occurs.

The vast_tracking response object has the following fields.

Example Response

{
  "object": "vast_tracking",
  "self": "/v1/vast_tracking/1554",
  "id": 1554,
  "banner_id": 2579,
  "type": "midpoint",
  "link": "http://www.google.com"
}
AdButler\VASTTracking JSON: {
  "object": "vast_tracking",
  "self": "/v1/vast_tracking/1554",
  "id": 1554,
  "banner_id": 2579,
  "type": "midpoint",
  "link": "http://www.google.com"
}
Field Type Description

object

string

A string denoting the object type which is always vast_tracking for the current resource.

self

string

The relative URL of the current resource which is always of the form /v1/vast-tracking/{TRACKING_ID}.

id

integer

The resource identifier (ID).

banner_id

integer

The ID of the VAST Banner that your tracking events will be attached to.

type

string

The event type to track. One of: "creativeView", "clicks", "start", "firstQuartile", "midpoint", "thirdQuartile", "complete", "mute", "unmute", "pause", "rewind", "resume", "fullscreen", "exitFullScreen", "companionClicks1", "companionClicks2", "companionClicks3", "companionClicks4", "companionClicks5", "companionViews1", "companionViews2", "companionViews3", "companionViews4", "companionViews5", "nlCreativeView", "expand", "collapse".

link

string

Your URL to be pinged at the time of the event.

Create a VAST Tracking

Definition

POST https://api.adbutler.com/v1/vast-tracking
\AdButler\VASTTracking::create()
adbutler.vastTracking.create()

Example Request

curl "https://api.adbutler.com/v1/vast-tracking" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{  
        "banner_id": 2579,
        "type": "midpoint",
        "link": "http://www.google.com"
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTTracking = \AdButler\VASTTracking::create(array(
  "banner_id" => 2579,
  "type" => "midpoint",
  "link" => "http://www.google.com"
));

echo $vASTTracking;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var postData = {
  "banner_id": 2579,
  "type": "midpoint",
  "link": "http://www.google.com"
};

// using callbacks
adbutler.vastTracking.create(postData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastTracking.create(postData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "vast_tracking",
  "self": "/v1/vast_tracking/1554",
  "id": 1554,
  "banner_id": 2579,
  "type": "midpoint",
  "link": "http://www.google.com"
}
AdButler\VASTTracking JSON: {
  "object": "vast_tracking",
  "self": "/v1/vast_tracking/1554",
  "id": 1554,
  "banner_id": 2579,
  "type": "midpoint",
  "link": "http://www.google.com"
}

Creates a new VAST Tracking.

Field Type Description

banner_id*

integer

The ID of the VAST Banner that your tracking events will be attached to.

type*

string

The event type to track. One of: "creativeView", "clicks", "start", "firstQuartile", "midpoint", "thirdQuartile", "complete", "mute", "unmute", "pause", "rewind", "resume", "fullscreen", "exitFullScreen", "companionClicks1", "companionClicks2", "companionClicks3", "companionClicks4", "companionClicks5", "companionViews1", "companionViews2", "companionViews3", "companionViews4", "companionViews5", "nlCreativeView", "expand", "collapse".

link*

string

Your URL to be pinged at the time of the event.

* = required field

Returns

Returns a vast_tracking object if the request succeeded, or an error if something went terribly wrong.

Retrieve a VAST Tracking

Definition

GET https://api.adbutler.com/v1/vast-tracking/{TRACKING-ID}
\AdButler\VASTTracking::retrieve()
adbutler.vastTracking.retrieve()

Example Request

curl "https://api.adbutler.com/v1/vast-tracking/1554" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTTracking = \AdButler\VASTTracking::retrieve( 1554 );

echo $vASTTracking;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastTracking.read(1554, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastTracking.read(1554).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "vast_tracking",
  "self": "/v1/vast_tracking/1554",
  "id": 1554,
  "banner_id": 2579,
  "type": "midpoint",
  "link": "http://www.google.com"
}
AdButler\VASTTracking JSON: {
  "object": "vast_tracking",
  "self": "/v1/vast_tracking/1554",
  "id": 1554,
  "banner_id": 2579,
  "type": "midpoint",
  "link": "http://www.google.com"
}

You can retrieve the information about an existing VAST tracking by giving the tracking ID that was returned in the VAST tracking object upon creation. You will see at the most 10 VAST tracking in the response. You can change this default limit by appending ?limit=25 if you want this request to return 25 VAST tracking.

Returns

Returns a vast_tracking object if the request succeeded, or an error if something went terribly wrong.

Update a VAST Tracking

Definition

PUT https://api.adbutler.com/v1/vast-tracking/{TRACKING-ID}
\AdButler\VASTTracking->save()
adbutler.vastTracking.update()

Example Request

curl "https://api.adbutler.com/v1/vast-tracking/1554" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{  
        "banner_id": 2579,
        "type": "midpoint",
        "link": "http://www.google.com"
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTTracking = \AdButler\VASTTracking::retrieve( 1554 );

$vASTTracking->banner_id = 2579;
$vASTTracking->type = "midpoint";
$vASTTracking->link = "http://www.google.com";

$vASTTracking->save();

echo $vASTTracking;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var updateData = {
  "banner_id": 2579,
  "type": "midpoint",
  "link": "http://www.google.com"
};

// using callbacks
adbutler.vastTracking.update(1554, updateData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastTracking.update(1554, updateData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "vast_tracking",
  "self": "/v1/vast_tracking/1554",
  "id": 1554,
  "banner_id": 2579,
  "type": "midpoint",
  "link": "http://www.google.com"
}
AdButler\VASTTracking JSON: {
  "object": "vast_tracking",
  "self": "/v1/vast_tracking/1554",
  "id": 1554,
  "banner_id": 2579,
  "type": "midpoint",
  "link": "http://www.google.com"
}

You can update a specific VAST tracking by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the VAST tracking creation request.

Field Type Description

banner_id

integer

The ID of the VAST Banner that your tracking events will be attached to.

type

string

The event type to track. One of: "creativeView", "clicks", "start", "firstQuartile", "midpoint", "thirdQuartile", "complete", "mute", "unmute", "pause", "rewind", "resume", "fullscreen", "exitFullScreen", "companionClicks1", "companionClicks2", "companionClicks3", "companionClicks4", "companionClicks5", "companionViews1", "companionViews2", "companionViews3", "companionViews4", "companionViews5", "nlCreativeView", "expand", "collapse".

link

string

Your URL to be pinged at the time of the event.

Returns

Returns a vast_tracking object if the request succeeded, or an error if something went terribly wrong.

Delete a VAST Tracking

Definition

DELETE https://api.adbutler.com/v1/vast-tracking/{TRACKING-ID}
\AdButler\VASTTracking->delete()
adbutler.vastTracking.delete()

Example Request

curl "https://api.adbutler.com/v1/vast-tracking/1554" \
  -H "Authorization: Basic {API_KEY}" \
  -X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTTracking = \AdButler\VASTTracking::retrieve( 1554 );
$vASTTracking->delete();

echo $vASTTracking;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastTracking.delete(1554, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastTracking.delete(1554).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "id": 1554,
  "delete": true
}
AdButler\VASTTracking JSON: {
  "id": 1554,
  "delete": true
}

Permanently deletes a VAST tracking. if successful, this operation cannot be undone so be very sure when deleting one.

Returns

Returns a VAST tracking ID if the request succeeded, or an error if something went terribly wrong.

List all VAST Tracking

Definition

GET https://api.adbutler.com/v1/vast-tracking
\AdButler\VASTTracking::retrieveAll()
adbutler.vastTracking.list()

Example Request

curl "https://api.adbutler.com/v1/vast-tracking?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$vASTTracking = \AdButler\VASTTracking::retrieveAll(array(
  "limit" => 2
));

echo $vASTTracking;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.vastTracking.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.vastTracking.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/vast-tracking",
  "data": [
    {
      "object": "vast_tracking",
      "self": "/v1/vast_tracking/1493",
      "id": 1493,
      "banner_id": 2553,
      "type": "midpoint",
      "link": "http://www.google.com"
    },
    {
      "object": "vast_tracking",
      "self": "/v1/vast_tracking/1494",
      "id": 1494,
      "banner_id": 2554,
      "type": "midpoint",
      "link": "http://www.google.com"
    }
  ]
}
AdButler\VASTTracking JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/vast-tracking",
  "data": [
    {
      "object": "vast_tracking",
      "self": "/v1/vast_tracking/1493",
      "id": 1493,
      "banner_id": 2553,
      "type": "midpoint",
      "link": "http://www.google.com"
    },
    {
      "object": "vast_tracking",
      "self": "/v1/vast_tracking/1494",
      "id": 1494,
      "banner_id": 2554,
      "type": "midpoint",
      "link": "http://www.google.com"
    }
  ]
}

Returns a list of all the VAST tracking. Most recent VAST tracking appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is a vast_tracking object, and if no objects were found the list will be empty.


Channels

Introduction

Channels allow advertisers to easily assign their campaigns to multiple zones usually having a particular focus (e.g sports) and perhaps owned by different publishers. This is desirable when a campaign with the same assignment settings is to be assigned to a large number of zones.

The channel response object has the following fields.

Example Response

{
  "object": "channel",
  "self": "/v1/channels/866",
  "id": 866,
  "name": "Demo Channel",
  "priority": "standard",
  "zones": [
    {
      "id": 104144,
      "type": "banner_zone"
    }
  ]
}
AdButler\Channel JSON: {
  "object": "channel",
  "self": "/v1/channels/866",
  "id": 866,
  "name": "Demo Channel",
  "priority": "standard",
  "zones": [
    {
      "id": 104144,
      "type": "banner_zone"
    }
  ]
}
Attributes Type Description

object

string

A string denoting the object type which is always channel for the current resource.

self

string

The relative URL of the current resource which is always of the form /v1/channels/{CHANNEL_ID}.

id

integer

The current resource identifier (ID).

name

string

A descriptive name of the channel.

priority

string

The serving priority of the channel.

zones

array/null

The list of zones assigned to the current resource.

Create a channel

Definition

POST https://api.adbutler.com/v1/channels
\AdButler\Channel::create()
adbutler.channels.create()

Example Request

curl "https://api.adbutler.com/v1/channels" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{  
        "name": "Demo Channel",
        "priority": "standard"
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$channel = \AdButler\Channel::create(array(
  "name" => "Demo Channel",
  "priority" => "standard"
));

echo $channel;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var postData = {
  "name": "Demo Channel",
  "priority": "standard"
};

// using callbacks
adbutler.channels.create(postData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.channels.create(postData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "channel",
  "self": "/v1/channels/866",
  "id": 866,
  "name": "Demo Channel",
  "priority": "standard",
  "zones": [
    {
      "id": 104144,
      "type": "banner_zone"
    }
  ]
}
AdButler\Channel JSON: {
  "object": "channel",
  "self": "/v1/channels/866",
  "id": 866,
  "name": "Demo Channel",
  "priority": "standard",
  "zones": [
    {
      "id": 104144,
      "type": "banner_zone"
    }
  ]
}

Creates a new channel.

Field Type Description

name*

string

A descriptive name of the channel.

priority

string

Priority allows you to prefer serving of some ads over others in a channel.

Possible values in descending order are "sponsorship", "standard", "network", "bulk" and "house". Defaults to "standard".

* = required field

Returns

Returns a channel object if the request succeeded, or an error if something went terribly wrong.

Retrieve a channel

Definition

GET https://api.adbutler.com/v1/channels/{CHANNEL-ID}
\AdButler\Channel::retrieve()
adbutler.channels.retrieve()

Example Request

curl "https://api.adbutler.com/v1/channels/866" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$channel = \AdButler\Channel::retrieve( 866 );

echo $channel;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.channels.read(866, function(err, response) {
  console.log(response);
});

// using promises
adbutler.channels.read(866).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "channel",
  "self": "/v1/channels/866",
  "id": 866,
  "name": "Demo Channel",
  "priority": "standard",
  "zones": [
    {
      "id": 104144,
      "type": "banner_zone"
    }
  ]
}
AdButler\Channel JSON: {
  "object": "channel",
  "self": "/v1/channels/866",
  "id": 866,
  "name": "Demo Channel",
  "priority": "standard",
  "zones": [
    {
      "id": 104144,
      "type": "banner_zone"
    }
  ]
}

You can retrieve the information about an existing channel by giving the channel ID that was returned in the channel object upon creation. You will see at the most 10 channels in the response. You can change this default limit by appending ?limit=25 if you want this request to return 25 channels.

Returns

Returns a channel object if the request succeeded, or an error if something went terribly wrong.

Update a channel

Definition

PUT https://api.adbutler.com/v1/channels/{CHANNEL-ID}
\AdButler\Channel->save()
adbutler.channels.update()

Example Request

curl "https://api.adbutler.com/v1/channels/866" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{  
        "name": "Demo Channel",
        "priority": "standard"
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$channel = \AdButler\Channel::retrieve( 866 );

$channel->name = "Demo Channel";
$channel->priority = "standard";

$channel->save();

echo $channel;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var updateData = {
  "name": "Demo Channel",
  "priority": "standard"
};

// using callbacks
adbutler.channels.update(866, updateData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.channels.update(866, updateData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "channel",
  "self": "/v1/channels/866",
  "id": 866,
  "name": "Demo Channel",
  "priority": "standard",
  "zones": [
    {
      "id": 104144,
      "type": "banner_zone"
    }
  ]
}
AdButler\Channel JSON: {
  "object": "channel",
  "self": "/v1/channels/866",
  "id": 866,
  "name": "Demo Channel",
  "priority": "standard",
  "zones": [
    {
      "id": 104144,
      "type": "banner_zone"
    }
  ]
}

You can update a specific channel by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the channel creation request.

Field Type Description

name

string

A descriptive name of the channel.

priority

string

Priority allows you to prefer serving of some ads over others in a channel.

Possible values in descending order are "sponsorship", "standard", "network", "bulk" and "house". Defaults to "standard".

Returns

Returns a channel object if the request succeeded, or an error if something went terribly wrong.

Delete a channel

Definition

DELETE https://api.adbutler.com/v1/channels/{CHANNEL-ID}
\AdButler\Channel->delete()
adbutler.channels.delete()

Example Request

curl "https://api.adbutler.com/v1/channels/866" \
  -H "Authorization: Basic {API_KEY}" \
  -X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$channel = \AdButler\Channel::retrieve( 866 );
$channel->delete();

echo $channel;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.channels.delete(866, function(err, response) {
  console.log(response);
});

// using promises
adbutler.channels.delete(866).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "id": 866,
  "delete": true
}
AdButler\Channel JSON: {
  "id": 866,
  "delete": true
}

Permanently deletes a channel. If successful, this operation cannot be undone so be very sure when deleting one.

Returns

Returns a channel ID if the request succeeded, or an error if something went terribly wrong.

List all channels

Definition

GET https://api.adbutler.com/v1/channels
\AdButler\Channel::retrieveAll()
adbutler.channels.list()

Example Request

curl "https://api.adbutler.com/v1/channels?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$channel = \AdButler\Channel::retrieveAll(array(
  "limit" => 2
));

echo $channel;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.channels.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.channels.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/channels",
  "data": [
    {
      "object": "channel",
      "self": "/v1/channels/853",
      "id": 853,
      "name": "Demo Channel",
      "priority": "standard",
      "zones": null
    },
    {
      "object": "channel",
      "self": "/v1/channels/852",
      "id": 852,
      "name": "Demo Channel",
      "priority": "standard",
      "zones": null
    }
  ]
}
AdButler\Channel JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/channels",
  "data": [
    {
      "object": "channel",
      "self": "/v1/channels/853",
      "id": 853,
      "name": "Demo Channel",
      "priority": "standard",
      "zones": null
    },
    {
      "object": "channel",
      "self": "/v1/channels/852",
      "id": 852,
      "name": "Demo Channel",
      "priority": "standard",
      "zones": null
    }
  ]
}

Returns a list of all the channels. Most recent channels appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is a channel object, and if no objects were found the list will be empty.


Channel Zone Assignments

Introduction

A channel zone assignment represents the relationship between a channel and a zone.

The channel_zone_assignment response object has the following fields.

Example Response

{
  "object": "channel_zone_assignment",
  "self": "/v1/channel-zone-assignments/20185",
  "id": 20185,
  "channel": 866,
  "zone": {
    "id": 104144,
    "type": "banner_zone"
  }
}
AdButler\ChannelZoneAssignment JSON: {
  "object": "channel_zone_assignment",
  "self": "/v1/channel-zone-assignments/20185",
  "id": 20185,
  "channel": 866,
  "zone": {
    "id": 104144,
    "type": "banner_zone"
  }
}
Field Type Description

object

string

A string denoting the object type which is always channel_zone_assignment for the current resource.

self

string

The relative URL of the current resource which is always of the form /v1/channel-zone-assignments/{CHANNEL_ZONE_ASSIGNMENT_ID}.

id

integer

The current resource identifier (ID).

channel

integer

The channel identifier (ID).

zone

array

An object containing banner, email, or text zone identifier (ID) and type.

Create a channel zone assignment

Definition

POST https://api.adbutler.com/v1/channel-zone-assignments
\AdButler\ChannelZoneAssignment::create()
adbutler.channel-zone-assignments.create()

Example Request

curl "https://api.adbutler.com/v1/channel-zone-assignments" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{  
        "channel": 866,
        "zone": 
                {
                        id: 104144,
                        type: "banner_zone"
                }
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$channelZoneAssignment = \AdButler\ChannelZoneAssignment::create(array(
  "channel" => 866,
  "zone" => 
    [
      id => 104144,
      type => "banner_zone"
    ]
));

echo $channelZoneAssignment;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var postData = {
  "channel": 866,
  "zone": 
    {
      id: 104144,
      type: "banner_zone"
    }
};

// using callbacks
adbutler.channel-zone-assignments.create(postData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.channel-zone-assignments.create(postData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "channel_zone_assignment",
  "self": "/v1/channel-zone-assignments/20185",
  "id": 20185,
  "channel": 866,
  "zone": {
    "id": 104144,
    "type": "banner_zone"
  }
}
AdButler\ChannelZoneAssignment JSON: {
  "object": "channel_zone_assignment",
  "self": "/v1/channel-zone-assignments/20185",
  "id": 20185,
  "channel": 866,
  "zone": {
    "id": 104144,
    "type": "banner_zone"
  }
}

Creates a new channel zone assignment.

Field Type Description

channel*

integer

The channel identifier (ID) to which you wish to assign the zones.

zone*

object

An object containing banner, email, or text zone identifier (ID) and type.

* = required field

Returns

Returns a channel_zone_assignment object if the request succeeded, or an error if something went terribly wrong.

Retrieve a channel zone assignment

Definition

GET https://api.adbutler.com/v1/channel-zone-assignments/{CHANNEL-ZONE-ASSIGNMENT-ID}
\AdButler\ChannelZoneAssignment::retrieve()
adbutler.channel-zone-assignments.retrieve()

Example Request

curl "https://api.adbutler.com/v1/channel-zone-assignments/20185" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$channelZoneAssignment = \AdButler\ChannelZoneAssignment::retrieve( 20185 );

echo $channelZoneAssignment;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.channel-zone-assignments.read(20185, function(err, response) {
  console.log(response);
});

// using promises
adbutler.channel-zone-assignments.read(20185).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "channel_zone_assignment",
  "self": "/v1/channel-zone-assignments/20185",
  "id": 20185,
  "channel": 866,
  "zone": {
    "id": 104144,
    "type": "banner_zone"
  }
}
AdButler\ChannelZoneAssignment JSON: {
  "object": "channel_zone_assignment",
  "self": "/v1/channel-zone-assignments/20185",
  "id": 20185,
  "channel": 866,
  "zone": {
    "id": 104144,
    "type": "banner_zone"
  }
}

You can retrieve the information about an existing channel zone assignment by giving the channel zone assignment ID that was returned in the channel zone assignment object upon creation. You will see at the most 10 channel zone assignments in the response. You can change this default limit by appending ?limit=25 if you want this request to return 25 channel zone assignments.

Returns

Returns a channel_zone_assignment object if the request succeeded, or an error if something went terribly wrong.

Delete a channel zone assignment

Definition

DELETE https://api.adbutler.com/v1/channel-zone-assignments/{CHANNEL-ZONE-ASSIGNMENT-ID}
\AdButler\ChannelZoneAssignment->delete()
adbutler.channel-zone-assignments.delete()

Example Request

curl "https://api.adbutler.com/v1/channel-zone-assignments/20185" \
  -H "Authorization: Basic {API_KEY}" \
  -X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$channelZoneAssignment = \AdButler\ChannelZoneAssignment::retrieve( 20185 );
$channelZoneAssignment->delete();

echo $channelZoneAssignment;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.channel-zone-assignments.delete(20185, function(err, response) {
  console.log(response);
});

// using promises
adbutler.channel-zone-assignments.delete(20185).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "id": 20185,
  "delete": true
}
AdButler\ChannelZoneAssignment JSON: {
  "id": 20185,
  "delete": true
}

Permanently deletes a channel zone assignment. If successful, this operation cannot be undone so be very sure when deleting one.

Returns

Returns a channel zone assignment ID if the request succeeded, or an error if something went terribly wrong.

List all channel zone assignments

Definition

GET https://api.adbutler.com/v1/channel-zone-assignments
\AdButler\ChannelZoneAssignment::retrieveAll()
adbutler.channel-zone-assignments.list()

Example Request

curl "https://api.adbutler.com/v1/channel-zone-assignments?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$channelZoneAssignment = \AdButler\ChannelZoneAssignment::retrieveAll(array(
  "limit" => 2
));

echo $channelZoneAssignment;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.channel-zone-assignments.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.channel-zone-assignments.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/channel-zone-assignments",
  "data": [
    {
      "object": "channel_zone_assignment",
      "self": "/v1/channel-zone-assignments/130",
      "id": 130,
      "channel": 161,
      "zone": {
        "id": 87208,
        "type": "banner_zone"
      }
    },
    {
      "object": "channel_zone_assignment",
      "self": "/v1/channel-zone-assignments/135",
      "id": 135,
      "channel": 161,
      "zone": {
        "id": 87209,
        "type": "banner_zone"
      }
    }
  ]
}
AdButler\ChannelZoneAssignment JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/channel-zone-assignments",
  "data": [
    {
      "object": "channel_zone_assignment",
      "self": "/v1/channel-zone-assignments/130",
      "id": 130,
      "channel": 161,
      "zone": {
        "id": 87208,
        "type": "banner_zone"
      }
    },
    {
      "object": "channel_zone_assignment",
      "self": "/v1/channel-zone-assignments/135",
      "id": 135,
      "channel": 161,
      "zone": {
        "id": 87209,
        "type": "banner_zone"
      }
    }
  ]
}

Returns a list of all the channel zone assignments. Most recent channel zone assignments appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is a channel_zone_assignment object, and if no objects were found the list will be empty.


Managers

Introduction

A manager is an individual whom you wish to delegate some responsibility of managing your AdButler account. You can grant as much or as little access based on your needs. Managers can be granted permissions to add and manage other managers, advertisers, or publishers.

The manager response object has the following fields.

Example Response

{
  "object": "manager",
  "self": "/v1/managers/608",
  "id": 608,
  "can_manage_links": true,
  "can_manage_media": true,
  "can_manage_targets": true,
  "can_manage_users": true,
  "created_date": "2018-11-28 11:49:46",
  "email": "demo.manager@adbutler.com",
  "last_accessed": null,
  "name": "Demo Manager",
  "notes": "",
  "position": "some company",
  "publisher_access": "none",
  "publisher_access_list": [],
  "statistics_access": "all"
}
AdButler\Manager JSON: {
  "object": "manager",
  "self": "/v1/managers/608",
  "id": 608,
  "can_manage_links": true,
  "can_manage_media": true,
  "can_manage_targets": true,
  "can_manage_users": true,
  "created_date": "2018-11-28 11:49:46",
  "email": "demo.manager@adbutler.com",
  "last_accessed": null,
  "name": "Demo Manager",
  "notes": "",
  "position": "some company",
  "publisher_access": "none",
  "publisher_access_list": [],
  "statistics_access": "all"
}
Field Type Description

object

string

A string denoting the object type which is always manager for the current resource.

self

string

The relative URL of the current resource which is always of the form /v1/managers/{MANAGER_ID}.

id

integer

The current resource identifier (ID).

can_manage_links

boolean

Whether to allow managing hypermedia links.

can_manage_media

boolean

Whether to allow managing various media.

can_manage_targets

boolean

Whether to allow this user to managing various ad targeting features.

can_manage_users

boolean

Whether to allow managing other accounts.

created_date

string

The date and time when this account was created.

email

string

A valid email of the manager.

last_accessed

string

The date and time when this account was last accessed.

name

string

Name of the manager.

notes

string

Aditional notes or information about the manager.

position

string

Position of the manager in the organization.

publisher_access

string

Whether to allow access to some or all of the publishers.

publisher_access_list

array

The list of publishers this manager has been granted access to.

statistics_access

string

Whether to allow viewing statistics or not.

Create a manager

Definition

POST https://api.adbutler.com/v1/managers
\AdButler\Manager::create()
adbutler.managers.create()

Example Request

curl "https://api.adbutler.com/v1/managers" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{  
        "can_manage_links": true,
        "can_manage_media": true,
        "can_manage_users": true,
        "email": "demo.manager@adbutler.com",
        "name": "Demo Manager",
        "notes": "",
        "position": "some company"
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$manager = \AdButler\Manager::create(array(
  "can_manage_links" => true,
  "can_manage_media" => true,
  "can_manage_users" => true,
  "email" => "demo.manager@adbutler.com",
  "name" => "Demo Manager",
  "notes" => "",
  "position" => "some company"
));

echo $manager;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var postData = {
  "can_manage_links": true,
  "can_manage_media": true,
  "can_manage_users": true,
  "email": "demo.manager@adbutler.com",
  "name": "Demo Manager",
  "notes": "",
  "position": "some company"
};

// using callbacks
adbutler.managers.create(postData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.managers.create(postData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "manager",
  "self": "/v1/managers/608",
  "id": 608,
  "can_manage_links": true,
  "can_manage_media": true,
  "can_manage_targets": true,
  "can_manage_users": true,
  "created_date": "2018-11-28 11:49:46",
  "email": "demo.manager@adbutler.com",
  "last_accessed": null,
  "name": "Demo Manager",
  "notes": "",
  "position": "some company",
  "publisher_access": "none",
  "publisher_access_list": [],
  "statistics_access": "all"
}
AdButler\Manager JSON: {
  "object": "manager",
  "self": "/v1/managers/608",
  "id": 608,
  "can_manage_links": true,
  "can_manage_media": true,
  "can_manage_targets": true,
  "can_manage_users": true,
  "created_date": "2018-11-28 11:49:46",
  "email": "demo.manager@adbutler.com",
  "last_accessed": null,
  "name": "Demo Manager",
  "notes": "",
  "position": "some company",
  "publisher_access": "none",
  "publisher_access_list": [],
  "statistics_access": "all"
}

Creates a new manager.

Field Type Description

name*

string

The name of the manager.

email*

string

A valid email of the manager.

password

string

A password for the manager account preferrable including uppercase letters and numbers.

position

string

The position of the manager in the organization.

notes

string

Aditional notes or information about the manager.

can_manage_links

boolean

Whether to allow managing hypermedia links.

can_manage_media

boolean

Whether to allow managing various media.

can_manage_targets

boolean

Whether to allow this user to managing various ad targeting features.

can_manage_users

boolean

Whether to allow managing other accounts.

publisher_access

string

Whether to allow this manager access to some or all publishers in the organization. The value must be one of all, specific, or none.

publisher_access_list

array

The list of publishers to give access to. This field must only be given when publisher_access is specific.

statistics_access

string

Whether to allow viewing the assigned ad serving statistics. The value must be one of all, specific, or none.

* = required field

Returns

Returns a manager object if the request succeeded, or an error if something went terribly wrong.

Retrieve a manager

Definition

GET https://api.adbutler.com/v1/managers/{MANAGER-ID}
\AdButler\Manager::retrieve()
adbutler.managers.retrieve()

Example Request

curl "https://api.adbutler.com/v1/managers/608" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$manager = \AdButler\Manager::retrieve( 608 );

echo $manager;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.managers.read(608, function(err, response) {
  console.log(response);
});

// using promises
adbutler.managers.read(608).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "manager",
  "self": "/v1/managers/608",
  "id": 608,
  "can_manage_links": true,
  "can_manage_media": true,
  "can_manage_targets": true,
  "can_manage_users": true,
  "created_date": "2018-11-28 11:49:46",
  "email": "demo.manager@adbutler.com",
  "last_accessed": null,
  "name": "Demo Manager",
  "notes": "",
  "position": "some company",
  "publisher_access": "none",
  "publisher_access_list": [],
  "statistics_access": "all"
}
AdButler\Manager JSON: {
  "object": "manager",
  "self": "/v1/managers/608",
  "id": 608,
  "can_manage_links": true,
  "can_manage_media": true,
  "can_manage_targets": true,
  "can_manage_users": true,
  "created_date": "2018-11-28 11:49:46",
  "email": "demo.manager@adbutler.com",
  "last_accessed": null,
  "name": "Demo Manager",
  "notes": "",
  "position": "some company",
  "publisher_access": "none",
  "publisher_access_list": [],
  "statistics_access": "all"
}

You can retrieve the information about an existing manager by giving the manager ID that was returned in the manager object upon creation.

Returns

Returns a manager object if the request succeeded, or an error if something went terribly wrong.

Update a manager

Definition

PUT https://api.adbutler.com/v1/managers/{MANAGER-ID}
\AdButler\Manager->save()
adbutler.managers.update()

Example Request

curl "https://api.adbutler.com/v1/managers/608" \
  -H "Authorization: Basic {API_KEY}" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{  
        "can_manage_links": true,
        "can_manage_media": true,
        "can_manage_users": true,
        "email": "demo.manager@adbutler.com",
        "name": "Demo Manager",
        "notes": "",
        "position": "some company"
      }'
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$manager = \AdButler\Manager::retrieve( 608 );

$manager->can_manage_links = true;
$manager->can_manage_media = true;
$manager->can_manage_users = true;
$manager->email = "demo.manager@adbutler.com";
$manager->name = "Demo Manager";
$manager->notes = "";
$manager->position = "some company";

$manager->save();

echo $manager;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

var updateData = {
  "can_manage_links": true,
  "can_manage_media": true,
  "can_manage_users": true,
  "email": "demo.manager@adbutler.com",
  "name": "Demo Manager",
  "notes": "",
  "position": "some company"
};

// using callbacks
adbutler.managers.update(608, updateData, function(err, response) {
  console.log(response);
});

// using promises
adbutler.managers.update(608, updateData).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "manager",
  "self": "/v1/managers/608",
  "id": 608,
  "can_manage_links": true,
  "can_manage_media": true,
  "can_manage_targets": true,
  "can_manage_users": true,
  "created_date": "2018-11-28 11:49:46",
  "email": "demo.manager@adbutler.com",
  "last_accessed": null,
  "name": "Demo Manager",
  "notes": "",
  "position": "some company",
  "publisher_access": "none",
  "publisher_access_list": [],
  "statistics_access": "all"
}
AdButler\Manager JSON: {
  "object": "manager",
  "self": "/v1/managers/608",
  "id": 608,
  "can_manage_links": true,
  "can_manage_media": true,
  "can_manage_targets": true,
  "can_manage_users": true,
  "created_date": "2018-11-28 11:49:46",
  "email": "demo.manager@adbutler.com",
  "last_accessed": null,
  "name": "Demo Manager",
  "notes": "",
  "position": "some company",
  "publisher_access": "none",
  "publisher_access_list": [],
  "statistics_access": "all"
}

You can update a specific manager account by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the manager creation request.

Field Type Description

name

string

The name of the manager.

email

string

A valid email of the manager.

password

string

A password for the manager account preferrable including uppercase letters and numbers.

position

string

The position of the manager in the organization.

notes

string

Aditional notes or information about the manager.

can_manage_links

boolean

Whether to allow managing hypermedia links.

can_manage_media

boolean

Whether to allow managing various media.

can_manage_targets

boolean

Whether to allow this user to managing various ad targeting features.

can_manage_users

boolean

Whether to allow managing other accounts.

publisher_access

string

Whether to allow this manager access to some or all publishers in the organization. The value must be one of all, specific, or none.

publisher_access_list

array

The list of publishers to give access to. This field must only be given when publisher_access is specific.

statistics_access

string

Whether to allow viewing the assigned ad serving statistics. The value must be one of all, specific, or none.

Returns

Returns a manager object if the request succeeded, or an error if something went terribly wrong.

Delete a manager

Definition

DELETE https://api.adbutler.com/v1/managers/{MANAGER-ID}
\AdButler\Manager->delete()
adbutler.managers.delete()

Example Request

curl "https://api.adbutler.com/v1/managers/608" \
  -H "Authorization: Basic {API_KEY}" \
  -X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$manager = \AdButler\Manager::retrieve( 608 );
$manager->delete();

echo $manager;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.managers.delete(608, function(err, response) {
  console.log(response);
});

// using promises
adbutler.managers.delete(608).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "id": 608,
  "delete": true
}
AdButler\Manager JSON: {
  "id": 608,
  "delete": true
}

Permanently deletes a manager. if successful, this operation cannot be undone so be very sure when deleting one.

Returns

Returns a manager ID if the request succeeded, or an error if something went terribly wrong.

List all managers

Definition

GET https://api.adbutler.com/v1/managers
\AdButler\Manager::retrieveAll()
adbutler.managers.list()

Example Request

curl "https://api.adbutler.com/v1/managers?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$manager = \AdButler\Manager::retrieveAll(array(
  "limit" => 2
));

echo $manager;
var AdButler = require("adbutler");
     
var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.managers.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.managers.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/managers",
  "data": [
    {
      "object": "manager",
      "self": "/v1/managers/595",
      "id": 595,
      "can_manage_links": true,
      "can_manage_media": true,
      "can_manage_targets": true,
      "can_manage_users": true,
      "created_date": "2018-06-28 09:55:56",
      "email": "demo.manager@adbutler.com",
      "last_accessed": null,
      "name": "Demo Manager",
      "notes": "",
      "position": "some company",
      "publisher_access": "none",
      "publisher_access_list": [],
      "statistics_access": "all"
    },
    {
      "object": "manager",
      "self": "/v1/managers/596",
      "id": 596,
      "can_manage_links": true,
      "can_manage_media": true,
      "can_manage_targets": true,
      "can_manage_users": true,
      "created_date": "2018-06-28 10:16:20",
      "email": "demo.manager@adbutler.com",
      "last_accessed": null,
      "name": "Demo Manager",
      "notes": "",
      "position": "some company",
      "publisher_access": "none",
      "publisher_access_list": [],
      "statistics_access": "all"
    }
  ]
}
AdButler\Manager JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/managers",
  "data": [
    {
      "object": "manager",
      "self": "/v1/managers/595",
      "id": 595,
      "can_manage_links": true,
      "can_manage_media": true,
      "can_manage_targets": true,
      "can_manage_users": true,
      "created_date": "2018-06-28 09:55:56",
      "email": "demo.manager@adbutler.com",
      "last_accessed": null,
      "name": "Demo Manager",
      "notes": "",
      "position": "some company",
      "publisher_access": "none",
      "publisher_access_list": [],
      "statistics_access": "all"
    },
    {
      "object": "manager",
      "self": "/v1/managers/596",
      "id": 596,
      "can_manage_links": true,
      "can_manage_media": true,
      "can_manage_targets": true,
      "can_manage_users": true,
      "created_date": "2018-06-28 10:16:20",
      "email": "demo.manager@adbutler.com",
      "last_accessed": null,
      "name": "Demo Manager",
      "notes": "",
      "position": "some company",
      "publisher_access": "none",
      "publisher_access_list": [],
      "statistics_access": "all"
    }
  ]
}

Returns a list of all the manager accounts. Most recent manager accounts appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is a manager object, and if no objects were found the list will be empty.


Flexible Types

Introduction

Flexible types can be assigned to Banner Zones, Image Banners and Banner Campaigns.
A flexble type has a minimum and maximum size, and an aspect ratio which is always maintained.

Read more about them here

The flexible_type response object has the following fields.

Example Response

{
  "object": "flexible-zone-type",
  "self": "/v1/zones/flexible-types/1",
  "id": "1",
  "name": "2x1_xlarge",
  "min_width": 900,
  "min_height": 450,
  "max_width": 1800,
  "max_height": 900,
  "aspect_ratio": "2:1"
}
AdButler\FlexibleType JSON: {
  "object": "flexible-zone-type",
  "self": "/v1/zones/flexible-types/1",
  "id": 1,
  "name": "2x1_xlarge",
  "min_width": 900,
  "min_height": 450,
  "max_width": 1800,
  "max_height": 900,
  "aspect_ratio": "2:1"
}
Field Type Description

object

string

A string denoting the object type which is always flexible_type for the current resource.

self

string

The relative URL of the current resource which is always of the form /v1/zones/flexible-types/{FLEXIBLE_TYPE_ID}.

id

string

The current resource identifier (ID).

name

string

An IAB inspired description of the type of dimensions the Flexible Type has.

min_width

integer

The minimum width in pixels the ad can appear with on screen.

min_height

integer

The minimum height in pixels the ad can appear with on screen.

max_width

integer

The maximum width in pixels the ad can appear with on screen.

max_height

integer

The maxiumum height in pixels the ad can appear with on screen.

aspect_ratio

string

The aspect ratio of the ad, which will be maintained if the placement is resized.

Retrieve a Flexible Type

Definition

GET https://api.adbutler.com/v1/zones/flexible-types/{FLEXIBLE-TYPE-ID}
\AdButler\FlexibleType::retrieve()
adbutler.zones.flexible-types.isp.retrieve()

Example Request

curl "https://api.adbutler.com/v1/zones/flexible-types/1" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$flexibleType = \AdButler\FlexibleType::retrieve( 1 );

echo $flexibleType;
var AdButler = require("adbutler");

var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.zones.flexible-types.isp.read(1, function(err, response) {
  console.log(response);
});

// using promises
adbutler.zones.flexible-types.isp.read(1).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "flexible-zone-type",
  "self": "/v1/zones/flexible-types/1",
  "id": "1",
  "name": "2x1_xlarge",
  "min_width": 900,
  "min_height": 450,
  "max_width": 1800,
  "max_height": 900,
  "aspect_ratio": "2:1"
}
AdButler\FlexibleType JSON: {
  "object": "flexible-zone-type",
  "self": "/v1/zones/flexible-types/1",
  "id": 1,
  "name": "2x1_xlarge",
  "min_width": 900,
  "min_height": 450,
  "max_width": 1800,
  "max_height": 900,
  "aspect_ratio": "2:1"
}

You can retrieve the information about an existing Flexible Type by giving the Flexible Type ID that was returned in the Flexible Type object upon creation. You will see at the most 10 Flexible Types in the response. You can change this default limit by appending ?limit=25 if you want this request to return 25 Flexible Types.

Returns

Returns a flexible_type object if the request succeeded, or an error if something went terribly wrong.

List all Flexible Types

Definition

GET https://api.adbutler.com/v1/zones/flexible-types
\AdButler\FlexibleType::retrieveAll()
adbutler.zones.flexible-types.isp.list()

Example Request

curl "https://api.adbutler.com/v1/zones/flexible-types?limit=2" \
  -H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );

$flexibleType = \AdButler\FlexibleType::retrieveAll(array(
  "limit" => 2
));

echo $flexibleType;
var AdButler = require("adbutler");

var adbutler = new AdButler({
  apiKey: "{API_KEY}"
});

// using callbacks
adbutler.zones.flexible-types.isp.list({
  limit: 2
}, function(err, response) {
  console.log(response);
});

// using promises
adbutler.zones.flexible-types.isp.list({
  limit: 2
}).then( function(response) {
  console.log(response);
}, function(error) {
  console.log(error);
});

Example Response

{
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/zones/flexible-types",
  "data": [
    {
      "object": "flexible-zone-type",
      "self": "/v1/zones/flexible-types/1",
      "id": "1",
      "name": "2x1_xlarge",
      "min_width": 900,
      "min_height": 450,
      "max_width": 1800,
      "max_height": 900,
      "aspect_ratio": "2:1"
    },
    {
      "object": "flexible-zone-type",
      "self": "/v1/zones/flexible-types/2",
      "id": "2",
      "name": "2x1_small",
      "min_width": 300,
      "min_height": 150,
      "max_width": 450,
      "max_height": 225,
      "aspect_ratio": "2:1"
    }
  ]
}
AdButler\FlexibleType JSON: {
  "object": "list",
  "has_more": true,
  "limit": 2,
  "offset": 0,
  "url": "/v1/zones/flexible-types",
  "data": [
    {
      "object": "flexible-zone-type",
      "self": "/v1/zones/flexible-types/1",
      "id": 1,
      "name": "2x1_xlarge",
      "min_width": 900,
      "min_height": 450,
      "max_width": 1800,
      "max_height": 900,
      "aspect_ratio": "2:1"
    },
    {
      "object": "flexible-zone-type",
      "self": "/v1/zones/flexible-types/2",
      "id": 2,
      "name": "2x1_small",
      "min_width": 300,
      "min_height": 150,
      "max_width": 450,
      "max_height": 225,
      "aspect_ratio": "2:1"
    }
  ]
}

Returns a list of all the Flexible Types. Most recent Flexible Types appear first in the list.

Returns

Returns an object with a data property that contains a list of up to the specified limit and/or offset of objects. Each entry in data is an flexible_type object, and if no objects were found the list will be empty.