Get an AdButler API key by visiting the AdButler API Settings page (Settings → API Settings).
curl php node
Topics
Publishers
Header Bidding
Advertisers
Advertisements
Creatives
Placements
Targets
Statistics
VAST
Other

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.

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.

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\&