NOTICE: You're viewing documentation for an old version of our API. Check out the latest version here.
API Reference
API Endpoint
https://api.adbutler.com
https://github.com/adbutler/adbutler-php
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.
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 here 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 Android and iOS SDK 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 |
self |
string |
The relative URL of the current resource which is always of the form |
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. |
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. |
string |
The email address of the publisher which defaults to |
|
password |
string |
The password of the optional user account tied to this publisher. This field must be 8 or more characters. If left blank on publisher creation, a random password will be generated. |
can_admin_account |
boolean |
Whether to grant administrator privileges to the publisher. If |
can_approve_ads |
boolean |
Whether to allow publisher to approve or deny advertisements assigned to their zones. If |
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. |
string |
The email address of the publisher which defaults to |
|
password |
string |
The password of the optional user account tied to this publisher. This field must be 8 or more characters. If left blank on publisher creation, a random password will be generated. |
can_admin_account |
boolean |
Whether to grant administrator privileges to the publisher. If |
can_approve_ads |
boolean |
Whether to allow publisher to approve or deny advertisements assigned to their zones. If |
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 |
url |
string |
The relative URL of the current resource which is always of the form |
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 |
url |
string |
The relative URL of the current resource which is always of the form |
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 |
self |
string |
The relative URL of the current resource which is always of the form |
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 |
height* |
integer |
The height of the email zone which must correspond to the banner height (see common banner dimensions). The |
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 |
height |
integer |
The height of the email zone which must correspond to the banner height (see common banner dimensions). The |
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 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 |
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 |
url |
string |
The relative URL of the current resource which is always of the form |
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 |
self |
string |
The relative URL of the current resource which is always of the form |
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 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 |
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 |
url |
string |
The relative URL of the current resource which is always of the form |
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 |
self |
string |
The relative URL of the current resource which is always of the form |
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 |
self |
string |
The relative URL of the current resource which is always of the form |
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. |
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. |
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. |
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 |
url |
string |
The relative URL of the current resource which is always of the form |
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 |
url |
string |
The relative URL of the current resource which is always of the form |
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 |
self |
string |
The relative URL of the current resource which is always of the form |
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 |
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 |
url |
string |
The relative URL of the current resource which is always of the form |
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 |
self |
string |
The relative URL of the current resource which is always of the form |
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 |
active |
boolean |
Whether to actively serve ads in the zones ( |
* = 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 |
active |
boolean |
Whether to actively serve ads in the zones ( |
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.
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 |
self |
string |
The relative URL of the current resource which is always of the form |
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 |
title_alignment |
string |
How to orient the title text of the ad. Possible values are |
content_alignment |
string |
How to orient the text ad's content. Possible values are |
display_url_alignment |
string |
How to orient the displayed URL to the user. Possible values are |
* = 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 |
title_alignment |
string |
How to orient the title text of the ad. Possible values are |
content_alignment |
string |
How to orient the text ad's content. Possible values are |
display_url_alignment |
string |
How to orient the displayed URL to the user. Possible values are |
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 |
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 |
url |
string |
The relative URL of the current resource which is always of the form |
data |
array |
The data object containing the conversion tag. |
Returns a conv_tag
object if the request succeeded, or an error if something went terribly wrong.
Popups
List all popups
Definition
GET https://api.adbutler.com/v1/popups
\AdButler\Popup::retrieveAll()
adbutler.popups.list()
Example Request
curl "https://api.adbutler.com/v1/popups?limit=2" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$popup = \AdButler\Popup::retrieveAll(array(
"limit" => 2
));
echo $popup;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.popups.list({
limit: 2
}, function(err, response) {
console.log(response);
});
// using promises
adbutler.popups.list({
limit: 2
}).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/popups",
"data": [
{
"object": "image_popup",
"self": "/v1/popups/image/2222",
"id": 2222,
"creative": 234,
"creative_url": "http://www.smartballoon/images/balloon.jpg",
"height": 250,
"html_alt_text": "A big balloon",
"html_content_below": "",
"location": "https://your-target-site.com",
"name": "Demo Image Popup",
"popup_style": "over",
"title": "Ad Window",
"tracking_pixel": "",
"width": 300
},
{
"object": "flash_popup",
"self": "/v1/popups/flash/2223",
"id": 2223,
"creative": 45254,
"creative_url": null,
"flash_html": "<object width=\"300\" height=\"250\" id=\"movie_5474863\">\\r\\n<param name=\"wmode\" value=\"opaque\">\\r\\n<param name=\"quality\" value=\"high\">\\r\\n<param name=\"version\" value=\"7\">\\r\\n<param name=\"allowScriptAccess\" value=\"always\">\\r\\n<param name=\"movie\" value=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\">\\r\\n<embed width=\"300\" height=\"250\" src=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\" wmode=\"opaque\" quality=\"high\" version=\"7\" allowScriptAccess=\"always\" type=\"application/x-shockwave-flash\">\\r\\n</object>",
"height": 250,
"html_content_below": "",
"location": "https://your-target-site.com",
"mode": "opaque",
"name": "Demo Flash Popup",
"popup_style": "over",
"quality": "high",
"title": "Ad Window",
"tracking_pixel": "",
"version": 7,
"width": 300
}
]
}
AdButler\Popup JSON: {
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/popups",
"data": [
{
"object": "image_popup",
"self": "/v1/popups/image/2222",
"id": 2222,
"creative": 234,
"creative_url": "http://www.smartballoon/images/balloon.jpg",
"height": 250,
"html_alt_text": "A big balloon",
"html_content_below": "",
"location": "https://your-target-site.com",
"name": "Demo Image Popup",
"popup_style": "over",
"title": "Ad Window",
"tracking_pixel": "",
"width": 300
},
{
"object": "flash_popup",
"self": "/v1/popups/flash/2223",
"id": 2223,
"creative": 45254,
"creative_url": null,
"flash_html": "<object width=\"300\" height=\"250\" id=\"movie_5474863\">\\r\\n<param name=\"wmode\" value=\"opaque\">\\r\\n<param name=\"quality\" value=\"high\">\\r\\n<param name=\"version\" value=\"7\">\\r\\n<param name=\"allowScriptAccess\" value=\"always\">\\r\\n<param name=\"movie\" value=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\">\\r\\n<embed width=\"300\" height=\"250\" src=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\" wmode=\"opaque\" quality=\"high\" version=\"7\" allowScriptAccess=\"always\" type=\"application/x-shockwave-flash\">\\r\\n</object>",
"height": 250,
"html_content_below": "",
"location": "https://your-target-site.com",
"mode": "opaque",
"name": "Demo Flash Popup",
"popup_style": "over",
"quality": "high",
"title": "Ad Window",
"tracking_pixel": "",
"version": 7,
"width": 300
}
]
}
You can retrieve a list of all the popups regardless of their type. You can optionally restrict the fields that you are interested in retrieving by using the fields
query parameter.
Returns
Returns an object with a data
property that contains a list of up to the specified limit and/or offset of objects. Each entry in data
is an object, and if no objects were found the list will be empty.
Image Popups
Introduction
A popup banner can catch your users attention by causing a separate window to appear with an advertisement in it. These ads can appear behind or in front of the content currently being browsed.
Popups require an option in the zone they belong to do be enabled to take effect.
The image_popup
response object has the following fields.
Example Response
{
"object": "image_popup",
"self": "/v1/popups/image/2260",
"id": 2260,
"creative": 234,
"creative_url": "http://www.smartballoon/images/balloon.jpg",
"height": 250,
"html_alt_text": "A big balloon",
"html_content_below": "",
"location": "https://your-target-site.com",
"name": "Demo Image Popup",
"popup_style": "over",
"title": "Ad Window",
"tracking_pixel": "",
"width": 300
}
AdButler\ImagePopup JSON: {
"object": "image_popup",
"self": "/v1/popups/image/2260",
"id": 2260,
"creative": 234,
"creative_url": "http://www.smartballoon/images/balloon.jpg",
"height": 250,
"html_alt_text": "A big balloon",
"html_content_below": "",
"location": "https://your-target-site.com",
"name": "Demo Image Popup",
"popup_style": "over",
"title": "Ad Window",
"tracking_pixel": "",
"width": 300
}
Field | Type | Description |
---|---|---|
object |
string |
A string denoting the object type which is always |
self |
string |
The relative URL of the current resource which is always of the form |
id |
integer |
The current resource identifier (ID). |
creative |
integer |
The image creative identifier (ID) |
creative_url |
string |
The image creative URL. |
height |
integer |
Height of the popup |
html_alt_text |
string |
The alternate text to appear if the image fails to load |
html_content_below |
string |
HTML below the main HTML |
location |
string |
The location to redirect to |
name |
string |
Name of the Custom HTML Popup |
popup_style |
string |
Where the popup should appear |
title |
string |
Title of the popup |
tracking_pixel |
string |
The pixel URL |
width |
integer |
Width of the popup |
Create an image popup
Definition
POST https://api.adbutler.com/v1/popups/image
\AdButler\ImagePopup::create()
adbutler.popups.images.create()
Example Request
curl "https://api.adbutler.com/v1/popups/image" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"creative": 234,
"creative_url": "http://www.smartballoon/images/balloon.jpg",
"height": 250,
"html_alt_text": "A big balloon",
"html_content_below": "",
"location": "https://your-target-site.com",
"name": "Demo Image Popup",
"popup_style": "over",
"title": "Ad Window",
"tracking_pixel": "",
"width": 300
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$imagePopup = \AdButler\ImagePopup::create(array(
"creative" => 234,
"creative_url" => "http://www.smartballoon/images/balloon.jpg",
"height" => 250,
"html_alt_text" => "A big balloon",
"html_content_below" => "",
"location" => "https://your-target-site.com",
"name" => "Demo Image Popup",
"popup_style" => "over",
"title" => "Ad Window",
"tracking_pixel" => "",
"width" => 300
));
echo $imagePopup;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var postData = {
"creative": 234,
"creative_url": "http://www.smartballoon/images/balloon.jpg",
"height": 250,
"html_alt_text": "A big balloon",
"html_content_below": "",
"location": "https://your-target-site.com",
"name": "Demo Image Popup",
"popup_style": "over",
"title": "Ad Window",
"tracking_pixel": "",
"width": 300
};
// using callbacks
adbutler.popups.images.create(postData, function(err, response) {
console.log(response);
});
// using promises
adbutler.popups.images.create(postData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "image_popup",
"self": "/v1/popups/image/2260",
"id": 2260,
"creative": 234,
"creative_url": "http://www.smartballoon/images/balloon.jpg",
"height": 250,
"html_alt_text": "A big balloon",
"html_content_below": "",
"location": "https://your-target-site.com",
"name": "Demo Image Popup",
"popup_style": "over",
"title": "Ad Window",
"tracking_pixel": "",
"width": 300
}
AdButler\ImagePopup JSON: {
"object": "image_popup",
"self": "/v1/popups/image/2260",
"id": 2260,
"creative": 234,
"creative_url": "http://www.smartballoon/images/balloon.jpg",
"height": 250,
"html_alt_text": "A big balloon",
"html_content_below": "",
"location": "https://your-target-site.com",
"name": "Demo Image Popup",
"popup_style": "over",
"title": "Ad Window",
"tracking_pixel": "",
"width": 300
}
Creates a new image popup.
Field | Type | Description |
---|---|---|
name* |
string |
A descriptive name of the image popup. We recommend using a naming convention that is consistent, relevant, and clear. |
title* |
string |
The user visible title that will appear on the frame of the popup window. |
width* |
integer |
The width of the popup window containing the advertisement (typically the same width as the advertisement itself). |
height* |
integer |
The height of the popup window containing the advertisement (typically the same height as the advertisement itself). |
creative† |
integer |
The image creative identifier (ID). It must be a valid ID if no |
creative_url† |
integer |
Specify the URL of an image file (PNG, JPEG, or GIF). |
location |
string |
A URL indicating where you want the user to go when they click on the popup. This field can be left blank. |
tracking_pixel |
string |
A URL of an image, typically 1x1 pixel in size, intended for impression tracking purposes. It is loaded alongside the popup allowing an external system to monitor impressions. |
html_content_below |
string |
The HTML content to appear below the image banner. |
html_alt_text |
string |
Text to display if the image fails to load. This is intended for use by the Assistive Technologies. |
popup_style |
string |
Whether this popup should appear in front of the page or behind it. Possible values are |
* = required field
Returns
Returns an image_popup
object if the request succeeded, or an error if something went terribly wrong.
Retrieve an image popup
Definition
GET https://api.adbutler.com/v1/popups/image/{IMAGE-POPUP-ID}
\AdButler\ImagePopup::retrieve()
adbutler.popups.images.retrieve()
Example Request
curl "https://api.adbutler.com/v1/popups/image/2260" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$imagePopup = \AdButler\ImagePopup::retrieve( 2260 );
echo $imagePopup;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.popups.images.read(2260, function(err, response) {
console.log(response);
});
// using promises
adbutler.popups.images.read(2260).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "image_popup",
"self": "/v1/popups/image/2260",
"id": 2260,
"creative": 234,
"creative_url": "http://www.smartballoon/images/balloon.jpg",
"height": 250,
"html_alt_text": "A big balloon",
"html_content_below": "",
"location": "https://your-target-site.com",
"name": "Demo Image Popup",
"popup_style": "over",
"title": "Ad Window",
"tracking_pixel": "",
"width": 300
}
AdButler\ImagePopup JSON: {
"object": "image_popup",
"self": "/v1/popups/image/2260",
"id": 2260,
"creative": 234,
"creative_url": "http://www.smartballoon/images/balloon.jpg",
"height": 250,
"html_alt_text": "A big balloon",
"html_content_below": "",
"location": "https://your-target-site.com",
"name": "Demo Image Popup",
"popup_style": "over",
"title": "Ad Window",
"tracking_pixel": "",
"width": 300
}
You can retrieve the information about an existing image popup by giving the image popup ID that was returned in the image popup object upon creation. You will see at the most 10 image popups in the response. You can change this default limit by appending ?limit=25
if you want this request to return 25 popups_image.
Returns
Returns an image_popup
object if the request succeeded, or an error if something went terribly wrong.
Update an image popup
Definition
PUT https://api.adbutler.com/v1/popups/image/{IMAGE-POPUP-ID}
\AdButler\ImagePopup->save()
adbutler.popups.images.update()
Example Request
curl "https://api.adbutler.com/v1/popups/image/2260" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
"creative": 234,
"creative_url": "http://www.smartballoon/images/balloon.jpg",
"height": 250,
"html_alt_text": "A big balloon",
"html_content_below": "",
"location": "https://your-target-site.com",
"name": "Demo Image Popup",
"popup_style": "over",
"title": "Ad Window",
"tracking_pixel": "",
"width": 300
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$imagePopup = \AdButler\ImagePopup::retrieve( 2260 );
$imagePopup->creative = 234;
$imagePopup->creative_url = "http://www.smartballoon/images/balloon.jpg";
$imagePopup->height = 250;
$imagePopup->html_alt_text = "A big balloon";
$imagePopup->html_content_below = "";
$imagePopup->location = "https://your-target-site.com";
$imagePopup->name = "Demo Image Popup";
$imagePopup->popup_style = "over";
$imagePopup->title = "Ad Window";
$imagePopup->tracking_pixel = "";
$imagePopup->width = 300;
$imagePopup->save();
echo $imagePopup;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var updateData = {
"creative": 234,
"creative_url": "http://www.smartballoon/images/balloon.jpg",
"height": 250,
"html_alt_text": "A big balloon",
"html_content_below": "",
"location": "https://your-target-site.com",
"name": "Demo Image Popup",
"popup_style": "over",
"title": "Ad Window",
"tracking_pixel": "",
"width": 300
};
// using callbacks
adbutler.popups.images.update(2260, updateData, function(err, response) {
console.log(response);
});
// using promises
adbutler.popups.images.update(2260, updateData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "image_popup",
"self": "/v1/popups/image/2260",
"id": 2260,
"creative": 234,
"creative_url": "http://www.smartballoon/images/balloon.jpg",
"height": 250,
"html_alt_text": "A big balloon",
"html_content_below": "",
"location": "https://your-target-site.com",
"name": "Demo Image Popup",
"popup_style": "over",
"title": "Ad Window",
"tracking_pixel": "",
"width": 300
}
AdButler\ImagePopup JSON: {
"object": "image_popup",
"self": "/v1/popups/image/2260",
"id": 2260,
"creative": 234,
"creative_url": "http://www.smartballoon/images/balloon.jpg",
"height": 250,
"html_alt_text": "A big balloon",
"html_content_below": "",
"location": "https://your-target-site.com",
"name": "Demo Image Popup",
"popup_style": "over",
"title": "Ad Window",
"tracking_pixel": "",
"width": 300
}
You can update a specific image popup account by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the image popup creation request.
Field | Type | Description |
---|---|---|
name |
string |
A descriptive name of the image popup. We recommend using a naming convention that is consistent, relevant, and clear. |
title |
string |
The user visible title that will appear on the frame of the popup window. |
width |
integer |
The width of the popup window containing the advertisement (typically the same width as the advertisement itself). |
height |
integer |
The height of the popup window containing the advertisement (typically the same height as the advertisement itself). |
creative† |
integer |
The image creative identifier (ID). It must be a valid ID if no |
creative_url† |
integer |
Specify the URL of an image file (PNG, JPEG, or GIF). |
location |
string |
A URL indicating where you want the user to go when they click on the popup. This field can be left blank. |
tracking_pixel |
string |
A URL of an image, typically 1x1 pixel in size, intended for impression tracking purposes. It is loaded alongside the popup allowing an external system to monitor impressions. |
html_content_below |
string |
The HTML content to appear below the image banner. |
html_alt_text |
string |
Text to display if the image fails to load. This is intended for use by the Assistive Technologies. |
popup_style |
string |
Whether this popup should appear in front of the page or behind it. Possible values are |
Returns
Returns an image_popup
object if the request succeeded, or an error if something went terribly wrong.
Delete an image popup
Definition
DELETE https://api.adbutler.com/v1/popups/image/{IMAGE-POPUP-ID}
\AdButler\ImagePopup->delete()
adbutler.popups.images.delete()
Example Request
curl "https://api.adbutler.com/v1/popups/image/2260" \
-H "Authorization: Basic {API_KEY}" \
-X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$imagePopup = \AdButler\ImagePopup::retrieve( 2260 );
$imagePopup->delete();
echo $imagePopup;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.popups.images.delete(2260, function(err, response) {
console.log(response);
});
// using promises
adbutler.popups.images.delete(2260).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"id": 2260,
"delete": true
}
AdButler\ImagePopup JSON: {
"id": 2260,
"delete": true
}
Permanently deletes an image popup. if successful, this operation cannot be undone so be very sure when deleting one. Also immediately stops serving any ads belonging to this image popup account.
Returns
Returns an image popup ID if the request succeeded, or an error if something went terribly wrong.
List all image popups
Definition
GET https://api.adbutler.com/v1/popups/image
\AdButler\ImagePopup::retrieveAll()
adbutler.popups.images.list()
Example Request
curl "https://api.adbutler.com/v1/popups/image?limit=2" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$imagePopup = \AdButler\ImagePopup::retrieveAll(array(
"limit" => 2
));
echo $imagePopup;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.popups.images.list({
limit: 2
}, function(err, response) {
console.log(response);
});
// using promises
adbutler.popups.images.list({
limit: 2
}).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/popups/image",
"data": [
{
"object": "image_popup",
"self": "/v1/popups/image/2222",
"id": 2222,
"creative": 234,
"creative_url": "http://www.smartballoon/images/balloon.jpg",
"height": 250,
"html_alt_text": "A big balloon",
"html_content_below": "",
"location": "https://your-target-site.com",
"name": "Demo Image Popup",
"popup_style": "over",
"title": "Ad Window",
"tracking_pixel": "",
"width": 300
},
{
"object": "image_popup",
"self": "/v1/popups/image/2225",
"id": 2225,
"creative": 234,
"creative_url": "http://www.smartballoon/images/balloon.jpg",
"height": 250,
"html_alt_text": "A big balloon",
"html_content_below": "",
"location": "https://your-target-site.com",
"name": "Demo Image Popup",
"popup_style": "over",
"title": "Ad Window",
"tracking_pixel": "",
"width": 300
}
]
}
AdButler\ImagePopup JSON: {
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/popups/image",
"data": [
{
"object": "image_popup",
"self": "/v1/popups/image/2222",
"id": 2222,
"creative": 234,
"creative_url": "http://www.smartballoon/images/balloon.jpg",
"height": 250,
"html_alt_text": "A big balloon",
"html_content_below": "",
"location": "https://your-target-site.com",
"name": "Demo Image Popup",
"popup_style": "over",
"title": "Ad Window",
"tracking_pixel": "",
"width": 300
},
{
"object": "image_popup",
"self": "/v1/popups/image/2225",
"id": 2225,
"creative": 234,
"creative_url": "http://www.smartballoon/images/balloon.jpg",
"height": 250,
"html_alt_text": "A big balloon",
"html_content_below": "",
"location": "https://your-target-site.com",
"name": "Demo Image Popup",
"popup_style": "over",
"title": "Ad Window",
"tracking_pixel": "",
"width": 300
}
]
}
Returns a list of all the image popup accounts. Most recent image popup accounts appear first in the list.
Returns
Returns an object with a data
property that contains a list of up to the specified limit and/or offset of objects. Each entry in data
is an image_popup
object, and if no objects were found the list will be empty.
Flash Popups
Introduction
A popup banner can catch your users attention by causing a separate window to appear with an advertisement in it. These ads can appear behind or in front of the content currently being browsed.
Popups require an option in the zone they belong to do be enabled to take effect.
The flash_popup
response object has the following fields.
Example Response
{
"object": "flash_popup",
"self": "/v1/popups/flash/2261",
"id": 2261,
"creative": 45254,
"creative_url": null,
"flash_html": "<object width=\"300\" height=\"250\" id=\"movie_5474863\">\\r\\n<param name=\"wmode\" value=\"opaque\">\\r\\n<param name=\"quality\" value=\"high\">\\r\\n<param name=\"version\" value=\"7\">\\r\\n<param name=\"allowScriptAccess\" value=\"always\">\\r\\n<param name=\"movie\" value=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\">\\r\\n<embed width=\"300\" height=\"250\" src=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\" wmode=\"opaque\" quality=\"high\" version=\"7\" allowScriptAccess=\"always\" type=\"application/x-shockwave-flash\">\\r\\n</object>",
"height": 250,
"html_content_below": "",
"location": "https://your-target-site.com",
"mode": "opaque",
"name": "Demo Flash Popup",
"popup_style": "over",
"quality": "high",
"title": "Ad Window",
"tracking_pixel": "",
"version": 7,
"width": 300
}
AdButler\FlashPopup JSON: {
"object": "flash_popup",
"self": "/v1/popups/flash/2261",
"id": 2261,
"creative": 45254,
"creative_url": null,
"flash_html": "<object width=\"300\" height=\"250\" id=\"movie_5474863\">\\r\\n<param name=\"wmode\" value=\"opaque\">\\r\\n<param name=\"quality\" value=\"high\">\\r\\n<param name=\"version\" value=\"7\">\\r\\n<param name=\"allowScriptAccess\" value=\"always\">\\r\\n<param name=\"movie\" value=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\">\\r\\n<embed width=\"300\" height=\"250\" src=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\" wmode=\"opaque\" quality=\"high\" version=\"7\" allowScriptAccess=\"always\" type=\"application/x-shockwave-flash\">\\r\\n</object>",
"height": 250,
"html_content_below": "",
"location": "https://your-target-site.com",
"mode": "opaque",
"name": "Demo Flash Popup",
"popup_style": "over",
"quality": "high",
"title": "Ad Window",
"tracking_pixel": "",
"version": 7,
"width": 300
}
Field | Type | Description |
---|---|---|
object |
string |
A string denoting the object type which is always |
self |
string |
The relative URL of the current resource which is always of the form |
id |
integer |
The current resource identifier (ID). |
name |
string |
Name of the Custom HTML Popup |
title |
string |
Title of the popup |
location |
string |
The location to redirect to |
width |
integer |
Width of the popup |
height |
integer |
Height of the popup |
tracking_pixel |
string |
The pixel URL |
html_content_below |
string |
HTML below the main HTML |
popup_style |
string |
Where the popup should appear |
flash_html |
string |
The generated flash HTML |
creative |
integer |
The creative ID |
creative_url |
NULL |
The creative URL |
mode |
string |
Flash mode |
quality |
string |
Flash quality |
version |
integer |
Flash version |
Create a flash popup
Definition
POST https://api.adbutler.com/v1/popups/flash
\AdButler\FlashPopup::create()
adbutler.popups.flash.create()
Example Request
curl "https://api.adbutler.com/v1/popups/flash" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"creative": 45254,
"creative_url": null,
"height": 250,
"html_content_below": "",
"location": "https://your-target-site.com",
"mode": "opaque",
"name": "Demo Flash Popup",
"popup_style": "over",
"quality": "high",
"title": "Ad Window",
"tracking_pixel": "",
"version": 7,
"width": 300
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$flashPopup = \AdButler\FlashPopup::create(array(
"creative" => 45254,
"creative_url" => null,
"height" => 250,
"html_content_below" => "",
"location" => "https://your-target-site.com",
"mode" => "opaque",
"name" => "Demo Flash Popup",
"popup_style" => "over",
"quality" => "high",
"title" => "Ad Window",
"tracking_pixel" => "",
"version" => 7,
"width" => 300
));
echo $flashPopup;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var postData = {
"creative": 45254,
"creative_url": null,
"height": 250,
"html_content_below": "",
"location": "https://your-target-site.com",
"mode": "opaque",
"name": "Demo Flash Popup",
"popup_style": "over",
"quality": "high",
"title": "Ad Window",
"tracking_pixel": "",
"version": 7,
"width": 300
};
// using callbacks
adbutler.popups.flash.create(postData, function(err, response) {
console.log(response);
});
// using promises
adbutler.popups.flash.create(postData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "flash_popup",
"self": "/v1/popups/flash/2261",
"id": 2261,
"creative": 45254,
"creative_url": null,
"flash_html": "<object width=\"300\" height=\"250\" id=\"movie_5474863\">\\r\\n<param name=\"wmode\" value=\"opaque\">\\r\\n<param name=\"quality\" value=\"high\">\\r\\n<param name=\"version\" value=\"7\">\\r\\n<param name=\"allowScriptAccess\" value=\"always\">\\r\\n<param name=\"movie\" value=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\">\\r\\n<embed width=\"300\" height=\"250\" src=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\" wmode=\"opaque\" quality=\"high\" version=\"7\" allowScriptAccess=\"always\" type=\"application/x-shockwave-flash\">\\r\\n</object>",
"height": 250,
"html_content_below": "",
"location": "https://your-target-site.com",
"mode": "opaque",
"name": "Demo Flash Popup",
"popup_style": "over",
"quality": "high",
"title": "Ad Window",
"tracking_pixel": "",
"version": 7,
"width": 300
}
AdButler\FlashPopup JSON: {
"object": "flash_popup",
"self": "/v1/popups/flash/2261",
"id": 2261,
"creative": 45254,
"creative_url": null,
"flash_html": "<object width=\"300\" height=\"250\" id=\"movie_5474863\">\\r\\n<param name=\"wmode\" value=\"opaque\">\\r\\n<param name=\"quality\" value=\"high\">\\r\\n<param name=\"version\" value=\"7\">\\r\\n<param name=\"allowScriptAccess\" value=\"always\">\\r\\n<param name=\"movie\" value=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\">\\r\\n<embed width=\"300\" height=\"250\" src=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\" wmode=\"opaque\" quality=\"high\" version=\"7\" allowScriptAccess=\"always\" type=\"application/x-shockwave-flash\">\\r\\n</object>",
"height": 250,
"html_content_below": "",
"location": "https://your-target-site.com",
"mode": "opaque",
"name": "Demo Flash Popup",
"popup_style": "over",
"quality": "high",
"title": "Ad Window",
"tracking_pixel": "",
"version": 7,
"width": 300
}
Creates a new flash popup.
Field | Type | Description |
---|---|---|
name* |
string |
A descriptive name of the flash popup. We recommend using a naming convention that is consistent, relevant, and clear. |
title* |
string |
The user visible title that will appear on the frame of the popup window. |
width* |
string |
The width of the popup window containing the advertisement (typically the same width as the advertisement itself). |
height* |
string |
The height of the popup window containing the advertisement (typically the same height as the advertisement itself). |
creative† |
string |
The flash creative identifier (ID). It must be a valid ID if no creative_url is given. |
creative_url† |
string |
Specify the URL of a flash (SWF) file. |
location |
string |
A URL indicating where you want the user to go when they click on the popup. This field can be left blank. |
tracking_pixel |
string |
A URL of an image, typically 1x1 pixel in size, intended for impression tracking purposes. It is loaded alongside the popup allowing an external system to monitor impressions. |
html_content_below |
string |
The HTML content to appear below the flash banner. |
popup_style |
string |
Whether this popup should appear in front of the page or behind it. Possible values are |
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
More information can be found here. |
quality |
string |
Possible values are
More information can be found here. |
version |
string |
Flash player version number ranging between 5 and 100. Defaults to |
* = required field
Returns
Returns a flash_popup
object if the request succeeded, or an error if something went terribly wrong.
Retrieve a flash popup
Definition
GET https://api.adbutler.com/v1/popups/flash/{FLASH-POPUP-ID}
\AdButler\FlashPopup::retrieve()
adbutler.popups.flash.retrieve()
Example Request
curl "https://api.adbutler.com/v1/popups/flash/2261" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$flashPopup = \AdButler\FlashPopup::retrieve( 2261 );
echo $flashPopup;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.popups.flash.read(2261, function(err, response) {
console.log(response);
});
// using promises
adbutler.popups.flash.read(2261).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "flash_popup",
"self": "/v1/popups/flash/2261",
"id": 2261,
"creative": 45254,
"creative_url": null,
"flash_html": "<object width=\"300\" height=\"250\" id=\"movie_5474863\">\\r\\n<param name=\"wmode\" value=\"opaque\">\\r\\n<param name=\"quality\" value=\"high\">\\r\\n<param name=\"version\" value=\"7\">\\r\\n<param name=\"allowScriptAccess\" value=\"always\">\\r\\n<param name=\"movie\" value=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\">\\r\\n<embed width=\"300\" height=\"250\" src=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\" wmode=\"opaque\" quality=\"high\" version=\"7\" allowScriptAccess=\"always\" type=\"application/x-shockwave-flash\">\\r\\n</object>",
"height": 250,
"html_content_below": "",
"location": "https://your-target-site.com",
"mode": "opaque",
"name": "Demo Flash Popup",
"popup_style": "over",
"quality": "high",
"title": "Ad Window",
"tracking_pixel": "",
"version": 7,
"width": 300
}
AdButler\FlashPopup JSON: {
"object": "flash_popup",
"self": "/v1/popups/flash/2261",
"id": 2261,
"creative": 45254,
"creative_url": null,
"flash_html": "<object width=\"300\" height=\"250\" id=\"movie_5474863\">\\r\\n<param name=\"wmode\" value=\"opaque\">\\r\\n<param name=\"quality\" value=\"high\">\\r\\n<param name=\"version\" value=\"7\">\\r\\n<param name=\"allowScriptAccess\" value=\"always\">\\r\\n<param name=\"movie\" value=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\">\\r\\n<embed width=\"300\" height=\"250\" src=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\" wmode=\"opaque\" quality=\"high\" version=\"7\" allowScriptAccess=\"always\" type=\"application/x-shockwave-flash\">\\r\\n</object>",
"height": 250,
"html_content_below": "",
"location": "https://your-target-site.com",
"mode": "opaque",
"name": "Demo Flash Popup",
"popup_style": "over",
"quality": "high",
"title": "Ad Window",
"tracking_pixel": "",
"version": 7,
"width": 300
}
You can retrieve the information about an existing flash popup by giving the flash popup ID that was returned in the flash popup object upon creation. You will see at the most 10 flash popups in the response. You can change this default limit by appending ?limit=25
if you want this request to return 25 popups_flash.
Returns
Returns a flash_popup
object if the request succeeded, or an error if something went terribly wrong.
Update a flash popup
Definition
PUT https://api.adbutler.com/v1/popups/flash/{FLASH-POPUP-ID}
\AdButler\FlashPopup->save()
adbutler.popups.flash.update()
Example Request
curl "https://api.adbutler.com/v1/popups/flash/2261" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
"creative": 45254,
"creative_url": null,
"height": 250,
"html_content_below": "",
"location": "https://your-target-site.com",
"mode": "opaque",
"name": "Demo Flash Popup",
"popup_style": "over",
"quality": "high",
"title": "Ad Window",
"tracking_pixel": "",
"version": 7,
"width": 300
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$flashPopup = \AdButler\FlashPopup::retrieve( 2261 );
$flashPopup->creative = 45254;
$flashPopup->creative_url = null;
$flashPopup->height = 250;
$flashPopup->html_content_below = "";
$flashPopup->location = "https://your-target-site.com";
$flashPopup->mode = "opaque";
$flashPopup->name = "Demo Flash Popup";
$flashPopup->popup_style = "over";
$flashPopup->quality = "high";
$flashPopup->title = "Ad Window";
$flashPopup->tracking_pixel = "";
$flashPopup->version = 7;
$flashPopup->width = 300;
$flashPopup->save();
echo $flashPopup;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var updateData = {
"creative": 45254,
"creative_url": null,
"height": 250,
"html_content_below": "",
"location": "https://your-target-site.com",
"mode": "opaque",
"name": "Demo Flash Popup",
"popup_style": "over",
"quality": "high",
"title": "Ad Window",
"tracking_pixel": "",
"version": 7,
"width": 300
};
// using callbacks
adbutler.popups.flash.update(2261, updateData, function(err, response) {
console.log(response);
});
// using promises
adbutler.popups.flash.update(2261, updateData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "flash_popup",
"self": "/v1/popups/flash/2261",
"id": 2261,
"creative": 45254,
"creative_url": null,
"flash_html": "<object width=\"300\" height=\"250\" id=\"movie_5474863\">\\r\\n<param name=\"wmode\" value=\"opaque\">\\r\\n<param name=\"quality\" value=\"high\">\\r\\n<param name=\"version\" value=\"7\">\\r\\n<param name=\"allowScriptAccess\" value=\"always\">\\r\\n<param name=\"movie\" value=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\">\\r\\n<embed width=\"300\" height=\"250\" src=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\" wmode=\"opaque\" quality=\"high\" version=\"7\" allowScriptAccess=\"always\" type=\"application/x-shockwave-flash\">\\r\\n</object>",
"height": 250,
"html_content_below": "",
"location": "https://your-target-site.com",
"mode": "opaque",
"name": "Demo Flash Popup",
"popup_style": "over",
"quality": "high",
"title": "Ad Window",
"tracking_pixel": "",
"version": 7,
"width": 300
}
AdButler\FlashPopup JSON: {
"object": "flash_popup",
"self": "/v1/popups/flash/2261",
"id": 2261,
"creative": 45254,
"creative_url": null,
"flash_html": "<object width=\"300\" height=\"250\" id=\"movie_5474863\">\\r\\n<param name=\"wmode\" value=\"opaque\">\\r\\n<param name=\"quality\" value=\"high\">\\r\\n<param name=\"version\" value=\"7\">\\r\\n<param name=\"allowScriptAccess\" value=\"always\">\\r\\n<param name=\"movie\" value=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\">\\r\\n<embed width=\"300\" height=\"250\" src=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\" wmode=\"opaque\" quality=\"high\" version=\"7\" allowScriptAccess=\"always\" type=\"application/x-shockwave-flash\">\\r\\n</object>",
"height": 250,
"html_content_below": "",
"location": "https://your-target-site.com",
"mode": "opaque",
"name": "Demo Flash Popup",
"popup_style": "over",
"quality": "high",
"title": "Ad Window",
"tracking_pixel": "",
"version": 7,
"width": 300
}
You can update a specific flash popup account by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the flash popup creation request.
Field | Type | Description |
---|---|---|
name |
string |
A descriptive name of the flash popup. We recommend using a naming convention that is consistent, relevant, and clear. |
title |
string |
The user visible title that will appear on the frame of the popup window. |
width |
string |
The width of the popup window containing the advertisement (typically the same width as the advertisement itself). |
height |
string |
The height of the popup window containing the advertisement (typically the same height as the advertisement itself). |
creative† |
string |
The flash creative identifier (ID). It must be a valid ID if no creative_url is given. |
creative_url† |
string |
Specify the URL of a flash (SWF) file. |
location |
string |
A URL indicating where you want the user to go when they click on the popup. This field can be left blank. |
tracking_pixel |
string |
A URL of an image, typically 1x1 pixel in size, intended for impression tracking purposes. It is loaded alongside the popup allowing an external system to monitor impressions. |
html_content_below |
string |
The HTML content to appear below the flash banner. |
popup_style |
string |
Whether this popup should appear in front of the page or behind it. Possible values are |
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
More information can be found here. |
quality |
string |
Possible values are
More information can be found here. |
version |
string |
Flash player version number ranging between 5 and 100. Defaults to |
Returns
Returns a flash_popup
object if the request succeeded, or an error if something went terribly wrong.
Delete a flash popup
Definition
DELETE https://api.adbutler.com/v1/popups/flash/{FLASH-POPUP-ID}
\AdButler\FlashPopup->delete()
adbutler.popups.flash.delete()
Example Request
curl "https://api.adbutler.com/v1/popups/flash/2261" \
-H "Authorization: Basic {API_KEY}" \
-X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$flashPopup = \AdButler\FlashPopup::retrieve( 2261 );
$flashPopup->delete();
echo $flashPopup;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.popups.flash.delete(2261, function(err, response) {
console.log(response);
});
// using promises
adbutler.popups.flash.delete(2261).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"id": 2261,
"delete": true
}
AdButler\FlashPopup JSON: {
"id": 2261,
"delete": true
}
Permanently deletes a flash popup. if successful, this operation cannot be undone so be very sure when deleting one. Also immediately stops serving any ads belonging to this flash popup account.
Returns
Returns a flash popup ID if the request succeeded, or an error if something went terribly wrong.
List all flash popups
Definition
GET https://api.adbutler.com/v1/popups/flash
\AdButler\FlashPopup::retrieveAll()
adbutler.popups.flash.list()
Example Request
curl "https://api.adbutler.com/v1/popups/flash?limit=2" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$flashPopup = \AdButler\FlashPopup::retrieveAll(array(
"limit" => 2
));
echo $flashPopup;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.popups.flash.list({
limit: 2
}, function(err, response) {
console.log(response);
});
// using promises
adbutler.popups.flash.list({
limit: 2
}).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/popups/flash",
"data": [
{
"object": "flash_popup",
"self": "/v1/popups/flash/2223",
"id": 2223,
"creative": 45254,
"creative_url": null,
"flash_html": "<object width=\"300\" height=\"250\" id=\"movie_5474863\">\\r\\n<param name=\"wmode\" value=\"opaque\">\\r\\n<param name=\"quality\" value=\"high\">\\r\\n<param name=\"version\" value=\"7\">\\r\\n<param name=\"allowScriptAccess\" value=\"always\">\\r\\n<param name=\"movie\" value=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\">\\r\\n<embed width=\"300\" height=\"250\" src=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\" wmode=\"opaque\" quality=\"high\" version=\"7\" allowScriptAccess=\"always\" type=\"application/x-shockwave-flash\">\\r\\n</object>",
"height": 250,
"html_content_below": "",
"location": "https://your-target-site.com",
"mode": "opaque",
"name": "Demo Flash Popup",
"popup_style": "over",
"quality": "high",
"title": "Ad Window",
"tracking_pixel": "",
"version": 7,
"width": 300
},
{
"object": "flash_popup",
"self": "/v1/popups/flash/2226",
"id": 2226,
"creative": 45254,
"creative_url": null,
"flash_html": "<object width=\"300\" height=\"250\" id=\"movie_5474863\">\\r\\n<param name=\"wmode\" value=\"opaque\">\\r\\n<param name=\"quality\" value=\"high\">\\r\\n<param name=\"version\" value=\"7\">\\r\\n<param name=\"allowScriptAccess\" value=\"always\">\\r\\n<param name=\"movie\" value=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\">\\r\\n<embed width=\"300\" height=\"250\" src=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\" wmode=\"opaque\" quality=\"high\" version=\"7\" allowScriptAccess=\"always\" type=\"application/x-shockwave-flash\">\\r\\n</object>",
"height": 250,
"html_content_below": "",
"location": "https://your-target-site.com",
"mode": "opaque",
"name": "Demo Flash Popup",
"popup_style": "over",
"quality": "high",
"title": "Ad Window",
"tracking_pixel": "",
"version": 7,
"width": 300
}
]
}
AdButler\FlashPopup JSON: {
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/popups/flash",
"data": [
{
"object": "flash_popup",
"self": "/v1/popups/flash/2223",
"id": 2223,
"creative": 45254,
"creative_url": null,
"flash_html": "<object width=\"300\" height=\"250\" id=\"movie_5474863\">\\r\\n<param name=\"wmode\" value=\"opaque\">\\r\\n<param name=\"quality\" value=\"high\">\\r\\n<param name=\"version\" value=\"7\">\\r\\n<param name=\"allowScriptAccess\" value=\"always\">\\r\\n<param name=\"movie\" value=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\">\\r\\n<embed width=\"300\" height=\"250\" src=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\" wmode=\"opaque\" quality=\"high\" version=\"7\" allowScriptAccess=\"always\" type=\"application/x-shockwave-flash\">\\r\\n</object>",
"height": 250,
"html_content_below": "",
"location": "https://your-target-site.com",
"mode": "opaque",
"name": "Demo Flash Popup",
"popup_style": "over",
"quality": "high",
"title": "Ad Window",
"tracking_pixel": "",
"version": 7,
"width": 300
},
{
"object": "flash_popup",
"self": "/v1/popups/flash/2226",
"id": 2226,
"creative": 45254,
"creative_url": null,
"flash_html": "<object width=\"300\" height=\"250\" id=\"movie_5474863\">\\r\\n<param name=\"wmode\" value=\"opaque\">\\r\\n<param name=\"quality\" value=\"high\">\\r\\n<param name=\"version\" value=\"7\">\\r\\n<param name=\"allowScriptAccess\" value=\"always\">\\r\\n<param name=\"movie\" value=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\">\\r\\n<embed width=\"300\" height=\"250\" src=\"//servedbyadbutler.com.baig.dev/getad.img?libBID=45254&clickTAG=[TRACKING_LINK_ENCODED]&clickTag=[TRACKING_LINK_ENCODED]\" wmode=\"opaque\" quality=\"high\" version=\"7\" allowScriptAccess=\"always\" type=\"application/x-shockwave-flash\">\\r\\n</object>",
"height": 250,
"html_content_below": "",
"location": "https://your-target-site.com",
"mode": "opaque",
"name": "Demo Flash Popup",
"popup_style": "over",
"quality": "high",
"title": "Ad Window",
"tracking_pixel": "",
"version": 7,
"width": 300
}
]
}
Returns a list of all the flash popup accounts. Most recent flash popup accounts appear first in the list.
Returns
Returns an object with a data
property that contains a list of up to the specified limit and/or offset of objects. Each entry in data
is a flash_popup
object, and if no objects were found the list will be empty.
Custom HTML Popups
Introduction
A popup banner can catch your users attention by causing a separate window to appear with an advertisement in it. These ads can appear behind or in front of the content currently being browsed.
Popups require an option in the zone they belong to do be enabled to take effect.
The custom_html_popup
response object has the following fields.
Example Response
{
"object": "custom_html_popup",
"self": "/v1/popups/custom-html/2262",
"id": 2262,
"name": "Demo Custom HTML Popup",
"title": "Ad Window",
"location": "https://your-target-site.com",
"width": 300,
"height": 250,
"tracking_pixel": "",
"html_content_below": "",
"popup_style": "over",
"custom_html": "<p>Hello world!</p>"
}
AdButler\CustomHTMLPopup JSON: {
"object": "custom_html_popup",
"self": "/v1/popups/custom-html/2262",
"id": 2262,
"name": "Demo Custom HTML Popup",
"title": "Ad Window",
"location": "https://your-target-site.com",
"width": 300,
"height": 250,
"tracking_pixel": "",
"html_content_below": "",
"popup_style": "over",
"custom_html": "<p>Hello world!</p>"
}
Field | Type | Description |
---|---|---|
object |
string |
A string denoting the object type which is always |
self |
string |
The relative URL of the current resource which is always of the form |
id |
integer |
The current resource identifier (ID). |
name |
string |
Name of the Custom HTML Popup |
title |
string |
Title of the popup |
location |
string |
The location to redirect to |
width |
integer |
Width of the popup |
height |
integer |
Height of the popup |
tracking_pixel |
string |
The pixel URL |
html_content_below |
string |
HTML below the main HTML |
popup_style |
string |
Where the popup should appear |
custom_html |
string |
Custom HTML |
Create a custom HTML popup
Definition
POST https://api.adbutler.com/v1/popups/custom-html
\AdButler\CustomHTMLPopup::create()
adbutler.popups.customHTML.create()
Example Request
curl "https://api.adbutler.com/v1/popups/custom-html" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"name": "Demo Custom HTML Popup",
"title": "Ad Window",
"location": "https://your-target-site.com",
"width": 300,
"height": 250,
"tracking_pixel": "",
"html_content_below": "",
"popup_style": "over",
"custom_html": "<p>Hello world!</p>"
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$customHTMLPopup = \AdButler\CustomHTMLPopup::create(array(
"name" => "Demo Custom HTML Popup",
"title" => "Ad Window",
"location" => "https://your-target-site.com",
"width" => 300,
"height" => 250,
"tracking_pixel" => "",
"html_content_below" => "",
"popup_style" => "over",
"custom_html" => "<p>Hello world!</p>"
));
echo $customHTMLPopup;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var postData = {
"name": "Demo Custom HTML Popup",
"title": "Ad Window",
"location": "https://your-target-site.com",
"width": 300,
"height": 250,
"tracking_pixel": "",
"html_content_below": "",
"popup_style": "over",
"custom_html": "<p>Hello world!</p>"
};
// using callbacks
adbutler.popups.customHTML.create(postData, function(err, response) {
console.log(response);
});
// using promises
adbutler.popups.customHTML.create(postData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "custom_html_popup",
"self": "/v1/popups/custom-html/2262",
"id": 2262,
"name": "Demo Custom HTML Popup",
"title": "Ad Window",
"location": "https://your-target-site.com",
"width": 300,
"height": 250,
"tracking_pixel": "",
"html_content_below": "",
"popup_style": "over",
"custom_html": "<p>Hello world!</p>"
}
AdButler\CustomHTMLPopup JSON: {
"object": "custom_html_popup",
"self": "/v1/popups/custom-html/2262",
"id": 2262,
"name": "Demo Custom HTML Popup",
"title": "Ad Window",
"location": "https://your-target-site.com",
"width": 300,
"height": 250,
"tracking_pixel": "",
"html_content_below": "",
"popup_style": "over",
"custom_html": "<p>Hello world!</p>"
}
Creates a new custom HTML popup.
Field | Type | Description |
---|---|---|
name* |
string |
A descriptive name of the custom HTML popup. We recommend using a naming convention that is consistent, relevant, and clear. |
title* |
string |
The user visible title that will appear on the frame of the popup window. |
width* |
integer |
The width of the popup window containing the advertisement (typically the same width as the advertisement itself). |
height* |
integer |
The height of the popup window containing the advertisement (typically the same height as the advertisement itself). |
custom_html* |
integer |
The HTML content of the popup. |
location |
string |
A URL indicating where you want the user to go when they click on the popup. This field can be left blank. |
tracking_pixel |
string |
A URL of an image, typically 1x1 pixel in size, intended for impression tracking purposes. It is loaded alongside the popup allowing an external system to monitor impressions. |
html_content_below |
string |
The HTML content to appear below the custom HTML popup. |
popup_style |
string |
Whether this popup should appear in front of the page or behind it. Possible values are |
* = required field
Returns
Returns a custom_html_popup
object if the request succeeded, or an error if something went terribly wrong.
Retrieve a custom HTML popup
Definition
GET https://api.adbutler.com/v1/popups/custom-html/{CUSTOM-HTML-POPUP-ID}
\AdButler\CustomHTMLPopup::retrieve()
adbutler.popups.customHTML.retrieve()
Example Request
curl "https://api.adbutler.com/v1/popups/custom-html/2262" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$customHTMLPopup = \AdButler\CustomHTMLPopup::retrieve( 2262 );
echo $customHTMLPopup;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.popups.customHTML.read(2262, function(err, response) {
console.log(response);
});
// using promises
adbutler.popups.customHTML.read(2262).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "custom_html_popup",
"self": "/v1/popups/custom-html/2262",
"id": 2262,
"name": "Demo Custom HTML Popup",
"title": "Ad Window",
"location": "https://your-target-site.com",
"width": 300,
"height": 250,
"tracking_pixel": "",
"html_content_below": "",
"popup_style": "over",
"custom_html": "<p>Hello world!</p>"
}
AdButler\CustomHTMLPopup JSON: {
"object": "custom_html_popup",
"self": "/v1/popups/custom-html/2262",
"id": 2262,
"name": "Demo Custom HTML Popup",
"title": "Ad Window",
"location": "https://your-target-site.com",
"width": 300,
"height": 250,
"tracking_pixel": "",
"html_content_below": "",
"popup_style": "over",
"custom_html": "<p>Hello world!</p>"
}
You can retrieve the information about an existing custom HTML popup by giving the custom HTML popup ID that was returned in the custom HTML popup object upon creation. You will see at the most 10 custom HTML popups in the response. You can change this default limit by appending ?limit=25
if you want this request to return 25 popups_custom-html.
Returns
Returns a custom_html_popup
object if the request succeeded, or an error if something went terribly wrong.
Update a custom HTML popup
Definition
PUT https://api.adbutler.com/v1/popups/custom-html/{CUSTOM-HTML-POPUP-ID}
\AdButler\CustomHTMLPopup->save()
adbutler.popups.customHTML.update()
Example Request
curl "https://api.adbutler.com/v1/popups/custom-html/2262" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
"name": "Demo Custom HTML Popup",
"title": "Ad Window",
"location": "https://your-target-site.com",
"width": 300,
"height": 250,
"tracking_pixel": "",
"html_content_below": "",
"popup_style": "over",
"custom_html": "<p>Hello world!</p>"
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$customHTMLPopup = \AdButler\CustomHTMLPopup::retrieve( 2262 );
$customHTMLPopup->name = "Demo Custom HTML Popup";
$customHTMLPopup->title = "Ad Window";
$customHTMLPopup->location = "https://your-target-site.com";
$customHTMLPopup->width = 300;
$customHTMLPopup->height = 250;
$customHTMLPopup->tracking_pixel = "";
$customHTMLPopup->html_content_below = "";
$customHTMLPopup->popup_style = "over";
$customHTMLPopup->custom_html = "<p>Hello world!</p>";
$customHTMLPopup->save();
echo $customHTMLPopup;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var updateData = {
"name": "Demo Custom HTML Popup",
"title": "Ad Window",
"location": "https://your-target-site.com",
"width": 300,
"height": 250,
"tracking_pixel": "",
"html_content_below": "",
"popup_style": "over",
"custom_html": "<p>Hello world!</p>"
};
// using callbacks
adbutler.popups.customHTML.update(2262, updateData, function(err, response) {
console.log(response);
});
// using promises
adbutler.popups.customHTML.update(2262, updateData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "custom_html_popup",
"self": "/v1/popups/custom-html/2262",
"id": 2262,
"name": "Demo Custom HTML Popup",
"title": "Ad Window",
"location": "https://your-target-site.com",
"width": 300,
"height": 250,
"tracking_pixel": "",
"html_content_below": "",
"popup_style": "over",
"custom_html": "<p>Hello world!</p>"
}
AdButler\CustomHTMLPopup JSON: {
"object": "custom_html_popup",
"self": "/v1/popups/custom-html/2262",
"id": 2262,
"name": "Demo Custom HTML Popup",
"title": "Ad Window",
"location": "https://your-target-site.com",
"width": 300,
"height": 250,
"tracking_pixel": "",
"html_content_below": "",
"popup_style": "over",
"custom_html": "<p>Hello world!</p>"
}
You can update a specific custom HTML popup account by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the custom HTML popup creation request.
Field | Type | Description |
---|---|---|
name |
string |
A descriptive name of the custom HTML popup. We recommend using a naming convention that is consistent, relevant, and clear. |
title |
string |
The user visible title that will appear on the frame of the popup window. |
width |
integer |
The width of the popup window containing the advertisement (typically the same width as the advertisement itself). |
height |
integer |
The height of the popup window containing the advertisement (typically the same height as the advertisement itself). |
custom_html |
integer |
The HTML content of the popup. |
location |
string |
A URL indicating where you want the user to go when they click on the popup. This field can be left blank. |
tracking_pixel |
string |
A URL of an image, typically 1x1 pixel in size, intended for impression tracking purposes. It is loaded alongside the popup allowing an external system to monitor impressions. |
html_content_below |
string |
The HTML content to appear below the custom HTML popup. |
popup_style |
string |
Whether this popup should appear in front of the page or behind it. Possible values are |
Returns
Returns a custom_html_popup
object if the request succeeded, or an error if something went terribly wrong.
Delete a custom HTML popup
Definition
DELETE https://api.adbutler.com/v1/popups/custom-html/{CUSTOM-HTML-POPUP-ID}
\AdButler\CustomHTMLPopup->delete()
adbutler.popups.customHTML.delete()
Example Request
curl "https://api.adbutler.com/v1/popups/custom-html/2262" \
-H "Authorization: Basic {API_KEY}" \
-X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$customHTMLPopup = \AdButler\CustomHTMLPopup::retrieve( 2262 );
$customHTMLPopup->delete();
echo $customHTMLPopup;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.popups.customHTML.delete(2262, function(err, response) {
console.log(response);
});
// using promises
adbutler.popups.customHTML.delete(2262).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"id": 2262,
"delete": true
}
AdButler\CustomHTMLPopup JSON: {
"id": 2262,
"delete": true
}
Permanently deletes a custom HTML popup. if successful, this operation cannot be undone so be very sure when deleting one. Also immediately stops serving any ads belonging to this custom HTML popup account.
Returns
Returns a custom HTML popup ID if the request succeeded, or an error if something went terribly wrong.
List all custom HTML popups
Definition
GET https://api.adbutler.com/v1/popups/custom-html
\AdButler\CustomHTMLPopup::retrieveAll()
adbutler.popups.customHTML.list()
Example Request
curl "https://api.adbutler.com/v1/popups/custom-html?limit=2" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$customHTMLPopup = \AdButler\CustomHTMLPopup::retrieveAll(array(
"limit" => 2
));
echo $customHTMLPopup;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.popups.customHTML.list({
limit: 2
}, function(err, response) {
console.log(response);
});
// using promises
adbutler.popups.customHTML.list({
limit: 2
}).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/popups/custom-html",
"data": [
{
"object": "custom_html_popup",
"self": "/v1/popups/custom-html/2224",
"id": 2224,
"name": "Demo Custom HTML Popup",
"title": "Ad Window",
"location": "https://your-target-site.com",
"width": 300,
"height": 250,
"tracking_pixel": "",
"html_content_below": "",
"popup_style": "over",
"custom_html": "<p>Hello world!</p>"
},
{
"object": "custom_html_popup",
"self": "/v1/popups/custom-html/2227",
"id": 2227,
"name": "Demo Custom HTML Popup",
"title": "Ad Window",
"location": "https://your-target-site.com",
"width": 300,
"height": 250,
"tracking_pixel": "",
"html_content_below": "",
"popup_style": "over",
"custom_html": "<p>Hello world!</p>"
}
]
}
AdButler\CustomHTMLPopup JSON: {
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/popups/custom-html",
"data": [
{
"object": "custom_html_popup",
"self": "/v1/popups/custom-html/2224",
"id": 2224,
"name": "Demo Custom HTML Popup",
"title": "Ad Window",
"location": "https://your-target-site.com",
"width": 300,
"height": 250,
"tracking_pixel": "",
"html_content_below": "",
"popup_style": "over",
"custom_html": "<p>Hello world!</p>"
},
{
"object": "custom_html_popup",
"self": "/v1/popups/custom-html/2227",
"id": 2227,
"name": "Demo Custom HTML Popup",
"title": "Ad Window",
"location": "https://your-target-site.com",
"width": 300,
"height": 250,
"tracking_pixel": "",
"html_content_below": "",
"popup_style": "over",
"custom_html": "<p>Hello world!</p>"
}
]
}
Returns a list of all the custom HTML popup accounts. Most recent custom HTML popup accounts appear first in the list.
Returns
Returns an object with a data
property that contains a list of up to the specified limit and/or offset of objects. Each entry in data
is a custom_html_popup
object, and if no objects were found the list will be empty.
Media Groups
Introduction
Media groups allow you to group creatives together for easier organization and management in your account.
The media_group
response object has the following fields.
Example Response
{
"object": "media_group",
"self": "/v1/media-groups/716",
"id": 716,
"name": "Default"
}
AdButler\MediaGroup JSON: {
"object": "media_group",
"self": "/v1/media-groups/716",
"id": 716,
"name": "Default"
}
Field | Type | Description |
---|---|---|
object |
string |
A string denoting the object type which is always |
self |
string |
The relative URL of the current resource which is always of the form |
id |
integer |
The current resource identifier (ID). |
name |
string |
The name of the media group. |
Create a media group
Definition
POST https://api.adbutler.com/v1/media-groups
\AdButler\MediaGroup::create()
adbutler.mediaGroups.create()
Example Request
curl "https://api.adbutler.com/v1/media-groups" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"name": "Default"
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$mediaGroup = \AdButler\MediaGroup::create(array(
"name" => "Default"
));
echo $mediaGroup;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var postData = {
"name": "Default"
};
// using callbacks
adbutler.mediaGroups.create(postData, function(err, response) {
console.log(response);
});
// using promises
adbutler.mediaGroups.create(postData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "media_group",
"self": "/v1/media-groups/716",
"id": 716,
"name": "Default"
}
AdButler\MediaGroup JSON: {
"object": "media_group",
"self": "/v1/media-groups/716",
"id": 716,
"name": "Default"
}
Creates a new media group.
Field | Type | Description |
---|---|---|
name* |
string |
A descriptive name of the media group. |
* = required field
Returns
Returns a media_group
object if the request succeeded, or an error if something went terribly wrong.
Retrieve a media group
Definition
GET https://api.adbutler.com/v1/media-groups/{MEDIA-GROUP-ID}
\AdButler\MediaGroup::retrieve()
adbutler.mediaGroups.retrieve()
Example Request
curl "https://api.adbutler.com/v1/media-groups/716" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$mediaGroup = \AdButler\MediaGroup::retrieve( 716 );
echo $mediaGroup;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.mediaGroups.read(716, function(err, response) {
console.log(response);
});
// using promises
adbutler.mediaGroups.read(716).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "media_group",
"self": "/v1/media-groups/716",
"id": 716,
"name": "Default"
}
AdButler\MediaGroup JSON: {
"object": "media_group",
"self": "/v1/media-groups/716",
"id": 716,
"name": "Default"
}
You can retrieve the information about an existing media group by giving the media group ID that was returned in the media group object upon creation. You will see at the most 10 media groups in the response. You can change this default limit by appending ?limit=25
if you want this request to return 25 media-groups.
Returns
Returns a media_group
object if the request succeeded, or an error if something went terribly wrong.
Update a media group
Definition
PUT https://api.adbutler.com/v1/media-groups/{MEDIA-GROUP-ID}
\AdButler\MediaGroup->save()
adbutler.mediaGroups.update()
Example Request
curl "https://api.adbutler.com/v1/media-groups/716" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
"name": "Default"
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$mediaGroup = \AdButler\MediaGroup::retrieve( 716 );
$mediaGroup->name = "Default";
$mediaGroup->save();
echo $mediaGroup;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var updateData = {
"name": "Default"
};
// using callbacks
adbutler.mediaGroups.update(716, updateData, function(err, response) {
console.log(response);
});
// using promises
adbutler.mediaGroups.update(716, updateData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "media_group",
"self": "/v1/media-groups/716",
"id": 716,
"name": "Default"
}
AdButler\MediaGroup JSON: {
"object": "media_group",
"self": "/v1/media-groups/716",
"id": 716,
"name": "Default"
}
You can update a specific media group by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the media group creation request.
Field | Type | Description |
---|---|---|
name |
string |
A descriptive name of the media group. |
Returns
Returns a media_group
object if the request succeeded, or an error if something went terribly wrong.
Delete a media group
Definition
DELETE https://api.adbutler.com/v1/media-groups/{MEDIA-GROUP-ID}
\AdButler\MediaGroup->delete()
adbutler.mediaGroups.delete()
Example Request
curl "https://api.adbutler.com/v1/media-groups/716" \
-H "Authorization: Basic {API_KEY}" \
-X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$mediaGroup = \AdButler\MediaGroup::retrieve( 716 );
$mediaGroup->delete();
echo $mediaGroup;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.mediaGroups.delete(716, function(err, response) {
console.log(response);
});
// using promises
adbutler.mediaGroups.delete(716).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"id": 716,
"delete": true
}
AdButler\MediaGroup JSON: {
"id": 716,
"delete": true
}
Permanently deletes a media group. If successful, this operation cannot be undone so be very sure when deleting one.
Returns
Returns a media group ID if the request succeeded, or an error if something went terribly wrong.
List all media groups
Definition
GET https://api.adbutler.com/v1/media-groups
\AdButler\MediaGroup::retrieveAll()
adbutler.mediaGroups.list()
Example Request
curl "https://api.adbutler.com/v1/media-groups?limit=2" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$mediaGroup = \AdButler\MediaGroup::retrieveAll(array(
"limit" => 2
));
echo $mediaGroup;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.mediaGroups.list({
limit: 2
}, function(err, response) {
console.log(response);
});
// using promises
adbutler.mediaGroups.list({
limit: 2
}).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/media-groups",
"data": [
{
"object": "media_group",
"self": "/v1/media-groups/693",
"id": 693,
"name": "Default"
},
{
"object": "media_group",
"self": "/v1/media-groups/694",
"id": 694,
"name": "Default"
}
]
}
AdButler\MediaGroup JSON: {
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/media-groups",
"data": [
{
"object": "media_group",
"self": "/v1/media-groups/693",
"id": 693,
"name": "Default"
},
{
"object": "media_group",
"self": "/v1/media-groups/694",
"id": 694,
"name": "Default"
}
]
}
Returns a list of all the media groups. Most recent media groups appear first in the list.
Returns
Returns an object with a data
property that contains a list of up to the specified limit and/or offset of objects. Each entry in data
is a media_group
object, and if no objects were found the list will be empty.
Creatives
List all creatives
Definition
GET https://api.adbutler.com/v1/creatives
\AdButler\Creative::retrieveAll()
adbutler.creatives.list()
Example Request
curl "https://api.adbutler.com/v1/creatives?limit=2" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$creative = \AdButler\Creative::retrieveAll(array(
"limit" => 2
));
echo $creative;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.creatives.list({
limit: 2
}, function(err, response) {
console.log(response);
});
// using promises
adbutler.creatives.list({
limit: 2
}).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/creatives",
"data": [
{
"object": "image_creative",
"self": "/v1/creatives/image/49981",
"id": 49981,
"description": "This is a demo image creative",
"file_name": "image-ad.png",
"file_size": 3696,
"group": 228,
"height": 250,
"mime_type": "image/png",
"name": "Demo Image Creative",
"upload_time": "2016-04-29 09:17:43",
"width": 300
},
{
"object": "flash_creative",
"self": "/v1/creatives/flash/49982",
"id": 49982,
"description": "This is a demo flash creative",
"file_name": "flash-ad.swf",
"file_size": 77587,
"group": 228,
"height": 250,
"mime_type": "application/x-shockwave-flash",
"name": "Demo Flash Creative",
"upload_time": "2016-04-29 09:36:35",
"width": 300
}
]
}
AdButler\Creative JSON: {
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/creatives",
"data": [
{
"object": "image_creative",
"self": "/v1/creatives/image/49981",
"id": 49981,
"description": "This is a demo image creative",
"file_name": "image-ad.png",
"file_size": 3696,
"group": 228,
"height": 250,
"mime_type": "image/png",
"name": "Demo Image Creative",
"upload_time": "2016-04-29 09:17:43",
"width": 300
},
{
"object": "flash_creative",
"self": "/v1/creatives/flash/49982",
"id": 49982,
"description": "This is a demo flash creative",
"file_name": "flash-ad.swf",
"file_size": 77587,
"group": 228,
"height": 250,
"mime_type": "application/x-shockwave-flash",
"name": "Demo Flash Creative",
"upload_time": "2016-04-29 09:36:35",
"width": 300
}
]
}
You can retrieve a list of all the creatives regardless of their type. You can optionally restrict the fields that you are interested in retrieving by using the fields
query parameter.
Returns
Returns an object with a data
property that contains a list of up to the specified limit and/or offset of objects. Each entry in data
is an object, and if no objects were found the list will be empty.
Image Creatives
Introduction
The image file that makes up an advertisement is known as the image creative. You can create a new image creative, retrieve one or more image creatives, update an existing image creative, or delete the image creative.
The image_creative
response object has the following fields.
Example Response
{
"object": "image_creative",
"self": "/v1/creatives/image/50645",
"id": 50645,
"description": "This is a demo image creative",
"file_name": "image-ad.png",
"file_size": 3696,
"group": 228,
"height": 250,
"mime_type": "image/png",
"name": "Demo Image Creative",
"upload_time": "2016-04-29 09:17:43",
"width": 300
}
AdButler\ImageCreative JSON: {
"object": "image_creative",
"self": "/v1/creatives/image/50645",
"id": 50645,
"description": "This is a demo image creative",
"file_name": "image-ad.png",
"file_size": 3696,
"group": 228,
"height": 250,
"mime_type": "image/png",
"name": "Demo Image Creative",
"upload_time": "2016-04-29 09:17:43",
"width": 300
}
Field | Type | Description |
---|---|---|
object |
string |
A string denoting the object type which is always |
self |
string |
The relative URL of the current resource which is always of the form |
id |
integer |
The current resource identifier (ID). |
description |
string |
Description of the image creative. |
file_name |
string |
Name of the uploaded image file. |
file_size |
integer |
Size of the uploaded image file. |
group |
integer |
Media group identifier (ID) the image creative belongs to. |
height |
integer |
Height of the image creative. |
mime_type |
string |
MIME type of the uploaded image creative. |
name |
string |
Name of the image creative. |
upload_time |
string |
The date and time when the image file was uploaded. |
width |
integer |
Width of the image creative. |
Create an image creative
Definition
POST https://api.adbutler.com/v1/creatives/image
\AdButler\ImageCreative::create()
adbutler.creatives.images.create()
Example Request
curl "https://api.adbutler.com/v1/creatives/image" \
-H "Authorization: Basic {API_KEY}" \
-H "Expect:" \
-X POST \
-F file=@image-ad.png \
-F attributes='{
"description": "This is a demo image creative",
"group": 228,
"name": "Demo Image Creative"
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$imageCreative = \AdButler\ImageCreative::create(array(
"description" => "This is a demo image creative",
"group" => 228,
"name" => "Demo Image Creative",
"file" => "image-ad.png"
));
echo $imageCreative;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var postData = {
"description": "This is a demo image creative",
"group": 228,
"name": "Demo Image Creative",
"file": "image-ad.png"
};
// using callbacks
adbutler.creatives.images.create(postData, function(err, response) {
console.log(response);
});
// using promises
adbutler.creatives.images.create(postData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "image_creative",
"self": "/v1/creatives/image/50645",
"id": 50645,
"description": "This is a demo image creative",
"file_name": "image-ad.png",
"file_size": 3696,
"group": 228,
"height": 250,
"mime_type": "image/png",
"name": "Demo Image Creative",
"upload_time": "2016-04-29 09:17:43",
"width": 300
}
AdButler\ImageCreative JSON: {
"object": "image_creative",
"self": "/v1/creatives/image/50645",
"id": 50645,
"description": "This is a demo image creative",
"file_name": "image-ad.png",
"file_size": 3696,
"group": 228,
"height": 250,
"mime_type": "image/png",
"name": "Demo Image Creative",
"upload_time": "2016-04-29 09:17:43",
"width": 300
}
Creates a new image creative.
Field | Type | Description |
---|---|---|
description |
string |
A short description about the image creative. |
file* |
string |
The aboslute or relative path to the image (JPEG, PNG, or GIF) file. |
group* |
integer |
The media group identifier (ID). |
name |
string |
A descriptive name of the image creative. |
* = required field
Returns
Returns an image_creative
object if the request succeeded, or an error if something went terribly wrong.
Retrieve an image creative
Definition
GET https://api.adbutler.com/v1/creatives/image/{}
\AdButler\ImageCreative::retrieve()
adbutler.creatives.images.retrieve()
Example Request
curl "https://api.adbutler.com/v1/creatives/image/50645" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$imageCreative = \AdButler\ImageCreative::retrieve( 50645 );
echo $imageCreative;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.creatives.images.read(50645, function(err, response) {
console.log(response);
});
// using promises
adbutler.creatives.images.read(50645).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "image_creative",
"self": "/v1/creatives/image/50645",
"id": 50645,
"description": "This is a demo image creative",
"file_name": "image-ad.png",
"file_size": 3696,
"group": 228,
"height": 250,
"mime_type": "image/png",
"name": "Demo Image Creative",
"upload_time": "2016-04-29 09:17:43",
"width": 300
}
AdButler\ImageCreative JSON: {
"object": "image_creative",
"self": "/v1/creatives/image/50645",
"id": 50645,
"description": "This is a demo image creative",
"file_name": "image-ad.png",
"file_size": 3696,
"group": 228,
"height": 250,
"mime_type": "image/png",
"name": "Demo Image Creative",
"upload_time": "2016-04-29 09:17:43",
"width": 300
}
You can retrieve the information about an existing image creative by giving the image creative identifier that was returned in the creative_image
object upon creation.
Returns
Returns an image_creative
object if the request succeeded, or an error if something went terribly wrong.
Update an image creative
Definition
POST https://api.adbutler.com/v1/creatives/image/{}
\AdButler\ImageCreative->save()
adbutler.creatives.images.update()
Example Request
curl "https://api.adbutler.com/v1/creatives/image/50645" \
-H "Authorization: Basic {API_KEY}" \
-H "Expect:" \
-X POST \
-F file=@image-ad.png \
-F attributes='{
"description": "This is a demo image creative",
"group": 228,
"name": "Demo Image Creative"
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$imageCreative = \AdButler\ImageCreative::retrieve( 50645 );
$imageCreative->description = "This is a demo image creative";
$imageCreative->group = 228;
$imageCreative->name = "Demo Image Creative";
$imageCreative->file = "image-ad.png";
$imageCreative->save();
echo $imageCreative;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var updateData = {
"description": "This is a demo image creative",
"group": 228,
"name": "Demo Image Creative",
"file": "image-ad.png"
};
// using callbacks
adbutler.creatives.images.update(50645, updateData, function(err, response) {
console.log(response);
});
// using promises
adbutler.creatives.images.update(50645, updateData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "image_creative",
"self": "/v1/creatives/image/50645",
"id": 50645,
"description": "This is a demo image creative",
"file_name": "image-ad.png",
"file_size": 3696,
"group": 228,
"height": 250,
"mime_type": "image/png",
"name": "Demo Image Creative",
"upload_time": "2016-04-29 09:17:43",
"width": 300
}
AdButler\ImageCreative JSON: {
"object": "image_creative",
"self": "/v1/creatives/image/50645",
"id": 50645,
"description": "This is a demo image creative",
"file_name": "image-ad.png",
"file_size": 3696,
"group": 228,
"height": 250,
"mime_type": "image/png",
"name": "Demo Image Creative",
"upload_time": "2016-04-29 09:17:43",
"width": 300
}
You can update a specific image creative by setting the values of the fields you want to update. If you want the field to retain its old value, then just omit that field from the update request. The update request accepts mostly the same arguments as the image creative creation request.
Field | Type | Description |
---|---|---|
description |
string |
A short description about the image creative. |
file |
string |
The aboslute or relative path to the image (JPEG, PNG, or GIF) file. |
group |
integer |
The media group identifier (ID). |
name |
string |
A descriptive name of the image creative. |
Returns
Returns an image_creative
object if the request succeeded, or an error if something went terribly wrong.
Delete an image creative
Definition
DELETE https://api.adbutler.com/v1/creatives/image/{}
\AdButler\ImageCreative->delete()
adbutler.creatives.images.delete()
Example Request
curl "https://api.adbutler.com/v1/creatives/image/50645" \
-H "Authorization: Basic {API_KEY}" \
-X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$imageCreative = \AdButler\ImageCreative::retrieve( 50645 );
$imageCreative->delete();
echo $imageCreative;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.creatives.images.delete(50645, function(err, response) {
console.log(response);
});
// using promises
adbutler.creatives.images.delete(50645).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"id": 50645,
"delete": true
}
AdButler\ImageCreative JSON: {
"id": 50645,
"delete": true
}
Permanently deletes an Image Creative. if successful, this operation cannot be undone so be very sure when deleting one.
Returns
Returns an image creative ID if the request succeeded, or an error if something went terribly wrong.
List all image creatives
Definition
GET https://api.adbutler.com/v1/creatives/image
\AdButler\ImageCreative::retrieveAll()
adbutler.creatives.images.list()
Example Request
curl "https://api.adbutler.com/v1/creatives/image?limit=2" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$imageCreative = \AdButler\ImageCreative::retrieveAll(array(
"limit" => 2
));
echo $imageCreative;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.creatives.images.list({
limit: 2
}, function(err, response) {
console.log(response);
});
// using promises
adbutler.creatives.images.list({
limit: 2
}).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/creatives/image",
"data": [
{
"object": "image_creative",
"self": "/v1/creatives/image/49981",
"id": 49981,
"description": "This is a demo image creative",
"file_name": "image-ad.png",
"file_size": 3696,
"group": 228,
"height": 250,
"mime_type": "image/png",
"name": "Demo Image Creative",
"upload_time": "2016-04-29 09:17:43",
"width": 300
},
{
"object": "image_creative",
"self": "/v1/creatives/image/49985",
"id": 49985,
"description": "This is a demo image creative",
"file_name": "image-ad.png",
"file_size": 3696,
"group": 228,
"height": 250,
"mime_type": "image/png",
"name": "Demo Image Creative",
"upload_time": "2016-04-29 09:17:43",
"width": 300
}
]
}
AdButler\ImageCreative JSON: {
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/creatives/image",
"data": [
{
"object": "image_creative",
"self": "/v1/creatives/image/49981",
"id": 49981,
"description": "This is a demo image creative",
"file_name": "image-ad.png",
"file_size": 3696,
"group": 228,
"height": 250,
"mime_type": "image/png",
"name": "Demo Image Creative",
"upload_time": "2016-04-29 09:17:43",
"width": 300
},
{
"object": "image_creative",
"self": "/v1/creatives/image/49985",
"id": 49985,
"description": "This is a demo image creative",
"file_name": "image-ad.png",
"file_size": 3696,
"group": 228,
"height": 250,
"mime_type": "image/png",
"name": "Demo Image Creative",
"upload_time": "2016-04-29 09:17:43",
"width": 300
}
]
}
Returns a list of all the image creatives. Most recent image creatives appear first in the list.
Returns
Returns an object with a data
property that contains a list of up to the specified limit and/or offset of objects. Each entry in data
is a image_creative
object, and if no objects were found the list will be empty.
Flash Creatives
Introduction
The flash file that makes up an advertisement is known as the flash creative. You can create a new flash creative, retrieve one or more flash creatives, update an existing flash creative, or delete the flash creative.
The flash_creative
response object has the following fields.
Example Response
{
"object": "flash_creative",
"self": "/v1/creatives/flash/50646",
"id": 50646,
"description": "This is a demo flash creative",
"file_name": "flash-ad.swf",
"file_size": 77587,
"group": 228,
"height": 250,
"mime_type": "application/x-shockwave-flash",
"name": "Demo Flash Creative",
"upload_time": "2016-04-29 09:36:35",
"width": 300
}
AdButler\FlashCreative JSON: {
"object": "flash_creative",
"self": "/v1/creatives/flash/50646",
"id": 50646,
"description": "This is a demo flash creative",
"file_name": "flash-ad.swf",
"file_size": 77587,
"group": 228,
"height": 250,
"mime_type": "application/x-shockwave-flash",
"name": "Demo Flash Creative",
"upload_time": "2016-04-29 09:36:35",
"width": 300
}
Field | Type | Description |
---|---|---|
object |
string |
A string denoting the object type. |
self |
string |
The URL string of the current resource. |
id |
integer |
The current resource identifier (ID). |
description |
string |
Description of the flash creative. |
file_name |
string |
Name of the uploaded flash file. |
file_size |
integer |
Size of the uploaded flash file. |
group |
integer |
Media group identifier (ID) the flash creative belongs to. |
height |
integer |
Height of the flash creative. |
mime_type |
string |
MIME type of the uploaded flash creative. |
name |
string |
Name of the flash creative. |
upload_time |
string |
The date and time when the flash file was uploaded. |
width |
integer |
Width of the flash creative. |
Create a flash creative
Definition
POST https://api.adbutler.com/v1/creatives/flash
\AdButler\FlashCreative::create()
adbutler.creatives.flash.create()
Example Request
curl "https://api.adbutler.com/v1/creatives/flash" \
-H "Authorization: Basic {API_KEY}" \
-H "Expect:" \
-X POST \
-F file=@flash-ad.swf \
-F attributes='{
"description": "This is a demo flash creative",
"group": 228,
"name": "Demo Flash Creative"
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$flashCreative = \AdButler\FlashCreative::create(array(
"description" => "This is a demo flash creative",
"group" => 228,
"name" => "Demo Flash Creative",
"file" => "flash-ad.swf"
));
echo $flashCreative;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var postData = {
"description": "This is a demo flash creative",
"group": 228,
"name": "Demo Flash Creative",
"file": "flash-ad.swf"
};
// using callbacks
adbutler.creatives.flash.create(postData, function(err, response) {
console.log(response);
});
// using promises
adbutler.creatives.flash.create(postData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "flash_creative",
"self": "/v1/creatives/flash/50646",
"id": 50646,
"description": "This is a demo flash creative",
"file_name": "flash-ad.swf",
"file_size": 77587,
"group": 228,
"height": 250,
"mime_type": "application/x-shockwave-flash",
"name": "Demo Flash Creative",
"upload_time": "2016-04-29 09:36:35",
"width": 300
}
AdButler\FlashCreative JSON: {
"object": "flash_creative",
"self": "/v1/creatives/flash/50646",
"id": 50646,
"description": "This is a demo flash creative",
"file_name": "flash-ad.swf",
"file_size": 77587,
"group": 228,
"height": 250,
"mime_type": "application/x-shockwave-flash",
"name": "Demo Flash Creative",
"upload_time": "2016-04-29 09:36:35",
"width": 300
}
Creates a new flash creative.
Field | Type | Description |
---|---|---|
description |
string |
A short description about the flash creative. |
file* |
string |
The aboslute or relative path to the flash (SWF) file. |
group* |
integer |
The media group identifier (ID). |
name |
string |
A descriptive name of the flash creative. |
* = required field
Returns
Returns a flash_creative
object if the request succeeded, or an error if something went terribly wrong.
Retrieve a flash creative
Definition
GET https://api.adbutler.com/v1/creatives/flash/{FLASH-CREATIVE-ID}
\AdButler\FlashCreative::retrieve()
adbutler.creatives.flash.retrieve()
Example Request
curl "https://api.adbutler.com/v1/creatives/flash/50646" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$flashCreative = \AdButler\FlashCreative::retrieve( 50646 );
echo $flashCreative;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.creatives.flash.read(50646, function(err, response) {
console.log(response);
});
// using promises
adbutler.creatives.flash.read(50646).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "flash_creative",
"self": "/v1/creatives/flash/50646",
"id": 50646,
"description": "This is a demo flash creative",
"file_name": "flash-ad.swf",
"file_size": 77587,
"group": 228,
"height": 250,
"mime_type": "application/x-shockwave-flash",
"name": "Demo Flash Creative",
"upload_time": "2016-04-29 09:36:35",
"width": 300
}
AdButler\FlashCreative JSON: {
"object": "flash_creative",
"self": "/v1/creatives/flash/50646",
"id": 50646,
"description": "This is a demo flash creative",
"file_name": "flash-ad.swf",
"file_size": 77587,
"group": 228,
"height": 250,
"mime_type": "application/x-shockwave-flash",
"name": "Demo Flash Creative",
"upload_time": "2016-04-29 09:36:35",
"width": 300
}
You can retrieve the information about an existing flash creative by giving the flash creative identifier that was returned in the creative_flash
object upon creation.
Returns
Returns a flash_creative
object if the request succeeded, or an error if something went terribly wrong.
Update a flash creative
Definition
POST https://api.adbutler.com/v1/creatives/flash/{FLASH-CREATIVE-ID}
\AdButler\FlashCreative->save()
adbutler.creatives.flash.update()
Example Request
curl "https://api.adbutler.com/v1/creatives/flash/50646" \
-H "Authorization: Basic {API_KEY}" \
-H "Expect:" \
-X POST \
-F file=@flash-ad.swf \
-F attributes='{
"description": "This is a demo flash creative",
"group": 228,
"name": "Demo Flash Creative"
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$flashCreative = \AdButler\FlashCreative::retrieve( 50646 );
$flashCreative->description = "This is a demo flash creative";
$flashCreative->group = 228;
$flashCreative->name = "Demo Flash Creative";
$flashCreative->file = "flash-ad.swf";
$flashCreative->save();
echo $flashCreative;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var updateData = {
"description": "This is a demo flash creative",
"group": 228,
"name": "Demo Flash Creative",
"file": "flash-ad.swf"
};
// using callbacks
adbutler.creatives.flash.update(50646, updateData, function(err, response) {
console.log(response);
});
// using promises
adbutler.creatives.flash.update(50646, updateData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "flash_creative",
"self": "/v1/creatives/flash/50646",
"id": 50646,
"description": "This is a demo flash creative",
"file_name": "flash-ad.swf",
"file_size": 77587,
"group": 228,
"height": 250,
"mime_type": "application/x-shockwave-flash",
"name": "Demo Flash Creative",
"upload_time": "2016-04-29 09:36:35",
"width": 300
}
AdButler\FlashCreative JSON: {
"object": "flash_creative",
"self": "/v1/creatives/flash/50646",
"id": 50646,
"description": "This is a demo flash creative",
"file_name": "flash-ad.swf",
"file_size": 77587,
"group": 228,
"height": 250,
"mime_type": "application/x-shockwave-flash",
"name": "Demo Flash Creative",
"upload_time": "2016-04-29 09:36:35",
"width": 300
}
You can update a specific flash creative by setting the values of the fields you want to update. If you want the field to retain its old value, then just omit that field from the update request. The update request accepts mostly the same arguments as the flash creative creation request.
Field | Type | Description |
---|---|---|
description |
string |
A short description about the flash creative. |
file |
string |
The aboslute or relative path to the flash (SWF) file. |
group |
integer |
The media group identifier (ID). |
name |
string |
A descriptive name of the flash creative. |
Returns
Returns a flash_creative
object if the request succeeded, or an error if something went terribly wrong.
Delete a flash creative
Definition
DELETE https://api.adbutler.com/v1/creatives/flash/{FLASH-CREATIVE-ID}
\AdButler\FlashCreative->delete()
adbutler.creatives.flash.delete()
Example Request
curl "https://api.adbutler.com/v1/creatives/flash/50646" \
-H "Authorization: Basic {API_KEY}" \
-X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$flashCreative = \AdButler\FlashCreative::retrieve( 50646 );
$flashCreative->delete();
echo $flashCreative;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.creatives.flash.delete(50646, function(err, response) {
console.log(response);
});
// using promises
adbutler.creatives.flash.delete(50646).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"id": 50646,
"delete": true
}
AdButler\FlashCreative JSON: {
"id": 50646,
"delete": true
}
Permanently deletes a flash creative. if successful, this operation cannot be undone so be very sure when deleting one.
Returns
Returns a flash creative ID if the request succeeded, or an error if something went terribly wrong.
List all flash creatives
Definition
GET https://api.adbutler.com/v1/creatives/flash
\AdButler\FlashCreative::retrieveAll()
adbutler.creatives.flash.list()
Example Request
curl "https://api.adbutler.com/v1/creatives/flash?limit=2" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$flashCreative = \AdButler\FlashCreative::retrieveAll(array(
"limit" => 2
));
echo $flashCreative;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.creatives.flash.list({
limit: 2
}, function(err, response) {
console.log(response);
});
// using promises
adbutler.creatives.flash.list({
limit: 2
}).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/creatives/flash",
"data": [
{
"object": "flash_creative",
"self": "/v1/creatives/flash/49982",
"id": 49982,
"description": "This is a demo flash creative",
"file_name": "flash-ad.swf",
"file_size": 77587,
"group": 228,
"height": 250,
"mime_type": "application/x-shockwave-flash",
"name": "Demo Flash Creative",
"upload_time": "2016-04-29 09:36:35",
"width": 300
},
{
"object": "flash_creative",
"self": "/v1/creatives/flash/49986",
"id": 49986,
"description": "This is a demo flash creative",
"file_name": "flash-ad.swf",
"file_size": 77587,
"group": 228,
"height": 250,
"mime_type": "application/x-shockwave-flash",
"name": "Demo Flash Creative",
"upload_time": "2016-04-29 09:36:35",
"width": 300
}
]
}
AdButler\FlashCreative JSON: {
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/creatives/flash",
"data": [
{
"object": "flash_creative",
"self": "/v1/creatives/flash/49982",
"id": 49982,
"description": "This is a demo flash creative",
"file_name": "flash-ad.swf",
"file_size": 77587,
"group": 228,
"height": 250,
"mime_type": "application/x-shockwave-flash",
"name": "Demo Flash Creative",
"upload_time": "2016-04-29 09:36:35",
"width": 300
},
{
"object": "flash_creative",
"self": "/v1/creatives/flash/49986",
"id": 49986,
"description": "This is a demo flash creative",
"file_name": "flash-ad.swf",
"file_size": 77587,
"group": 228,
"height": 250,
"mime_type": "application/x-shockwave-flash",
"name": "Demo Flash Creative",
"upload_time": "2016-04-29 09:36:35",
"width": 300
}
]
}
Returns a list of all the flash creatives. Most recent flash creatives appear first in the list.
Returns
Returns an object with a data
property that contains a list of up to the specified limit and/or offset of objects. Each entry in data
is a flash_creative
object, and if no objects were found the list will be empty.
Video Creatives
Introduction
The video file that makes up an advertisement is known as the video creative. You can create a new video creative, retrieve one or more video creatives, update an existing video creative, or delete the video creative.
The video_creative
response object has the following fields.
Example Response
{
"object": "video_creative",
"self": "/v1/creatives/video/50648",
"id": 50648,
"description": "This is a demo video creative",
"duration": 6,
"file_name": "video-ad.mp4",
"file_size": 2107842,
"group": 228,
"height": 250,
"mime_type": "video/mp4",
"name": "Demo Video Creative",
"upload_time": "2016-04-29 09:48:35",
"video_data_rate": 329677,
"width": 300
}
AdButler\VideoCreative JSON: {
"object": "video_creative",
"self": "/v1/creatives/video/50648",
"id": 50648,
"description": "This is a demo video creative",
"duration": 6,
"file_name": "video-ad.mp4",
"file_size": 2107842,
"group": 228,
"height": 250,
"mime_type": "video/mp4",
"name": "Demo Video Creative",
"upload_time": "2016-04-29 09:48:35",
"video_data_rate": 329677,
"width": 300
}
Field | Type | Description |
---|---|---|
object |
string |
A string denoting the object type which is always |
self |
string |
The relative URL of the current resource which is always of the form |
id |
integer |
The current resource identifier (ID). |
description |
string |
Description of the video creative. |
duration |
integer |
Duration of the video creative. |
file_name |
string |
Name of the uploaded video file. |
file_size |
integer |
Size of the uploaded video file. |
group |
integer |
Media group identifier (ID) the video creative belongs to. |
height |
integer |
Height of the video creative. |
mime_type |
string |
MIME type of the uploaded video creative. |
name |
string |
Name of the video creative. |
upload_time |
string |
The date and time when the video file was uploaded. |
width |
integer |
Width of the video creative. |
video_data_rate |
integer |
Bitrate of the video creative. |
Create a video creative
Definition
POST https://api.adbutler.com/v1/creatives/video
\AdButler\VideoCreative::create()
adbutler.creatives.videos.create()
Example Request
curl "https://api.adbutler.com/v1/creatives/video" \
-H "Authorization: Basic {API_KEY}" \
-H "Expect:" \
-X POST \
-F file=@video-ad.mp4 \
-F attributes='{
"description": "This is a demo video creative",
"group": 228,
"name": "Demo Video Creative"
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$videoCreative = \AdButler\VideoCreative::create(array(
"description" => "This is a demo video creative",
"group" => 228,
"name" => "Demo Video Creative",
"file" => "video-ad.mp4"
));
echo $videoCreative;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var postData = {
"description": "This is a demo video creative",
"group": 228,
"name": "Demo Video Creative",
"file": "video-ad.mp4"
};
// using callbacks
adbutler.creatives.videos.create(postData, function(err, response) {
console.log(response);
});
// using promises
adbutler.creatives.videos.create(postData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "video_creative",
"self": "/v1/creatives/video/50648",
"id": 50648,
"description": "This is a demo video creative",
"duration": 6,
"file_name": "video-ad.mp4",
"file_size": 2107842,
"group": 228,
"height": 250,
"mime_type": "video/mp4",
"name": "Demo Video Creative",
"upload_time": "2016-04-29 09:48:35",
"video_data_rate": 329677,
"width": 300
}
AdButler\VideoCreative JSON: {
"object": "video_creative",
"self": "/v1/creatives/video/50648",
"id": 50648,
"description": "This is a demo video creative",
"duration": 6,
"file_name": "video-ad.mp4",
"file_size": 2107842,
"group": 228,
"height": 250,
"mime_type": "video/mp4",
"name": "Demo Video Creative",
"upload_time": "2016-04-29 09:48:35",
"video_data_rate": 329677,
"width": 300
}
Creates a new video creative.
Field | Type | Description |
---|---|---|
description |
string |
A short description about the video creative. |
file* |
string |
The aboslute or relative path to the video (FLV, MP4, OGV, or WEBM) file. |
group* |
integer |
The media group identifier (ID). |
name |
string |
A descriptive name of the video creative. |
* = required field
Returns
Returns a video_creative
object if the request succeeded, or an error if something went terribly wrong.
Retrieve a video creative
Definition
GET https://api.adbutler.com/v1/creatives/video/{VIDEO-CREATIVE-ID}
\AdButler\VideoCreative::retrieve()
adbutler.creatives.videos.retrieve()
Example Request
curl "https://api.adbutler.com/v1/creatives/video/50648" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$videoCreative = \AdButler\VideoCreative::retrieve( 50648 );
echo $videoCreative;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.creatives.videos.read(50648, function(err, response) {
console.log(response);
});
// using promises
adbutler.creatives.videos.read(50648).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "video_creative",
"self": "/v1/creatives/video/50648",
"id": 50648,
"description": "This is a demo video creative",
"duration": 6,
"file_name": "video-ad.mp4",
"file_size": 2107842,
"group": 228,
"height": 250,
"mime_type": "video/mp4",
"name": "Demo Video Creative",
"upload_time": "2016-04-29 09:48:35",
"video_data_rate": 329677,
"width": 300
}
AdButler\VideoCreative JSON: {
"object": "video_creative",
"self": "/v1/creatives/video/50648",
"id": 50648,
"description": "This is a demo video creative",
"duration": 6,
"file_name": "video-ad.mp4",
"file_size": 2107842,
"group": 228,
"height": 250,
"mime_type": "video/mp4",
"name": "Demo Video Creative",
"upload_time": "2016-04-29 09:48:35",
"video_data_rate": 329677,
"width": 300
}
You can retrieve the information about an existing video creative by giving the video creative identifier that was returned in the creative_video
object upon creation.
Returns
Returns a video_creative
object if the request succeeded, or an error if something went terribly wrong.
Update a video creative
Definition
POST https://api.adbutler.com/v1/creatives/video/{VIDEO-CREATIVE-ID}
\AdButler\VideoCreative->save()
adbutler.creatives.videos.update()
Example Request
curl "https://api.adbutler.com/v1/creatives/video/50648" \
-H "Authorization: Basic {API_KEY}" \
-H "Expect:" \
-X POST \
-F file=@video-ad.mp4 \
-F attributes='{
"description": "This is a demo video creative",
"group": 228,
"name": "Demo Video Creative"
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$videoCreative = \AdButler\VideoCreative::retrieve( 50648 );
$videoCreative->description = "This is a demo video creative";
$videoCreative->group = 228;
$videoCreative->name = "Demo Video Creative";
$videoCreative->file = "video-ad.mp4";
$videoCreative->save();
echo $videoCreative;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var updateData = {
"description": "This is a demo video creative",
"group": 228,
"name": "Demo Video Creative",
"file": "video-ad.mp4"
};
// using callbacks
adbutler.creatives.videos.update(50648, updateData, function(err, response) {
console.log(response);
});
// using promises
adbutler.creatives.videos.update(50648, updateData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "video_creative",
"self": "/v1/creatives/video/50648",
"id": 50648,
"description": "This is a demo video creative",
"duration": 6,
"file_name": "video-ad.mp4",
"file_size": 2107842,
"group": 228,
"height": 250,
"mime_type": "video/mp4",
"name": "Demo Video Creative",
"upload_time": "2016-04-29 09:48:35",
"video_data_rate": 329677,
"width": 300
}
AdButler\VideoCreative JSON: {
"object": "video_creative",
"self": "/v1/creatives/video/50648",
"id": 50648,
"description": "This is a demo video creative",
"duration": 6,
"file_name": "video-ad.mp4",
"file_size": 2107842,
"group": 228,
"height": 250,
"mime_type": "video/mp4",
"name": "Demo Video Creative",
"upload_time": "2016-04-29 09:48:35",
"video_data_rate": 329677,
"width": 300
}
You can update a specific video creative by setting the values of the fields you want to update. If you want the field to retain its old value, then just omit that field from the update request. The update request accepts mostly the same arguments as the video creative creation request.
Field | Type | Description |
---|---|---|
description |
string |
A short description about the video creative. |
file |
string |
The aboslute or relative path to the video (FLV, MP4, OGV, or WEBM) file. |
group |
integer |
The media group identifier (ID). |
name |
string |
A descriptive name of the video creative. |
Returns
Returns a video_creative
object if the request succeeded, or an error if something went terribly wrong.
Delete a video creative
Definition
DELETE https://api.adbutler.com/v1/creatives/video/{VIDEO-CREATIVE-ID}
\AdButler\VideoCreative->delete()
adbutler.creatives.videos.delete()
Example Request
curl "https://api.adbutler.com/v1/creatives/video/50648" \
-H "Authorization: Basic {API_KEY}" \
-X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$videoCreative = \AdButler\VideoCreative::retrieve( 50648 );
$videoCreative->delete();
echo $videoCreative;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.creatives.videos.delete(50648, function(err, response) {
console.log(response);
});
// using promises
adbutler.creatives.videos.delete(50648).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"id": 50648,
"delete": true
}
AdButler\VideoCreative JSON: {
"id": 50648,
"delete": true
}
Permanently deletes a video creative. if successful, this operation cannot be undone so be very sure when deleting one.
Returns
Returns a video creative ID if the request succeeded, or an error if something went terribly wrong.
List all video creatives
Definition
GET https://api.adbutler.com/v1/creatives/video
\AdButler\VideoCreative::retrieveAll()
adbutler.creatives.videos.list()
Example Request
curl "https://api.adbutler.com/v1/creatives/video?limit=2" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$videoCreative = \AdButler\VideoCreative::retrieveAll(array(
"limit" => 2
));
echo $videoCreative;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.creatives.videos.list({
limit: 2
}, function(err, response) {
console.log(response);
});
// using promises
adbutler.creatives.videos.list({
limit: 2
}).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/creatives/video",
"data": [
{
"object": "video_creative",
"self": "/v1/creatives/video/49984",
"id": 49984,
"description": "This is a demo video creative",
"duration": 6,
"file_name": "video-ad.mp4",
"file_size": 2107842,
"group": 228,
"height": 250,
"mime_type": "video/mp4",
"name": "Demo Video Creative",
"upload_time": "2016-04-29 09:48:35",
"video_data_rate": 329677,
"width": 300
},
{
"object": "video_creative",
"self": "/v1/creatives/video/49988",
"id": 49988,
"description": "This is a demo video creative",
"duration": 6,
"file_name": "video-ad.mp4",
"file_size": 2107842,
"group": 228,
"height": 250,
"mime_type": "video/mp4",
"name": "Demo Video Creative",
"upload_time": "2016-04-29 09:48:35",
"video_data_rate": 329677,
"width": 300
}
]
}
AdButler\VideoCreative JSON: {
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/creatives/video",
"data": [
{
"object": "video_creative",
"self": "/v1/creatives/video/49984",
"id": 49984,
"description": "This is a demo video creative",
"duration": 6,
"file_name": "video-ad.mp4",
"file_size": 2107842,
"group": 228,
"height": 250,
"mime_type": "video/mp4",
"name": "Demo Video Creative",
"upload_time": "2016-04-29 09:48:35",
"video_data_rate": 329677,
"width": 300
},
{
"object": "video_creative",
"self": "/v1/creatives/video/49988",
"id": 49988,
"description": "This is a demo video creative",
"duration": 6,
"file_name": "video-ad.mp4",
"file_size": 2107842,
"group": 228,
"height": 250,
"mime_type": "video/mp4",
"name": "Demo Video Creative",
"upload_time": "2016-04-29 09:48:35",
"video_data_rate": 329677,
"width": 300
}
]
}
Returns a list of all the video creatives. Most recent video creatives appear first in the list.
Returns
Returns an object with a data
property that contains a list of up to the specified limit and/or offset of objects. Each entry in data
is a video_creative
object, and if no objects were found the list will be empty.
Rich Media Creatives
Introduction
The zip archive of HTML, CSS and JavaScript files that makes up an advertisement is known as the rich media creative. You can create a new rich media creative, retrieve one or more rich media creatives, update an existing rich media creative, or delete the rich media creative.
The rich_media_creative
response object has the following fields.
Example Response
{
"object": "rich_media_creative",
"self": "/v1/creatives/rich-media/50647",
"id": 50647,
"description": "This is a demo rich media creative",
"file_name": "rich-media-ad.zip",
"file_size": 87587,
"group": 228,
"mime_type": "application/zip",
"name": "Demo Rich Media Creative",
"upload_time": "2016-04-29 09:45:35"
}
AdButler\RichMediaCreative JSON: {
"object": "rich_media_creative",
"self": "/v1/creatives/rich-media/50647",
"id": 50647,
"description": "This is a demo rich media creative",
"file_name": "rich-media-ad.zip",
"file_size": 87587,
"group": 228,
"mime_type": "application/zip",
"name": "Demo Rich Media Creative",
"upload_time": "2016-04-29 09:45:35"
}
Attributes | Type | Description |
---|---|---|
object |
string |
A string denoting the object type which is always |
self |
string |
The relative URL of the current resource which is always of the form |
id |
integer |
The current resource identifier (ID). |
description |
string |
The description of the rich media creative. |
file_name |
string |
The name of the uploaded rich media archive. |
file_size |
integer |
The size of the uploaded rich media archive. |
group |
integer |
Media group identifier (ID) the rich media creative belongs to. |
mime_type |
string |
MIME type of the uploaded rich media archive. |
name |
string |
The name of the rich media creative. |
upload_time |
string |
The date and time when the rich media archive was uploaded. |
Create a rich media creative
Definition
POST https://api.adbutler.com/v1/creatives/rich-media
\AdButler\RichMediaCreative::create()
adbutler.creatives.richMedia.create()
Example Request
curl "https://api.adbutler.com/v1/creatives/rich-media" \
-H "Authorization: Basic {API_KEY}" \
-H "Expect:" \
-X POST \
-F file=@rich-media-ad.zip \
-F attributes='{
"description": "This is a demo rich media creative",
"group": 228,
"name": "Demo Rich Media Creative"
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$richMediaCreative = \AdButler\RichMediaCreative::create(array(
"description" => "This is a demo rich media creative",
"group" => 228,
"name" => "Demo Rich Media Creative",
"file" => "rich-media-ad.zip"
));
echo $richMediaCreative;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var postData = {
"description": "This is a demo rich media creative",
"group": 228,
"name": "Demo Rich Media Creative",
"file": "rich-media-ad.zip"
};
// using callbacks
adbutler.creatives.richMedia.create(postData, function(err, response) {
console.log(response);
});
// using promises
adbutler.creatives.richMedia.create(postData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "rich_media_creative",
"self": "/v1/creatives/rich-media/50647",
"id": 50647,
"description": "This is a demo rich media creative",
"file_name": "rich-media-ad.zip",
"file_size": 87587,
"group": 228,
"mime_type": "application/zip",
"name": "Demo Rich Media Creative",
"upload_time": "2016-04-29 09:45:35"
}
AdButler\RichMediaCreative JSON: {
"object": "rich_media_creative",
"self": "/v1/creatives/rich-media/50647",
"id": 50647,
"description": "This is a demo rich media creative",
"file_name": "rich-media-ad.zip",
"file_size": 87587,
"group": 228,
"mime_type": "application/zip",
"name": "Demo Rich Media Creative",
"upload_time": "2016-04-29 09:45:35"
}
Creates a new rich media creative.
Field | Type | Description |
---|---|---|
description |
string |
A short description about the rich media creative. |
file* |
string |
The aboslute or relative path to the rich media archive (ZIP) file. |
group* |
integer |
The media group identifier (ID). |
name |
string |
A descriptive name of the rich media creative. |
* = required field
Returns
Returns a rich_media_creative
object if the request succeeded, or an error if something went terribly wrong.
Retrieve a rich media creative
Definition
GET https://api.adbutler.com/v1/creatives/rich-media/{RICH-MEDIA-CREATIVE-ID}
\AdButler\RichMediaCreative::retrieve()
adbutler.creatives.richMedia.retrieve()
Example Request
curl "https://api.adbutler.com/v1/creatives/rich-media/50647" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$richMediaCreative = \AdButler\RichMediaCreative::retrieve( 50647 );
echo $richMediaCreative;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.creatives.richMedia.read(50647, function(err, response) {
console.log(response);
});
// using promises
adbutler.creatives.richMedia.read(50647).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "rich_media_creative",
"self": "/v1/creatives/rich-media/50647",
"id": 50647,
"description": "This is a demo rich media creative",
"file_name": "rich-media-ad.zip",
"file_size": 87587,
"group": 228,
"mime_type": "application/zip",
"name": "Demo Rich Media Creative",
"upload_time": "2016-04-29 09:45:35"
}
AdButler\RichMediaCreative JSON: {
"object": "rich_media_creative",
"self": "/v1/creatives/rich-media/50647",
"id": 50647,
"description": "This is a demo rich media creative",
"file_name": "rich-media-ad.zip",
"file_size": 87587,
"group": 228,
"mime_type": "application/zip",
"name": "Demo Rich Media Creative",
"upload_time": "2016-04-29 09:45:35"
}
You can retrieve the information about an existing rich media creative by giving the rich media creative identifier that was returned in the creative_rich_media
object upon creation.
Returns
Returns a rich_media_creative
object if the request succeeded, or an error if something went terribly wrong.
Update a rich media creative
Definition
POST https://api.adbutler.com/v1/creatives/rich-media/{RICH-MEDIA-CREATIVE-ID}
\AdButler\RichMediaCreative->save()
adbutler.creatives.richMedia.update()
Example Request
curl "https://api.adbutler.com/v1/creatives/rich-media/50647" \
-H "Authorization: Basic {API_KEY}" \
-H "Expect:" \
-X POST \
-F file=@rich-media-ad.zip \
-F attributes='{
"description": "This is a demo rich media creative",
"group": 228,
"name": "Demo Rich Media Creative"
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$richMediaCreative = \AdButler\RichMediaCreative::retrieve( 50647 );
$richMediaCreative->description = "This is a demo rich media creative";
$richMediaCreative->group = 228;
$richMediaCreative->name = "Demo Rich Media Creative";
$richMediaCreative->file = "rich-media-ad.zip";
$richMediaCreative->save();
echo $richMediaCreative;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var updateData = {
"description": "This is a demo rich media creative",
"group": 228,
"name": "Demo Rich Media Creative",
"file": "rich-media-ad.zip"
};
// using callbacks
adbutler.creatives.richMedia.update(50647, updateData, function(err, response) {
console.log(response);
});
// using promises
adbutler.creatives.richMedia.update(50647, updateData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "rich_media_creative",
"self": "/v1/creatives/rich-media/50647",
"id": 50647,
"description": "This is a demo rich media creative",
"file_name": "rich-media-ad.zip",
"file_size": 87587,
"group": 228,
"mime_type": "application/zip",
"name": "Demo Rich Media Creative",
"upload_time": "2016-04-29 09:45:35"
}
AdButler\RichMediaCreative JSON: {
"object": "rich_media_creative",
"self": "/v1/creatives/rich-media/50647",
"id": 50647,
"description": "This is a demo rich media creative",
"file_name": "rich-media-ad.zip",
"file_size": 87587,
"group": 228,
"mime_type": "application/zip",
"name": "Demo Rich Media Creative",
"upload_time": "2016-04-29 09:45:35"
}
You can update a specific rich media creative by setting the values of the fields you want to update. If you want the field to retain its old value, then just omit that field from the update request. The update request accepts mostly the same arguments as the rich media creative creation request.
Field | Type | Description |
---|---|---|
description |
string |
A short description about the rich media creative. |
file |
string |
The aboslute or relative path to the rich media archive (ZIP) file. |
group |
integer |
The media group identifier (ID). |
name |
string |
A descriptive name of the rich media creative. |
Returns
Returns a rich_media_creative
object if the request succeeded, or an error if something went terribly wrong.
Delete a rich media creative
Definition
DELETE https://api.adbutler.com/v1/creatives/rich-media/{RICH-MEDIA-CREATIVE-ID}
\AdButler\RichMediaCreative->delete()
adbutler.creatives.richMedia.delete()
Example Request
curl "https://api.adbutler.com/v1/creatives/rich-media/50647" \
-H "Authorization: Basic {API_KEY}" \
-X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$richMediaCreative = \AdButler\RichMediaCreative::retrieve( 50647 );
$richMediaCreative->delete();
echo $richMediaCreative;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.creatives.richMedia.delete(50647, function(err, response) {
console.log(response);
});
// using promises
adbutler.creatives.richMedia.delete(50647).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"id": 50647,
"delete": true
}
AdButler\RichMediaCreative JSON: {
"id": 50647,
"delete": true
}
Permanently deletes an Image Creative. if successful, this operation cannot be undone so be very sure when deleting one.
Returns
Returns a rich media creative ID if the request succeeded, or an error if something went terribly wrong.
List all rich media creatives
Definition
GET https://api.adbutler.com/v1/creatives/rich-media
\AdButler\RichMediaCreative::retrieveAll()
adbutler.creatives.richMedia.list()
Example Request
curl "https://api.adbutler.com/v1/creatives/rich-media?limit=2" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$richMediaCreative = \AdButler\RichMediaCreative::retrieveAll(array(
"limit" => 2
));
echo $richMediaCreative;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.creatives.richMedia.list({
limit: 2
}, function(err, response) {
console.log(response);
});
// using promises
adbutler.creatives.richMedia.list({
limit: 2
}).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/creatives/rich-media",
"data": [
{
"object": "rich_media_creative",
"self": "/v1/creatives/rich-media/49983",
"id": 49983,
"description": "This is a demo rich media creative",
"file_name": "rich-media-ad.zip",
"file_size": 87587,
"group": 228,
"mime_type": "application/zip",
"name": "Demo Rich Media Creative",
"upload_time": "2016-04-29 09:45:35"
},
{
"object": "rich_media_creative",
"self": "/v1/creatives/rich-media/49987",
"id": 49987,
"description": "This is a demo rich media creative",
"file_name": "rich-media-ad.zip",
"file_size": 87587,
"group": 228,
"mime_type": "application/zip",
"name": "Demo Rich Media Creative",
"upload_time": "2016-04-29 09:45:35"
}
]
}
AdButler\RichMediaCreative JSON: {
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/creatives/rich-media",
"data": [
{
"object": "rich_media_creative",
"self": "/v1/creatives/rich-media/49983",
"id": 49983,
"description": "This is a demo rich media creative",
"file_name": "rich-media-ad.zip",
"file_size": 87587,
"group": 228,
"mime_type": "application/zip",
"name": "Demo Rich Media Creative",
"upload_time": "2016-04-29 09:45:35"
},
{
"object": "rich_media_creative",
"self": "/v1/creatives/rich-media/49987",
"id": 49987,
"description": "This is a demo rich media creative",
"file_name": "rich-media-ad.zip",
"file_size": 87587,
"group": 228,
"mime_type": "application/zip",
"name": "Demo Rich Media Creative",
"upload_time": "2016-04-29 09:45:35"
}
]
}
Returns a list of all the rich media creatives. Most recent rich media creatives appear first in the list.
Returns
Returns an object with a data
property that contains a list of up to the specified limit and/or offset of objects. Each entry in data
is a rich_media_creative
object, and if no objects were found the list will be empty.
Schedules
Introduction
Schedules describe the conditions necessary for serving advertisements. Common conditions include start and end dates, and quotas.
You can also use the delivery methods to determine the expiration and pacing set up for advertisements.
Default delivery delivers the impressions as quickly as possible. Smooth delivery will evenly serve over the lifetime dates and quotas.
For example, with smooth delivery, if your campaign has a quota of 30,000 impression set over a period of 60 days, the system would serve the assignment 500 times per day. Smooth delivery assignments have the highest potential priority for serving within AdButler. If a quota has not been filled then that assignment will generally always serve as long as a targeting system does not interfere.
The schedule
response object has the following fields.
Example Response
{
"object": "schedule",
"self": "/v1/schedules/22758",
"id": 22758,
"clicks": 0,
"created_date": "2016-03-22 14:26:50",
"day_cap_type": null,
"day_cap_limit": null,
"delivery_method": "default",
"end_date": "2014-11-02 14:00:00",
"per_user_view_limit": null,
"per_user_view_period": null,
"quota_lifetime": 5000,
"quota_remaining": 5000,
"quota_type": "views",
"start_date": "2014-08-01 14:00:00",
"under_delivery_behaviour": "endOnQuota",
"views": 0
}
AdButler\Schedule JSON: {
"object": "schedule",
"self": "/v1/schedules/22758",
"id": 22758,
"clicks": 0,
"created_date": "2016-03-22 14:26:50",
"day_cap_type": null,
"day_cap_limit": null,
"delivery_method": "default",
"end_date": "2014-11-02 14:00:00",
"per_user_view_limit": null,
"per_user_view_period": null,
"quota_lifetime": 5000,
"quota_remaining": 5000,
"quota_type": "views",
"start_date": "2014-08-01 14:00:00",
"under_delivery_behaviour": "endOnQuota",
"views": 0
}
Field | Type | Description |
---|---|---|
object |
string |
A string denoting the object type which is always |
self |
string |
The relative URL of the current resource which is always of the form |
id |
integer |
The current resource identifier (ID). |
clicks |
integer |
The number of clicks recorded on far. |
created_date |
string |
The date and time when the schedule was created. |
day_cap_limit |
NULL |
The number of times an ad will be shown in a day. |
day_cap_type |
NULL |
Whether |
delivery_method |
string |
The type of ad delivery method. |
end_date |
string |
The date and time when the ad serving should come to halt. |
per_user_view_limit |
NULL |
The number of times the ad will be shown to a particular user in a time period given by |
per_user_view_period |
NULL |
The number of days after which the |
quota_lifetime |
integer |
The number of total impressions to serve. |
quota_remaining |
integer |
The number of impressions remaining to be served. |
quota_type |
string |
The type of quota. |
start_date |
string |
The date and time when the ad serving should start. |
under_delivery_behaviour |
string |
The ad serving behavior once the end date has been reached. |
views |
integer |
The number of views recorded so far. |
Create a schedule
Definition
POST https://api.adbutler.com/v1/schedules
\AdButler\Schedule::create()
adbutler.schedules.create()
Example Request
curl "https://api.adbutler.com/v1/schedules" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"delivery_method": "default",
"end_date": "2014-11-02 14:00:00",
"quota_lifetime": 5000,
"quota_type": "views",
"start_date": "2014-08-01 14:00:00",
"under_delivery_behaviour": "endOnQuota"
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$schedule = \AdButler\Schedule::create(array(
"delivery_method" => "default",
"end_date" => "2014-11-02 14:00:00",
"quota_lifetime" => 5000,
"quota_type" => "views",
"start_date" => "2014-08-01 14:00:00",
"under_delivery_behaviour" => "endOnQuota"
));
echo $schedule;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var postData = {
"delivery_method": "default",
"end_date": "2014-11-02 14:00:00",
"quota_lifetime": 5000,
"quota_type": "views",
"start_date": "2014-08-01 14:00:00",
"under_delivery_behaviour": "endOnQuota"
};
// using callbacks
adbutler.schedules.create(postData, function(err, response) {
console.log(response);
});
// using promises
adbutler.schedules.create(postData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "schedule",
"self": "/v1/schedules/22758",
"id": 22758,
"clicks": 0,
"created_date": "2016-03-22 14:26:50",
"day_cap_type": null,
"day_cap_limit": null,
"delivery_method": "default",
"end_date": "2014-11-02 14:00:00",
"per_user_view_limit": null,
"per_user_view_period": null,
"quota_lifetime": 5000,
"quota_remaining": 5000,
"quota_type": "views",
"start_date": "2014-08-01 14:00:00",
"under_delivery_behaviour": "endOnQuota",
"views": 0
}
AdButler\Schedule JSON: {
"object": "schedule",
"self": "/v1/schedules/22758",
"id": 22758,
"clicks": 0,
"created_date": "2016-03-22 14:26:50",
"day_cap_type": null,
"day_cap_limit": null,
"delivery_method": "default",
"end_date": "2014-11-02 14:00:00",
"per_user_view_limit": null,
"per_user_view_period": null,
"quota_lifetime": 5000,
"quota_remaining": 5000,
"quota_type": "views",
"start_date": "2014-08-01 14:00:00",
"under_delivery_behaviour": "endOnQuota",
"views": 0
}
Creates a new schedule.
Field | Type | Description |
---|---|---|
day_cap_limit |
integer |
The number of times an ad will be shown in a day. Defaults to |
day_cap_type |
string |
Whether to impose dialy limits on the amount of views ( |
delivery_method |
string |
Whether to deliver the impressions as quickly as spossible ( |
start_date† |
string |
The time and date when AdButler should start serving your advertisement. You can delay serving of ads by setting a future start date. Defaults to midnight of the current date if not given. |
end_date† |
string |
The time and date when AdButler should stop serving your advertisement. The end date can be as far in the future as desired. This allows you to set time-based expiration for your ads and we guarantee accuracy to the hour. Leave this field empty if you want ad serving to never end. |
per_user_view_limit |
integer |
The number of times the ad will be shown to a particular user in a time period given by |
per_user_view_period |
integer |
The number of days after which the |
quota_lifetime† |
integer |
The amount of quota when seeting up quota-based expiration which is a direct number ( |
quota_type† |
string |
The type of quota when setting up quota-based expiration which can be the number of clicks ( |
under_delivery_behaviour† |
string |
Whether to keep serving ads until the quota is met ( |
* = required field
† = must be given if delivery_method
is smooth
, otherwise defaults to the default value of the field
Returns
Returns a schedule
object if the request succeeded, or an error if something went terribly wrong.
Retrieve a schedule
Definition
GET https://api.adbutler.com/v1/schedules/{SCHEDULE-ID}
\AdButler\Schedule::retrieve()
adbutler.schedules.retrieve()
Example Request
curl "https://api.adbutler.com/v1/schedules/22758" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$schedule = \AdButler\Schedule::retrieve( 22758 );
echo $schedule;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.schedules.read(22758, function(err, response) {
console.log(response);
});
// using promises
adbutler.schedules.read(22758).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "schedule",
"self": "/v1/schedules/22758",
"id": 22758,
"clicks": 0,
"created_date": "2016-03-22 14:26:50",
"day_cap_type": null,
"day_cap_limit": null,
"delivery_method": "default",
"end_date": "2014-11-02 14:00:00",
"per_user_view_limit": null,
"per_user_view_period": null,
"quota_lifetime": 5000,
"quota_remaining": 5000,
"quota_type": "views",
"start_date": "2014-08-01 14:00:00",
"under_delivery_behaviour": "endOnQuota",
"views": 0
}
AdButler\Schedule JSON: {
"object": "schedule",
"self": "/v1/schedules/22758",
"id": 22758,
"clicks": 0,
"created_date": "2016-03-22 14:26:50",
"day_cap_type": null,
"day_cap_limit": null,
"delivery_method": "default",
"end_date": "2014-11-02 14:00:00",
"per_user_view_limit": null,
"per_user_view_period": null,
"quota_lifetime": 5000,
"quota_remaining": 5000,
"quota_type": "views",
"start_date": "2014-08-01 14:00:00",
"under_delivery_behaviour": "endOnQuota",
"views": 0
}
You can retrieve the information about an existing schedule by giving the schedule ID that was returned in the schedule object upon creation. You will see at the most 10 schedules in the response. You can change this default limit by appending ?limit=25
if you want this request to return 25 schedules.
Returns
Returns a schedule
object if the request succeeded, or an error if something went terribly wrong.
Update a schedule
Definition
PUT https://api.adbutler.com/v1/schedules/{SCHEDULE-ID}
\AdButler\Schedule->save()
adbutler.schedules.update()
Example Request
curl "https://api.adbutler.com/v1/schedules/22758" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
"delivery_method": "default",
"end_date": "2014-11-02 14:00:00",
"quota_lifetime": 5000,
"quota_type": "views",
"start_date": "2014-08-01 14:00:00",
"under_delivery_behaviour": "endOnQuota"
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$schedule = \AdButler\Schedule::retrieve( 22758 );
$schedule->delivery_method = "default";
$schedule->end_date = "2014-11-02 14:00:00";
$schedule->quota_lifetime = 5000;
$schedule->quota_type = "views";
$schedule->start_date = "2014-08-01 14:00:00";
$schedule->under_delivery_behaviour = "endOnQuota";
$schedule->save();
echo $schedule;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var updateData = {
"delivery_method": "default",
"end_date": "2014-11-02 14:00:00",
"quota_lifetime": 5000,
"quota_type": "views",
"start_date": "2014-08-01 14:00:00",
"under_delivery_behaviour": "endOnQuota"
};
// using callbacks
adbutler.schedules.update(22758, updateData, function(err, response) {
console.log(response);
});
// using promises
adbutler.schedules.update(22758, updateData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "schedule",
"self": "/v1/schedules/22758",
"id": 22758,
"clicks": 0,
"created_date": "2016-03-22 14:26:50",
"day_cap_type": null,
"day_cap_limit": null,
"delivery_method": "default",
"end_date": "2014-11-02 14:00:00",
"per_user_view_limit": null,
"per_user_view_period": null,
"quota_lifetime": 5000,
"quota_remaining": 5000,
"quota_type": "views",
"start_date": "2014-08-01 14:00:00",
"under_delivery_behaviour": "endOnQuota",
"views": 0
}
AdButler\Schedule JSON: {
"object": "schedule",
"self": "/v1/schedules/22758",
"id": 22758,
"clicks": 0,
"created_date": "2016-03-22 14:26:50",
"day_cap_type": null,
"day_cap_limit": null,
"delivery_method": "default",
"end_date": "2014-11-02 14:00:00",
"per_user_view_limit": null,
"per_user_view_period": null,
"quota_lifetime": 5000,
"quota_remaining": 5000,
"quota_type": "views",
"start_date": "2014-08-01 14:00:00",
"under_delivery_behaviour": "endOnQuota",
"views": 0
}
You can update a specific schedule by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the schedule creation request.
Field | Type | Description |
---|---|---|
day_cap_limit |
integer |
The number of times an ad will be shown in a day. Defaults to |
day_cap_type |
string |
Whether to impose dialy limits on the amount of views ( |
delivery_method |
string |
Whether to deliver the impressions as quickly as spossible ( |
start_date† |
string |
The time and date when AdButler should start serving your advertisement. You can delay serving of ads by setting a future start date. Defaults to midnight of the current date if not given. |
end_date† |
string |
The time and date when AdButler should stop serving your advertisement. The end date can be as far in the future as desired. This allows you to set time-based expiration for your ads and we guarantee accuracy to the hour. Leave this field empty if you want ad serving to never end. |
per_user_view_limit |
integer |
The number of times the ad will be shown to a particular user in a time period given by |
per_user_view_period |
integer |
The number of days after which the |
quota_lifetime† |
integer |
The amount of quota when seeting up quota-based expiration which is a direct number ( |
quota_type† |
string |
The type of quota when setting up quota-based expiration which can be the number of clicks ( |
under_delivery_behaviour† |
string |
Whether to keep serving ads until the quota is met ( |
† = must be given if delivery_method
is smooth
, otherwise defaults to the default value of the field
Returns
Returns a schedule
object if the request succeeded, or an error if something went terribly wrong.
Delete a schedule
Definition
DELETE https://api.adbutler.com/v1/schedules/{SCHEDULE-ID}
\AdButler\Schedule->delete()
adbutler.schedules.delete()
Example Request
curl "https://api.adbutler.com/v1/schedules/22758" \
-H "Authorization: Basic {API_KEY}" \
-X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$schedule = \AdButler\Schedule::retrieve( 22758 );
$schedule->delete();
echo $schedule;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.schedules.delete(22758, function(err, response) {
console.log(response);
});
// using promises
adbutler.schedules.delete(22758).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"id": 22758,
"delete": true
}
AdButler\Schedule JSON: {
"id": 22758,
"delete": true
}
Permanently deletes a schedule. if successful, this operation cannot be undone so be very sure when deleting one.
Returns
Returns a schedule ID if the request succeeded, or an error if something went terribly wrong.
List all schedules
Definition
GET https://api.adbutler.com/v1/schedules
\AdButler\Schedule::retrieveAll()
adbutler.schedules.list()
Example Request
curl "https://api.adbutler.com/v1/schedules?limit=2" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$schedule = \AdButler\Schedule::retrieveAll(array(
"limit" => 2
));
echo $schedule;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.schedules.list({
limit: 2
}, function(err, response) {
console.log(response);
});
// using promises
adbutler.schedules.list({
limit: 2
}).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/schedules",
"data": [
{
"object": "schedule",
"self": "/v1/schedules/22512",
"id": 22512,
"clicks": 0,
"created_date": "2018-06-28 09:48:12",
"day_cap_type": "views",
"day_cap_limit": null,
"delivery_method": "default",
"end_date": null,
"per_user_view_limit": null,
"per_user_view_period": null,
"quota_lifetime": null,
"quota_remaining": null,
"quota_type": null,
"start_date": null,
"under_delivery_behaviour": "endOnDate",
"views": 0
},
{
"object": "schedule",
"self": "/v1/schedules/22513",
"id": 22513,
"clicks": 0,
"created_date": "2018-06-28 09:48:12",
"day_cap_type": "views",
"day_cap_limit": null,
"delivery_method": "default",
"end_date": null,
"per_user_view_limit": null,
"per_user_view_period": null,
"quota_lifetime": null,
"quota_remaining": null,
"quota_type": null,
"start_date": null,
"under_delivery_behaviour": "endOnDate",
"views": 0
}
]
}
AdButler\Schedule JSON: {
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/schedules",
"data": [
{
"object": "schedule",
"self": "/v1/schedules/22512",
"id": 22512,
"clicks": 0,
"created_date": "2018-06-28 09:48:12",
"day_cap_type": "views",
"day_cap_limit": null,
"delivery_method": "default",
"end_date": null,
"per_user_view_limit": null,
"per_user_view_period": null,
"quota_lifetime": null,
"quota_remaining": null,
"quota_type": null,
"start_date": null,
"under_delivery_behaviour": "endOnDate",
"views": 0
},
{
"object": "schedule",
"self": "/v1/schedules/22513",
"id": 22513,
"clicks": 0,
"created_date": "2018-06-28 09:48:12",
"day_cap_type": "views",
"day_cap_limit": null,
"delivery_method": "default",
"end_date": null,
"per_user_view_limit": null,
"per_user_view_period": null,
"quota_lifetime": null,
"quota_remaining": null,
"quota_type": null,
"start_date": null,
"under_delivery_behaviour": "endOnDate",
"views": 0
}
]
}
Returns a list of all the schedules. Most recent schedule accounts appear first in the list.
Returns
Returns an object with a data
property that contains a list of up to the specified limit and/or offset of objects. Each entry in data
is a schedule
object, and if no objects were found the list will be empty.
Placements
Introduction
Assign an advertisement to a zone based on a set of scheduling criteria using the placements endpoint.
Each placement represents combination of criteria required to serve an advertisement. Prior to creating a placement, you will need to have created several other resources:
- Advertisement (banner/campaign/text-ad/popup)
- Zone
- Schedule
You may also optionally create targeting options, keywords, and activity limits to further control the deliverability of your placements.
The placement
response object has the following fields.
Example Response
{
"object": "placement",
"self": "/v1/placements/18597",
"id": 18597,
"active": true,
"advertisement": {
"id": 518889981,
"type": "image_banner"
},
"channel": null,
"cost": {
"cpm": 0.05,
"cpc": 0.1,
"cpa": 0.05
},
"created_date": "2018-11-28 11:49:48",
"day_cap_limit": 5000,
"day_cap_type": null,
"geo_target": null,
"isp_target": null,
"keywords": "",
"keywords_match_method": "preferred",
"payout_percent": 2,
"per_user_view_limit": 500,
"per_user_view_period": 3,
"platform_target": null,
"priority": "standard",
"schedule": 22758,
"weight": 2,
"zone": {
"id": 104144,
"type": "banner_zone"
}
}
AdButler\Placement JSON: {
"object": "placement",
"self": "/v1/placements/18597",
"id": 18597,
"active": true,
"advertisement": {
"id": 518889981,
"type": "image_banner"
},
"channel": null,
"cost": {
"cpm": 0.05,
"cpc": 0.1,
"cpa": 0.05
},
"created_date": "2018-11-28 11:49:48",
"day_cap_limit": 5000,
"day_cap_type": null,
"geo_target": null,
"isp_target": null,
"keywords": "",
"keywords_match_method": "preferred",
"payout_percent": 2,
"per_user_view_limit": 500,
"per_user_view_period": 3,
"platform_target": null,
"priority": "standard",
"schedule": 22758,
"weight": 2,
"zone": {
"id": 104144,
"type": "banner_zone"
}
}
Field | Type | Description |
---|---|---|
object |
string |
A string denoting the object type which is always |
self |
string |
The relative URL of the current resource which is always of the form |
id |
integer |
The current resource identifier (ID). |
active |
boolean |
The status of ad serving whether it is being served in the given zone or not. |
advertisement |
array |
An object containing image banner, flash banner, rich media banner, custom HTML banner, banner campaign, text campaign, image popup, flash popup, custom HTML popup, or text ad identifier (ID) and type. |
channel |
NULL |
The channel identifier (ID). |
cost |
array |
The revenue details of the banner placement. |
created_date |
string |
The date and time when the banner placement was created. |
day_cap_limit |
integer |
This field has been moved to the schedule object and is now deprecated. |
day_cap_type |
NULL |
This field has been moved to the schedule object and is now deprecated. |
geo_target |
NULL |
The geotarget identifier (ID). |
isp_target |
NULL |
The ISP target identifier (ID). |
keywords |
string |
The list of comma separated words to determine whether the ad should or should not be served if word matches are found. |
keywords_match_method |
string |
Whether to serve the ad only if a keyword match is found ("required") or just increase the serving priority of the ad whenever a keyword match is found ("preferred"). The Keyword match method indicates how important the keyword is. |
payout_percent |
integer |
The percentage of the ad generated revenue paid out to the publisher. |
per_user_view_limit |
integer |
This field has been moved to the schedule object and is now deprecated. |
per_user_view_period |
integer |
This field has been moved to the schedule object and is now deprecated. |
platform_target |
NULL |
The platform target identifier (ID). |
priority |
string |
A value specifying whether to prefer serving of some ads over others in a campaign or channel. |
schedule |
integer |
The schedule identifier (ID). |
weight |
integer |
A number used to compute the probability of serving a particular ad. |
zone |
array |
An object containing banner, email, or text zone identifier (ID) and type. |
Create a placement
Definition
POST https://api.adbutler.com/v1/placements
\AdButler\Placement::create()
adbutler.placements.create()
Example Request
curl "https://api.adbutler.com/v1/placements" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"active": true,
"advertisement":
{
id: 518889981,
type: "image_banner"
},
"cost":
{
cpm: 0.05,
cpc: 0.1,
cpa: 0.05
},
"day_cap_limit": 5000,
"day_cap_type": null,
"geo_target": null,
"isp_target": null,
"keywords": "",
"keywords_match_method": "preferred",
"payout_percent": 2,
"per_user_view_limit": 500,
"per_user_view_period": 3,
"platform_target": null,
"priority": "standard",
"schedule": 22758,
"weight": 2,
"zone":
{
id: 104144,
type: "banner_zone"
}
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$placement = \AdButler\Placement::create(array(
"active" => true,
"advertisement" =>
[
id => 518889981,
type => "image_banner"
],
"cost" =>
[
cpm => 0.05,
cpc => 0.1,
cpa => 0.05
],
"day_cap_limit" => 5000,
"day_cap_type" => null,
"geo_target" => null,
"isp_target" => null,
"keywords" => "",
"keywords_match_method" => "preferred",
"payout_percent" => 2,
"per_user_view_limit" => 500,
"per_user_view_period" => 3,
"platform_target" => null,
"priority" => "standard",
"schedule" => 22758,
"weight" => 2,
"zone" =>
[
id => 104144,
type => "banner_zone"
]
));
echo $placement;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var postData = {
"active": true,
"advertisement":
{
id: 518889981,
type: "image_banner"
},
"cost":
{
cpm: 0.05,
cpc: 0.1,
cpa: 0.05
},
"day_cap_limit": 5000,
"day_cap_type": null,
"geo_target": null,
"isp_target": null,
"keywords": "",
"keywords_match_method": "preferred",
"payout_percent": 2,
"per_user_view_limit": 500,
"per_user_view_period": 3,
"platform_target": null,
"priority": "standard",
"schedule": 22758,
"weight": 2,
"zone":
{
id: 104144,
type: "banner_zone"
}
};
// using callbacks
adbutler.placements.create(postData, function(err, response) {
console.log(response);
});
// using promises
adbutler.placements.create(postData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "placement",
"self": "/v1/placements/18597",
"id": 18597,
"active": true,
"advertisement": {
"id": 518889981,
"type": "image_banner"
},
"channel": null,
"cost": {
"cpm": 0.05,
"cpc": 0.1,
"cpa": 0.05
},
"created_date": "2018-11-28 11:49:48",
"day_cap_limit": 5000,
"day_cap_type": null,
"geo_target": null,
"isp_target": null,
"keywords": "",
"keywords_match_method": "preferred",
"payout_percent": 2,
"per_user_view_limit": 500,
"per_user_view_period": 3,
"platform_target": null,
"priority": "standard",
"schedule": 22758,
"weight": 2,
"zone": {
"id": 104144,
"type": "banner_zone"
}
}
AdButler\Placement JSON: {
"object": "placement",
"self": "/v1/placements/18597",
"id": 18597,
"active": true,
"advertisement": {
"id": 518889981,
"type": "image_banner"
},
"channel": null,
"cost": {
"cpm": 0.05,
"cpc": 0.1,
"cpa": 0.05
},
"created_date": "2018-11-28 11:49:48",
"day_cap_limit": 5000,
"day_cap_type": null,
"geo_target": null,
"isp_target": null,
"keywords": "",
"keywords_match_method": "preferred",
"payout_percent": 2,
"per_user_view_limit": 500,
"per_user_view_period": 3,
"platform_target": null,
"priority": "standard",
"schedule": 22758,
"weight": 2,
"zone": {
"id": 104144,
"type": "banner_zone"
}
}
Creates a new banner placement.
Field | Type | Description |
---|---|---|
schedule* |
integer |
The schedule identifier (ID). |
advertisement* |
object |
An object containing image banner, flash banner, rich media banner, custom HTML banner, banner campaign, text campaign, image popup, flash popup, custom HTML popup, or text ad identifier (ID) and type. |
zone* |
integer |
An object containing banner, email, or text zone identifier (ID) and type. |
active |
boolean |
Whether to actively serve ads in the zones ( |
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 |
priority |
string |
Priority allows you to prefer serving of some ads over others in a campaign or channel. Possible values in descending order are |
|
|
This field has been moved to the schedule object. Using this field is now deprecated. |
|
|
This field has been moved to the schedule object. Using this field is now deprecated. |
|
|
This field has been moved to the schedule object. Using this field is now deprecated. |
|
|
This field has been moved to the schedule object. Using this field is now deprecated. |
cost |
object |
An object associating a pricing model with the performance of your banner placement. This information will be used to calculate the revenue generated by your ad. You can either use a fixed cost or a rate based pricing model for your ad placements. Fixed cost is tied to the amount of quota and is given as |
payout_percent |
integer/float |
The percentage of the ad generated revenue paid out to the publisher. Publisher payout is ideal for profit sharing where the revenue is split between money earned by the advertiser and money earned by the publisher. Defaults to |
geo_target |
integer |
The geotarget identifier (ID) if you want your ads to be delivered to a particular location only. This will direct your audience to ads in their region. Defaults to |
platform_target |
integer |
The platform target identifier (ID) if you intend to restrict delivery of your ads to a certain device or a platform. Defaults to |
keywords |
string |
Specify words separated by commas to determine if this ad should be served if a match is found. Use asterisk "*" character to represent a wildcard in a keyword e.g. "paint*" would match paint, painter, painting, paints etc. You can also stop the ad from being served in presence of a specific word by prepending a negative sign ( |
keywords_match_method |
string |
Whether to serve the ad only if a match is found ( |
* = required field
Returns
Returns a placement
object if the request succeeded, or an error if something went terribly wrong.
Retrieve a placement
Definition
GET https://api.adbutler.com/v1/placements/{PLACEMENT-ID}
\AdButler\Placement::retrieve()
adbutler.placements.retrieve()
Example Request
curl "https://api.adbutler.com/v1/placements/18597" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$placement = \AdButler\Placement::retrieve( 18597 );
echo $placement;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.placements.read(18597, function(err, response) {
console.log(response);
});
// using promises
adbutler.placements.read(18597).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "placement",
"self": "/v1/placements/18597",
"id": 18597,
"active": true,
"advertisement": {
"id": 518889981,
"type": "image_banner"
},
"channel": null,
"cost": {
"cpm": 0.05,
"cpc": 0.1,
"cpa": 0.05
},
"created_date": "2018-11-28 11:49:48",
"day_cap_limit": 5000,
"day_cap_type": null,
"geo_target": null,
"isp_target": null,
"keywords": "",
"keywords_match_method": "preferred",
"payout_percent": 2,
"per_user_view_limit": 500,
"per_user_view_period": 3,
"platform_target": null,
"priority": "standard",
"schedule": 22758,
"weight": 2,
"zone": {
"id": 104144,
"type": "banner_zone"
}
}
AdButler\Placement JSON: {
"object": "placement",
"self": "/v1/placements/18597",
"id": 18597,
"active": true,
"advertisement": {
"id": 518889981,
"type": "image_banner"
},
"channel": null,
"cost": {
"cpm": 0.05,
"cpc": 0.1,
"cpa": 0.05
},
"created_date": "2018-11-28 11:49:48",
"day_cap_limit": 5000,
"day_cap_type": null,
"geo_target": null,
"isp_target": null,
"keywords": "",
"keywords_match_method": "preferred",
"payout_percent": 2,
"per_user_view_limit": 500,
"per_user_view_period": 3,
"platform_target": null,
"priority": "standard",
"schedule": 22758,
"weight": 2,
"zone": {
"id": 104144,
"type": "banner_zone"
}
}
You can retrieve the information about an existing banner placement by giving the banner placement ID that was returned in the banner placement object upon creation. You will see at the most 10 banner placements in the response. You can change this default limit by appending ?limit=25
if you want this request to return 25 banner placements.
Returns
Returns a placement
object if the request succeeded, or an error if something went terribly wrong.
Update a placement
Definition
PUT https://api.adbutler.com/v1/placements/{PLACEMENT-ID}
\AdButler\Placement->save()
adbutler.placements.update()
Example Request
curl "https://api.adbutler.com/v1/placements/18597" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
"active": true,
"advertisement":
{
id: 518889981,
type: "image_banner"
},
"cost":
{
cpm: 0.05,
cpc: 0.1,
cpa: 0.05
},
"day_cap_limit": 5000,
"day_cap_type": null,
"geo_target": null,
"isp_target": null,
"keywords": "",
"keywords_match_method": "preferred",
"payout_percent": 2,
"per_user_view_limit": 500,
"per_user_view_period": 3,
"platform_target": null,
"priority": "standard",
"schedule": 22758,
"weight": 2,
"zone":
{
id: 104144,
type: "banner_zone"
}
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$placement = \AdButler\Placement::retrieve( 18597 );
$placement->active = true;
$placement->advertisement =
[
id = 518889981,
type = "image_banner"
];
$placement->cost =
[
cpm = 0.05,
cpc = 0.1,
cpa = 0.05
];
$placement->day_cap_limit = 5000;
$placement->day_cap_type = null;
$placement->geo_target = null;
$placement->isp_target = null;
$placement->keywords = "";
$placement->keywords_match_method = "preferred";
$placement->payout_percent = 2;
$placement->per_user_view_limit = 500;
$placement->per_user_view_period = 3;
$placement->platform_target = null;
$placement->priority = "standard";
$placement->schedule = 22758;
$placement->weight = 2;
$placement->zone =
[
id = 104144,
type = "banner_zone"
];
$placement->save();
echo $placement;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var updateData = {
"active": true,
"advertisement":
{
id: 518889981,
type: "image_banner"
},
"cost":
{
cpm: 0.05,
cpc: 0.1,
cpa: 0.05
},
"day_cap_limit": 5000,
"day_cap_type": null,
"geo_target": null,
"isp_target": null,
"keywords": "",
"keywords_match_method": "preferred",
"payout_percent": 2,
"per_user_view_limit": 500,
"per_user_view_period": 3,
"platform_target": null,
"priority": "standard",
"schedule": 22758,
"weight": 2,
"zone":
{
id: 104144,
type: "banner_zone"
}
};
// using callbacks
adbutler.placements.update(18597, updateData, function(err, response) {
console.log(response);
});
// using promises
adbutler.placements.update(18597, updateData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "placement",
"self": "/v1/placements/18597",
"id": 18597,
"active": true,
"advertisement": {
"id": 518889981,
"type": "image_banner"
},
"channel": null,
"cost": {
"cpm": 0.05,
"cpc": 0.1,
"cpa": 0.05
},
"created_date": "2018-11-28 11:49:48",
"day_cap_limit": 5000,
"day_cap_type": null,
"geo_target": null,
"isp_target": null,
"keywords": "",
"keywords_match_method": "preferred",
"payout_percent": 2,
"per_user_view_limit": 500,
"per_user_view_period": 3,
"platform_target": null,
"priority": "standard",
"schedule": 22758,
"weight": 2,
"zone": {
"id": 104144,
"type": "banner_zone"
}
}
AdButler\Placement JSON: {
"object": "placement",
"self": "/v1/placements/18597",
"id": 18597,
"active": true,
"advertisement": {
"id": 518889981,
"type": "image_banner"
},
"channel": null,
"cost": {
"cpm": 0.05,
"cpc": 0.1,
"cpa": 0.05
},
"created_date": "2018-11-28 11:49:48",
"day_cap_limit": 5000,
"day_cap_type": null,
"geo_target": null,
"isp_target": null,
"keywords": "",
"keywords_match_method": "preferred",
"payout_percent": 2,
"per_user_view_limit": 500,
"per_user_view_period": 3,
"platform_target": null,
"priority": "standard",
"schedule": 22758,
"weight": 2,
"zone": {
"id": 104144,
"type": "banner_zone"
}
}
You can update a specific banner placement by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the banner placement creation request.
Field | Type | Description |
---|---|---|
schedule |
integer |
The schedule identifier (ID). |
advertisement |
object |
An object containing image banner, flash banner, rich media banner, custom HTML banner, banner campaign, text campaign, image popup, flash popup, custom HTML popup, or text ad identifier (ID) and type. |
zone |
integer |
An object containing banner, email, or text zone identifier (ID) and type. |
active |
boolean |
Whether to actively serve ads in the zones ( |
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 |
priority |
string |
Priority allows you to prefer serving of some ads over others in a campaign or channel. Possible values in descending order are |
|
|
This field has been moved to the schedule object. Using this field is now deprecated. |
|
|
This field has been moved to the schedule object. Using this field is now deprecated. |
|
|
This field has been moved to the schedule object. Using this field is now deprecated. |
|
|
This field has been moved to the schedule object. Using this field is now deprecated. |
cost |
object |
An object associating a pricing model with the performance of your banner placement. This information will be used to calculate the revenue generated by your ad. You can either use a fixed cost or a rate based pricing model for your ad placements. Fixed cost is tied to the amount of quota and is given as |
payout_percent |
integer/float |
The percentage of the ad generated revenue paid out to the publisher. Publisher payout is ideal for profit sharing where the revenue is split between money earned by the advertiser and money earned by the publisher. Defaults to |
geo_target |
integer |
The geotarget identifier (ID) if you want your ads to be delivered to a particular location only. This will direct your audience to ads in their region. Defaults to |
platform_target |
integer |
The platform target identifier (ID) if you intend to restrict delivery of your ads to a certain device or a platform. Defaults to |
keywords |
string |
Specify words separated by commas to determine if this ad should be served if a match is found. Use asterisk "*" character to represent a wildcard in a keyword e.g. "paint*" would match paint, painter, painting, paints etc. You can also stop the ad from being served in presence of a specific word by prepending a negative sign ( |
keywords_match_method |
string |
Whether to serve the ad only if a match is found ( |
Returns
Returns a placement
object if the request succeeded, or an error if something went terribly wrong.
Delete a placement
Definition
DELETE https://api.adbutler.com/v1/placements/{PLACEMENT-ID}
\AdButler\Placement->delete()
adbutler.placements.delete()
Example Request
curl "https://api.adbutler.com/v1/placements/18597" \
-H "Authorization: Basic {API_KEY}" \
-X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$placement = \AdButler\Placement::retrieve( 18597 );
$placement->delete();
echo $placement;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.placements.delete(18597, function(err, response) {
console.log(response);
});
// using promises
adbutler.placements.delete(18597).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"id": 18597,
"delete": true
}
AdButler\Placement JSON: {
"id": 18597,
"delete": true
}
Permanently deletes a banner placement. if successful, this operation cannot be undone so be very sure when deleting one.
Returns
Returns a placement ID if the request succeeded, or an error if something went terribly wrong.
List all placements
Definition
GET https://api.adbutler.com/v1/placements
\AdButler\Placement::retrieveAll()
adbutler.placements.list()
Example Request
curl "https://api.adbutler.com/v1/placements?limit=2" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$placement = \AdButler\Placement::retrieveAll(array(
"limit" => 2
));
echo $placement;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.placements.list({
limit: 2
}, function(err, response) {
console.log(response);
});
// using promises
adbutler.placements.list({
limit: 2
}).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/placements",
"data": [
{
"object": "placement",
"self": "/v1/placements/18377",
"id": 18377,
"active": true,
"advertisement": {
"id": 518889708,
"type": "image_banner"
},
"channel": null,
"cost": [],
"created_date": "2018-06-28 09:48:12",
"day_cap_limit": null,
"day_cap_type": null,
"geo_target": null,
"isp_target": null,
"keywords": "",
"keywords_match_method": "preferred",
"payout_percent": null,
"per_user_view_limit": null,
"per_user_view_period": null,
"platform_target": null,
"priority": "standard",
"schedule": 22512,
"weight": 1,
"zone": {
"id": 104022,
"type": "banner_zone"
}
},
{
"object": "placement",
"self": "/v1/placements/18378",
"id": 18378,
"active": true,
"advertisement": {
"id": 4567,
"type": "text_ad"
},
"channel": null,
"cost": [],
"created_date": "2018-06-28 09:48:12",
"day_cap_limit": null,
"day_cap_type": null,
"geo_target": null,
"isp_target": null,
"keywords": "",
"keywords_match_method": "preferred",
"payout_percent": null,
"per_user_view_limit": null,
"per_user_view_period": null,
"platform_target": null,
"priority": "standard",
"schedule": 22513,
"weight": 1,
"zone": {
"id": 104023,
"type": "text_zone"
}
}
]
}
AdButler\Placement JSON: {
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/placements",
"data": [
{
"object": "placement",
"self": "/v1/placements/18377",
"id": 18377,
"active": true,
"advertisement": {
"id": 518889708,
"type": "image_banner"
},
"channel": null,
"cost": [],
"created_date": "2018-06-28 09:48:12",
"day_cap_limit": null,
"day_cap_type": null,
"geo_target": null,
"isp_target": null,
"keywords": "",
"keywords_match_method": "preferred",
"payout_percent": null,
"per_user_view_limit": null,
"per_user_view_period": null,
"platform_target": null,
"priority": "standard",
"schedule": 22512,
"weight": 1,
"zone": {
"id": 104022,
"type": "banner_zone"
}
},
{
"object": "placement",
"self": "/v1/placements/18378",
"id": 18378,
"active": true,
"advertisement": {
"id": 4567,
"type": "text_ad"
},
"channel": null,
"cost": [],
"created_date": "2018-06-28 09:48:12",
"day_cap_limit": null,
"day_cap_type": null,
"geo_target": null,
"isp_target": null,
"keywords": "",
"keywords_match_method": "preferred",
"payout_percent": null,
"per_user_view_limit": null,
"per_user_view_period": null,
"platform_target": null,
"priority": "standard",
"schedule": 22513,
"weight": 1,
"zone": {
"id": 104023,
"type": "text_zone"
}
}
]
}
Returns a list of all the banner placements. Most recent banner placements appear first in the list.
Returns
Returns an object with a data
property that contains a list of up to the specified limit and/or offset of objects. Each entry in data
is a placement
object, and if no objects were found the list will be empty.
Retrieve placement conversion tag
Definition
GET https://api.adbutler.com/v1/placements/{PLACEMENT-ID}/conversion-tag
\AdButler\PlacementConvTag::retrieve()
adbutler.placements.conversionTag.retrieve()
Example Request
curl "https://api.adbutler.com/v1/placements/ID/conversion-tag/18597" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$placementConvTag = \AdButler\PlacementConvTag::retrieve( 18597 );
echo $placementConvTag;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.placements.conversionTag.read(18597, function(err, response) {
console.log(response);
});
// using promises
adbutler.placements.conversionTag.read(18597).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Retrieves an HTML tag which can be used to track conversions for the provided placement.
Query Parameters
Parameter | Description |
---|---|
protocol |
Whether to use |
Returns
Example Response
{
"object": "conv_tag",
"url": "/v1/placements/18597/conversion-tag",
"data": {
"src": "https://servedbyadbutler.com.vm.test/convtrack.spark?MID=108607&placementID=18597",
"html": "<img src='https://servedbyadbutler.com.vm.test/convtrack.spark?MID=108607&placementID=18597' width='1' height='1' border='0' />"
}
}
AdButler\PlacementConvTag JSON: {
"object": "conv_tag",
"url": "/v1/placements/18597/conversion-tag",
"data": {
"src": "https://servedbyadbutler.com.vm.test/convtrack.spark?MID=108607&placementID=18597",
"html": "<img src='https://servedbyadbutler.com.vm.test/convtrack.spark?MID=108607&placementID=18597' width='1' height='1' border='0' />"
}
}
Field | Type | Description |
---|---|---|
object |
string |
A string denoting the object type which is always |
url |
string |
The relative URL of the current resource which is always of the form |
data |
array |
The data object containing the conversion tag. |
Returns a conv_tag
object if the request succeeded, or an error if something went terribly wrong.
Geo Targets
Introduction
Geo-targets enable you to deliver advertisements to users based on their geographic location. This is an effective way of reducing wasted impressions and increasing your return on investment.
You may inclusively or exclusively target by country, region and city, and additionally other cities found within a specified range.
The geo_target
response object contains the following fields:
Example Response
{
"object": "geo_target",
"self": "/v1/geo-targets/1785",
"id": 1785,
"range": 3,
"unit": "kilometers",
"inclusive": true,
"name": "Demo Geo Target",
"areas": [
{
"country": "NZ",
"region": "Ontago",
"city": "Arrowtown"
},
{
"country": "AU",
"region": "New South Wales",
"city": null
},
{
"country": "GL",
"region": null,
"city": null
},
{
"country": "UM",
"region": null,
"city": null
},
{
"country": "BM",
"region": null,
"city": null
},
{
"country": "CA",
"region": null,
"city": null
},
{
"country": "US",
"region": null,
"city": null
}
]
}
AdButler\GeoTarget JSON: {
"object": "geo_target",
"self": "/v1/geo-targets/1785",
"id": 1785,
"range": 3,
"unit": "kilometers",
"inclusive": true,
"name": "Demo Geo Target",
"areas": [
{
"country": "NZ",
"region": "Ontago",
"city": "Arrowtown"
},
{
"country": "AU",
"region": "New South Wales",
"city": null
},
{
"country": "GL",
"region": null,
"city": null
},
{
"country": "UM",
"region": null,
"city": null
},
{
"country": "BM",
"region": null,
"city": null
},
{
"country": "CA",
"region": null,
"city": null
},
{
"country": "US",
"region": null,
"city": null
}
]
}
Field | Type | Description |
---|---|---|
object |
string |
A string denoting the object type which is always |
self |
string |
The relative URL of the current resource which is always of the form |
id |
integer |
The current resource identifier (ID). |
range |
integer |
The additional distance around the selected locations to include in the target. |
unit |
string |
The unit of distance for the |
inclusive |
boolean |
Whether it is an inclusion or an exclusion target. |
name |
string |
The name of the geographic target. |
areas |
array |
The list of the targeted locations. |
Create a geo target
Definition
POST https://api.adbutler.com/v1/geo-targets
\AdButler\GeoTarget::create()
adbutler.targets.geo.create()
Example Request
curl "https://api.adbutler.com/v1/geo-targets" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"range": 3,
"unit": "kilometers",
"inclusive": true,
"name": "Demo Geo Target",
"areas": [
{
country: "NZ",
region: "Ontago",
city: "Arrowtown"
},
{
country: "AU",
region: "New South Wales",
city: null
},
{
country: "GL",
region: null,
city: null
},
{
country: "UM",
region: null,
city: null
},
{
country: "BM",
region: null,
city: null
},
{
country: "CA",
region: null,
city: null
},
{
country: "US",
region: null,
city: null
}
]
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$geoTarget = \AdButler\GeoTarget::create(array(
"range" => 3,
"unit" => "kilometers",
"inclusive" => true,
"name" => "Demo Geo Target",
"areas" => [
[
country => "NZ",
region => "Ontago",
city => "Arrowtown"
],
[
country => "AU",
region => "New South Wales",
city => null
],
[
country => "GL",
region => null,
city => null
],
[
country => "UM",
region => null,
city => null
],
[
country => "BM",
region => null,
city => null
],
[
country => "CA",
region => null,
city => null
],
[
country => "US",
region => null,
city => null
]
]
));
echo $geoTarget;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var postData = {
"range": 3,
"unit": "kilometers",
"inclusive": true,
"name": "Demo Geo Target",
"areas": [
{
country: "NZ",
region: "Ontago",
city: "Arrowtown"
},
{
country: "AU",
region: "New South Wales",
city: null
},
{
country: "GL",
region: null,
city: null
},
{
country: "UM",
region: null,
city: null
},
{
country: "BM",
region: null,
city: null
},
{
country: "CA",
region: null,
city: null
},
{
country: "US",
region: null,
city: null
}
]
};
// using callbacks
adbutler.targets.geo.create(postData, function(err, response) {
console.log(response);
});
// using promises
adbutler.targets.geo.create(postData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "geo_target",
"self": "/v1/geo-targets/1785",
"id": 1785,
"range": 3,
"unit": "kilometers",
"inclusive": true,
"name": "Demo Geo Target",
"areas": [
{
"country": "NZ",
"region": "Ontago",
"city": "Arrowtown"
},
{
"country": "AU",
"region": "New South Wales",
"city": null
},
{
"country": "GL",
"region": null,
"city": null
},
{
"country": "UM",
"region": null,
"city": null
},
{
"country": "BM",
"region": null,
"city": null
},
{
"country": "CA",
"region": null,
"city": null
},
{
"country": "US",
"region": null,
"city": null
}
]
}
AdButler\GeoTarget JSON: {
"object": "geo_target",
"self": "/v1/geo-targets/1785",
"id": 1785,
"range": 3,
"unit": "kilometers",
"inclusive": true,
"name": "Demo Geo Target",
"areas": [
{
"country": "NZ",
"region": "Ontago",
"city": "Arrowtown"
},
{
"country": "AU",
"region": "New South Wales",
"city": null
},
{
"country": "GL",
"region": null,
"city": null
},
{
"country": "UM",
"region": null,
"city": null
},
{
"country": "BM",
"region": null,
"city": null
},
{
"country": "CA",
"region": null,
"city": null
},
{
"country": "US",
"region": null,
"city": null
}
]
}
Creates a new geographic target.
Field | Type | Description |
---|---|---|
name* |
string |
A descriptive name of the geographic target. |
range |
integer |
The additional distance around the selected |
unit |
string |
The unit of distance for the |
inclusive |
boolean |
Whether it is an inclusion or an exclusion target. |
areas* |
boolean |
A list of areas included in the current geo-target. Each area object represents some location on the map and may look like this: |
* = required field
Returns
Returns a geo_target
object if the request succeeded, or an error if something went terribly wrong.
Retrieve a geo target
Definition
GET https://api.adbutler.com/v1/geo-targets/{GEO-TARGET-ID}
\AdButler\GeoTarget::retrieve()
adbutler.targets.geo.retrieve()
Example Request
curl "https://api.adbutler.com/v1/geo-targets/1785" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$geoTarget = \AdButler\GeoTarget::retrieve( 1785 );
echo $geoTarget;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.targets.geo.read(1785, function(err, response) {
console.log(response);
});
// using promises
adbutler.targets.geo.read(1785).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "geo_target",
"self": "/v1/geo-targets/1785",
"id": 1785,
"range": 3,
"unit": "kilometers",
"inclusive": true,
"name": "Demo Geo Target",
"areas": [
{
"country": "NZ",
"region": "Ontago",
"city": "Arrowtown"
},
{
"country": "AU",
"region": "New South Wales",
"city": null
},
{
"country": "GL",
"region": null,
"city": null
},
{
"country": "UM",
"region": null,
"city": null
},
{
"country": "BM",
"region": null,
"city": null
},
{
"country": "CA",
"region": null,
"city": null
},
{
"country": "US",
"region": null,
"city": null
}
]
}
AdButler\GeoTarget JSON: {
"object": "geo_target",
"self": "/v1/geo-targets/1785",
"id": 1785,
"range": 3,
"unit": "kilometers",
"inclusive": true,
"name": "Demo Geo Target",
"areas": [
{
"country": "NZ",
"region": "Ontago",
"city": "Arrowtown"
},
{
"country": "AU",
"region": "New South Wales",
"city": null
},
{
"country": "GL",
"region": null,
"city": null
},
{
"country": "UM",
"region": null,
"city": null
},
{
"country": "BM",
"region": null,
"city": null
},
{
"country": "CA",
"region": null,
"city": null
},
{
"country": "US",
"region": null,
"city": null
}
]
}
You can retrieve the information about an existing geo-target by giving the geo target ID that was returned in the geo-target object upon creation. You will see at the most 10 geo-targets in the response. You can change this default limit by appending ?limit=25
if you want this request to return 25 geo-targets.
Returns
Returns a geo_target
object if the request succeeded, or an error if something went terribly wrong.
Update a geo target
Definition
PUT https://api.adbutler.com/v1/geo-targets/{GEO-TARGET-ID}
\AdButler\GeoTarget->save()
adbutler.targets.geo.update()
Example Request
curl "https://api.adbutler.com/v1/geo-targets/1785" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
"range": 3,
"unit": "kilometers",
"inclusive": true,
"name": "Demo Geo Target",
"areas": [
{
country: "NZ",
region: "Ontago",
city: "Arrowtown"
},
{
country: "AU",
region: "New South Wales",
city: null
},
{
country: "GL",
region: null,
city: null
},
{
country: "UM",
region: null,
city: null
},
{
country: "BM",
region: null,
city: null
},
{
country: "CA",
region: null,
city: null
},
{
country: "US",
region: null,
city: null
}
]
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$geoTarget = \AdButler\GeoTarget::retrieve( 1785 );
$geoTarget->range = 3;
$geoTarget->unit = "kilometers";
$geoTarget->inclusive = true;
$geoTarget->name = "Demo Geo Target";
$geoTarget->areas = [
[
country = "NZ",
region = "Ontago",
city = "Arrowtown"
],
[
country = "AU",
region = "New South Wales",
city = null
],
[
country = "GL",
region = null,
city = null
],
[
country = "UM",
region = null,
city = null
],
[
country = "BM",
region = null,
city = null
],
[
country = "CA",
region = null,
city = null
],
[
country = "US",
region = null,
city = null
]
];
$geoTarget->save();
echo $geoTarget;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var updateData = {
"range": 3,
"unit": "kilometers",
"inclusive": true,
"name": "Demo Geo Target",
"areas": [
{
country: "NZ",
region: "Ontago",
city: "Arrowtown"
},
{
country: "AU",
region: "New South Wales",
city: null
},
{
country: "GL",
region: null,
city: null
},
{
country: "UM",
region: null,
city: null
},
{
country: "BM",
region: null,
city: null
},
{
country: "CA",
region: null,
city: null
},
{
country: "US",
region: null,
city: null
}
]
};
// using callbacks
adbutler.targets.geo.update(1785, updateData, function(err, response) {
console.log(response);
});
// using promises
adbutler.targets.geo.update(1785, updateData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "geo_target",
"self": "/v1/geo-targets/1785",
"id": 1785,
"range": 3,
"unit": "kilometers",
"inclusive": true,
"name": "Demo Geo Target",
"areas": [
{
"country": "NZ",
"region": "Ontago",
"city": "Arrowtown"
},
{
"country": "AU",
"region": "New South Wales",
"city": null
},
{
"country": "GL",
"region": null,
"city": null
},
{
"country": "UM",
"region": null,
"city": null
},
{
"country": "BM",
"region": null,
"city": null
},
{
"country": "CA",
"region": null,
"city": null
},
{
"country": "US",
"region": null,
"city": null
}
]
}
AdButler\GeoTarget JSON: {
"object": "geo_target",
"self": "/v1/geo-targets/1785",
"id": 1785,
"range": 3,
"unit": "kilometers",
"inclusive": true,
"name": "Demo Geo Target",
"areas": [
{
"country": "NZ",
"region": "Ontago",
"city": "Arrowtown"
},
{
"country": "AU",
"region": "New South Wales",
"city": null
},
{
"country": "GL",
"region": null,
"city": null
},
{
"country": "UM",
"region": null,
"city": null
},
{
"country": "BM",
"region": null,
"city": null
},
{
"country": "CA",
"region": null,
"city": null
},
{
"country": "US",
"region": null,
"city": null
}
]
}
You can update a specific geo-target account by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the geo-target creation request.
Field | Type | Description |
---|---|---|
name |
string |
A descriptive name of the geographic target. |
range |
integer |
The additional distance around the selected |
unit |
string |
The unit of distance for the |
inclusive |
boolean |
Whether it is an inclusion or an exclusion target. |
areas |
boolean |
A list of areas included in the current geo-target. Each area object represents some location on the map and may look like this: |
Returns
Returns a geo_target
object if the request succeeded, or an error if something went terribly wrong.
Delete a geo target
Definition
DELETE https://api.adbutler.com/v1/geo-targets/{GEO-TARGET-ID}
\AdButler\GeoTarget->delete()
adbutler.targets.geo.delete()
Example Request
curl "https://api.adbutler.com/v1/geo-targets/1785" \
-H "Authorization: Basic {API_KEY}" \
-X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$geoTarget = \AdButler\GeoTarget::retrieve( 1785 );
$geoTarget->delete();
echo $geoTarget;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.targets.geo.delete(1785, function(err, response) {
console.log(response);
});
// using promises
adbutler.targets.geo.delete(1785).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/geo-targets",
"data": [
{
"object": "geo_target",
"self": "/v1/geo-targets/1426",
"id": 1426,
"range": 200,
"unit": "miles",
"inclusive": true,
"name": "Adbutler API Test Target (Wasif)",
"areas": [
{
"country": "CA",
"region": "British Columbia",
"city": "Vancouver"
},
{
"country": "CA",
"region": "British Columbia",
"city": ""
},
{
"country": "US",
"region": "Washington",
"city": ""
},
{
"country": "CA",
"region": "British Columbia",
"city": "100 Mile House"
},
{
"country": "US",
"region": "Washington",
"city": "Noon"
}
]
},
{
"object": "geo_target",
"self": "/v1/geo-targets/1454",
"id": 1454,
"range": 10,
"unit": "miles",
"inclusive": false,
"name": "Adbutler API Test Target (Wasif)",
"areas": [
{
"country": "US",
"region": null,
"city": null
},
{
"country": "CA",
"region": null,
"city": null
},
{
"country": "AU",
"region": "New South Wales",
"city": null
},
{
"country": "NZ",
"region": "Otago",
"city": "Arrowtown"
},
{
"country": "NZ",
"region": "Otago",
"city": "Wharehuanui"
}
]
}
]
}
AdButler\Collection JSON: {
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/geo-targets",
"data": [
AdButler\GeoTarget JSON: {
"object": "geo_target",
"self": "/v1/geo-targets/1426",
"id": 1426,
"range": 200,
"unit": "miles",
"inclusive": true,
"name": "Adbutler API Test Target (Wasif)",
"areas": [
{
"country": "CA",
"region": "British Columbia",
"city": "Vancouver"
},
{
"country": "CA",
"region": "British Columbia",
"city": ""
},
{
"country": "US",
"region": "Washington",
"city": ""
},
{
"country": "CA",
"region": "British Columbia",
"city": "100 Mile House"
},
{
"country": "US",
"region": "Washington",
"city": "Noon"
}
]
},
AdButler\GeoTarget JSON: {
"object": "geo_target",
"self": "/v1/geo-targets/1454",
"id": 1454,
"range": 10,
"unit": "miles",
"inclusive": false,
"name": "Adbutler API Test Target (Wasif)",
"areas": [
{
"country": "US",
"region": null,
"city": null
},
{
"country": "CA",
"region": null,
"city": null
},
{
"country": "AU",
"region": "New South Wales",
"city": null
},
{
"country": "NZ",
"region": "Otago",
"city": "Arrowtown"
},
{
"country": "NZ",
"region": "Otago",
"city": "Wharehuanui"
}
]
}
]
}
Permanently deletes a geo-target. if successful, this operation cannot be undone so be very sure when deleting one.
Returns
Returns a geo-target ID if the request succeeded, or an error if something went terribly wrong.
List all geo targets
Definition
GET https://api.adbutler.com/v1/geo-targets
\AdButler\GeoTarget::retrieveAll()
adbutler.targets.geo.list()
Example Request
curl "https://api.adbutler.com/v1/geo-targets?limit=2" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$geoTarget = \AdButler\GeoTarget::retrieveAll(array(
"limit" => 2
));
echo $geoTarget;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.targets.geo.list({
limit: 2
}, function(err, response) {
console.log(response);
});
// using promises
adbutler.targets.geo.list({
limit: 2
}).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/geo-targets",
"data": [
{
"object": "geo_target",
"self": "/v1/geo-targets/1770",
"id": 1770,
"range": 3,
"unit": "kilometers",
"inclusive": true,
"name": "Demo Geo Target",
"areas": [
{
"country": "US",
"region": null,
"city": null
},
{
"country": "CA",
"region": null,
"city": null
},
{
"country": "BM",
"region": null,
"city": null
},
{
"country": "UM",
"region": null,
"city": null
},
{
"country": "GL",
"region": null,
"city": null
},
{
"country": "AU",
"region": "New South Wales",
"city": null
},
{
"country": "NZ",
"region": "Ontago",
"city": "Arrowtown"
}
]
},
{
"object": "geo_target",
"self": "/v1/geo-targets/1785",
"id": 1785,
"range": 3,
"unit": "kilometers",
"inclusive": true,
"name": "Demo Geo Target",
"areas": [
{
"country": "NZ",
"region": "Ontago",
"city": "Arrowtown"
},
{
"country": "AU",
"region": "New South Wales",
"city": null
},
{
"country": "GL",
"region": null,
"city": null
},
{
"country": "UM",
"region": null,
"city": null
},
{
"country": "BM",
"region": null,
"city": null
},
{
"country": "CA",
"region": null,
"city": null
},
{
"country": "US",
"region": null,
"city": null
}
]
}
]
}
AdButler\GeoTarget JSON: {
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/geo-targets",
"data": [
{
"object": "geo_target",
"self": "/v1/geo-targets/1770",
"id": 1770,
"range": 3,
"unit": "kilometers",
"inclusive": true,
"name": "Demo Geo Target",
"areas": [
{
"country": "US",
"region": null,
"city": null
},
{
"country": "CA",
"region": null,
"city": null
},
{
"country": "BM",
"region": null,
"city": null
},
{
"country": "UM",
"region": null,
"city": null
},
{
"country": "GL",
"region": null,
"city": null
},
{
"country": "AU",
"region": "New South Wales",
"city": null
},
{
"country": "NZ",
"region": "Ontago",
"city": "Arrowtown"
}
]
},
{
"object": "geo_target",
"self": "/v1/geo-targets/1785",
"id": 1785,
"range": 3,
"unit": "kilometers",
"inclusive": true,
"name": "Demo Geo Target",
"areas": [
{
"country": "NZ",
"region": "Ontago",
"city": "Arrowtown"
},
{
"country": "AU",
"region": "New South Wales",
"city": null
},
{
"country": "GL",
"region": null,
"city": null
},
{
"country": "UM",
"region": null,
"city": null
},
{
"country": "BM",
"region": null,
"city": null
},
{
"country": "CA",
"region": null,
"city": null
},
{
"country": "US",
"region": null,
"city": null
}
]
}
]
}
Returns a list of all the geo-targets. Most recent geo-targets appear first in the list.
Returns
Returns an object with a data
property that contains a list of up to the specified limit and/or offset of objects. Each entry in data
is a geo_target
object, and if no objects were found the list will be empty.
ISP Targets
Introduction
Direct users to ads relevant to them using ISP Targets, which help filter your audience by specific Internet Service Providers using Autonomous System Numbers (ASNs) ASN is a number which uniquely identifies each network on the Internet.
The isp_target
response object has the following fields.
Example Response
{
"object": "isp_target",
"self": "/v1/isp-targets/412",
"id": 412,
"name": "Demo ISP Target",
"asn_list": [
{
"asn": "24",
"isp": "National Aeronautics and Space Administration"
},
{
"asn": "1234",
"isp": "Fortum"
},
{
"asn": "2345",
"isp": "France Telecom"
}
]
}
AdButler\ISPTarget JSON: {
"object": "isp_target",
"self": "/v1/isp-targets/412",
"id": 412,
"name": "Demo ISP Target",
"asn_list": [
{
"asn": 24,
"isp": "National Aeronautics and Space Administration"
},
{
"asn": 1234,
"isp": "Fortum"
},
{
"asn": 2345,
"isp": "France Telecom"
}
]
}
Field | Type | Description |
---|---|---|
object |
string |
A string denoting the object type which is always |
self |
string |
The relative URL of the current resource which is always of the form |
id |
integer |
The current resource identifier (ID). |
name |
string |
A descriptive name of the ISP Target. |
asn_list |
array |
A list of targeted Autonomous System Numbers (ASNs). |
Create an ISP target
Definition
POST https://api.adbutler.com/v1/isp-targets
\AdButler\ISPTarget::create()
adbutler.targets.isp.create()
Example Request
curl "https://api.adbutler.com/v1/isp-targets" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"name": "Demo ISP Target",
"asn_list": [
{
asn: "24",
isp: "National Aeronautics and Space Administration"
},
{
asn: "1234",
isp: "Fortum"
},
{
asn: "2345",
isp: "France Telecom"
}
]
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$iSPTarget = \AdButler\ISPTarget::create(array(
"name" => "Demo ISP Target",
"asn_list" => [
[
asn => "24",
isp => "National Aeronautics and Space Administration"
],
[
asn => "1234",
isp => "Fortum"
],
[
asn => "2345",
isp => "France Telecom"
]
]
));
echo $iSPTarget;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var postData = {
"name": "Demo ISP Target",
"asn_list": [
{
asn: "24",
isp: "National Aeronautics and Space Administration"
},
{
asn: "1234",
isp: "Fortum"
},
{
asn: "2345",
isp: "France Telecom"
}
]
};
// using callbacks
adbutler.targets.isp.create(postData, function(err, response) {
console.log(response);
});
// using promises
adbutler.targets.isp.create(postData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "isp_target",
"self": "/v1/isp-targets/412",
"id": 412,
"name": "Demo ISP Target",
"asn_list": [
{
"asn": "24",
"isp": "National Aeronautics and Space Administration"
},
{
"asn": "1234",
"isp": "Fortum"
},
{
"asn": "2345",
"isp": "France Telecom"
}
]
}
AdButler\ISPTarget JSON: {
"object": "isp_target",
"self": "/v1/isp-targets/412",
"id": 412,
"name": "Demo ISP Target",
"asn_list": [
{
"asn": 24,
"isp": "National Aeronautics and Space Administration"
},
{
"asn": 1234,
"isp": "Fortum"
},
{
"asn": 2345,
"isp": "France Telecom"
}
]
}
Creates a new ISP target.
Field | Type | Description |
---|---|---|
name* |
string |
A descriptive name of the ISP target. |
asn_list* |
array |
The list of Autonomous System Numbers (ASNs) to include in the target. The list can be found here. |
* = required field
Returns
Returns an isp_target
object if the request succeeded, or an error if something went terribly wrong.
Retrieve an ISP target
Definition
GET https://api.adbutler.com/v1/isp-targets/{ISP-TARGET-ID}
\AdButler\ISPTarget::retrieve()
adbutler.targets.isp.retrieve()
Example Request
curl "https://api.adbutler.com/v1/isp-targets/412" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$iSPTarget = \AdButler\ISPTarget::retrieve( 412 );
echo $iSPTarget;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.targets.isp.read(412, function(err, response) {
console.log(response);
});
// using promises
adbutler.targets.isp.read(412).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "isp_target",
"self": "/v1/isp-targets/412",
"id": 412,
"name": "Demo ISP Target",
"asn_list": [
{
"asn": "24",
"isp": "National Aeronautics and Space Administration"
},
{
"asn": "1234",
"isp": "Fortum"
},
{
"asn": "2345",
"isp": "France Telecom"
}
]
}
AdButler\ISPTarget JSON: {
"object": "isp_target",
"self": "/v1/isp-targets/412",
"id": 412,
"name": "Demo ISP Target",
"asn_list": [
{
"asn": 24,
"isp": "National Aeronautics and Space Administration"
},
{
"asn": 1234,
"isp": "Fortum"
},
{
"asn": 2345,
"isp": "France Telecom"
}
]
}
You can retrieve the information about an existing ISP target by giving the ISP target ID that was returned in the ISP target object upon creation. You will see at the most 10 ISP targets in the response. You can change this default limit by appending ?limit=25
if you want this request to return 25 ISP targets.
Returns
Returns an isp_target
object if the request succeeded, or an error if something went terribly wrong.
Update an ISP target
Definition
PUT https://api.adbutler.com/v1/isp-targets/{ISP-TARGET-ID}
\AdButler\ISPTarget->save()
adbutler.targets.isp.update()
Example Request
curl "https://api.adbutler.com/v1/isp-targets/412" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
"name": "Demo ISP Target",
"asn_list": [
{
asn: "24",
isp: "National Aeronautics and Space Administration"
},
{
asn: "1234",
isp: "Fortum"
},
{
asn: "2345",
isp: "France Telecom"
}
]
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$iSPTarget = \AdButler\ISPTarget::retrieve( 412 );
$iSPTarget->name = "Demo ISP Target";
$iSPTarget->asn_list = [
[
asn = "24",
isp = "National Aeronautics and Space Administration"
],
[
asn = "1234",
isp = "Fortum"
],
[
asn = "2345",
isp = "France Telecom"
]
];
$iSPTarget->save();
echo $iSPTarget;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var updateData = {
"name": "Demo ISP Target",
"asn_list": [
{
asn: "24",
isp: "National Aeronautics and Space Administration"
},
{
asn: "1234",
isp: "Fortum"
},
{
asn: "2345",
isp: "France Telecom"
}
]
};
// using callbacks
adbutler.targets.isp.update(412, updateData, function(err, response) {
console.log(response);
});
// using promises
adbutler.targets.isp.update(412, updateData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "isp_target",
"self": "/v1/isp-targets/412",
"id": 412,
"name": "Demo ISP Target",
"asn_list": [
{
"asn": "24",
"isp": "National Aeronautics and Space Administration"
},
{
"asn": "1234",
"isp": "Fortum"
},
{
"asn": "2345",
"isp": "France Telecom"
}
]
}
AdButler\ISPTarget JSON: {
"object": "isp_target",
"self": "/v1/isp-targets/412",
"id": 412,
"name": "Demo ISP Target",
"asn_list": [
{
"asn": 24,
"isp": "National Aeronautics and Space Administration"
},
{
"asn": 1234,
"isp": "Fortum"
},
{
"asn": 2345,
"isp": "France Telecom"
}
]
}
You can update a specific ISP target account by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the ISP target creation request.
Field | Type | Description |
---|---|---|
name |
string |
A descriptive name of the ISP target. |
asn_list |
array |
The list of Autonomous System Numbers (ASNs) to include in the target. The list can be found here. |
Returns
Returns an isp_target
object if the request succeeded, or an error if something went terribly wrong.
Delete an ISP target
Definition
DELETE https://api.adbutler.com/v1/isp-targets/{ISP-TARGET-ID}
\AdButler\ISPTarget->delete()
adbutler.targets.isp.delete()
Example Request
curl "https://api.adbutler.com/v1/isp-targets/412" \
-H "Authorization: Basic {API_KEY}" \
-X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$iSPTarget = \AdButler\ISPTarget::retrieve( 412 );
$iSPTarget->delete();
echo $iSPTarget;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.targets.isp.delete(412, function(err, response) {
console.log(response);
});
// using promises
adbutler.targets.isp.delete(412).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"id": 412,
"delete": true
}
AdButler\ISPTarget JSON: {
"id": 412,
"delete": true
}
Permanently deletes an ISP target. if successful, this operation cannot be undone so be very sure when deleting one.
Returns
Returns an ISP target ID if the request succeeded, or an error if something went terribly wrong.
List all ISP targets
Definition
GET https://api.adbutler.com/v1/isp-targets
\AdButler\ISPTarget::retrieveAll()
adbutler.targets.isp.list()
Example Request
curl "https://api.adbutler.com/v1/isp-targets?limit=2" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$iSPTarget = \AdButler\ISPTarget::retrieveAll(array(
"limit" => 2
));
echo $iSPTarget;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.targets.isp.list({
limit: 2
}, function(err, response) {
console.log(response);
});
// using promises
adbutler.targets.isp.list({
limit: 2
}).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/isp-targets",
"data": [
{
"object": "isp_target",
"self": "/v1/isp-targets/400",
"id": 400,
"name": "Demo ISP Target",
"asn_list": [
{
"asn": "24",
"isp": "National Aeronautics and Space Administration"
},
{
"asn": "1234",
"isp": "Fortum"
},
{
"asn": "2345",
"isp": "France Telecom"
}
]
},
{
"object": "isp_target",
"self": "/v1/isp-targets/401",
"id": 401,
"name": "Demo ISP Target",
"asn_list": [
{
"asn": "24",
"isp": "National Aeronautics and Space Administration"
},
{
"asn": "1234",
"isp": "Fortum"
},
{
"asn": "2345",
"isp": "France Telecom"
}
]
}
]
}
AdButler\ISPTarget JSON: {
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/isp-targets",
"data": [
{
"object": "isp_target",
"self": "/v1/isp-targets/400",
"id": 400,
"name": "Demo ISP Target",
"asn_list": [
{
"asn": 24,
"isp": "National Aeronautics and Space Administration"
},
{
"asn": 1234,
"isp": "Fortum"
},
{
"asn": 2345,
"isp": "France Telecom"
}
]
},
{
"object": "isp_target",
"self": "/v1/isp-targets/401",
"id": 401,
"name": "Demo ISP Target",
"asn_list": [
{
"asn": 24,
"isp": "National Aeronautics and Space Administration"
},
{
"asn": 1234,
"isp": "Fortum"
},
{
"asn": 2345,
"isp": "France Telecom"
}
]
}
]
}
Returns a list of all the ISP targets. Most recent ISP targets appear first in the list.
Returns
Returns an object with a data
property that contains a list of up to the specified limit and/or offset of objects. Each entry in data
is an isp_target
object, and if no objects were found the list will be empty.
Platform Targets
Introduction
Target your advertisements to specific mobile/tablet/notebook/desktop devices, or to specific browsers and operating systems to help ensure users get the best ads for their platform. You can also target specific mobile phones or tablets, such as the iPhones or Samsung devices using device targeting filters.
The platform_target
response object has the following fields.
Example Response
{
"object": "platform_target",
"self": "/v1/platform-targets/1636",
"id": 1636,
"name": "Demo Platform Target",
"platform": "mobile",
"desktop_browser_targets": [],
"mobile_browser_targets": [
"chrome",
"opera",
"safari"
],
"desktop_os_targets": [],
"mobile_os_targets": [
"android",
"blackberry",
"ios",
"windows_phone"
],
"device_targets": [
"Nexus*",
"Apple*"
]
}
AdButler\PlatformTarget JSON: {
"object": "platform_target",
"self": "/v1/platform-targets/1636",
"id": 1636,
"name": "Demo Platform Target",
"platform": "mobile",
"desktop_browser_targets": [],
"mobile_browser_targets": [
"chrome",
"opera",
"safari"
],
"desktop_os_targets": [],
"mobile_os_targets": [
"android",
"blackberry",
"ios",
"windows_phone"
],
"device_targets": [
"Nexus*",
"Apple*"
]
}
Field | Type | Description |
---|---|---|
object |
string |
A string denoting the object type which is always |
self |
string |
The relative URL of the current resource which is always of the form |
id |
integer |
The current resource identifier (ID). |
name |
string |
A descriptive name of the platform target. |
platform |
string |
A preset grouping of the platform target. |
desktop_browser_targets |
array |
The list of desktop internet browser included in the platform target. |
mobile_browser_targets |
array |
The list of mobile internet browsers included in the platform target. |
desktop_os_targets |
array |
The list of desktop Operating Systems included in the platform target. |
mobile_os_targets |
array |
The list of mobile Operating Systems included in the platform target. |
device_targets |
array |
The list of device patterns included in the platform target. |
Create a platform target
Definition
POST https://api.adbutler.com/v1/platform-targets
\AdButler\PlatformTarget::create()
adbutler.targets.platform.create()
Example Request
curl "https://api.adbutler.com/v1/platform-targets" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"name": "Demo Platform Target",
"platform": "mobile"
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$platformTarget = \AdButler\PlatformTarget::create(array(
"name" => "Demo Platform Target",
"platform" => "mobile"
));
echo $platformTarget;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var postData = {
"name": "Demo Platform Target",
"platform": "mobile"
};
// using callbacks
adbutler.targets.platform.create(postData, function(err, response) {
console.log(response);
});
// using promises
adbutler.targets.platform.create(postData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "platform_target",
"self": "/v1/platform-targets/1636",
"id": 1636,
"name": "Demo Platform Target",
"platform": "mobile",
"desktop_browser_targets": [],
"mobile_browser_targets": [
"chrome",
"opera",
"safari"
],
"desktop_os_targets": [],
"mobile_os_targets": [
"android",
"blackberry",
"ios",
"windows_phone"
],
"device_targets": [
"Nexus*",
"Apple*"
]
}
AdButler\PlatformTarget JSON: {
"object": "platform_target",
"self": "/v1/platform-targets/1636",
"id": 1636,
"name": "Demo Platform Target",
"platform": "mobile",
"desktop_browser_targets": [],
"mobile_browser_targets": [
"chrome",
"opera",
"safari"
],
"desktop_os_targets": [],
"mobile_os_targets": [
"android",
"blackberry",
"ios",
"windows_phone"
],
"device_targets": [
"Nexus*",
"Apple*"
]
}
Creates a new platform target.
Field | Type | Description |
---|---|---|
name* |
string |
A descriptive name of the platform target. |
platform |
string |
A preset platform target including devices of a certain form factor. Possible values are |
desktop_browser_targets |
array |
The list of desktop internet browsers to target. Disabled if |
mobile_browser_targets |
array |
The list of mobile internet browsers to target. Disabled if |
desktop_os_targets |
array |
The list of desktop operating systems to target. Disabled if |
mobile_os_targets |
array |
The list of mobile operating systems to target. Disabled if |
device_targets |
array |
A list of device specific patterns used only if platform is |
* = required field
Returns
Returns a platform_target
object if the request succeeded, or an error if something went terribly wrong.
Retrieve a platform target
Definition
GET https://api.adbutler.com/v1/platform-targets/{PLATFORM-TARGET-ID}
\AdButler\PlatformTarget::retrieve()
adbutler.targets.platform.retrieve()
Example Request
curl "https://api.adbutler.com/v1/platform-targets/1636" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$platformTarget = \AdButler\PlatformTarget::retrieve( 1636 );
echo $platformTarget;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.targets.platform.read(1636, function(err, response) {
console.log(response);
});
// using promises
adbutler.targets.platform.read(1636).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "platform_target",
"self": "/v1/platform-targets/1636",
"id": 1636,
"name": "Demo Platform Target",
"platform": "mobile",
"desktop_browser_targets": [],
"mobile_browser_targets": [
"chrome",
"opera",
"safari"
],
"desktop_os_targets": [],
"mobile_os_targets": [
"android",
"blackberry",
"ios",
"windows_phone"
],
"device_targets": [
"Nexus*",
"Apple*"
]
}
AdButler\PlatformTarget JSON: {
"object": "platform_target",
"self": "/v1/platform-targets/1636",
"id": 1636,
"name": "Demo Platform Target",
"platform": "mobile",
"desktop_browser_targets": [],
"mobile_browser_targets": [
"chrome",
"opera",
"safari"
],
"desktop_os_targets": [],
"mobile_os_targets": [
"android",
"blackberry",
"ios",
"windows_phone"
],
"device_targets": [
"Nexus*",
"Apple*"
]
}
You can retrieve the information about an existing platform target by giving the platform target ID that was returned in the platform target object upon creation. You will see at the most 10 platform targets in the response. You can change this default limit by appending ?limit=25
if you want this request to return 25 platform targets.
Returns
Returns a platform_target
object if the request succeeded, or an error if something went terribly wrong.
Update a platform target
Definition
PUT https://api.adbutler.com/v1/platform-targets/{PLATFORM-TARGET-ID}
\AdButler\PlatformTarget->save()
adbutler.targets.platform.update()
Example Request
curl "https://api.adbutler.com/v1/platform-targets/1636" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
"name": "Demo Platform Target",
"platform": "mobile"
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$platformTarget = \AdButler\PlatformTarget::retrieve( 1636 );
$platformTarget->name = "Demo Platform Target";
$platformTarget->platform = "mobile";
$platformTarget->save();
echo $platformTarget;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var updateData = {
"name": "Demo Platform Target",
"platform": "mobile"
};
// using callbacks
adbutler.targets.platform.update(1636, updateData, function(err, response) {
console.log(response);
});
// using promises
adbutler.targets.platform.update(1636, updateData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "platform_target",
"self": "/v1/platform-targets/1636",
"id": 1636,
"name": "Demo Platform Target",
"platform": "mobile",
"desktop_browser_targets": [],
"mobile_browser_targets": [
"chrome",
"opera",
"safari"
],
"desktop_os_targets": [],
"mobile_os_targets": [
"android",
"blackberry",
"ios",
"windows_phone"
],
"device_targets": [
"Nexus*",
"Apple*"
]
}
AdButler\PlatformTarget JSON: {
"object": "platform_target",
"self": "/v1/platform-targets/1636",
"id": 1636,
"name": "Demo Platform Target",
"platform": "mobile",
"desktop_browser_targets": [],
"mobile_browser_targets": [
"chrome",
"opera",
"safari"
],
"desktop_os_targets": [],
"mobile_os_targets": [
"android",
"blackberry",
"ios",
"windows_phone"
],
"device_targets": [
"Nexus*",
"Apple*"
]
}
You can update a specific platform target by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the platform target creation request.
Field | Type | Description |
---|---|---|
name |
string |
A descriptive name of the platform target. |
platform |
string |
A preset platform target including devices of a certain form factor. Possible values are |
desktop_browser_targets |
array |
The list of desktop internet browsers to target. Disabled if |
mobile_browser_targets |
array |
The list of mobile internet browsers to target. Disabled if |
desktop_os_targets |
array |
The list of desktop operating systems to target. Disabled if |
mobile_os_targets |
array |
The list of mobile operating systems to target. Disabled if |
device_targets |
array |
A list of device specific patterns used only if platform is |
Returns
Returns a platform_target
object if the request succeeded, or an error if something went terribly wrong.
Delete a platform target
Definition
DELETE https://api.adbutler.com/v1/platform-targets/{PLATFORM-TARGET-ID}
\AdButler\PlatformTarget->delete()
adbutler.targets.platform.delete()
Example Request
curl "https://api.adbutler.com/v1/platform-targets/1636" \
-H "Authorization: Basic {API_KEY}" \
-X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$platformTarget = \AdButler\PlatformTarget::retrieve( 1636 );
$platformTarget->delete();
echo $platformTarget;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.targets.platform.delete(1636, function(err, response) {
console.log(response);
});
// using promises
adbutler.targets.platform.delete(1636).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"id": 1636,
"delete": true
}
AdButler\PlatformTarget JSON: {
"id": 1636,
"delete": true
}
Permanently deletes a platform target. If successful, this operation cannot be undone so be very sure when deleting one.
Returns
Returns a platform target ID if the request succeeded, or an error if something went terribly wrong.
List all platform targets
Definition
GET https://api.adbutler.com/v1/platform-targets
\AdButler\PlatformTarget::retrieveAll()
adbutler.targets.platform.list()
Example Request
curl "https://api.adbutler.com/v1/platform-targets?limit=2" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$platformTarget = \AdButler\PlatformTarget::retrieveAll(array(
"limit" => 2
));
echo $platformTarget;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.targets.platform.list({
limit: 2
}, function(err, response) {
console.log(response);
});
// using promises
adbutler.targets.platform.list({
limit: 2
}).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/platform-targets",
"data": [
{
"object": "platform_target",
"self": "/v1/platform-targets/1635",
"id": 1635,
"name": "Demo Platform Target",
"platform": "mobile",
"desktop_browser_targets": [],
"mobile_browser_targets": [
"chrome",
"opera",
"safari"
],
"desktop_os_targets": [],
"mobile_os_targets": [
"android",
"blackberry",
"ios",
"windows_phone"
],
"device_targets": [
"Nexus*",
"Apple*"
]
},
{
"object": "platform_target",
"self": "/v1/platform-targets/1636",
"id": 1636,
"name": "Demo Platform Target",
"platform": "mobile",
"desktop_browser_targets": [],
"mobile_browser_targets": [
"chrome",
"opera",
"safari"
],
"desktop_os_targets": [],
"mobile_os_targets": [
"android",
"blackberry",
"ios",
"windows_phone"
],
"device_targets": [
"Nexus*",
"Apple*"
]
}
]
}
AdButler\PlatformTarget JSON: {
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/platform-targets",
"data": [
{
"object": "platform_target",
"self": "/v1/platform-targets/1635",
"id": 1635,
"name": "Demo Platform Target",
"platform": "mobile",
"desktop_browser_targets": [],
"mobile_browser_targets": [
"chrome",
"opera",
"safari"
],
"desktop_os_targets": [],
"mobile_os_targets": [
"android",
"blackberry",
"ios",
"windows_phone"
],
"device_targets": [
"Nexus*",
"Apple*"
]
},
{
"object": "platform_target",
"self": "/v1/platform-targets/1636",
"id": 1636,
"name": "Demo Platform Target",
"platform": "mobile",
"desktop_browser_targets": [],
"mobile_browser_targets": [
"chrome",
"opera",
"safari"
],
"desktop_os_targets": [],
"mobile_os_targets": [
"android",
"blackberry",
"ios",
"windows_phone"
],
"device_targets": [
"Nexus*",
"Apple*"
]
}
]
}
Returns a list of all the platform targets. Most recent platform targets appear first in the list.
Returns
Returns an object with a data
property that contains a list of up to the specified limit and/or offset of objects. Each entry in data
is a platform_target
object, and if no objects were found the list will be empty.
Keyword Targets
Introduction
Keyword targeting is another powerful targeting technique available within AdButler. They are configured in the placements resource. You can specify the relevant keywords in the keywords
field. You can specify the keywords match method by specifying either "required" or "preferred" as value to the keywords_match_method
field. You will need to modify the zone tag in order to deploy keyword targeting.
Reports
Introduction
Reporting is the new interface to Statistics. It serves to quantify the serving of your advertisements across price and performance related metrics. They are updated in real time. We go to great lengths to give you detailed and accurate data about the performance of your advertisements, to help you make informed decisions. This endpoint enables you to build your own reporting dashboard should you feel the need to.
The report
response object has the following fields.
Example Response
{
"object": "report",
"url": "/v1/reports",
"data": [
{
"type": "overview",
"id": 107870,
"summary": {
"responses": 222,
"impressions": 222,
"clicks": 0,
"conversions": 0,
"cost": 5.51,
"payout": 0,
"revenue": 5.51,
"e_cpm": 24.821,
"e_cpc": 0,
"e_cpa": 0,
"breakdown": [
{
"placement": 16778,
"banner": {
"type": "image_banner",
"id": 518887977
},
"text_ad": null,
"popup": null,
"campaign": {
"type": "banner_campaign",
"id": 9415
},
"zone": {
"type": "banner_zone",
"id": 103294
},
"responses": 129,
"impressions": 129,
"clicks": 0,
"conversions": 0,
"cost": 5.509,
"payout": 0.003,
"revenue": 5.507,
"e_cpm": 42.709,
"e_cpc": 0,
"e_cpa": 0
},
{
"placement": 16779,
"banner": {
"type": "image_banner",
"id": 518887978
},
"text_ad": null,
"popup": null,
"campaign": {
"type": "banner_campaign",
"id": 9416
},
"zone": {
"type": "banner_zone",
"id": 103295
},
"responses": 93,
"impressions": 93,
"clicks": 0,
"conversions": 0,
"cost": 0.001,
"payout": 0,
"revenue": 0.001,
"e_cpm": 0.01,
"e_cpc": 0,
"e_cpa": 0
}
]
},
"details": [
{
"start_date": "2017-08-09T00:00:00-07:00",
"responses": 222,
"impressions": 222,
"clicks": 0,
"conversions": 0,
"cost": 5.51,
"payout": 0,
"revenue": 5.51,
"e_cpm": 24.821,
"e_cpc": 0,
"e_cpa": 0,
"breakdown": [
{
"placement": 16778,
"banner": {
"type": "image_banner",
"id": 518887977
},
"text_ad": null,
"popup": null,
"campaign": {
"type": "banner_campaign",
"id": 9415
},
"zone": {
"type": "banner_zone",
"id": 103294
},
"responses": 129,
"impressions": 129,
"clicks": 0,
"conversions": 0,
"cost": 5.509,
"payout": 0.003,
"revenue": 5.507,
"e_cpm": 42.709,
"e_cpc": 0,
"e_cpa": 0
},
{
"placement": 16779,
"banner": {
"type": "image_banner",
"id": 518887978
},
"text_ad": null,
"popup": null,
"campaign": {
"type": "banner_campaign",
"id": 9416
},
"zone": {
"type": "banner_zone",
"id": 103295
},
"responses": 93,
"impressions": 93,
"clicks": 0,
"conversions": 0,
"cost": 0.001,
"payout": 0,
"revenue": 0.001,
"e_cpm": 0.01,
"e_cpc": 0,
"e_cpa": 0
}
]
}
]
}
],
"meta": {
"type": "overview",
"period": "day",
"from": "2017-08-07T00:00:00-07:00",
"to": "2017-08-10T00:00:00-07:00",
"timezone": "America/Los_Angeles"
}
}
AdButler\Report JSON: {
"object": "report",
"url": "/v1/reports",
"data": [
{
"type": "overview",
"id": 107870,
"summary": {
"responses": 222,
"impressions": 222,
"clicks": 0,
"conversions": 0,
"cost": 5.51,
"payout": 0,
"revenue": 5.51,
"e_cpm": 24.821,
"e_cpc": 0,
"e_cpa": 0,
"breakdown": [
{
"placement": 16778,
"banner": {
"type": "image_banner",
"id": 518887977
},
"text_ad": null,
"popup": null,
"campaign": {
"type": "banner_campaign",
"id": 9415
},
"zone": {
"type": "banner_zone",
"id": 103294
},
"responses": 129,
"impressions": 129,
"clicks": 0,
"conversions": 0,
"cost": 5.509,
"payout": 0.003,
"revenue": 5.507,
"e_cpm": 42.709,
"e_cpc": 0,
"e_cpa": 0
},
{
"placement": 16779,
"banner": {
"type": "image_banner",
"id": 518887978
},
"text_ad": null,
"popup": null,
"campaign": {
"type": "banner_campaign",
"id": 9416
},
"zone": {
"type": "banner_zone",
"id": 103295
},
"responses": 93,
"impressions": 93,
"clicks": 0,
"conversions": 0,
"cost": 0.001,
"payout": 0,
"revenue": 0.001,
"e_cpm": 0.01,
"e_cpc": 0,
"e_cpa": 0
}
]
},
"details": [
{
"start_date": "2017-08-09T00:00:00-07:00",
"responses": 222,
"impressions": 222,
"clicks": 0,
"conversions": 0,
"cost": 5.51,
"payout": 0,
"revenue": 5.51,
"e_cpm": 24.821,
"e_cpc": 0,
"e_cpa": 0,
"breakdown": [
{
"placement": 16778,
"banner": {
"type": "image_banner",
"id": 518887977
},
"text_ad": null,
"popup": null,
"campaign": {
"type": "banner_campaign",
"id": 9415
},
"zone": {
"type": "banner_zone",
"id": 103294
},
"responses": 129,
"impressions": 129,
"clicks": 0,
"conversions": 0,
"cost": 5.509,
"payout": 0.003,
"revenue": 5.507,
"e_cpm": 42.709,
"e_cpc": 0,
"e_cpa": 0
},
{
"placement": 16779,
"banner": {
"type": "image_banner",
"id": 518887978
},
"text_ad": null,
"popup": null,
"campaign": {
"type": "banner_campaign",
"id": 9416
},
"zone": {
"type": "banner_zone",
"id": 103295
},
"responses": 93,
"impressions": 93,
"clicks": 0,
"conversions": 0,
"cost": 0.001,
"payout": 0,
"revenue": 0.001,
"e_cpm": 0.01,
"e_cpc": 0,
"e_cpa": 0
}
]
}
]
}
],
"meta": {
"type": "overview",
"period": "day",
"from": "2017-08-07T00:00:00-07:00",
"to": "2017-08-10T00:00:00-07:00",
"timezone": "America/Los_Angeles"
}
}
Field | Type | Description |
---|---|---|
object |
string |
A string denoting the object type which is always |
url |
string |
The relative URL of the current resource which is always of the form |
data |
array |
The data retrieved given the criteria in the URL. |
meta |
array |
Additional information about the request. |
Retrieve reports
Definition
GET https://api.adbutler.com/v1/reports
\AdButler\Report::retrieve()
adbutler.reports.retrieve()
Example Request
curl "https://api.adbutler.com/v1/reports?type=overview&from=2017-08-07T16:30:00-07:00&to=2017-08-10T18:00:00-07:00&period=day&timezone=America/Los_Angeles&summary=true&details=true&breakdown=true&financials=true" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$report = \AdButler\Report::retrieve( array(
'type' => 'overview'
'from' => '2017-08-07T16:30:00-07:00'
'to' => '2017-08-10T18:00:00-07:00'
'period' => 'day'
'timezone' => 'America/Los_Angeles'
'summary' => true
'details' => true
'breakdown' => true
'financials' => true
));
echo $report;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.reports.read({
type: 'overview',
from: '2017-08-07T16:30:00-07:00',
to: 2017-08-10T18:00:00-07:00,
period: 'day',
timezone: America/Los_Angeles,
summary: true,
details: true,
breakdown: true,
financials: true
}, function(response) {
console.log(response);
});
// using promises
adbutler.reports.read({
type: 'overview',
from: 2017-08-07T16:30:00-07:00,
to: '2017-08-10T18:00:00-07:00',
period: 'day',
timezone: America/Los_Angeles,
summary: true,
details: true,
breakdown: true,
financials: true
}).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "report",
"url": "/v1/reports",
"data": [
{
"type": "overview",
"id": 107870,
"summary": {
"responses": 222,
"impressions": 222,
"clicks": 0,
"conversions": 0,
"cost": 5.51,
"payout": 0,
"revenue": 5.51,
"e_cpm": 24.821,
"e_cpc": 0,
"e_cpa": 0,
"breakdown": [
{
"placement": 16778,
"banner": {
"type": "image_banner",
"id": 518887977
},
"text_ad": null,
"popup": null,
"campaign": {
"type": "banner_campaign",
"id": 9415
},
"zone": {
"type": "banner_zone",
"id": 103294
},
"responses": 129,
"impressions": 129,
"clicks": 0,
"conversions": 0,
"cost": 5.509,
"payout": 0.003,
"revenue": 5.507,
"e_cpm": 42.709,
"e_cpc": 0,
"e_cpa": 0
},
{
"placement": 16779,
"banner": {
"type": "image_banner",
"id": 518887978
},
"text_ad": null,
"popup": null,
"campaign": {
"type": "banner_campaign",
"id": 9416
},
"zone": {
"type": "banner_zone",
"id": 103295
},
"responses": 93,
"impressions": 93,
"clicks": 0,
"conversions": 0,
"cost": 0.001,
"payout": 0,
"revenue": 0.001,
"e_cpm": 0.01,
"e_cpc": 0,
"e_cpa": 0
}
]
},
"details": [
{
"start_date": "2017-08-09T00:00:00-07:00",
"responses": 222,
"impressions": 222,
"clicks": 0,
"conversions": 0,
"cost": 5.51,
"payout": 0,
"revenue": 5.51,
"e_cpm": 24.821,
"e_cpc": 0,
"e_cpa": 0,
"breakdown": [
{
"placement": 16778,
"banner": {
"type": "image_banner",
"id": 518887977
},
"text_ad": null,
"popup": null,
"campaign": {
"type": "banner_campaign",
"id": 9415
},
"zone": {
"type": "banner_zone",
"id": 103294
},
"responses": 129,
"impressions": 129,
"clicks": 0,
"conversions": 0,
"cost": 5.509,
"payout": 0.003,
"revenue": 5.507,
"e_cpm": 42.709,
"e_cpc": 0,
"e_cpa": 0
},
{
"placement": 16779,
"banner": {
"type": "image_banner",
"id": 518887978
},
"text_ad": null,
"popup": null,
"campaign": {
"type": "banner_campaign",
"id": 9416
},
"zone": {
"type": "banner_zone",
"id": 103295
},
"responses": 93,
"impressions": 93,
"clicks": 0,
"conversions": 0,
"cost": 0.001,
"payout": 0,
"revenue": 0.001,
"e_cpm": 0.01,
"e_cpc": 0,
"e_cpa": 0
}
]
}
]
}
],
"meta": {
"type": "overview",
"period": "day",
"from": "2017-08-07T00:00:00-07:00",
"to": "2017-08-10T00:00:00-07:00",
"timezone": "America/Los_Angeles"
}
}
AdButler\Report JSON: {
"object": "report",
"url": "/v1/reports",
"data": [
{
"type": "overview",
"id": 107870,
"summary": {
"responses": 222,
"impressions": 222,
"clicks": 0,
"conversions": 0,
"cost": 5.51,
"payout": 0,
"revenue": 5.51,
"e_cpm": 24.821,
"e_cpc": 0,
"e_cpa": 0,
"breakdown": [
{
"placement": 16778,
"banner": {
"type": "image_banner",
"id": 518887977
},
"text_ad": null,
"popup": null,
"campaign": {
"type": "banner_campaign",
"id": 9415
},
"zone": {
"type": "banner_zone",
"id": 103294
},
"responses": 129,
"impressions": 129,
"clicks": 0,
"conversions": 0,
"cost": 5.509,
"payout": 0.003,
"revenue": 5.507,
"e_cpm": 42.709,
"e_cpc": 0,
"e_cpa": 0
},
{
"placement": 16779,
"banner": {
"type": "image_banner",
"id": 518887978
},
"text_ad": null,
"popup": null,
"campaign": {
"type": "banner_campaign",
"id": 9416
},
"zone": {
"type": "banner_zone",
"id": 103295
},
"responses": 93,
"impressions": 93,
"clicks": 0,
"conversions": 0,
"cost": 0.001,
"payout": 0,
"revenue": 0.001,
"e_cpm": 0.01,
"e_cpc": 0,
"e_cpa": 0
}
]
},
"details": [
{
"start_date": "2017-08-09T00:00:00-07:00",
"responses": 222,
"impressions": 222,
"clicks": 0,
"conversions": 0,
"cost": 5.51,
"payout": 0,
"revenue": 5.51,
"e_cpm": 24.821,
"e_cpc": 0,
"e_cpa": 0,
"breakdown": [
{
"placement": 16778,
"banner": {
"type": "image_banner",
"id": 518887977
},
"text_ad": null,
"popup": null,
"campaign": {
"type": "banner_campaign",
"id": 9415
},
"zone": {
"type": "banner_zone",
"id": 103294
},
"responses": 129,
"impressions": 129,
"clicks": 0,
"conversions": 0,
"cost": 5.509,
"payout": 0.003,
"revenue": 5.507,
"e_cpm": 42.709,
"e_cpc": 0,
"e_cpa": 0
},
{
"placement": 16779,
"banner": {
"type": "image_banner",
"id": 518887978
},
"text_ad": null,
"popup": null,
"campaign": {
"type": "banner_campaign",
"id": 9416
},
"zone": {
"type": "banner_zone",
"id": 103295
},
"responses": 93,
"impressions": 93,
"clicks": 0,
"conversions": 0,
"cost": 0.001,
"payout": 0,
"revenue": 0.001,
"e_cpm": 0.01,
"e_cpc": 0,
"e_cpa": 0
}
]
}
]
}
],
"meta": {
"type": "overview",
"period": "day",
"from": "2017-08-07T00:00:00-07:00",
"to": "2017-08-10T00:00:00-07:00",
"timezone": "America/Los_Angeles"
}
}
You can retrieve overview of all the information or about a specific publisher
, advertiser
, zone
, campaign
, or banner
in specified periods.
Query Parameters
Parameter | Description |
---|---|
type* |
Specifies the focus of the statistics you are interested in viewing. The value must be one of |
period* |
The range of time you are interested in viewing. The value must be one of |
preset† |
Frequently used time frames for reporting statistics are bundled as presets You can pick a value from the presets instead of creating your own custom date range using the |
timezone* |
Timezone for the |
from† |
A valid ISO 8601 formatted date denoting the start of the period, e.g. |
to† |
A valid ISO 8601 formatted date denoting the end of the period, e.g. |
summary‡ |
Whether to show a summary ( |
details‡ |
Whether to show details ( |
breakdown |
Whether to show breakdown of summary and details ( |
financials |
Whether to show financial data ( |
publishers |
Submit this parameter to filter your report by a list of publisher IDs. The IDs must be submitted as a comma-separated list. |
zones |
Submit this parameter to filter your report by a list of zone IDs. The IDs must be submitted as a comma-separated list. |
advertisers |
Submit this parameter to filter your report by a list of advertiser IDs. The IDs must be submitted as a comma-separated list. |
campaigns |
Submit this parameter to filter your report by a list of campaign IDs. The IDs must be submitted as a comma-separated list. |
banners |
Submit this parameter to filter your report by a list of banner IDs. The IDs must be submitted as a comma-separated list. |
textads |
Submit this parameter to filter your report by a list of text ad IDs. The IDs must be submitted as a comma-separated list. |
popups |
Submit this parameter to filter your report by a list of popup IDs. The IDs must be submitted as a comma-separated list. |
* = required field
✝ = Either preset
or specific to
and from
dates must be specified
‡ = Either summary
or details
must be specified
Returns
Returns a report
object if the request succeeded, or an error if something went terribly wrong.
VAST Reports
Introduction
Reporting is the new interface to Statistics. It serves to quantify the serving of your advertisements across price and performance related metrics. They are updated in real time. We go to great lengths to give you detailed and accurate data about the performance of your advertisements, to help you make informed decisions. This endpoint enables you to build your own reporting dashboard should you feel the need to.
The vast_report
response object has the following fields.
Example Response
{
"object": "vast-report",
"url": "/v1/vast-reports",
"data": [
{
"type": "overview",
"id": 108508,
"summary": {
"requests": 4668,
"impressions": 4717,
"clicks": 425,
"companionClicks1": 51,
"companionClicks2": 46,
"companionClicks3": 38,
"companionClicks4": 38,
"companionClicks5": 46,
"companionViews1": 43,
"companionViews2": 52,
"companionViews3": 49,
"companionViews4": 43,
"companionViews5": 43,
"start": 3777,
"firstQuartile": 2882,
"midpoint": 2081,
"thirdQuartile": 1225,
"complete": 621,
"mute": 219,
"unmute": 196,
"pause": 211,
"rewind": 218,
"resume": 214,
"fullscreen": 808,
"exitFullscreen": 221,
"expand": 38,
"collapse": 49,
"acceptInvitationLinear": 55,
"closeLinear": 32,
"skip": 1422,
"conversions": 0,
"cost": 0,
"payout": 0,
"revenue": 0,
"e_cpm": 0,
"e_cpc": 0,
"e_cpa": 0
},
"details": [
{
"start_date": "2018-01-01T00:00:00-08:00",
"requests": 2445,
"impressions": 2493,
"clicks": 244,
"companionClicks1": 26,
"companionClicks2": 26,
"companionClicks3": 17,
"companionClicks4": 18,
"companionClicks5": 26,
"companionViews1": 26,
"companionViews2": 31,
"companionViews3": 27,
"companionViews4": 21,
"companionViews5": 26,
"start": 1969,
"firstQuartile": 1507,
"midpoint": 1094,
"thirdQuartile": 641,
"complete": 306,
"mute": 107,
"unmute": 106,
"pause": 106,
"rewind": 109,
"resume": 115,
"fullscreen": 425,
"exitFullscreen": 120,
"expand": 26,
"collapse": 28,
"acceptInvitationLinear": 30,
"closeLinear": 14,
"skip": 737,
"conversions": 0,
"cost": 0,
"payout": 0,
"revenue": 0,
"e_cpm": 0,
"e_cpc": 0,
"e_cpa": 0
},
{
"start_date": "2018-02-01T00:00:00-08:00",
"requests": 2223,
"impressions": 2224,
"clicks": 181,
"companionClicks1": 25,
"companionClicks2": 20,
"companionClicks3": 21,
"companionClicks4": 20,
"companionClicks5": 20,
"companionViews1": 17,
"companionViews2": 21,
"companionViews3": 22,
"companionViews4": 22,
"companionViews5": 17,
"start": 1808,
"firstQuartile": 1375,
"midpoint": 987,
"thirdQuartile": 584,
"complete": 315,
"mute": 112,
"unmute": 90,
"pause": 105,
"rewind": 109,
"resume": 99,
"fullscreen": 383,
"exitFullscreen": 101,
"expand": 12,
"collapse": 21,
"acceptInvitationLinear": 25,
"closeLinear": 18,
"skip": 685,
"conversions": 0,
"cost": 0,
"payout": 0,
"revenue": 0,
"e_cpm": 0,
"e_cpc": 0,
"e_cpa": 0
}
]
}
],
"meta": {
"type": "overview",
"period": "month",
"from": "2018-01-01T00:00:00-08:00",
"to": "2018-03-01T00:00:00-08:00",
"timezone": "America/Los_Angeles"
}
}
AdButler\VASTReport JSON: {
"object": "vast_report",
"url": "/v1/vast-reports",
"data": [
{
"type": "overview",
"id": 108508,
"summary": {
"requests": 4668,
"impressions": 4717,
"clicks": 425,
"companionClicks1": 51,
"companionClicks2": 46,
"companionClicks3": 38,
"companionClicks4": 38,
"companionClicks5": 46,
"companionViews1": 43,
"companionViews2": 52,
"companionViews3": 49,
"companionViews4": 43,
"companionViews5": 43,
"start": 3777,
"firstQuartile": 2882,
"midpoint": 2081,
"thirdQuartile": 1225,
"complete": 621,
"mute": 219,
"unmute": 196,
"pause": 211,
"rewind": 218,
"resume": 214,
"fullscreen": 808,
"exitFullscreen": 221,
"expand": 38,
"collapse": 49,
"acceptInvitationLinear": 55,
"closeLinear": 32,
"skip": 1422,
"conversions": 0,
"cost": 0,
"payout": 0,
"revenue": 0,
"e_cpm": 0,
"e_cpc": 0,
"e_cpa": 0
},
"details": [
{
"start_date": "2018-01-01T00:00:00-08:00",
"requests": 2445,
"impressions": 2493,
"clicks": 244,
"companionClicks1": 26,
"companionClicks2": 26,
"companionClicks3": 17,
"companionClicks4": 18,
"companionClicks5": 26,
"companionViews1": 26,
"companionViews2": 31,
"companionViews3": 27,
"companionViews4": 21,
"companionViews5": 26,
"start": 1969,
"firstQuartile": 1507,
"midpoint": 1094,
"thirdQuartile": 641,
"complete": 306,
"mute": 107,
"unmute": 106,
"pause": 106,
"rewind": 109,
"resume": 115,
"fullscreen": 425,
"exitFullscreen": 120,
"expand": 26,
"collapse": 28,
"acceptInvitationLinear": 30,
"closeLinear": 14,
"skip": 737,
"conversions": 0,
"cost": 0,
"payout": 0,
"revenue": 0,
"e_cpm": 0,
"e_cpc": 0,
"e_cpa": 0
},
{
"start_date": "2018-02-01T00:00:00-08:00",
"requests": 2223,
"impressions": 2224,
"clicks": 181,
"companionClicks1": 25,
"companionClicks2": 20,
"companionClicks3": 21,
"companionClicks4": 20,
"companionClicks5": 20,
"companionViews1": 17,
"companionViews2": 21,
"companionViews3": 22,
"companionViews4": 22,
"companionViews5": 17,
"start": 1808,
"firstQuartile": 1375,
"midpoint": 987,
"thirdQuartile": 584,
"complete": 315,
"mute": 112,
"unmute": 90,
"pause": 105,
"rewind": 109,
"resume": 99,
"fullscreen": 383,
"exitFullscreen": 101,
"expand": 12,
"collapse": 21,
"acceptInvitationLinear": 25,
"closeLinear": 18,
"skip": 685,
"conversions": 0,
"cost": 0,
"payout": 0,
"revenue": 0,
"e_cpm": 0,
"e_cpc": 0,
"e_cpa": 0
}
]
}
],
"meta": {
"type": "overview",
"period": "month",
"from": "2018-01-01T00:00:00-08:00",
"to": "2018-03-01T00:00:00-08:00",
"timezone": "America/Los_Angeles"
}
}
Field | Type | Description |
---|---|---|
object |
string |
A string denoting the object type which is always |
url |
string |
The relative URL of the current resource which is always of the form |
data |
array |
The data retrieved given the criteria in the URL. |
meta |
array |
Additional information about the request. |
Retrieve VAST Reports
Definition
GET https://api.adbutler.com/v1/vast-reports
\AdButler\VASTReport::retrieve()
adbutler.vast-reports.retrieve()
Example Request
curl "https://api.adbutler.com/v1/vast-reports?type=overview&from=2018-01-01T00:00:00-08:00&to=2018-02-01T12:00:00-08:00&period=month&timezone=America/Los_Angeles&summary=true&details=true&breakdown=false&financials=true" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$report = \AdButler\VASTReport::retrieve( array(
'type' => 'overview'
'from' => '2017-08-07T16:30:00-07:00'
'to' => '2017-08-10T18:00:00-07:00'
'period' => 'day'
'timezone' => 'America/Los_Angeles'
'summary' => true
'details' => true
'breakdown' => true
'financials' => true
));
echo $report;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.vast-reports.read({
type: overview,
from: 2017-08-07T16:30:00-07:00,
to: 2017-08-10T18:00:00-07:00,
period: day,
timezone: America/Los_Angeles,
summary: true,
details: true,
breakdown: true,
financials: true
}, function(response) {
console.log(response);
});
// using promises
adbutler.vast-reports.read({
type: overview,
from: 2017-08-07T16:30:00-07:00,
to: 2017-08-10T18:00:00-07:00,
period: day,
timezone: America/Los_Angeles,
summary: true,
details: true,
breakdown: true,
financials: true
}).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "vast-report",
"url": "/v1/vast-reports",
"data": [
{
"type": "overview",
"id": 108508,
"summary": {
"requests": 4668,
"impressions": 4717,
"clicks": 425,
"companionClicks1": 51,
"companionClicks2": 46,
"companionClicks3": 38,
"companionClicks4": 38,
"companionClicks5": 46,
"companionViews1": 43,
"companionViews2": 52,
"companionViews3": 49,
"companionViews4": 43,
"companionViews5": 43,
"start": 3777,
"firstQuartile": 2882,
"midpoint": 2081,
"thirdQuartile": 1225,
"complete": 621,
"mute": 219,
"unmute": 196,
"pause": 211,
"rewind": 218,
"resume": 214,
"fullscreen": 808,
"exitFullscreen": 221,
"expand": 38,
"collapse": 49,
"acceptInvitationLinear": 55,
"closeLinear": 32,
"skip": 1422,
"conversions": 0,
"cost": 0,
"payout": 0,
"revenue": 0,
"e_cpm": 0,
"e_cpc": 0,
"e_cpa": 0
},
"details": [
{
"start_date": "2018-01-01T00:00:00-08:00",
"requests": 2445,
"impressions": 2493,
"clicks": 244,
"companionClicks1": 26,
"companionClicks2": 26,
"companionClicks3": 17,
"companionClicks4": 18,
"companionClicks5": 26,
"companionViews1": 26,
"companionViews2": 31,
"companionViews3": 27,
"companionViews4": 21,
"companionViews5": 26,
"start": 1969,
"firstQuartile": 1507,
"midpoint": 1094,
"thirdQuartile": 641,
"complete": 306,
"mute": 107,
"unmute": 106,
"pause": 106,
"rewind": 109,
"resume": 115,
"fullscreen": 425,
"exitFullscreen": 120,
"expand": 26,
"collapse": 28,
"acceptInvitationLinear": 30,
"closeLinear": 14,
"skip": 737,
"conversions": 0,
"cost": 0,
"payout": 0,
"revenue": 0,
"e_cpm": 0,
"e_cpc": 0,
"e_cpa": 0
},
{
"start_date": "2018-02-01T00:00:00-08:00",
"requests": 2223,
"impressions": 2224,
"clicks": 181,
"companionClicks1": 25,
"companionClicks2": 20,
"companionClicks3": 21,
"companionClicks4": 20,
"companionClicks5": 20,
"companionViews1": 17,
"companionViews2": 21,
"companionViews3": 22,
"companionViews4": 22,
"companionViews5": 17,
"start": 1808,
"firstQuartile": 1375,
"midpoint": 987,
"thirdQuartile": 584,
"complete": 315,
"mute": 112,
"unmute": 90,
"pause": 105,
"rewind": 109,
"resume": 99,
"fullscreen": 383,
"exitFullscreen": 101,
"expand": 12,
"collapse": 21,
"acceptInvitationLinear": 25,
"closeLinear": 18,
"skip": 685,
"conversions": 0,
"cost": 0,
"payout": 0,
"revenue": 0,
"e_cpm": 0,
"e_cpc": 0,
"e_cpa": 0
}
]
}
],
"meta": {
"type": "overview",
"period": "month",
"from": "2018-01-01T00:00:00-08:00",
"to": "2018-03-01T00:00:00-08:00",
"timezone": "America/Los_Angeles"
}
}
AdButler\VASTReport JSON: {
"object": "vast_report",
"url": "/v1/vast-reports",
"data": [
{
"type": "overview",
"id": 108508,
"summary": {
"requests": 4668,
"impressions": 4717,
"clicks": 425,
"companionClicks1": 51,
"companionClicks2": 46,
"companionClicks3": 38,
"companionClicks4": 38,
"companionClicks5": 46,
"companionViews1": 43,
"companionViews2": 52,
"companionViews3": 49,
"companionViews4": 43,
"companionViews5": 43,
"start": 3777,
"firstQuartile": 2882,
"midpoint": 2081,
"thirdQuartile": 1225,
"complete": 621,
"mute": 219,
"unmute": 196,
"pause": 211,
"rewind": 218,
"resume": 214,
"fullscreen": 808,
"exitFullscreen": 221,
"expand": 38,
"collapse": 49,
"acceptInvitationLinear": 55,
"closeLinear": 32,
"skip": 1422,
"conversions": 0,
"cost": 0,
"payout": 0,
"revenue": 0,
"e_cpm": 0,
"e_cpc": 0,
"e_cpa": 0
},
"details": [
{
"start_date": "2018-01-01T00:00:00-08:00",
"requests": 2445,
"impressions": 2493,
"clicks": 244,
"companionClicks1": 26,
"companionClicks2": 26,
"companionClicks3": 17,
"companionClicks4": 18,
"companionClicks5": 26,
"companionViews1": 26,
"companionViews2": 31,
"companionViews3": 27,
"companionViews4": 21,
"companionViews5": 26,
"start": 1969,
"firstQuartile": 1507,
"midpoint": 1094,
"thirdQuartile": 641,
"complete": 306,
"mute": 107,
"unmute": 106,
"pause": 106,
"rewind": 109,
"resume": 115,
"fullscreen": 425,
"exitFullscreen": 120,
"expand": 26,
"collapse": 28,
"acceptInvitationLinear": 30,
"closeLinear": 14,
"skip": 737,
"conversions": 0,
"cost": 0,
"payout": 0,
"revenue": 0,
"e_cpm": 0,
"e_cpc": 0,
"e_cpa": 0
},
{
"start_date": "2018-02-01T00:00:00-08:00",
"requests": 2223,
"impressions": 2224,
"clicks": 181,
"companionClicks1": 25,
"companionClicks2": 20,
"companionClicks3": 21,
"companionClicks4": 20,
"companionClicks5": 20,
"companionViews1": 17,
"companionViews2": 21,
"companionViews3": 22,
"companionViews4": 22,
"companionViews5": 17,
"start": 1808,
"firstQuartile": 1375,
"midpoint": 987,
"thirdQuartile": 584,
"complete": 315,
"mute": 112,
"unmute": 90,
"pause": 105,
"rewind": 109,
"resume": 99,
"fullscreen": 383,
"exitFullscreen": 101,
"expand": 12,
"collapse": 21,
"acceptInvitationLinear": 25,
"closeLinear": 18,
"skip": 685,
"conversions": 0,
"cost": 0,
"payout": 0,
"revenue": 0,
"e_cpm": 0,
"e_cpc": 0,
"e_cpa": 0
}
]
}
],
"meta": {
"type": "overview",
"period": "month",
"from": "2018-01-01T00:00:00-08:00",
"to": "2018-03-01T00:00:00-08:00",
"timezone": "America/Los_Angeles"
}
}
You can retrieve overview of all the information or about a specific publisher
, advertiser
, zone
, campaign
, or banner
in specified periods.
Query Parameters
Parameter | Description |
---|---|
type* |
Specifies the focus of the statistics you are interested in viewing. The value must be one of |
period* |
The range of time you are interested in viewing. The value must be one of |
preset† |
Frequently used time frames for reporting statistics are bundled as presets You can pick a value from the presets instead of creating your own custom date range using the |
timezone* |
Timezone for the |
from† |
A valid ISO 8601 formatted date denoting the start of the period, e.g. |
to† |
A valid ISO 8601 formatted date denoting the end of the period, e.g. |
summary‡ |
Whether to show a summary ( |
details‡ |
Whether to show details ( |
breakdown |
Whether to show breakdown of summary and details ( |
financials |
Whether to show financial data ( |
* = required field
✝ = Either preset
or specific to
and from
dates must be specified
‡ = Either summary
or details
must be specified
Returns
Returns a vast_report
object if the request succeeded, or an error if something went terribly wrong.
Click Details
Introduction
This endpoint will allow you to get detailed breakdown of clicks in your account. Please note that we only keep the latest 3 months of click-through data.
The click_detail_report
response object has the following fields.
Example Response
{
"object": "click_detail_report",
"url": "/v1/reports/click-details",
"data": [
{
"zone": 86133,
"campaign": 5053,
"advertisement": {
"type": "banner",
"id": 518881649
},
"click_date": "2018-09-10 22:35:39",
"ip": "192.168.10.xxx",
"country": null,
"region": null,
"city": null,
"custom_param_1": null,
"custom_param_2": null,
"custom_param_3": null,
"custom_param_4": null,
"custom_param_5": null
}
],
"meta": {
"limit": "1",
"offset": "10",
"has_more": true,
"from": "2018-09-01T00:00:00-07:00",
"to": "2018-10-01T00:00:00-07:00",
"timezone": "America/Los_Angeles"
}
}
AdButler\Report JSON: {
"object": "click_detail_report",
"url": "/v1/reports/click-details",
"data": [
{
"zone": 86133,
"campaign": 5053,
"advertisement": {
"type": "banner",
"id": 518881649
},
"click_date": "2018-09-10 22:35:39",
"ip": "192.168.10.xxx",
"country": null,
"region": null,
"city": null,
"custom_param_1": null,
"custom_param_2": null,
"custom_param_3": null,
"custom_param_4": null,
"custom_param_5": null
}
],
"meta": {
"limit": "1",
"offset": "10",
"has_more": true,
"from": "2018-09-01T00:00:00-07:00",
"to": "2018-10-01T00:00:00-07:00",
"timezone": "America/Los_Angeles"
}
}
Field | Type | Description |
---|---|---|
object |
string |
A string denoting the object type which is always |
url |
string |
The relative URL of the current resource which is always of the form |
data |
array |
The data retrieved given the criteria in the URL. |
meta |
array |
Additional information about the request. |
Retrieve Click Details
Definition
GET https://api.adbutler.com/v1/reports/click-details
\AdButler\ClickDetails::retrieve()
adbutler.clickDetails.retrieve()
Example Request
curl "https://api.adbutler.com/v1/reports/click-details?vast=false&from=2018-09-01T00:00:00-07:00&to=2018-10-01T00:00:00-07:00&limit=1&offset=10" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$report = \AdButler\ClickDetails::retrieve( array(
'vast' => 'false',
'from' => '2018-09-01T00:00:00-07:00',
'to' => '2018-10-01T00:00:00-07:00',
'limit' => 1,
'offset' => 10,
));
echo $report;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.clickDetails.read({
vast: false,
from: 2018-09-01T00:00:00-07:00,
to: 2018-10-01T00:00:00-07:00,
limit: 1,
offset: 10,
}, function(response) {
console.log(response);
});
// using promises
adbutler.reports.read({
vast: false,
from: 2018-09-01T00:00:00-07:00,
to: 2018-10-01T00:00:00-07:00,
limit: 1,
offset: 10,
}).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "click_detail_report",
"url": "/v1/reports/click-details",
"data": [
{
"zone": 86133,
"campaign": 5053,
"advertisement": {
"type": "banner",
"id": 518881649
},
"click_date": "2018-09-10 22:35:39",
"ip": "192.168.10.xxx",
"country": null,
"region": null,
"city": null,
"custom_param_1": null,
"custom_param_2": null,
"custom_param_3": null,
"custom_param_4": null,
"custom_param_5": null
}
],
"meta": {
"limit": "1",
"offset": "10",
"has_more": true,
"from": "2018-09-01T00:00:00-07:00",
"to": "2018-10-01T00:00:00-07:00",
"timezone": "America/Los_Angeles"
}
}
AdButler\Report JSON: {
"object": "click_detail_report",
"url": "/v1/reports/click-details",
"data": [
{
"zone": 86133,
"campaign": 5053,
"advertisement": {
"type": "banner",
"id": 518881649
},
"click_date": "2018-09-10 22:35:39",
"ip": "192.168.10.xxx",
"country": null,
"region": null,
"city": null,
"custom_param_1": null,
"custom_param_2": null,
"custom_param_3": null,
"custom_param_4": null,
"custom_param_5": null
}
],
"meta": {
"limit": "1",
"offset": "10",
"has_more": true,
"from": "2018-09-01T00:00:00-07:00",
"to": "2018-10-01T00:00:00-07:00",
"timezone": "America/Los_Angeles"
}
}
You can retrieve a report of clicks on your account.
Query Parameters
Parameter | Description |
---|---|
vast |
Whether this report will return display or VAST clicks. |
filter_type |
Describes how you would like to filter the report. Either by |
filter_ids |
A comma-separated list of IDs to filter the report by. If 'filter_type' is omitted, omit this field as well. |
custom_filter_params |
If your account is set up to use Custom Parameters, you can filter your clicks based on those parameters. This field is a comma-separated list of custom parameters you'd like to filter this report by. |
preset† |
Frequently used time frames for reporting statistics are bundled as presets You can pick a value from the presets instead of creating your own custom date range using the |
timezone* |
Timezone for the |
from† |
A valid ISO 8601 formatted date denoting the start of the period, e.g. |
to† |
A valid ISO 8601 formatted date denoting the end of the period, e.g. |
limit |
A non-negative integer that indicates the number of records you'd like returned in the response. |
offset |
A non-negative integer that indicates how many records to skip when compiling the response. |
✝ = Either preset
or specific to
and from
dates must be specified
Returns
Returns a click_detail_report
object if the request succeeded, or an error if something went terribly wrong.
Conversion Details
Introduction
If you are tracking conversions, this endpoint can be a great way to get a more detailed breakdown of how they are performing. You can get reports on conversions for specific zones, campaigns, and date ranges.
NOTE: This endpoint is not available by default. Please contact our support team to get it enabled for your account.
The conversion_detail_report
response object has the following fields.
Example Response
{
"object": "conversion_detail_report",
"url": "/v1/reports/conversion-details",
"data": [
{
"zone": 86133,
"campaign": 5053,
"advertisement": {
"type": "banner",
"id": 518881680
},
"conversion_date": "2018-09-10 22:35:39",
"referrer": "adbutler.com",
"ip": "192.168.10.xxx",
"country": null,
"region": null,
"city": null,
"value": 35.75,
"transaction_id": "abcd-1234",
"product_id": null
}
],
"meta": {
"limit": "1",
"offset": "10",
"has_more": true,
"from": "2018-09-01T00:00:00-07:00",
"to": "2018-10-01T00:00:00-07:00",
"timezone": "America/Los_Angeles"
}
}
AdButler\Report JSON: {
"object": "conversion_detail_report",
"url": "/v1/reports/conversion-details",
"data": [
{
"zone": 86133,
"campaign": 5053,
"advertisement": {
"type": "banner",
"id": 518881680
},
"conversion_date": "2018-09-10 22:35:39",
"referrer": "adbutler.com",
"ip": "192.168.10.xxx",
"country": null,
"region": null,
"city": null,
"value": 35.75,
"transaction_id": "abcd-1234",
"product_id": null
}
],
"meta": {
"limit": "1",
"offset": "10",
"has_more": true,
"from": "2018-09-01T00:00:00-07:00",
"to": "2018-10-01T00:00:00-07:00",
"timezone": "America/Los_Angeles"
}
}
Field | Type | Description |
---|---|---|
object |
string |
A string denoting the object type which is always |
url |
string |
The relative URL of the current resource which is always of the form |
data |
array |
The data retrieved given the criteria in the URL. |
meta |
array |
Additional information about the request. |
Retrieve Conversion Details
Definition
GET https://api.adbutler.com/v1/reports/conversion-details
\AdButler\ConversionDetails::retrieve()
adbutler.conversionDetails.retrieve()
Example Request
curl "https://api.adbutler.com/v1/reports/conversion-details?vast=false&from=2018-09-01T00:00:00-07:00&to=2018-10-01T00:00:00-07:00&limit=1&offset=10" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$report = \AdButler\ConversionDetails::retrieve( array(
'vast' => 'false',
'from' => '2018-09-01T00:00:00-07:00',
'to' => '2018-10-01T00:00:00-07:00',
'limit' => 1,
'offset' => 10,
));
echo $report;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.conversionDetails.read({
vast: false,
from: 2018-09-01T00:00:00-07:00,
to: 2018-10-01T00:00:00-07:00,
limit: 1,
offset: 10,
}, function(response) {
console.log(response);
});
// using promises
adbutler.reports.read({
vast: false,
from: 2018-09-01T00:00:00-07:00,
to: 2018-10-01T00:00:00-07:00,
limit: 1,
offset: 10,
}).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "conversion_detail_report",
"url": "/v1/reports/conversion-details",
"data": [
{
"zone": 86133,
"campaign": 5053,
"advertisement": {
"type": "banner",
"id": 518881680
},
"conversion_date": "2018-09-10 22:35:39",
"referrer": "adbutler.com",
"ip": "192.168.10.xxx",
"country": null,
"region": null,
"city": null,
"value": 35.75,
"transaction_id": "abcd-1234",
"product_id": null
}
],
"meta": {
"limit": "1",
"offset": "10",
"has_more": true,
"from": "2018-09-01T00:00:00-07:00",
"to": "2018-10-01T00:00:00-07:00",
"timezone": "America/Los_Angeles"
}
}
AdButler\Report JSON: {
"object": "conversion_detail_report",
"url": "/v1/reports/conversion-details",
"data": [
{
"zone": 86133,
"campaign": 5053,
"advertisement": {
"type": "banner",
"id": 518881680
},
"conversion_date": "2018-09-10 22:35:39",
"referrer": "adbutler.com",
"ip": "192.168.10.xxx",
"country": null,
"region": null,
"city": null,
"value": 35.75,
"transaction_id": "abcd-1234",
"product_id": null
}
],
"meta": {
"limit": "1",
"offset": "10",
"has_more": true,
"from": "2018-09-01T00:00:00-07:00",
"to": "2018-10-01T00:00:00-07:00",
"timezone": "America/Los_Angeles"
}
}
You can retrieve a report of conversions on your account.
Query Parameters
Parameter | Description |
---|---|
vast |
Whether this report will return display or VAST conversions. |
filter_type |
Describes how you would like to filter the report. Either by |
filter_ids |
A comma-separated list of IDs to filter the report by. If 'filter_type' is omitted, omit this field as well. |
preset† |
Frequently used time frames for reporting statistics are bundled as presets You can pick a value from the presets instead of creating your own custom date range using the |
timezone* |
Timezone for the |
from† |
A valid ISO 8601 formatted date denoting the start of the period, e.g. |
to† |
A valid ISO 8601 formatted date denoting the end of the period, e.g. |
limit |
A non-negative integer that indicates the number of records you'd like returned in the response. |
offset |
A non-negative integer that indicates how many records to skip when compiling the response. |
✝ = Either preset
or specific to
and from
dates must be specified
Returns
Returns a conversion_detail_report
object if the request succeeded, or an error if something went terribly wrong.
Stats
Introduction
Statistics quantify the serving of your advertisements across price and performance related metrics. They are updated in real time. We go to great lengths to give you detailed and accurate data about the performance of your advertisements, to help you make informed decisions. This endpoint enables you to build your own reporting dashboard should you feel the need to.
The stats
response object has the following fields.
Example Response
{
"object": "stats",
"url": "/v1/stats",
"data": {
"1770": [
{
"start_date": "2016-01-01T00:00:00+00:00",
"responses": 2399,
"impressions": 2399,
"clicks": 2399,
"conversions": 2399,
"cost": 0,
"payout": 0,
"revenue": 0,
"e_cpm": 0,
"e_cpc": 0,
"e_cpa": 0
}
]
},
"meta": {
"type": "publisher",
"period": "year",
"from": "2016-01-01T00:00:00+00:00",
"to": "2016-12-31T23:00:00+00:00"
}
}
AdButler\Stats JSON: {
"object": "stats",
"url": "/v1/stats",
"data": {
"1770": [
{
"start_date": "2016-01-01T00:00:00+00:00",
"responses": 2399,
"impressions": 2399,
"clicks": 2399,
"conversions": 2399,
"cost": 0,
"payout": 0,
"revenue": 0,
"e_cpm": 0,
"e_cpc": 0,
"e_cpa": 0
}
]
},
"meta": {
"type": "publisher",
"period": "year",
"from": "2016-01-01T00:00:00+00:00",
"to": "2016-12-31T23:00:00+00:00"
}
}
Field | Type | Description |
---|---|---|
object |
string |
A string denoting the object type which is always |
url |
string |
The relative URL of the current resource which is always of the form |
data |
array |
The data retrieved given the criteria in the URL. |
meta |
array |
Additional information about the request. |
Retrieve statistics
Definition
GET https://api.adbutler.com/v1/stats
\AdButler\Stats::retrieve()
adbutler.stats.retrieve()
Example Request
curl "https://api.adbutler.com/v1/stats?type=publisher" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$stat = \AdButler\Stats::retrieve( array(
'type' => 'publisher',
'from' => '2016-09-01T00:00:00+00:00',
'to' => '2016-10-15T16:00:00+00:00',
'period' => 'year',
'show_financial_data' => true
));
echo $stat;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.stats.read(3199, function(response) {
console.log(response);
});
// using promises
adbutler.stats.read(3199).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "stats",
"url": "/v1/stats",
"data": {
"1770": [
{
"start_date": "2016-01-01T00:00:00+00:00",
"responses": 2399,
"impressions": 2399,
"clicks": 2399,
"conversions": 2399,
"cost": 0,
"payout": 0,
"revenue": 0,
"e_cpm": 0,
"e_cpc": 0,
"e_cpa": 0
}
]
},
"meta": {
"type": "publisher",
"period": "year",
"from": "2016-01-01T00:00:00+00:00",
"to": "2016-12-31T23:00:00+00:00"
}
}
AdButler\Stats JSON: {
"object": "stats",
"url": "/v1/stats",
"data": {
"1770": [
{
"start_date": "2016-01-01T00:00:00+00:00",
"responses": 2399,
"impressions": 2399,
"clicks": 2399,
"conversions": 2399,
"cost": 0,
"payout": 0,
"revenue": 0,
"e_cpm": 0,
"e_cpc": 0,
"e_cpa": 0
}
]
},
"meta": {
"type": "publisher",
"period": "year",
"from": "2016-01-01T00:00:00+00:00",
"to": "2016-12-31T23:00:00+00:00"
}
}
You can retrieve overview of all the information or about a specific publisher
, advertiser
, zone
, campaign
, or banner
in specified periods.
Query Parameters
Parameter | Description |
---|---|
type* |
Specifies the focus of the statistics you are interested in viewing. The value must be one of |
period* |
The range of time you are interested in viewing. The value must be one of |
preset† |
Frequently used time frames for reporting statistics are bundled as presets You can pick a value from the presets instead of creating your own custom date range using the |
timezone* |
Timezone for the |
from† |
A valid ISO 8601 formatted date denoting the start of the period, e.g. |
to† |
A valid ISO 8601 formatted date denoting the end of the period, e.g. |
show_financial_data |
A flag to indicate whether to show financial data in the response or not. When true you will see |
* = required field
✝ = Either preset
or specific to
and from
dates must be specified
Returns
Returns a stats
object if the request succeeded, or an error if something went terribly wrong.
Retrieve summary statistics
Definition
GET https://api.adbutler.com/v1/stats
\AdButler\Stats::retrieve()
adbutler.stats.retrieve()
Example Request
curl "https://api.adbutler.com/v1/stats?type=publisher" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$stat = \AdButler\Stats::retrieve( array(
'type' => 'publisher'
));
echo $stat;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.stats.read(3199, function(response) {
console.log(response);
});
// using promises
adbutler.stats.read(3199).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "stats",
"url": "/v1/stats/summary",
"data": {
"1520": {
"responses": 2778043,
"impressions": 2778094,
"clicks": 11,
"conversions": 8,
"cost": 2399.22634,
"payout": 287.9071608,
"revenue": 2111.3191792,
"e_cpm": 0.864,
"e_cpc": 218.111,
"e_cpa": 299.903
},
"1747": {
"responses": 922621,
"impressions": 922611,
"clicks": 0,
"conversions": 0,
"cost": 0,
"payout": 0,
"revenue": 0,
"e_cpm": 0,
"e_cpc": 0,
"e_cpa": 0
}
},
"meta": {
"type": "publisher",
"period": "total",
"from": "2016-06-01T00:00:00-07:00",
"to": "2016-11-10T13:00:00-08:00"
}
}
AdButler\Stats JSON: {
"object": "stats",
"url": "/v1/stats/summary",
"data": {
"1520": {
"responses": 2778043,
"impressions": 2778094,
"clicks": 11,
"conversions": 8,
"cost": 2399.22634,
"payout": 287.9071608,
"revenue": 2111.3191792,
"e_cpm": 0.864,
"e_cpc": 218.111,
"e_cpa": 299.903
},
"1747": {
"responses": 922621,
"impressions": 922611,
"clicks": 0,
"conversions": 0,
"cost": 0,
"payout": 0,
"revenue": 0,
"e_cpm": 0,
"e_cpc": 0,
"e_cpa": 0
}
},
"meta": {
"type": "publisher",
"period": "total",
"from": "2016-06-01T00:00:00-07:00",
"to": "2016-11-10T13:00:00-08:00"
}
}
Summary statistics present the overall performance metrics. You can retrieve an overview of all the information or about a specific publisher
, advertiser
, zone
, campaign
, or banner
.
Query Parameters
Parameter | Description |
---|---|
type* |
Specifies the focus of the statistics you are interested in viewing. The value must be one of |
period* |
The range of time you are interested in viewing. The value must be one of |
preset† |
Frequently used time frames for reporting statistics are bundled as presets You can pick a value from the presets instead of creating your own custom date range using the |
preset_tz |
Timezone for the |
from† |
A valid ISO 8601 formatted date denoting the start of the period, e.g. |
to† |
A valid ISO 8601 formatted date denoting the end of the period, e.g. |
show_financial_data |
A flag to indicate whether to show financial data in the response or not. When true you will see |
* = required field
✝ = Either preset
or specific to
and from
dates must be specified
Returns
Returns a stats
object if the request succeeded, or an error if something went terribly wrong.
VAST Schedules
Introduction
VAST Schedules describe the conditions necessary for serving VAST ads. Common conditions include start and end dates, and quotas.
If a quota has not been filled then that assignment will generally always serve as long as a targeting system does not interfere.
The vast_schedule
response object has the following fields.
Example Response
{
"object": "vast_schedule",
"self": "/v1/vast-schedules/12209",
"id": 12209,
"delivery_method": "default",
"quota_lifetime": 0,
"quota_type": null,
"start_date": "0000-00-00 00:00:00",
"end_date": "9999-01-01 00:00:00",
"views": 0,
"clicks": 0,
"geo_target": 0
}
AdButler\VASTSchedule JSON: {
"object": "vast_schedule",
"self": "/v1/vast-schedules/12209",
"id": 12209,
"delivery_method": "default",
"quota_lifetime": 0,
"quota_type": null,
"start_date": "0000-00-00 00:00:00",
"end_date": "9999-01-01 00:00:00",
"views": 0,
"clicks": 0,
"geo_target": 0
}
Field | Type | Description |
---|---|---|
object |
string |
A string denoting the object type which is always |
self |
string |
The relative URL of the current resource which is always of the form |
id |
integer |
The resource identifier (ID). |
delivery_method |
string |
Whether to deliver the impressions as quickly as possible ( |
quota_lifetime |
integer |
The amount of quota when setting up quota-based expiration which is a direct number ( |
quota_type |
string |
The type of quota when setting up quota-based expiration which can be the number of clicks ( |
start_date |
datetime |
The time and date when AdButler should start serving your advertisement. You can delay serving of ads by setting a future start date. Defaults to midnight of the current date if not given. |
end_date |
datetime |
The time and date when AdButler should stop serving your advertisement. The end date can be as far in the future as desired. This allows you to set time-based expiration for your ads and we guarantee accuracy to the hour. Leave this field empty if you want ad serving to never end. |
views |
integer |
The number of views recorded so far. |
clicks |
integer |
The number of clicks recorded so far. |
geo_target |
integer |
The geotarget identifier (ID) if you want your ads to be delivered to a particular location only. This will direct your audience to ads in their region. Defaults to |
Create a VAST Schedule
Definition
POST https://api.adbutler.com/v1/vast-schedules
\AdButler\VASTSchedule::create()
adbutler.vastSchedules.create()
Example Request
curl "https://api.adbutler.com/v1/vast-schedules" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"quota_lifetime": 0,
"quota_type": null,
"start_date": "0000-00-00 00:00:00",
"end_date": "9999-01-01 00:00:00"
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTSchedule = \AdButler\VASTSchedule::create(array(
"quota_lifetime" => 0,
"quota_type" => null,
"start_date" => "0000-00-00 00:00:00",
"end_date" => "9999-01-01 00:00:00"
));
echo $vASTSchedule;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var postData = {
"quota_lifetime": 0,
"quota_type": null,
"start_date": "0000-00-00 00:00:00",
"end_date": "9999-01-01 00:00:00"
};
// using callbacks
adbutler.vastSchedules.create(postData, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastSchedules.create(postData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "vast_schedule",
"self": "/v1/vast-schedules/12209",
"id": 12209,
"delivery_method": "default",
"quota_lifetime": 0,
"quota_type": null,
"start_date": "0000-00-00 00:00:00",
"end_date": "9999-01-01 00:00:00",
"views": 0,
"clicks": 0,
"geo_target": 0
}
AdButler\VASTSchedule JSON: {
"object": "vast_schedule",
"self": "/v1/vast-schedules/12209",
"id": 12209,
"delivery_method": "default",
"quota_lifetime": 0,
"quota_type": null,
"start_date": "0000-00-00 00:00:00",
"end_date": "9999-01-01 00:00:00",
"views": 0,
"clicks": 0,
"geo_target": 0
}
Creates a new VAST schedule.
Field | Type | Description |
---|---|---|
delivery_method |
string |
Whether to deliver the impressions as quickly as possible ( |
quota_lifetime† |
integer |
The amount of quota when setting up quota-based expiration which is a direct number ( |
quota_type† |
string |
The type of quota when setting up quota-based expiration which can be the number of clicks ( |
start_date† |
datetime |
The time and date when AdButler should start serving your advertisement. You can delay serving of ads by setting a future start date. Defaults to midnight of the current date if not given. |
end_date† |
datetime |
The time and date when AdButler should stop serving your advertisement. The end date can be as far in the future as desired. This allows you to set time-based expiration for your ads and we guarantee accuracy to the hour. Leave this field empty if you want ad serving to never end. |
geo_target |
integer |
The geotarget identifier (ID) if you want your ads to be delivered to a particular location only. This will direct your audience to ads in their region. Defaults to |
* = required field
† = must be given if delivery_method
is smooth
, otherwise defaults to the default value of the field
Returns
Returns a vast_schedule
object if the request succeeded, or an error if something went terribly wrong.
Retrieve a VAST Schedule
Definition
GET https://api.adbutler.com/v1/vast-schedules/{SCHEDULE-ID}
\AdButler\VASTSchedule::retrieve()
adbutler.vastSchedules.retrieve()
Example Request
curl "https://api.adbutler.com/v1/vast-schedules/12209" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTSchedule = \AdButler\VASTSchedule::retrieve( 12209 );
echo $vASTSchedule;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.vastSchedules.read(12209, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastSchedules.read(12209).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "vast_schedule",
"self": "/v1/vast-schedules/12209",
"id": 12209,
"delivery_method": "default",
"quota_lifetime": 0,
"quota_type": null,
"start_date": "0000-00-00 00:00:00",
"end_date": "9999-01-01 00:00:00",
"views": 0,
"clicks": 0,
"geo_target": 0
}
AdButler\VASTSchedule JSON: {
"object": "vast_schedule",
"self": "/v1/vast-schedules/12209",
"id": 12209,
"delivery_method": "default",
"quota_lifetime": 0,
"quota_type": null,
"start_date": "0000-00-00 00:00:00",
"end_date": "9999-01-01 00:00:00",
"views": 0,
"clicks": 0,
"geo_target": 0
}
You can retrieve the information about an existing VAST schedule by giving the schedule ID that was returned in the VAST schedule object upon creation. You will see at the most 10 VAST schedules in the response. You can change this default limit by appending ?limit=25
if you want this request to return 25 VAST schedules.
Returns
Returns a vast_schedule
object if the request succeeded, or an error if something went terribly wrong.
Update a VAST Schedule
Definition
PUT https://api.adbutler.com/v1/vast-schedules/{SCHEDULE-ID}
\AdButler\VASTSchedule->save()
adbutler.vastSchedules.update()
Example Request
curl "https://api.adbutler.com/v1/vast-schedules/12209" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
"quota_lifetime": 0,
"quota_type": null,
"start_date": "0000-00-00 00:00:00",
"end_date": "9999-01-01 00:00:00"
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTSchedule = \AdButler\VASTSchedule::retrieve( 12209 );
$vASTSchedule->quota_lifetime = 0;
$vASTSchedule->quota_type = null;
$vASTSchedule->start_date = "0000-00-00 00:00:00";
$vASTSchedule->end_date = "9999-01-01 00:00:00";
$vASTSchedule->save();
echo $vASTSchedule;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var updateData = {
"quota_lifetime": 0,
"quota_type": null,
"start_date": "0000-00-00 00:00:00",
"end_date": "9999-01-01 00:00:00"
};
// using callbacks
adbutler.vastSchedules.update(12209, updateData, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastSchedules.update(12209, updateData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "vast_schedule",
"self": "/v1/vast-schedules/12209",
"id": 12209,
"delivery_method": "default",
"quota_lifetime": 0,
"quota_type": null,
"start_date": "0000-00-00 00:00:00",
"end_date": "9999-01-01 00:00:00",
"views": 0,
"clicks": 0,
"geo_target": 0
}
AdButler\VASTSchedule JSON: {
"object": "vast_schedule",
"self": "/v1/vast-schedules/12209",
"id": 12209,
"delivery_method": "default",
"quota_lifetime": 0,
"quota_type": null,
"start_date": "0000-00-00 00:00:00",
"end_date": "9999-01-01 00:00:00",
"views": 0,
"clicks": 0,
"geo_target": 0
}
You can update a specific VAST schedule by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the VAST schedule creation request.
Field | Type | Description |
---|---|---|
delivery_method |
string |
Whether to deliver the impressions as quickly as possible ( |
quota_lifetime† |
integer |
The amount of quota when setting up quota-based expiration which is a direct number ( |
quota_type† |
string |
The type of quota when setting up quota-based expiration which can be the number of clicks ( |
start_date† |
datetime |
The time and date when AdButler should start serving your advertisement. You can delay serving of ads by setting a future start date. Defaults to midnight of the current date if not given. |
end_date† |
datetime |
The time and date when AdButler should stop serving your advertisement. The end date can be as far in the future as desired. This allows you to set time-based expiration for your ads and we guarantee accuracy to the hour. Leave this field empty if you want ad serving to never end. |
geo_target |
integer |
The geotarget identifier (ID) if you want your ads to be delivered to a particular location only. This will direct your audience to ads in their region. Defaults to |
† = must be given if delivery_method
is smooth
, otherwise defaults to the default value of the field
Returns
Returns a vast_schedule
object if the request succeeded, or an error if something went terribly wrong.
Delete a VAST Schedule
Definition
DELETE https://api.adbutler.com/v1/vast-schedules/{SCHEDULE-ID}
\AdButler\VASTSchedule->delete()
adbutler.vastSchedules.delete()
Example Request
curl "https://api.adbutler.com/v1/vast-schedules/12209" \
-H "Authorization: Basic {API_KEY}" \
-X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTSchedule = \AdButler\VASTSchedule::retrieve( 12209 );
$vASTSchedule->delete();
echo $vASTSchedule;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.vastSchedules.delete(12209, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastSchedules.delete(12209).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"id": 12209,
"delete": true
}
AdButler\VASTSchedule JSON: {
"id": 12209,
"delete": true
}
Permanently deletes a VAST schedule. if successful, this operation cannot be undone so be very sure when deleting one.
Returns
Returns a VAST schedule ID if the request succeeded, or an error if something went terribly wrong.
List all VAST Schedules
Definition
GET https://api.adbutler.com/v1/vast-schedules
\AdButler\VASTSchedule::retrieveAll()
adbutler.vastSchedules.list()
Example Request
curl "https://api.adbutler.com/v1/vast-schedules?limit=2" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTSchedule = \AdButler\VASTSchedule::retrieveAll(array(
"limit" => 2
));
echo $vASTSchedule;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.vastSchedules.list({
limit: 2
}, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastSchedules.list({
limit: 2
}).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/vast-schedules",
"data": [
{
"object": "vast_schedule",
"self": "/v1/vast-schedules/12153",
"id": 12153,
"delivery_method": "default",
"quota_lifetime": 0,
"quota_type": null,
"start_date": "0000-00-00 00:00:00",
"end_date": "9999-01-01 00:00:00",
"views": 0,
"clicks": 0,
"geo_target": 0
},
{
"object": "vast_schedule",
"self": "/v1/vast-schedules/12154",
"id": 12154,
"delivery_method": "default",
"quota_lifetime": 0,
"quota_type": null,
"start_date": "0000-00-00 00:00:00",
"end_date": "9999-01-01 00:00:00",
"views": 0,
"clicks": 0,
"geo_target": 0
}
]
}
AdButler\VASTSchedule JSON: {
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/vast-schedules",
"data": [
{
"object": "vast_schedule",
"self": "/v1/vast-schedules/12153",
"id": 12153,
"delivery_method": "default",
"quota_lifetime": 0,
"quota_type": null,
"start_date": "0000-00-00 00:00:00",
"end_date": "9999-01-01 00:00:00",
"views": 0,
"clicks": 0,
"geo_target": 0
},
{
"object": "vast_schedule",
"self": "/v1/vast-schedules/12154",
"id": 12154,
"delivery_method": "default",
"quota_lifetime": 0,
"quota_type": null,
"start_date": "0000-00-00 00:00:00",
"end_date": "9999-01-01 00:00:00",
"views": 0,
"clicks": 0,
"geo_target": 0
}
]
}
Returns a list of all the VAST schedules. Most recent VAST schedules appear first in the list.
Returns
Returns an object with a data
property that contains a list of up to the specified limit and/or offset of objects. Each entry in data
is a vast_schedule
object, and if no objects were found the list will be empty.
VAST Zones
Introduction
A VAST zone is a collection of VAST placements that you wish to serve. Each VAST zone has its own VAST ad tag you can use to retrieve ads.
The vast_zone
response object has the following fields.
Example Response
{
"object": "vast_zone",
"self": "/v1/vast-zones/85772",
"id": 85772,
"name": "demo-account-zone",
"publisher": 123,
"default_vast_banner": 2579,
"default_vast_campaign": 0
}
AdButler\VASTZone JSON: {
"object": "vast_zone",
"self": "/v1/vast-zones/85772",
"id": 85772,
"name": "demo-account-zone",
"publisher": 123,
"default_vast_banner": 2579,
"default_vast_campaign": 0
}
Field | Type | Description |
---|---|---|
object |
string |
A string denoting the object type which is always |
self |
string |
The relative URL of the current resource which is always of the form |
id |
integer |
The resource identifier (ID). |
name |
string |
Name of the zone. |
publisher |
integer |
The publisher identifier (ID) the banner zone belongs to. You can create zones without a publisher but you cannot use them unless you associate them with a publisher first. |
default_vast_banner |
integer |
The default VAST banner identifier (ID). A default banner will show if there is nothing else available in the zone. |
default_vast_campaign |
integer |
The default VAST campaign identifier (ID). A default campaign will show if there is nothing else available in the zone. |
Create a VAST Zone
Definition
POST https://api.adbutler.com/v1/vast-zones
\AdButler\VASTZone::create()
adbutler.vastZones.create()
Example Request
curl "https://api.adbutler.com/v1/vast-zones" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"name": "demo-account-zone",
"publisher": 123,
"default_vast_banner": 2579,
"default_vast_campaign": 0
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTZone = \AdButler\VASTZone::create(array(
"name" => "demo-account-zone",
"publisher" => 123,
"default_vast_banner" => 2579,
"default_vast_campaign" => 0
));
echo $vASTZone;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var postData = {
"name": "demo-account-zone",
"publisher": 123,
"default_vast_banner": 2579,
"default_vast_campaign": 0
};
// using callbacks
adbutler.vastZones.create(postData, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastZones.create(postData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "vast_zone",
"self": "/v1/vast-zones/85772",
"id": 85772,
"name": "demo-account-zone",
"publisher": 123,
"default_vast_banner": 2579,
"default_vast_campaign": 0
}
AdButler\VASTZone JSON: {
"object": "vast_zone",
"self": "/v1/vast-zones/85772",
"id": 85772,
"name": "demo-account-zone",
"publisher": 123,
"default_vast_banner": 2579,
"default_vast_campaign": 0
}
Creates a new VAST Zone.
Field | Type | Description |
---|---|---|
name* |
string |
Name of the zone. |
publisher |
integer |
The publisher identifier (ID) the banner zone belongs to. You can create zones without a publisher but you cannot use them unless you associate them with a publisher first. |
default_vast_banner† |
integer |
The default VAST banner identifier (ID). A default banner will show if there is nothing else available in the zone. |
default_vast_campaign† |
integer |
The default VAST campaign identifier (ID). A default campaign will show if there is nothing else available in the zone. |
* = required field
† = only one of default_vast_banner
or default_vast_campaign
may be submitted
Returns
Returns a vast_zone
object if the request succeeded, or an error if something went terribly wrong.
Retrieve a VAST Zone
Definition
GET https://api.adbutler.com/v1/vast-zones/{ZONE-ID}
\AdButler\VASTZone::retrieve()
adbutler.vastZones.retrieve()
Example Request
curl "https://api.adbutler.com/v1/vast-zones/85772" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTZone = \AdButler\VASTZone::retrieve( 85772 );
echo $vASTZone;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.vastZones.read(85772, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastZones.read(85772).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "vast_zone",
"self": "/v1/vast-zones/85772",
"id": 85772,
"name": "demo-account-zone",
"publisher": 123,
"default_vast_banner": 2579,
"default_vast_campaign": 0
}
AdButler\VASTZone JSON: {
"object": "vast_zone",
"self": "/v1/vast-zones/85772",
"id": 85772,
"name": "demo-account-zone",
"publisher": 123,
"default_vast_banner": 2579,
"default_vast_campaign": 0
}
You can retrieve the information about an existing VAST zone by giving the zone ID that was returned in the VAST zone object upon creation. You will see at the most 10 VAST zones in the response. You can change this default limit by appending ?limit=25
if you want this request to return 25 VAST zones.
Returns
Returns a vast_zone
object if the request succeeded, or an error if something went terribly wrong.
Update a VAST Zone
Definition
PUT https://api.adbutler.com/v1/vast-zones/{ZONE-ID}
\AdButler\VASTZone->save()
adbutler.vastZones.update()
Example Request
curl "https://api.adbutler.com/v1/vast-zones/85772" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
"name": "demo-account-zone",
"publisher": 123,
"default_vast_banner": 2579,
"default_vast_campaign": 0
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTZone = \AdButler\VASTZone::retrieve( 85772 );
$vASTZone->name = "demo-account-zone";
$vASTZone->publisher = 123;
$vASTZone->default_vast_banner = 2579;
$vASTZone->default_vast_campaign = 0;
$vASTZone->save();
echo $vASTZone;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var updateData = {
"name": "demo-account-zone",
"publisher": 123,
"default_vast_banner": 2579,
"default_vast_campaign": 0
};
// using callbacks
adbutler.vastZones.update(85772, updateData, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastZones.update(85772, updateData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "vast_zone",
"self": "/v1/vast-zones/85772",
"id": 85772,
"name": "demo-account-zone",
"publisher": 123,
"default_vast_banner": 2579,
"default_vast_campaign": 0
}
AdButler\VASTZone JSON: {
"object": "vast_zone",
"self": "/v1/vast-zones/85772",
"id": 85772,
"name": "demo-account-zone",
"publisher": 123,
"default_vast_banner": 2579,
"default_vast_campaign": 0
}
You can update a specific VAST zone by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the VAST zone creation request.
Field | Type | Description |
---|---|---|
name |
string |
Name of the zone. |
publisher |
integer |
The publisher identifier (ID) the banner zone belongs to. You can create zones without a publisher but you cannot use them unless you associate them with a publisher first. |
default_vast_banner† |
integer |
The default VAST banner identifier (ID). A default banner will show if there is nothing else available in the zone. |
default_vast_campaign† |
integer |
The default VAST campaign identifier (ID). A default campaign will show if there is nothing else available in the zone. |
† = only one of default_vast_banner
or default_vast_campaign
may be submitted
Returns
Returns a vast_zone
object if the request succeeded, or an error if something went terribly wrong.
Delete a VAST Zone
Definition
DELETE https://api.adbutler.com/v1/vast-zones/{ZONE-ID}
\AdButler\VASTZone->delete()
adbutler.vastZones.delete()
Example Request
curl "https://api.adbutler.com/v1/vast-zones/85772" \
-H "Authorization: Basic {API_KEY}" \
-X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTZone = \AdButler\VASTZone::retrieve( 85772 );
$vASTZone->delete();
echo $vASTZone;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.vastZones.delete(85772, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastZones.delete(85772).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"id": 85772,
"delete": true
}
AdButler\VASTZone JSON: {
"id": 85772,
"delete": true
}
Permanently deletes a VAST zone. if successful, this operation cannot be undone so be very sure when deleting one.
Returns
Returns a VAST zone ID if the request succeeded, or an error if something went terribly wrong.
List all VAST Zones
Definition
GET https://api.adbutler.com/v1/vast-zones
\AdButler\VASTZone::retrieveAll()
adbutler.vastZones.list()
Example Request
curl "https://api.adbutler.com/v1/vast-zones?limit=2" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTZone = \AdButler\VASTZone::retrieveAll(array(
"limit" => 2
));
echo $vASTZone;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.vastZones.list({
limit: 2
}, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastZones.list({
limit: 2
}).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/vast-zones",
"data": [
{
"object": "vast_zone",
"self": "/v1/vast-zones/85756",
"id": 85756,
"name": "demo-account-zone",
"publisher": 123,
"default_vast_banner": 2553,
"default_vast_campaign": 0
},
{
"object": "vast_zone",
"self": "/v1/vast-zones/85757",
"id": 85757,
"name": "demo-account-zone",
"publisher": 123,
"default_vast_banner": 2554,
"default_vast_campaign": 0
}
]
}
AdButler\VASTZone JSON: {
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/vast-zones",
"data": [
{
"object": "vast_zone",
"self": "/v1/vast-zones/85756",
"id": 85756,
"name": "demo-account-zone",
"publisher": 123,
"default_vast_banner": 2553,
"default_vast_campaign": 0
},
{
"object": "vast_zone",
"self": "/v1/vast-zones/85757",
"id": 85757,
"name": "demo-account-zone",
"publisher": 123,
"default_vast_banner": 2554,
"default_vast_campaign": 0
}
]
}
Returns a list of all the VAST zones. Most recent VAST zones appear first in the list.
Returns
Returns an object with a data
property that contains a list of up to the specified limit and/or offset of objects. Each entry in data
is a vast_zone
object, and if no objects were found the list will be empty.
Retrieve VAST zone conversion tag
Definition
GET https://api.adbutler.com/v1/vast-zones/{ZONE-ID}/conversion-tag
\AdButler\VASTZoneConvTag::retrieve()
adbutler.vastZones.conversionTag.retrieve()
Example Request
curl "https://api.adbutler.com/v1/vast-zones/ID/conversion-tag/85772" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTZoneConvTag = \AdButler\VASTZoneConvTag::retrieve( 85772 );
echo $vASTZoneConvTag;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.vastZones.conversionTag.read(85772, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastZones.conversionTag.read(85772).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Retrieves an HTML tag which can be used to track conversions for the provided VAST zone.
Query Parameters
Parameter | Description |
---|---|
protocol |
Whether to use |
Returns
Example Response
{
"object": "conv_tag",
"url": "/v1/vast-zones/85772/conversion-tag",
"data": {
"src": "https://servedbyadbutler.com.vm.test/vconvtrack.spark?MID=108607&vastZoneID=85772",
"html": "<img src='https://servedbyadbutler.com.vm.test/vconvtrack.spark?MID=108607&vastZoneID=85772' width='1' height='1' border='0' />"
}
}
AdButler\VASTZoneConvTag JSON: {
"object": "conv_tag",
"url": "/v1/vast-zones/85772/conversion-tag",
"data": {
"src": "https://servedbyadbutler.com.vm.test/vconvtrack.spark?MID=108607&vastZoneID=85772",
"html": "<img src='https://servedbyadbutler.com.vm.test/vconvtrack.spark?MID=108607&vastZoneID=85772' width='1' height='1' border='0' />"
}
}
Field | Type | Description |
---|---|---|
object |
string |
A string denoting the object type which is always |
url |
string |
The relative URL of the current resource which is always of the form |
data |
array |
The data object containing the conversion tag. |
Returns a conv_tag
object if the request succeeded, or an error if something went terribly wrong.
VAST Campaigns
Introduction
VAST campaigns are an effective way for you to organize your ads under an Advertiser for purposes of clarity and reporting.
The vast_campaign
response object has the following fields.
Example Response
{
"object": "vast_campaign",
"self": "/v1/vast-campaigns/4449",
"id": 4449,
"name": "demo-account-zone",
"advertiser": 123
}
AdButler\VASTCampaign JSON: {
"object": "vast_campaign",
"self": "/v1/vast-campaigns/4449",
"id": 4449,
"name": "demo-account-zone",
"advertiser": 123
}
Field | Type | Description |
---|---|---|
object |
string |
A string denoting the object type which is always |
self |
string |
The relative URL of the current resource which is always of the form |
id |
integer |
The resource identifier (ID). |
name |
string |
Name of the campaign. |
advertiser |
integer |
The advertiser resource identifier (ID). |
Create a VAST Campaign
Definition
POST https://api.adbutler.com/v1/vast-campaigns
\AdButler\VASTCampaign::create()
adbutler.vastCampaigns.create()
Example Request
curl "https://api.adbutler.com/v1/vast-campaigns" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"name": "demo-account-zone",
"advertiser": 123
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTCampaign = \AdButler\VASTCampaign::create(array(
"name" => "demo-account-zone",
"advertiser" => 123
));
echo $vASTCampaign;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var postData = {
"name": "demo-account-zone",
"advertiser": 123
};
// using callbacks
adbutler.vastCampaigns.create(postData, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastCampaigns.create(postData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "vast_campaign",
"self": "/v1/vast-campaigns/4449",
"id": 4449,
"name": "demo-account-zone",
"advertiser": 123
}
AdButler\VASTCampaign JSON: {
"object": "vast_campaign",
"self": "/v1/vast-campaigns/4449",
"id": 4449,
"name": "demo-account-zone",
"advertiser": 123
}
Creates a new VAST campaign.
Field | Type | Description |
---|---|---|
name* |
string |
Name of the campaign. |
advertiser |
integer |
The advertiser resource identifier (ID). |
* = required field
Returns
Returns a vast_campaign
object if the request succeeded, or an error if something went terribly wrong.
Retrieve a VAST Campaign
Definition
GET https://api.adbutler.com/v1/vast-campaigns/{CAMPAIGN-ID}
\AdButler\VASTCampaign::retrieve()
adbutler.vastCampaigns.retrieve()
Example Request
curl "https://api.adbutler.com/v1/vast-campaigns/4449" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTCampaign = \AdButler\VASTCampaign::retrieve( 4449 );
echo $vASTCampaign;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.vastCampaigns.read(4449, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastCampaigns.read(4449).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "vast_campaign",
"self": "/v1/vast-campaigns/4449",
"id": 4449,
"name": "demo-account-zone",
"advertiser": 123
}
AdButler\VASTCampaign JSON: {
"object": "vast_campaign",
"self": "/v1/vast-campaigns/4449",
"id": 4449,
"name": "demo-account-zone",
"advertiser": 123
}
You can retrieve the information about an existing VAST campaign by giving the campaign ID that was returned in the VAST campaign object upon creation. You will see at the most 10 VAST campaigns in the response. You can change this default limit by appending ?limit=25
if you want this request to return 25 VAST campaigns.
Returns
Returns a vast_campaign
object if the request succeeded, or an error if something went terribly wrong.
Update a VAST Campaign
Definition
PUT https://api.adbutler.com/v1/vast-campaigns/{CAMPAIGN-ID}
\AdButler\VASTCampaign->save()
adbutler.vastCampaigns.update()
Example Request
curl "https://api.adbutler.com/v1/vast-campaigns/4449" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
"name": "demo-account-zone",
"advertiser": 123
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTCampaign = \AdButler\VASTCampaign::retrieve( 4449 );
$vASTCampaign->name = "demo-account-zone";
$vASTCampaign->advertiser = 123;
$vASTCampaign->save();
echo $vASTCampaign;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var updateData = {
"name": "demo-account-zone",
"advertiser": 123
};
// using callbacks
adbutler.vastCampaigns.update(4449, updateData, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastCampaigns.update(4449, updateData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "vast_campaign",
"self": "/v1/vast-campaigns/4449",
"id": 4449,
"name": "demo-account-zone",
"advertiser": 123
}
AdButler\VASTCampaign JSON: {
"object": "vast_campaign",
"self": "/v1/vast-campaigns/4449",
"id": 4449,
"name": "demo-account-zone",
"advertiser": 123
}
You can update a specific VAST campaign by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the VAST campaign creation request.
Field | Type | Description |
---|---|---|
name |
string |
Name of the campaign. |
advertiser |
integer |
The advertiser resource identifier (ID). |
Returns
Returns a vast_campaign
object if the request succeeded, or an error if something went terribly wrong.
Delete a VAST Campaign
Definition
DELETE https://api.adbutler.com/v1/vast-campaigns/{CAMPAIGN-ID}
\AdButler\VASTCampaign->delete()
adbutler.vastCampaigns.delete()
Example Request
curl "https://api.adbutler.com/v1/vast-campaigns/4449" \
-H "Authorization: Basic {API_KEY}" \
-X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTCampaign = \AdButler\VASTCampaign::retrieve( 4449 );
$vASTCampaign->delete();
echo $vASTCampaign;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.vastCampaigns.delete(4449, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastCampaigns.delete(4449).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"id": 4449,
"delete": true
}
AdButler\VASTCampaign JSON: {
"id": 4449,
"delete": true
}
Permanently deletes a VAST campaign. if successful, this operation cannot be undone so be very sure when deleting one.
Returns
Returns a VAST campaign ID if the request succeeded, or an error if something went terribly wrong.
List all VAST campaigns
Definition
GET https://api.adbutler.com/v1/vast-campaigns
\AdButler\VASTCampaign::retrieveAll()
adbutler.vastCampaigns.list()
Example Request
curl "https://api.adbutler.com/v1/vast-campaigns?limit=2" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTCampaign = \AdButler\VASTCampaign::retrieveAll(array(
"limit" => 2
));
echo $vASTCampaign;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.vastCampaigns.list({
limit: 2
}, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastCampaigns.list({
limit: 2
}).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/vast-campaigns",
"data": [
{
"object": "vast_campaign",
"self": "/v1/vast-campaigns/4436",
"id": 4436,
"name": "demo-account-zone",
"advertiser": 123
},
{
"object": "vast_campaign",
"self": "/v1/vast-campaigns/4435",
"id": 4435,
"name": "demo-account-zone",
"advertiser": 123
}
]
}
AdButler\VASTCampaign JSON: {
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/vast-campaigns",
"data": [
{
"object": "vast_campaign",
"self": "/v1/vast-campaigns/4436",
"id": 4436,
"name": "demo-account-zone",
"advertiser": 123
},
{
"object": "vast_campaign",
"self": "/v1/vast-campaigns/4435",
"id": 4435,
"name": "demo-account-zone",
"advertiser": 123
}
]
}
Returns a list of all the VAST campaigns. Most recent VAST campaigns appear first in the list.
Returns
Returns an object with a data
property that contains a list of up to the specified limit and/or offset of objects. Each entry in data
is a vast_campaign
object, and if no objects were found the list will be empty.
Retrieve VAST campaign conversion tag
Definition
GET https://api.adbutler.com/v1/vast-campaigns/{CAMPAIGN-ID}/conversion-tag
\AdButler\VASTCampaignConvTag::retrieve()
adbutler.vastCampaigns.conversionTag.retrieve()
Example Request
curl "https://api.adbutler.com/v1/vast-campaigns/ID/conversion-tag/4449" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTCampaignConvTag = \AdButler\VASTCampaignConvTag::retrieve( 4449 );
echo $vASTCampaignConvTag;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.vastCampaigns.conversionTag.read(4449, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastCampaigns.conversionTag.read(4449).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Retrieves an HTML tag which can be used to track conversions for the provided VAST campaign.
Query Parameters
Parameter | Description |
---|---|
protocol |
Whether to use |
Returns
Example Response
{
"object": "conv_tag",
"url": "/v1/vast-campaigns/4449/conversion-tag",
"data": {
"src": "https://servedbyadbutler.com.vm.test/vconvtrack.spark?MID=108607&vastCampaignID=4449",
"html": "<img src='https://servedbyadbutler.com.vm.test/vconvtrack.spark?MID=108607&vastCampaignID=4449' width='1' height='1' border='0' />"
}
}
AdButler\VASTCampaignConvTag JSON: {
"object": "conv_tag",
"url": "/v1/vast-campaigns/4449/conversion-tag",
"data": {
"src": "https://servedbyadbutler.com.vm.test/vconvtrack.spark?MID=108607&vastCampaignID=4449",
"html": "<img src='https://servedbyadbutler.com.vm.test/vconvtrack.spark?MID=108607&vastCampaignID=4449' width='1' height='1' border='0' />"
}
}
Field | Type | Description |
---|---|---|
object |
string |
A string denoting the object type which is always |
url |
string |
The relative URL of the current resource which is always of the form |
data |
array |
The data object containing the conversion tag. |
Returns a conv_tag
object if the request succeeded, or an error if something went terribly wrong.
VAST Campaign Assignments
Introduction
A VAST campaign assignment represents the relationship between a VAST banner and a VAST campaign.
The vast_campaign_assignment
response object has the following fields.
Example Response
{
"object": "vast_campaign_assignment",
"self": "/v1/vast_campaign_assignments/7697",
"id": 7697,
"active": true,
"banner": 2579,
"campaign": 4449
}
AdButler\VASTCampaignAssignment JSON: {
"object": "vast_campaign_assignment",
"self": "/v1/vast_campaign_assignments/7697",
"id": 7697,
"active": true,
"banner": 2579,
"campaign": 4449
}
Field | Type | Description |
---|---|---|
object |
string |
A string denoting the object type which is always |
self |
string |
The relative URL of the current resource which is always of the form |
id |
integer |
The current resource identifier (ID). |
active |
boolean |
The status of ad serving whether it is being served in the given zone or not. |
banner |
integer |
The VAST banner resource identifier (ID). |
campaign |
integer |
The VAST campaign resource identifier (ID). |
Create a VAST campaign assignment
Definition
POST https://api.adbutler.com/v1/vast-campaign-assignments
\AdButler\VASTCampaignAssignment::create()
adbutler.vastCampaignAssignments.create()
Example Request
curl "https://api.adbutler.com/v1/vast-campaign-assignments" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"active": true,
"banner": 2579,
"campaign": 4449
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTCampaignAssignment = \AdButler\VASTCampaignAssignment::create(array(
"active" => true,
"banner" => 2579,
"campaign" => 4449
));
echo $vASTCampaignAssignment;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var postData = {
"active": true,
"banner": 2579,
"campaign": 4449
};
// using callbacks
adbutler.vastCampaignAssignments.create(postData, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastCampaignAssignments.create(postData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "vast_campaign_assignment",
"self": "/v1/vast_campaign_assignments/7697",
"id": 7697,
"active": true,
"banner": 2579,
"campaign": 4449
}
AdButler\VASTCampaignAssignment JSON: {
"object": "vast_campaign_assignment",
"self": "/v1/vast_campaign_assignments/7697",
"id": 7697,
"active": true,
"banner": 2579,
"campaign": 4449
}
Creates a new VAST campaign assignment.
Field | Type | Description |
---|---|---|
campaign* |
integer |
The VAST campaign resource identifier (ID). |
banner* |
integer |
The VAST banner resource identifier (ID). |
active |
boolean |
Whether to actively serve ads in the zones ( |
* = required field
Returns
Returns a vast_campaign_assignment
object if the request succeeded, or an error if something went terribly wrong.
Retrieve a VAST campaign assignment
Definition
GET https://api.adbutler.com/v1/vast-campaign-assignments/{CAMPAIGN-ASSIGNMENT-ID}
\AdButler\VASTCampaignAssignment::retrieve()
adbutler.vastCampaignAssignments.retrieve()
Example Request
curl "https://api.adbutler.com/v1/vast-campaign-assignments/7697" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTCampaignAssignment = \AdButler\VASTCampaignAssignment::retrieve( 7697 );
echo $vASTCampaignAssignment;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.vastCampaignAssignments.read(7697, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastCampaignAssignments.read(7697).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "vast_campaign_assignment",
"self": "/v1/vast_campaign_assignments/7697",
"id": 7697,
"active": true,
"banner": 2579,
"campaign": 4449
}
AdButler\VASTCampaignAssignment JSON: {
"object": "vast_campaign_assignment",
"self": "/v1/vast_campaign_assignments/7697",
"id": 7697,
"active": true,
"banner": 2579,
"campaign": 4449
}
You can retrieve the information about an existing VAST campaign assignment by giving the VAST campaign assignment ID that was returned in the vast_campaign_assignment
object upon creation. You will see at the most 10 VAST campaign assignments in the response. You can change this default limit by appending ?limit=25
if you want this request to return 25 campaign assignments.
Returns
Returns a vast_campaign_assignment
object if the request succeeded, or an error if something went terribly wrong.
Update a VAST campaign assignment
Definition
PUT https://api.adbutler.com/v1/vast-campaign-assignments/{CAMPAIGN-ASSIGNMENT-ID}
\AdButler\VASTCampaignAssignment->save()
adbutler.vastCampaignAssignments.update()
Example Request
curl "https://api.adbutler.com/v1/vast-campaign-assignments/7697" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
"active": true,
"banner": 2579,
"campaign": 4449
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTCampaignAssignment = \AdButler\VASTCampaignAssignment::retrieve( 7697 );
$vASTCampaignAssignment->active = true;
$vASTCampaignAssignment->banner = 2579;
$vASTCampaignAssignment->campaign = 4449;
$vASTCampaignAssignment->save();
echo $vASTCampaignAssignment;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var updateData = {
"active": true,
"banner": 2579,
"campaign": 4449
};
// using callbacks
adbutler.vastCampaignAssignments.update(7697, updateData, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastCampaignAssignments.update(7697, updateData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "vast_campaign_assignment",
"self": "/v1/vast_campaign_assignments/7697",
"id": 7697,
"active": true,
"banner": 2579,
"campaign": 4449
}
AdButler\VASTCampaignAssignment JSON: {
"object": "vast_campaign_assignment",
"self": "/v1/vast_campaign_assignments/7697",
"id": 7697,
"active": true,
"banner": 2579,
"campaign": 4449
}
You can update a specific VAST campaign assignment by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the campaign assignment creation request.
Field | Type | Description |
---|---|---|
campaign |
integer |
The VAST campaign resource identifier (ID). |
banner |
integer |
The VAST banner resource identifier (ID). |
active |
boolean |
Whether to actively serve ads in the zones ( |
Returns
Returns a vast_campaign_assignment
object if the request succeeded, or an error if something went terribly wrong.
Delete a VAST campaign assignment
Definition
DELETE https://api.adbutler.com/v1/vast-campaign-assignments/{CAMPAIGN-ASSIGNMENT-ID}
\AdButler\VASTCampaignAssignment->delete()
adbutler.vastCampaignAssignments.delete()
Example Request
curl "https://api.adbutler.com/v1/vast-campaign-assignments/7697" \
-H "Authorization: Basic {API_KEY}" \
-X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTCampaignAssignment = \AdButler\VASTCampaignAssignment::retrieve( 7697 );
$vASTCampaignAssignment->delete();
echo $vASTCampaignAssignment;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.vastCampaignAssignments.delete(7697, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastCampaignAssignments.delete(7697).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"id": 7697,
"delete": true
}
AdButler\VASTCampaignAssignment JSON: {
"id": 7697,
"delete": true
}
Permanently deletes a VAST campaign assignment. If successful, this operation cannot be undone so be very sure when deleting one.
Returns
Returns a vast_campaign_assignment ID if the request succeeded, or an error if something went terribly wrong.
List all VAST campaign assignments
Definition
GET https://api.adbutler.com/v1/vast-campaign-assignments
\AdButler\VASTCampaignAssignment::retrieveAll()
adbutler.vastCampaignAssignments.list()
Example Request
curl "https://api.adbutler.com/v1/vast-campaign-assignments?limit=2" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTCampaignAssignment = \AdButler\VASTCampaignAssignment::retrieveAll(array(
"limit" => 2
));
echo $vASTCampaignAssignment;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.vastCampaignAssignments.list({
limit: 2
}, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastCampaignAssignments.list({
limit: 2
}).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/vast-campaign-assignments",
"data": [
{
"object": "vast_campaign_assignment",
"self": "/v1/vast_campaign_assignments/7692",
"id": 7692,
"active": true,
"banner": 2576,
"campaign": 4447
},
{
"object": "vast_campaign_assignment",
"self": "/v1/vast_campaign_assignments/7695",
"id": 7695,
"active": true,
"banner": 2578,
"campaign": 4448
}
]
}
AdButler\VASTCampaignAssignment JSON: {
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/vast-campaign-assignments",
"data": [
{
"object": "vast_campaign_assignment",
"self": "/v1/vast_campaign_assignments/7692",
"id": 7692,
"active": true,
"banner": 2576,
"campaign": 4447
},
{
"object": "vast_campaign_assignment",
"self": "/v1/vast_campaign_assignments/7695",
"id": 7695,
"active": true,
"banner": 2578,
"campaign": 4448
}
]
}
Returns a list of all the VAST campaign assignments. Most recent campaign assignments appear first in the list.
Returns
Returns an object with a data
property that contains a list of up to the specified limit and/or offset of objects. Each entry in data
is a vast_campaign_assignment
object, and if no objects were found the list will be empty.
VAST Channels
Introduction
VAST channels provide an easy way to assign your VAST campaigns to multiple zones usually having a particular focus and perhaps owned by different publishers. This is desirable when a campaign with the same assignment settings is to be assigned to a large number of zones.
The vast_channel
response object has the following fields.
Example Response
{
"object": "vast_channel",
"self": "/v1/vast-channels/1053",
"id": 1053,
"name": "demo-account-zone",
"priority": "standard",
"vast_zones": [
{
"id": 85772,
"name": "demo-account-zone",
"type": "VAST Zone"
}
]
}
AdButler\VASTChannel JSON: {
"object": "vast_channel",
"self": "/v1/vast-channels/1053",
"id": 1053,
"name": "demo-account-zone",
"priority": "standard",
"vast_zones": [
{
"id": 85772,
"name": "demo-account-zone",
"type": "VAST Zone"
}
]
}
Field | Type | Description |
---|---|---|
object |
string |
A string denoting the object type which is always |
self |
string |
The relative URL of the current resource which is always of the form |
id |
integer |
The resource identifier (ID). |
name |
string |
Name of the channel. |
priority |
string |
Priority allows you to prefer serving of some ads over others in a channel. Possible values in descending order are |
vast_zones |
array |
An array of VAST zones assigned to the current resource. |
Create a VAST Channel
Definition
POST https://api.adbutler.com/v1/vast-channels
\AdButler\VASTChannel::create()
adbutler.vastChannels.create()
Example Request
curl "https://api.adbutler.com/v1/vast-channels" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"name": "demo-account-zone",
"priority": "standard",
"vast_zones": [
{
id: 85772,
name: "demo-account-zone",
type: "VAST Zone"
}
]
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTChannel = \AdButler\VASTChannel::create(array(
"name" => "demo-account-zone",
"priority" => "standard",
"vast_zones" => [
[
id => 85772,
name => "demo-account-zone",
type => "VAST Zone"
]
]
));
echo $vASTChannel;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var postData = {
"name": "demo-account-zone",
"priority": "standard",
"vast_zones": [
{
id: 85772,
name: "demo-account-zone",
type: "VAST Zone"
}
]
};
// using callbacks
adbutler.vastChannels.create(postData, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastChannels.create(postData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "vast_channel",
"self": "/v1/vast-channels/1053",
"id": 1053,
"name": "demo-account-zone",
"priority": "standard",
"vast_zones": [
{
"id": 85772,
"name": "demo-account-zone",
"type": "VAST Zone"
}
]
}
AdButler\VASTChannel JSON: {
"object": "vast_channel",
"self": "/v1/vast-channels/1053",
"id": 1053,
"name": "demo-account-zone",
"priority": "standard",
"vast_zones": [
{
"id": 85772,
"name": "demo-account-zone",
"type": "VAST Zone"
}
]
}
Creates a new VAST Channel.
Field | Type | Description |
---|---|---|
name* |
string |
Name of the channel. |
priority |
string |
Priority allows you to prefer serving of some ads over others in a channel. Possible values in descending order are |
* = required field
Returns
Returns a vast_channel
object if the request succeeded, or an error if something went terribly wrong.
Retrieve a VAST Channel
Definition
GET https://api.adbutler.com/v1/vast-channels/{CHANNEL-ID}
\AdButler\VASTChannel::retrieve()
adbutler.vastChannels.retrieve()
Example Request
curl "https://api.adbutler.com/v1/vast-channels/1053" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTChannel = \AdButler\VASTChannel::retrieve( 1053 );
echo $vASTChannel;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.vastChannels.read(1053, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastChannels.read(1053).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "vast_channel",
"self": "/v1/vast-channels/1053",
"id": 1053,
"name": "demo-account-zone",
"priority": "standard",
"vast_zones": [
{
"id": 85772,
"name": "demo-account-zone",
"type": "VAST Zone"
}
]
}
AdButler\VASTChannel JSON: {
"object": "vast_channel",
"self": "/v1/vast-channels/1053",
"id": 1053,
"name": "demo-account-zone",
"priority": "standard",
"vast_zones": [
{
"id": 85772,
"name": "demo-account-zone",
"type": "VAST Zone"
}
]
}
You can retrieve the information about an existing VAST channel by giving the channel ID that was returned in the VAST channel object upon creation. You will see at the most 10 VAST channels in the response. You can change this default limit by appending ?limit=25
if you want this request to return 25 VAST channels.
Returns
Returns a vast_channel
object if the request succeeded, or an error if something went terribly wrong.
Update a VAST Channel
Definition
PUT https://api.adbutler.com/v1/vast-channels/{CHANNEL-ID}
\AdButler\VASTChannel->save()
adbutler.vastChannels.update()
Example Request
curl "https://api.adbutler.com/v1/vast-channels/1053" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
"name": "demo-account-zone",
"priority": "standard",
"vast_zones": [
{
id: 85772,
name: "demo-account-zone",
type: "VAST Zone"
}
]
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTChannel = \AdButler\VASTChannel::retrieve( 1053 );
$vASTChannel->name = "demo-account-zone";
$vASTChannel->priority = "standard";
$vASTChannel->vast_zones = [
[
id = 85772,
name = "demo-account-zone",
type = "VAST Zone"
]
];
$vASTChannel->save();
echo $vASTChannel;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var updateData = {
"name": "demo-account-zone",
"priority": "standard",
"vast_zones": [
{
id: 85772,
name: "demo-account-zone",
type: "VAST Zone"
}
]
};
// using callbacks
adbutler.vastChannels.update(1053, updateData, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastChannels.update(1053, updateData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "vast_channel",
"self": "/v1/vast-channels/1053",
"id": 1053,
"name": "demo-account-zone",
"priority": "standard",
"vast_zones": [
{
"id": 85772,
"name": "demo-account-zone",
"type": "VAST Zone"
}
]
}
AdButler\VASTChannel JSON: {
"object": "vast_channel",
"self": "/v1/vast-channels/1053",
"id": 1053,
"name": "demo-account-zone",
"priority": "standard",
"vast_zones": [
{
"id": 85772,
"name": "demo-account-zone",
"type": "VAST Zone"
}
]
}
You can update a specific VAST channel by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the VAST channel creation request.
Field | Type | Description |
---|---|---|
name |
string |
Name of the channel. |
priority |
string |
Priority allows you to prefer serving of some ads over others in a channel. Possible values in descending order are |
Returns
Returns a vast_channel
object if the request succeeded, or an error if something went terribly wrong.
Delete a VAST Channel
Definition
DELETE https://api.adbutler.com/v1/vast-channels/{CHANNEL-ID}
\AdButler\VASTChannel->delete()
adbutler.vastChannels.delete()
Example Request
curl "https://api.adbutler.com/v1/vast-channels/1053" \
-H "Authorization: Basic {API_KEY}" \
-X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTChannel = \AdButler\VASTChannel::retrieve( 1053 );
$vASTChannel->delete();
echo $vASTChannel;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.vastChannels.delete(1053, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastChannels.delete(1053).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"id": 1053,
"delete": true
}
AdButler\VASTChannel JSON: {
"id": 1053,
"delete": true
}
Permanently deletes a VAST channel. if successful, this operation cannot be undone so be very sure when deleting one.
Returns
Returns a VAST channel ID if the request succeeded, or an error if something went terribly wrong.
List all VAST Channels
Definition
GET https://api.adbutler.com/v1/vast-channels
\AdButler\VASTChannel::retrieveAll()
adbutler.vastChannels.list()
Example Request
curl "https://api.adbutler.com/v1/vast-channels?limit=2" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTChannel = \AdButler\VASTChannel::retrieveAll(array(
"limit" => 2
));
echo $vASTChannel;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.vastChannels.list({
limit: 2
}, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastChannels.list({
limit: 2
}).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/vast-channels",
"data": [
{
"object": "vast_channel",
"self": "/v1/vast-channels/1042",
"id": 1042,
"name": "demo-account-zone",
"priority": "standard",
"vast_zones": [
{
"id": 85756,
"name": "demo-account-zone",
"type": "VAST Zone"
}
]
},
{
"object": "vast_channel",
"self": "/v1/vast-channels/1043",
"id": 1043,
"name": "demo-account-zone",
"priority": "standard",
"vast_zones": [
{
"id": 85757,
"name": "demo-account-zone",
"type": "VAST Zone"
}
]
}
]
}
AdButler\VASTChannel JSON: {
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/vast-channels",
"data": [
{
"object": "vast_channel",
"self": "/v1/vast-channels/1042",
"id": 1042,
"name": "demo-account-zone",
"priority": "standard",
"vast_zones": [
{
"id": 85756,
"name": "demo-account-zone",
"type": "VAST Zone"
}
]
},
{
"object": "vast_channel",
"self": "/v1/vast-channels/1043",
"id": 1043,
"name": "demo-account-zone",
"priority": "standard",
"vast_zones": [
{
"id": 85757,
"name": "demo-account-zone",
"type": "VAST Zone"
}
]
}
]
}
Returns a list of all the VAST channels. Most recent VAST channels appear first in the list.
Returns
Returns an object with a data
property that contains a list of up to the specified limit and/or offset of objects. Each entry in data
is a vast_channel
object, and if no objects were found the list will be empty.
VAST Channel Zone Assignments
Introduction
A VAST channel zone assignment represents the relationship between a VAST channel and a VAST zone.
The vast_channel_zone_assignment
response object has the following fields.
Example Response
{
"object": "vast_channel_zone_assignment",
"self": "/v1/vast-channel-zone-assignments/58",
"id": 58,
"vast_channel": 1053,
"vast_zone": {
"id": 85772,
"type": "VAST Zone"
}
}
AdButler\VASTChannelZoneAssignment JSON: {
"object": "vast_channel_zone_assignment",
"self": "/v1/vast-channel-zone-assignments/58",
"id": 58,
"vast_channel": 1053,
"vast_zone": {
"id": 85772,
"type": "VAST Zone"
}
}
Field | Type | Description |
---|---|---|
object |
string |
A string denoting the object type which is always |
self |
string |
The relative URL of the current resource which is always of the form |
id |
integer |
The resource identifier (ID). |
vast_channel |
integer |
The VAST channel identifier (ID) that you want the zone assigned to. |
vast_zone |
object |
An object containing a VAST zone identifier (ID) and type. |
Create a VAST Channel Zone Assignment
Definition
POST https://api.adbutler.com/v1/vast-channel-zone-assignments
\AdButler\VASTChannelZoneAssignment::create()
adbutler.vastChannelZoneAssignments.create()
Example Request
curl "https://api.adbutler.com/v1/vast-channel-zone-assignments" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X POST \
-d '{
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTChannelZoneAssignment = \AdButler\VASTChannelZoneAssignment::create(array(
));
echo $vASTChannelZoneAssignment;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var postData = {
};
// using callbacks
adbutler.vastChannelZoneAssignments.create(postData, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastChannelZoneAssignments.create(postData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "vast_channel_zone_assignment",
"self": "/v1/vast-channel-zone-assignments/58",
"id": 58,
"vast_channel": 1053,
"vast_zone": {
"id": 85772,
"type": "VAST Zone"
}
}
AdButler\VASTChannelZoneAssignment JSON: {
"object": "vast_channel_zone_assignment",
"self": "/v1/vast-channel-zone-assignments/58",
"id": 58,
"vast_channel": 1053,
"vast_zone": {
"id": 85772,
"type": "VAST Zone"
}
}
Creates a new VAST Channel Zone Assignment.
Field | Type | Description |
---|---|---|
vast_channel* |
integer |
The VAST channel identifier (ID) that you want the zone assigned to. |
vast_zone* |
object |
An object containing a VAST zone identifier (ID) and type. |
* = required field
Returns
Returns a vast_channel_zone_assignment
object if the request succeeded, or an error if something went terribly wrong.
Retrieve a VAST Channel Zone Assignment
Definition
GET https://api.adbutler.com/v1/vast-channel-zone-assignments/{CHANNEL-ZONE-ASSIGNMENT-ID}
\AdButler\VASTChannelZoneAssignment::retrieve()
adbutler.vastChannelZoneAssignments.retrieve()
Example Request
curl "https://api.adbutler.com/v1/vast-channel-zone-assignments/58" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTChannelZoneAssignment = \AdButler\VASTChannelZoneAssignment::retrieve( 58 );
echo $vASTChannelZoneAssignment;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.vastChannelZoneAssignments.read(58, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastChannelZoneAssignments.read(58).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "vast_channel_zone_assignment",
"self": "/v1/vast-channel-zone-assignments/58",
"id": 58,
"vast_channel": 1053,
"vast_zone": {
"id": 85772,
"type": "VAST Zone"
}
}
AdButler\VASTChannelZoneAssignment JSON: {
"object": "vast_channel_zone_assignment",
"self": "/v1/vast-channel-zone-assignments/58",
"id": 58,
"vast_channel": 1053,
"vast_zone": {
"id": 85772,
"type": "VAST Zone"
}
}
You can retrieve the information about an existing VAST channel assignment by giving the channel zone assignment ID that was returned in the VAST channel object upon creation. You will see at the most 10 VAST channel-zone-assignments in the response. You can change this default limit by appending ?limit=25
if you want this request to return 25 VAST channel-zone-assignments.
Returns
Returns a vast_channel_zone_assignment
object if the request succeeded, or an error if something went terribly wrong.
Update a VAST Channel Zone Assignment
Definition
PUT https://api.adbutler.com/v1/vast-channel-zone-assignments/{CHANNEL-ZONE-ASSIGNMENT-ID}
\AdButler\VASTChannelZoneAssignment->save()
adbutler.vastChannelZoneAssignments.update()
Example Request
curl "https://api.adbutler.com/v1/vast-channel-zone-assignments/58" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTChannelZoneAssignment = \AdButler\VASTChannelZoneAssignment::retrieve( 58 );
$vASTChannelZoneAssignment->save();
echo $vASTChannelZoneAssignment;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var updateData = {
};
// using callbacks
adbutler.vastChannelZoneAssignments.update(58, updateData, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastChannelZoneAssignments.update(58, updateData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "vast_channel_zone_assignment",
"self": "/v1/vast-channel-zone-assignments/58",
"id": 58,
"vast_channel": 1053,
"vast_zone": {
"id": 85772,
"type": "VAST Zone"
}
}
AdButler\VASTChannelZoneAssignment JSON: {
"object": "vast_channel_zone_assignment",
"self": "/v1/vast-channel-zone-assignments/58",
"id": 58,
"vast_channel": 1053,
"vast_zone": {
"id": 85772,
"type": "VAST Zone"
}
}
You can update a specific VAST channel zone assignment by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the VAST channel zone assignment creation request.
Field | Type | Description |
---|---|---|
vast_channel |
integer |
The VAST channel identifier (ID) that you want the zone assigned to. |
vast_zone |
object |
An object containing a VAST zone identifier (ID) and type. |
Returns
Returns a vast_channel_zone_assignment
object if the request succeeded, or an error if something went terribly wrong.
Delete a VAST Channel Zone Assignment
Definition
DELETE https://api.adbutler.com/v1/vast-channel-zone-assignments/{CHANNEL-ZONE-ASSIGNMENT-ID}
\AdButler\VASTChannelZoneAssignment->delete()
adbutler.vastChannelZoneAssignments.delete()
Example Request
curl "https://api.adbutler.com/v1/vast-channel-zone-assignments/58" \
-H "Authorization: Basic {API_KEY}" \
-X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTChannelZoneAssignment = \AdButler\VASTChannelZoneAssignment::retrieve( 58 );
$vASTChannelZoneAssignment->delete();
echo $vASTChannelZoneAssignment;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.vastChannelZoneAssignments.delete(58, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastChannelZoneAssignments.delete(58).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"id": 58,
"delete": true
}
AdButler\VASTChannelZoneAssignment JSON: {
"id": 58,
"delete": true
}
Permanently deletes a VAST channel zone assignment. if successful, this operation cannot be undone so be very sure when deleting one.
Returns
Returns a VAST channel zone assignment ID if the request succeeded, or an error if something went terribly wrong.
List all VAST Channel Zone Assignments
Definition
GET https://api.adbutler.com/v1/vast-channel-zone-assignments
\AdButler\VASTChannelZoneAssignment::retrieveAll()
adbutler.vastChannelZoneAssignments.list()
Example Request
curl "https://api.adbutler.com/v1/vast-channel-zone-assignments?limit=2" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTChannelZoneAssignment = \AdButler\VASTChannelZoneAssignment::retrieveAll(array(
"limit" => 2
));
echo $vASTChannelZoneAssignment;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.vastChannelZoneAssignments.list({
limit: 2
}, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastChannelZoneAssignments.list({
limit: 2
}).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/vast-channel-zone-assignments",
"data": [
{
"object": "vast_channel_zone_assignment",
"self": "/v1/vast-channel-zone-assignments/45",
"id": 45,
"vast_channel": 1042,
"vast_zone": {
"id": 85756,
"type": "VAST Zone"
}
},
{
"object": "vast_channel_zone_assignment",
"self": "/v1/vast-channel-zone-assignments/46",
"id": 46,
"vast_channel": 1043,
"vast_zone": {
"id": 85757,
"type": "VAST Zone"
}
}
]
}
AdButler\VASTChannelZoneAssignment JSON: {
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/vast-channel-zone-assignments",
"data": [
{
"object": "vast_channel_zone_assignment",
"self": "/v1/vast-channel-zone-assignments/45",
"id": 45,
"vast_channel": 1042,
"vast_zone": {
"id": 85756,
"type": "VAST Zone"
}
},
{
"object": "vast_channel_zone_assignment",
"self": "/v1/vast-channel-zone-assignments/46",
"id": 46,
"vast_channel": 1043,
"vast_zone": {
"id": 85757,
"type": "VAST Zone"
}
}
]
}
Returns a list of all the VAST channel zone assignments. Most recent VAST channel zone assignments appear first in the list.
Returns
Returns an object with a data
property that contains a list of up to the specified limit and/or offset of objects. Each entry in data
is a vast_channel_zone_assignment
object, and if no objects were found the list will be empty.
VAST Companions
Introduction
A VAST companion is a display banner that will be rendered in a container that is connected to the video player, usually close by. A VAST companion is part of a VAST banner just like a linear or non-linear ad and is usually related to the content of the main creative.
The vast_companion
response object has the following fields.
Example Response
{
"object": "vast_companion",
"self": "/v1/vast_companions/1416",
"id": 1416,
"banner": 2579,
"resource_type": "static",
"type": "image/png",
"width": 100,
"height": 100,
"asset_width": 0,
"asset_height": 0,
"scalable": false,
"expanded_width": 0,
"expanded_height": 0,
"api_framework": null,
"content": null,
"alt_text": null,
"dom_element_id": null,
"sequence": "1",
"creative": 0,
"location": null,
"encode_parameters": "none",
"ad_parameters": null
}
AdButler\VASTCompanion JSON: {
"object": "vast_companion",
"self": "/v1/vast_companions/1416",
"id": 1416,
"banner": 2579,
"resource_type": "static",
"type": "image/png",
"width": 100,
"height": 100,
"asset_width": 0,
"asset_height": 0,
"scalable": false,
"expanded_width": 0,
"expanded_height": 0,
"api_framework": null,
"content": null,
"alt_text": null,
"dom_element_id": null,
"sequence": 1,
"creative": 0,
"location": null,
"encode_parameters": "none",
"ad_parameters": null
}
Field | Type | Description |
---|---|---|
object |
string |
A string denoting the object type which is always |
self |
string |
The relative URL of the current resource which is always of the form |
id |
integer |
The resource identifier (ID). |
banner |
integer |
The ID of the VAST banner, for which this is a companion. |
resource_type |
string |
The type of resource. One of : |
type |
string |
MIME type of the resource. |
width |
integer |
The width, in pixels, of the ad slot for which the companion ad is intended. |
height |
integer |
The height, in pixels, of the ad slot for which the companion ad is intended. |
asset_width |
integer |
The width, in pixels, of the creative. |
asset_height |
integer |
The height, in pixels, of the creative. |
scalable |
boolean |
Whether the companion is scalable. |
expanded_width |
integer |
The maximum pixel width of the creative in its expanded state. |
expanded_height |
integer |
The maximum pixel height of the creative in its expanded state. |
api_framework |
string |
The API necessary to communicate with the creative, if available. |
content |
string |
If |
alt_text |
string |
Alt text of the resource. |
dom_element_id |
string |
The HTML DOM element ID where the creative will be served. |
sequence |
integer |
The sequence number of the companion. An integer between 1 and 5. |
creative |
integer |
The image creative identifier (ID). |
location |
string |
A URL indicating where you want the user to go when they click on the banner. This field can be left blank. |
ad_parameters |
string |
Custom parameters for executable media or API frameworks. |
encode_parameters |
integer |
How the |
Create a VAST Companion
Definition
POST https://api.adbutler.com/v1/vast-companions
\AdButler\VASTCompanion::create()
adbutler.vastCompanions.create()
Example Request
curl "https://api.adbutler.com/v1/vast-companions" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"resource_type": "static",
"type": "image/png",
"width": 100,
"height": 100,
"sequence": "1"
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTCompanion = \AdButler\VASTCompanion::create(array(
"resource_type" => "static",
"type" => "image/png",
"width" => 100,
"height" => 100,
"sequence" => "1"
));
echo $vASTCompanion;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var postData = {
"resource_type": "static",
"type": "image/png",
"width": 100,
"height": 100,
"sequence": "1"
};
// using callbacks
adbutler.vastCompanions.create(postData, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastCompanions.create(postData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "vast_companion",
"self": "/v1/vast_companions/1416",
"id": 1416,
"banner": 2579,
"resource_type": "static",
"type": "image/png",
"width": 100,
"height": 100,
"asset_width": 0,
"asset_height": 0,
"scalable": false,
"expanded_width": 0,
"expanded_height": 0,
"api_framework": null,
"content": null,
"alt_text": null,
"dom_element_id": null,
"sequence": "1",
"creative": 0,
"location": null,
"encode_parameters": "none",
"ad_parameters": null
}
AdButler\VASTCompanion JSON: {
"object": "vast_companion",
"self": "/v1/vast_companions/1416",
"id": 1416,
"banner": 2579,
"resource_type": "static",
"type": "image/png",
"width": 100,
"height": 100,
"asset_width": 0,
"asset_height": 0,
"scalable": false,
"expanded_width": 0,
"expanded_height": 0,
"api_framework": null,
"content": null,
"alt_text": null,
"dom_element_id": null,
"sequence": 1,
"creative": 0,
"location": null,
"encode_parameters": "none",
"ad_parameters": null
}
Creates a new VAST Companion.
Field | Type | Description |
---|---|---|
banner* |
integer |
The ID of the VAST banner, for which this is a companion. |
resource_type* |
string |
The type of resource. One of : |
type* |
string |
MIME type of the resource. |
width* |
integer |
The width, in pixels, of the ad slot for which the companion ad is intended. |
height* |
integer |
The height, in pixels, of the ad slot for which the companion ad is intended. |
sequence* |
integer |
The sequence number of the companion. An integer between 1 and 5. |
scalable |
integer |
The height, in pixels, of the ad slot for which the companion ad is intended. |
expanded_width |
integer |
The maximum pixel width of the creative in its expanded state. |
expanded_height |
integer |
The maximum pixel height of the creative in its expanded state. |
api_framework |
string |
The API necessary to communicate with the creative, if available. |
content |
string |
If |
alt_text |
string |
Alt text of the resource. |
dom_element_id |
string |
The HTML DOM element ID where the creative will be served. |
creative |
integer |
The image creative identifier (ID). |
location |
string |
A URL indicating where you want the user to go when they click on the banner. This field can be left blank. |
ad_parameters |
string |
Custom parameters for executable media or API frameworks. |
encode_parameters |
integer |
How the |
* = required field
Returns
Returns a vast_companion
object if the request succeeded, or an error if something went terribly wrong.
Retrieve a VAST Companion
Definition
GET https://api.adbutler.com/v1/vast-companions/{COMPANION-ID}
\AdButler\VASTCompanion::retrieve()
adbutler.vastCompanions.retrieve()
Example Request
curl "https://api.adbutler.com/v1/vast-companions/1416" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTCompanion = \AdButler\VASTCompanion::retrieve( 1416 );
echo $vASTCompanion;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.vastCompanions.read(1416, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastCompanions.read(1416).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "vast_companion",
"self": "/v1/vast_companions/1416",
"id": 1416,
"banner": 2579,
"resource_type": "static",
"type": "image/png",
"width": 100,
"height": 100,
"asset_width": 0,
"asset_height": 0,
"scalable": false,
"expanded_width": 0,
"expanded_height": 0,
"api_framework": null,
"content": null,
"alt_text": null,
"dom_element_id": null,
"sequence": "1",
"creative": 0,
"location": null,
"encode_parameters": "none",
"ad_parameters": null
}
AdButler\VASTCompanion JSON: {
"object": "vast_companion",
"self": "/v1/vast_companions/1416",
"id": 1416,
"banner": 2579,
"resource_type": "static",
"type": "image/png",
"width": 100,
"height": 100,
"asset_width": 0,
"asset_height": 0,
"scalable": false,
"expanded_width": 0,
"expanded_height": 0,
"api_framework": null,
"content": null,
"alt_text": null,
"dom_element_id": null,
"sequence": 1,
"creative": 0,
"location": null,
"encode_parameters": "none",
"ad_parameters": null
}
You can retrieve the information about an existing VAST companion by giving the companion ID that was returned in the VAST companion object upon creation. You will see at the most 10 VAST companions in the response. You can change this default limit by appending ?limit=25
if you want this request to return 25 VAST companions.
Returns
Returns a vast_companion
object if the request succeeded, or an error if something went terribly wrong.
Update a VAST Companion
Definition
PUT https://api.adbutler.com/v1/vast-companions/{COMPANION-ID}
\AdButler\VASTCompanion->save()
adbutler.vastCompanions.update()
Example Request
curl "https://api.adbutler.com/v1/vast-companions/1416" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
"resource_type": "static",
"type": "image/png",
"width": 100,
"height": 100,
"sequence": "1"
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTCompanion = \AdButler\VASTCompanion::retrieve( 1416 );
$vASTCompanion->resource_type = "static";
$vASTCompanion->type = "image/png";
$vASTCompanion->width = 100;
$vASTCompanion->height = 100;
$vASTCompanion->sequence = "1";
$vASTCompanion->save();
echo $vASTCompanion;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var updateData = {
"resource_type": "static",
"type": "image/png",
"width": 100,
"height": 100,
"sequence": "1"
};
// using callbacks
adbutler.vastCompanions.update(1416, updateData, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastCompanions.update(1416, updateData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "vast_companion",
"self": "/v1/vast_companions/1416",
"id": 1416,
"banner": 2579,
"resource_type": "static",
"type": "image/png",
"width": 100,
"height": 100,
"asset_width": 0,
"asset_height": 0,
"scalable": false,
"expanded_width": 0,
"expanded_height": 0,
"api_framework": null,
"content": null,
"alt_text": null,
"dom_element_id": null,
"sequence": "1",
"creative": 0,
"location": null,
"encode_parameters": "none",
"ad_parameters": null
}
AdButler\VASTCompanion JSON: {
"object": "vast_companion",
"self": "/v1/vast_companions/1416",
"id": 1416,
"banner": 2579,
"resource_type": "static",
"type": "image/png",
"width": 100,
"height": 100,
"asset_width": 0,
"asset_height": 0,
"scalable": false,
"expanded_width": 0,
"expanded_height": 0,
"api_framework": null,
"content": null,
"alt_text": null,
"dom_element_id": null,
"sequence": 1,
"creative": 0,
"location": null,
"encode_parameters": "none",
"ad_parameters": null
}
You can update a specific VAST companion by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the VAST companion creation request.
Field | Type | Description |
---|---|---|
banner |
integer |
The ID of the VAST banner, for which this is a companion. |
resource_type |
string |
The type of resource. One of : |
type |
string |
MIME type of the resource. |
width |
integer |
The width, in pixels, of the ad slot for which the companion ad is intended. |
height |
integer |
The height, in pixels, of the ad slot for which the companion ad is intended. |
sequence |
integer |
The sequence number of the companion. An integer between 1 and 5. |
scalable |
integer |
The height, in pixels, of the ad slot for which the companion ad is intended. |
expanded_width |
integer |
The maximum pixel width of the creative in its expanded state. |
expanded_height |
integer |
The maximum pixel height of the creative in its expanded state. |
api_framework |
string |
The API necessary to communicate with the creative, if available. |
content |
string |
If |
alt_text |
string |
Alt text of the resource. |
dom_element_id |
string |
The HTML DOM element ID where the creative will be served. |
creative |
integer |
The image creative identifier (ID). |
location |
string |
A URL indicating where you want the user to go when they click on the banner. This field can be left blank. |
ad_parameters |
string |
Custom parameters for executable media or API frameworks. |
encode_parameters |
integer |
How the |
Returns
Returns a vast_companion
object if the request succeeded, or an error if something went terribly wrong.
Delete a VAST Companion
Definition
DELETE https://api.adbutler.com/v1/vast-companions/{COMPANION-ID}
\AdButler\VASTCompanion->delete()
adbutler.vastCompanions.delete()
Example Request
curl "https://api.adbutler.com/v1/vast-companions/1416" \
-H "Authorization: Basic {API_KEY}" \
-X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTCompanion = \AdButler\VASTCompanion::retrieve( 1416 );
$vASTCompanion->delete();
echo $vASTCompanion;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.vastCompanions.delete(1416, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastCompanions.delete(1416).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"id": 1416,
"delete": true
}
AdButler\VASTCompanion JSON: {
"id": 1416,
"delete": true
}
Permanently deletes a VAST companion. if successful, this operation cannot be undone so be very sure when deleting one.
Returns
Returns a VAST companion ID if the request succeeded, or an error if something went terribly wrong.
List all VAST Companions
Definition
GET https://api.adbutler.com/v1/vast-companions
\AdButler\VASTCompanion::retrieveAll()
adbutler.vastCompanions.list()
Example Request
curl "https://api.adbutler.com/v1/vast-companions?limit=2" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTCompanion = \AdButler\VASTCompanion::retrieveAll(array(
"limit" => 2
));
echo $vASTCompanion;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.vastCompanions.list({
limit: 2
}, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastCompanions.list({
limit: 2
}).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/vast-companions",
"data": [
{
"object": "vast_companion",
"self": "/v1/vast_companions/1402",
"id": 1402,
"banner": 2553,
"resource_type": "static",
"type": "image/png",
"width": 100,
"height": 100,
"asset_width": 0,
"asset_height": 0,
"scalable": false,
"expanded_width": 0,
"expanded_height": 0,
"api_framework": null,
"content": null,
"alt_text": null,
"dom_element_id": null,
"sequence": "1",
"creative": 0,
"location": null,
"encode_parameters": "none",
"ad_parameters": null
},
{
"object": "vast_companion",
"self": "/v1/vast_companions/1403",
"id": 1403,
"banner": 2554,
"resource_type": "static",
"type": "image/png",
"width": 100,
"height": 100,
"asset_width": 0,
"asset_height": 0,
"scalable": false,
"expanded_width": 0,
"expanded_height": 0,
"api_framework": null,
"content": null,
"alt_text": null,
"dom_element_id": null,
"sequence": "1",
"creative": 0,
"location": null,
"encode_parameters": "none",
"ad_parameters": null
}
]
}
AdButler\VASTCompanion JSON: {
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/vast-companions",
"data": [
{
"object": "vast_companion",
"self": "/v1/vast_companions/1402",
"id": 1402,
"banner": 2553,
"resource_type": "static",
"type": "image/png",
"width": 100,
"height": 100,
"asset_width": 0,
"asset_height": 0,
"scalable": false,
"expanded_width": 0,
"expanded_height": 0,
"api_framework": null,
"content": null,
"alt_text": null,
"dom_element_id": null,
"sequence": 1,
"creative": 0,
"location": null,
"encode_parameters": "none",
"ad_parameters": null
},
{
"object": "vast_companion",
"self": "/v1/vast_companions/1403",
"id": 1403,
"banner": 2554,
"resource_type": "static",
"type": "image/png",
"width": 100,
"height": 100,
"asset_width": 0,
"asset_height": 0,
"scalable": false,
"expanded_width": 0,
"expanded_height": 0,
"api_framework": null,
"content": null,
"alt_text": null,
"dom_element_id": null,
"sequence": 1,
"creative": 0,
"location": null,
"encode_parameters": "none",
"ad_parameters": null
}
]
}
Returns a list of all the VAST companions. Most recent VAST companions appear first in the list.
Returns
Returns an object with a data
property that contains a list of up to the specified limit and/or offset of objects. Each entry in data
is a vast_companion
object, and if no objects were found the list will be empty.
VAST Media
List all VAST Media
Definition
GET https://api.adbutler.com/v1/vast-medias
\AdButler\VASTMedia::retrieveAll()
adbutler.vastMedia.list()
Example Request
curl "https://api.adbutler.com/v1/vast-media?limit=2" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTMedia = \AdButler\VASTMedia::retrieveAll(array(
"limit" => 2
));
echo $vASTMedia;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.vastMedia.list({
limit: 2
}, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastMedia.list({
limit: 2
}).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/vast-media",
"data": [
{
"object": "vast_media_non_linear",
"self": "/v1/vast-media/non-linear/5964",
"id": 5964,
"banner": 2554,
"type": null,
"maintain_aspect_ratio": false,
"is_linear": false,
"creative": {
"type": "image_url",
"source": null
},
"scalable": false,
"expanded_width": 0,
"expanded_height": 0,
"ad_parameters": null,
"min_suggested_duration": 0,
"width": 100,
"height": 100,
"encode_parameters": "none"
},
{
"object": "vast_media_linear",
"self": "/v1/vast-media/linear/5963",
"id": 5963,
"banner": 2554,
"maintain_aspect_ratio": false,
"is_linear": true,
"creative": 0,
"scalable": false,
"delivery": "progressive",
"codec": null,
"api_framework": null,
"min_bitrate": 0,
"max_bitrate": 0,
"creative_url": null,
"width": 100,
"height": 100,
"type": null
}
]
}
AdButler\VASTMedia JSON: {
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/vast-media",
"data": [
{
"object": "vast_media_non_linear",
"self": "/v1/vast-media/non-linear/5964",
"id": 5964,
"banner": 2554,
"type": null,
"maintain_aspect_ratio": false,
"is_linear": false,
"creative": {
"type": "image_url",
"source": null
},
"scalable": false,
"expanded_width": 0,
"expanded_height": 0,
"ad_parameters": null,
"min_suggested_duration": 0,
"width": 100,
"height": 100,
"encode_parameters": "none"
},
{
"object": "vast_media_linear",
"self": "/v1/vast-media/linear/5963",
"id": 5963,
"banner": 2554,
"maintain_aspect_ratio": false,
"is_linear": true,
"creative": 0,
"scalable": false,
"delivery": "progressive",
"codec": null,
"api_framework": null,
"min_bitrate": 0,
"max_bitrate": 0,
"creative_url": null,
"width": 100,
"height": 100,
"type": null
}
]
}
Returns a list of all the VAST medias. Most recent VAST medias appear first in the list.
Returns
Returns an object with a data
property that contains a list of up to the specified limit and/or offset of objects. Each entry in data
is a vast-media
object, and if no objects were found the list will be empty.
VAST Media Linear
Introduction
The VAST Linear Media object is a reference to a linear creative that will be served in a VAST Banner. A linear creative is one that is video-based and plays pre-roll, mid-roll or post-roll in relation to the video content.
The vast_media_linear
response object has the following fields.
Example Response
{
"object": "vast_media_linear",
"self": "/v1/vast-media/linear/6015",
"id": 6015,
"banner": 2579,
"maintain_aspect_ratio": false,
"creative": 0,
"scalable": false,
"delivery": "progressive",
"codec": null,
"api_framework": null,
"min_bitrate": 0,
"max_bitrate": 0,
"creative_url": null,
"width": 100,
"height": 100,
"type": null
}
AdButler\VASTMediaLinear JSON: {
"object": "vast_media_linear",
"self": "/v1/vast-media/linear/6015",
"id": 6015,
"banner": 2579,
"maintain_aspect_ratio": false,
"creative": 0,
"scalable": false,
"delivery": "progressive",
"codec": null,
"api_framework": null,
"min_bitrate": 0,
"max_bitrate": 0,
"creative_url": null,
"width": 100,
"height": 100,
"type": null
}
Field | Type | Description |
---|---|---|
object |
string |
A string denoting the object type which is always |
self |
string |
The relative URL of the current resource which is always of the form |
id |
integer |
The resource identifier (ID). |
banner |
string |
The ID of the VAST banner that this object belongs to. |
type |
string |
MIME type of the resource. |
delivery |
string |
The method that the media is delivered. One of: |
width |
integer |
Width of the media. |
height |
integer |
Height of the media. |
scalable |
boolean |
Whether the video file can scale to a larger size. |
maintain_aspect_ratio |
boolean |
Whether the video file will be forced to maintain it's native aspect ratio when scaled. |
creative |
integer |
The video creative identifier (ID). |
creative_url |
string |
The URL of a video file. |
codec |
string |
The codec used to encode the file, as specific by RFC 4281. |
min_bitrate |
integer |
The minimum bitrate for the file. |
max_bitrate |
integer |
The maximum bitrate for the file. |
api_framework |
string |
The API necessary to communicate with the creative, if available. |
Create a VAST Linear Media
Definition
POST https://api.adbutler.com/v1/vast-media-linear
\AdButler\VASTMediaLinear::create()
adbutler.vastMedia.linear.create()
Example Request
curl "https://api.adbutler.com/v1/vast-media/linear" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"delivery": "progressive",
"width": 100,
"height": 100
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTMediaLinear = \AdButler\VASTMediaLinear::create(array(
"delivery" => "progressive",
"width" => 100,
"height" => 100
));
echo $vASTMediaLinear;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var postData = {
"delivery": "progressive",
"width": 100,
"height": 100
};
// using callbacks
adbutler.vastMedia.linear.create(postData, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastMedia.linear.create(postData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "vast_media_linear",
"self": "/v1/vast-media/linear/6015",
"id": 6015,
"banner": 2579,
"maintain_aspect_ratio": false,
"creative": 0,
"scalable": false,
"delivery": "progressive",
"codec": null,
"api_framework": null,
"min_bitrate": 0,
"max_bitrate": 0,
"creative_url": null,
"width": 100,
"height": 100,
"type": null
}
AdButler\VASTMediaLinear JSON: {
"object": "vast_media_linear",
"self": "/v1/vast-media/linear/6015",
"id": 6015,
"banner": 2579,
"maintain_aspect_ratio": false,
"creative": 0,
"scalable": false,
"delivery": "progressive",
"codec": null,
"api_framework": null,
"min_bitrate": 0,
"max_bitrate": 0,
"creative_url": null,
"width": 100,
"height": 100,
"type": null
}
Creates a new VAST Linear Media.
Field | Type | Description |
---|---|---|
banner* |
string |
The ID of the VAST banner that this object belongs to. |
type |
string |
MIME type of the resource. Required if |
delivery* |
string |
The method that the media is delivered. One of: |
width |
integer |
Width of the media. Required if |
height |
integer |
Height of the media. Required if |
scalable |
boolean |
Whether the video file can scale to a larger size. |
maintain_aspect_ratio |
boolean |
Whether the video file will be forced to maintain it's native aspect ratio when scaled. |
creative |
integer |
The video creative identifier (ID). Must be a valid ID if no |
creative_url |
string |
The URL of a video file. |
codec |
string |
The codec used to encode the file, as specific by RFC 4281. |
min_bitrate |
integer |
The minimum bitrate for the file. Only include this field if |
max_bitrate |
integer |
The maximum bitrate for the file. Only include this field if |
api_framework |
string |
The API necessary to communicate with the creative, if available. |
* = required field
Returns
Returns a vast-media-linear
object if the request succeeded, or an error if something went terribly wrong.
Retrieve a VAST Linear Media
Definition
GET https://api.adbutler.com/v1/vast-media-linear/{MEDIA-ID}
\AdButler\VASTMediaLinear::retrieve()
adbutler.vastMedia.linear.retrieve()
Example Request
curl "https://api.adbutler.com/v1/vast-media/linear/6015" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTMediaLinear = \AdButler\VASTMediaLinear::retrieve( 6015 );
echo $vASTMediaLinear;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.vastMedia.linear.read(6015, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastMedia.linear.read(6015).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "vast_media_linear",
"self": "/v1/vast-media/linear/6015",
"id": 6015,
"banner": 2579,
"maintain_aspect_ratio": false,
"creative": 0,
"scalable": false,
"delivery": "progressive",
"codec": null,
"api_framework": null,
"min_bitrate": 0,
"max_bitrate": 0,
"creative_url": null,
"width": 100,
"height": 100,
"type": null
}
AdButler\VASTMediaLinear JSON: {
"object": "vast_media_linear",
"self": "/v1/vast-media/linear/6015",
"id": 6015,
"banner": 2579,
"maintain_aspect_ratio": false,
"creative": 0,
"scalable": false,
"delivery": "progressive",
"codec": null,
"api_framework": null,
"min_bitrate": 0,
"max_bitrate": 0,
"creative_url": null,
"width": 100,
"height": 100,
"type": null
}
You can retrieve the information about an existing VAST media by giving the media ID that was returned in the VAST media object upon creation. You will see at the most 10 VAST medias in the response. You can change this default limit by appending ?limit=25
if you want this request to return 25 VAST linear media.
Returns
Returns a vast-media-linear
object if the request succeeded, or an error if something went terribly wrong.
Update a VAST Linear Media
Definition
PUT https://api.adbutler.com/v1/vast-media-linear/{MEDIA-ID}
\AdButler\VASTMediaLinear->save()
adbutler.vastMedia.linear.update()
Example Request
curl "https://api.adbutler.com/v1/vast-media/linear/6015" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
"delivery": "progressive",
"width": 100,
"height": 100
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTMediaLinear = \AdButler\VASTMediaLinear::retrieve( 6015 );
$vASTMediaLinear->delivery = "progressive";
$vASTMediaLinear->width = 100;
$vASTMediaLinear->height = 100;
$vASTMediaLinear->save();
echo $vASTMediaLinear;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var updateData = {
"delivery": "progressive",
"width": 100,
"height": 100
};
// using callbacks
adbutler.vastMedia.linear.update(6015, updateData, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastMedia.linear.update(6015, updateData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "vast_media_linear",
"self": "/v1/vast-media/linear/6015",
"id": 6015,
"banner": 2579,
"maintain_aspect_ratio": false,
"creative": 0,
"scalable": false,
"delivery": "progressive",
"codec": null,
"api_framework": null,
"min_bitrate": 0,
"max_bitrate": 0,
"creative_url": null,
"width": 100,
"height": 100,
"type": null
}
AdButler\VASTMediaLinear JSON: {
"object": "vast_media_linear",
"self": "/v1/vast-media/linear/6015",
"id": 6015,
"banner": 2579,
"maintain_aspect_ratio": false,
"creative": 0,
"scalable": false,
"delivery": "progressive",
"codec": null,
"api_framework": null,
"min_bitrate": 0,
"max_bitrate": 0,
"creative_url": null,
"width": 100,
"height": 100,
"type": null
}
You can update a specific VAST linear media by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the VAST media creation request.
Field | Type | Description |
---|---|---|
banner |
string |
The ID of the VAST banner that this object belongs to. |
type |
string |
MIME type of the resource. Required if |
delivery |
string |
The method that the media is delivered. One of: |
width |
integer |
Width of the media. Required if |
height |
integer |
Height of the media. Required if |
scalable |
boolean |
Whether the video file can scale to a larger size. |
maintain_aspect_ratio |
boolean |
Whether the video file will be forced to maintain it's native aspect ratio when scaled. |
creative |
integer |
The video creative identifier (ID). Must be a valid ID if no |
creative_url |
string |
The URL of a video file. |
codec |
string |
The codec used to encode the file, as specific by RFC 4281. |
min_bitrate |
integer |
The minimum bitrate for the file. Only include this field if |
max_bitrate |
integer |
The maximum bitrate for the file. Only include this field if |
api_framework |
string |
The API necessary to communicate with the creative, if available. |
† To change a vast_media_linear
object from using a library creative to an external one (or vice-versa), you'll need set the old value to null
.
Returns
Returns a vast-media-linear
object if the request succeeded, or an error if something went terribly wrong.
Delete a VAST Linear Media
Definition
DELETE https://api.adbutler.com/v1/vast-media-linear/{MEDIA-ID}
\AdButler\VASTMediaLinear->delete()
adbutler.vastMedia.linear.delete()
Example Request
curl "https://api.adbutler.com/v1/vast-media/linear/6015" \
-H "Authorization: Basic {API_KEY}" \
-X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTMediaLinear = \AdButler\VASTMediaLinear::retrieve( 6015 );
$vASTMediaLinear->delete();
echo $vASTMediaLinear;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.vastMedia.linear.delete(6015, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastMedia.linear.delete(6015).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"id": 6015,
"delete": true
}
AdButler\VASTMediaLinear JSON: {
"id": 6015,
"delete": true
}
Permanently deletes a VAST linear media. if successful, this operation cannot be undone so be very sure when deleting one.
Returns
Returns a VAST media ID if the request succeeded, or an error if something went terribly wrong.
List all VAST Linear Media
Definition
GET https://api.adbutler.com/v1/vast-media-linear
\AdButler\VASTMediaLinear::retrieveAll()
adbutler.vastMedia.linear.list()
Example Request
curl "https://api.adbutler.com/v1/vast-media/linear?limit=2" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTMediaLinear = \AdButler\VASTMediaLinear::retrieveAll(array(
"limit" => 2
));
echo $vASTMediaLinear;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.vastMedia.linear.list({
limit: 2
}, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastMedia.linear.list({
limit: 2
}).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/vast-media/linear",
"data": [
{
"object": "vast_media_linear",
"self": "/v1/vast-media/linear/5963",
"id": 5963,
"banner": 2554,
"maintain_aspect_ratio": false,
"creative": 0,
"scalable": false,
"delivery": "progressive",
"codec": null,
"api_framework": null,
"min_bitrate": 0,
"max_bitrate": 0,
"creative_url": null,
"width": 100,
"height": 100,
"type": null
},
{
"object": "vast_media_linear",
"self": "/v1/vast-media/linear/5961",
"id": 5961,
"banner": 2553,
"maintain_aspect_ratio": false,
"creative": 0,
"scalable": false,
"delivery": "progressive",
"codec": null,
"api_framework": null,
"min_bitrate": 0,
"max_bitrate": 0,
"creative_url": null,
"width": 100,
"height": 100,
"type": null
}
]
}
AdButler\VASTMediaLinear JSON: {
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/vast-media/linear",
"data": [
{
"object": "vast_media_linear",
"self": "/v1/vast-media/linear/5963",
"id": 5963,
"banner": 2554,
"maintain_aspect_ratio": false,
"creative": 0,
"scalable": false,
"delivery": "progressive",
"codec": null,
"api_framework": null,
"min_bitrate": 0,
"max_bitrate": 0,
"creative_url": null,
"width": 100,
"height": 100,
"type": null
},
{
"object": "vast_media_linear",
"self": "/v1/vast-media/linear/5961",
"id": 5961,
"banner": 2553,
"maintain_aspect_ratio": false,
"creative": 0,
"scalable": false,
"delivery": "progressive",
"codec": null,
"api_framework": null,
"min_bitrate": 0,
"max_bitrate": 0,
"creative_url": null,
"width": 100,
"height": 100,
"type": null
}
]
}
Returns a list of all the VAST linear medias. Most recent VAST medias appear first in the list.
Returns
Returns an object with a data
property that contains a list of up to the specified limit and/or offset of objects. Each entry in data
is a vast-media
object, and if no objects were found the list will be empty.
VAST Media Non-Linear
Introduction
The VAST Linear Media object is a reference to a linear creative that will be served in a VAST Banner. A linear creative is one that is video-based and plays pre-roll, mid-roll or post-roll in relation to the video content.
The vast_media_non_linear
response object has the following fields.
Example Response
{
"object": "vast_media_non_linear",
"self": "/v1/vast-media/non-linear/6016",
"id": 6016,
"banner": 2579,
"type": "image/png",
"maintain_aspect_ratio": false,
"creative": {
"type": "image_url",
"source": "https://admin.adbutler.com/assets/icons/adbutler_logo_inapp@2x.png"
},
"scalable": false,
"expanded_width": 0,
"expanded_height": 0,
"ad_parameters": null,
"min_suggested_duration": 0,
"width": 325,
"height": 100,
"encode_parameters": "none"
}
AdButler\VASTMediaNonLinear JSON: {
"object": "vast_media_non_linear",
"self": "/v1/vast-media/non-linear/6016",
"id": 6016,
"banner": 2579,
"type": "image/png",
"maintain_aspect_ratio": false,
"creative": {
"type": "image_url",
"source": "https://admin.adbutler.com/assets/icons/adbutler_logo_inapp@2x.png"
},
"scalable": false,
"expanded_width": 0,
"expanded_height": 0,
"ad_parameters": null,
"min_suggested_duration": 0,
"width": 325,
"height": 100,
"encode_parameters": "none"
}
Field | Type | Description |
---|---|---|
object |
string |
A string denoting the object type which is always |
self |
string |
The relative URL of the current resource which is always of the form |
id |
integer |
The resource identifier (ID). |
banner |
string |
The ID of the VAST banner that this object belongs to. |
creative |
object |
An object that describes the type of creative this object will contain. It contains the |
type |
string |
Describes the type of creative. If it is an image, this will be the MIME type or image format. |
width |
integer |
Width of the media. |
height |
integer |
Height of the media. |
expanded_width |
integer |
The width of the media if it is scaled up. |
expanded_height |
integer |
The height of the media if it is scaled up. |
scalable |
boolean |
Whether the video file can scale to a larger size. |
maintain_aspect_ratio |
boolean |
Whether the video file will be forced to maintain it's native aspect ratio when scaled. |
min_suggested_duration |
integer |
The minimum amount of time, in seconds, that this media file should be displayed in the player. |
ad_parameters |
string |
Any custom parameters for executable media or API frameworks that might be required by the creative. |
encode_parameters |
string |
Specifies whether the entities in |
Create a VAST Non-Linear Media
Definition
POST https://api.adbutler.com/v1/vast-media-non-linear
\AdButler\VASTMediaNonLinear::create()
adbutler.vastMedia.nonLinear.create()
Example Request
curl "https://api.adbutler.com/v1/vast-media/non-linear" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"width": 325,
"height": 100
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTMediaNonLinear = \AdButler\VASTMediaNonLinear::create(array(
"width" => 325,
"height" => 100
));
echo $vASTMediaNonLinear;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var postData = {
"width": 325,
"height": 100
};
// using callbacks
adbutler.vastMedia.nonLinear.create(postData, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastMedia.nonLinear.create(postData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "vast_media_non_linear",
"self": "/v1/vast-media/non-linear/6016",
"id": 6016,
"banner": 2579,
"type": "image/png",
"maintain_aspect_ratio": false,
"creative": {
"type": "image_url",
"source": "https://admin.adbutler.com/assets/icons/adbutler_logo_inapp@2x.png"
},
"scalable": false,
"expanded_width": 0,
"expanded_height": 0,
"ad_parameters": null,
"min_suggested_duration": 0,
"width": 325,
"height": 100,
"encode_parameters": "none"
}
AdButler\VASTMediaNonLinear JSON: {
"object": "vast_media_non_linear",
"self": "/v1/vast-media/non-linear/6016",
"id": 6016,
"banner": 2579,
"type": "image/png",
"maintain_aspect_ratio": false,
"creative": {
"type": "image_url",
"source": "https://admin.adbutler.com/assets/icons/adbutler_logo_inapp@2x.png"
},
"scalable": false,
"expanded_width": 0,
"expanded_height": 0,
"ad_parameters": null,
"min_suggested_duration": 0,
"width": 325,
"height": 100,
"encode_parameters": "none"
}
Creates a new VAST Non-Linear Media.
Field | Type | Description |
---|---|---|
banner* |
string |
The ID of the VAST banner that this object belongs to. |
creative* |
object |
An object that describes the type of creative this object will contain. It contains the |
width |
integer |
Width of the media. This field is required if the creative type is anything other than |
height |
integer |
Height of the media. This field is required if the creative type is anything other than |
expanded_width |
integer |
The width of the media if it is scaled up. |
expanded_height |
integer |
The height of the media if it is scaled up. |
scalable |
boolean |
Whether the video file can scale to a larger size. |
maintain_aspect_ratio |
boolean |
Whether the video file will be forced to maintain it's native aspect ratio when scaled. |
min_suggested_duration |
integer |
The minimum amount of time, in seconds, that this media file should be displayed in the player. |
ad_parameters |
string |
Any custom parameters for executable media or API frameworks that might be required by the creative. |
encode_parameters |
string |
Specifies whether the entities in |
* = required field
Returns
Returns a vast-media-non-linear
object if the request succeeded, or an error if something went terribly wrong.
Retrieve a VAST Non-Linear Media
Definition
GET https://api.adbutler.com/v1/vast-media-non-linear/{MEDIA-ID}
\AdButler\VASTMediaNonLinear::retrieve()
adbutler.vastMedia.nonLinear.retrieve()
Example Request
curl "https://api.adbutler.com/v1/vast-media/non-linear/6016" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTMediaNonLinear = \AdButler\VASTMediaNonLinear::retrieve( 6016 );
echo $vASTMediaNonLinear;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.vastMedia.nonLinear.read(6016, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastMedia.nonLinear.read(6016).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "vast_media_non_linear",
"self": "/v1/vast-media/non-linear/6016",
"id": 6016,
"banner": 2579,
"type": "image/png",
"maintain_aspect_ratio": false,
"creative": {
"type": "image_url",
"source": "https://admin.adbutler.com/assets/icons/adbutler_logo_inapp@2x.png"
},
"scalable": false,
"expanded_width": 0,
"expanded_height": 0,
"ad_parameters": null,
"min_suggested_duration": 0,
"width": 325,
"height": 100,
"encode_parameters": "none"
}
AdButler\VASTMediaNonLinear JSON: {
"object": "vast_media_non_linear",
"self": "/v1/vast-media/non-linear/6016",
"id": 6016,
"banner": 2579,
"type": "image/png",
"maintain_aspect_ratio": false,
"creative": {
"type": "image_url",
"source": "https://admin.adbutler.com/assets/icons/adbutler_logo_inapp@2x.png"
},
"scalable": false,
"expanded_width": 0,
"expanded_height": 0,
"ad_parameters": null,
"min_suggested_duration": 0,
"width": 325,
"height": 100,
"encode_parameters": "none"
}
You can retrieve the information about an existing VAST media by giving the media ID that was returned in the VAST media object upon creation. You will see at the most 10 VAST medias in the response. You can change this default limit by appending ?limit=25
if you want this request to return 25 VAST linear media.
Returns
Returns a vast-media-non-linear
object if the request succeeded, or an error if something went terribly wrong.
Update a VAST Non-Linear Media
Definition
PUT https://api.adbutler.com/v1/vast-media-non-linear/{MEDIA-ID}
\AdButler\VASTMediaNonLinear->save()
adbutler.vastMedia.nonLinear.update()
Example Request
curl "https://api.adbutler.com/v1/vast-media/non-linear/6016" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
"width": 325,
"height": 100
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTMediaNonLinear = \AdButler\VASTMediaNonLinear::retrieve( 6016 );
$vASTMediaNonLinear->width = 325;
$vASTMediaNonLinear->height = 100;
$vASTMediaNonLinear->save();
echo $vASTMediaNonLinear;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var updateData = {
"width": 325,
"height": 100
};
// using callbacks
adbutler.vastMedia.nonLinear.update(6016, updateData, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastMedia.nonLinear.update(6016, updateData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "vast_media_non_linear",
"self": "/v1/vast-media/non-linear/6016",
"id": 6016,
"banner": 2579,
"type": "image/png",
"maintain_aspect_ratio": false,
"creative": {
"type": "image_url",
"source": "https://admin.adbutler.com/assets/icons/adbutler_logo_inapp@2x.png"
},
"scalable": false,
"expanded_width": 0,
"expanded_height": 0,
"ad_parameters": null,
"min_suggested_duration": 0,
"width": 325,
"height": 100,
"encode_parameters": "none"
}
AdButler\VASTMediaNonLinear JSON: {
"object": "vast_media_non_linear",
"self": "/v1/vast-media/non-linear/6016",
"id": 6016,
"banner": 2579,
"type": "image/png",
"maintain_aspect_ratio": false,
"creative": {
"type": "image_url",
"source": "https://admin.adbutler.com/assets/icons/adbutler_logo_inapp@2x.png"
},
"scalable": false,
"expanded_width": 0,
"expanded_height": 0,
"ad_parameters": null,
"min_suggested_duration": 0,
"width": 325,
"height": 100,
"encode_parameters": "none"
}
You can update a specific VAST non-linear media by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the VAST media creation request.
Field | Type | Description |
---|---|---|
banner |
string |
The ID of the VAST banner that this object belongs to. |
creative |
object |
An object that describes the type of creative this object will contain. It contains the |
width |
integer |
Width of the media. This field is required if the creative type is anything other than |
height |
integer |
Height of the media. This field is required if the creative type is anything other than |
expanded_width |
integer |
The width of the media if it is scaled up. |
expanded_height |
integer |
The height of the media if it is scaled up. |
scalable |
boolean |
Whether the video file can scale to a larger size. |
maintain_aspect_ratio |
boolean |
Whether the video file will be forced to maintain it's native aspect ratio when scaled. |
min_suggested_duration |
integer |
The minimum amount of time, in seconds, that this media file should be displayed in the player. |
ad_parameters |
string |
Any custom parameters for executable media or API frameworks that might be required by the creative. |
encode_parameters |
string |
Specifies whether the entities in |
Returns
Returns a vast-media-non-linear
object if the request succeeded, or an error if something went terribly wrong.
Delete a VAST Non-Linear Media
Definition
DELETE https://api.adbutler.com/v1/vast-media-non-linear/{MEDIA-ID}
\AdButler\VASTMediaNonLinear->delete()
adbutler.vastMedia.nonLinear.delete()
Example Request
curl "https://api.adbutler.com/v1/vast-media/non-linear/6016" \
-H "Authorization: Basic {API_KEY}" \
-X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTMediaNonLinear = \AdButler\VASTMediaNonLinear::retrieve( 6016 );
$vASTMediaNonLinear->delete();
echo $vASTMediaNonLinear;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.vastMedia.nonLinear.delete(6016, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastMedia.nonLinear.delete(6016).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"id": 6016,
"delete": true
}
AdButler\VASTMediaNonLinear JSON: {
"id": 6016,
"delete": true
}
Permanently deletes a VAST non-linear media. if successful, this operation cannot be undone so be very sure when deleting one.
Returns
Returns a VAST media ID if the request succeeded, or an error if something went terribly wrong.
List all VAST Non-Linear Media
Definition
GET https://api.adbutler.com/v1/vast-media-non-linear
\AdButler\VASTMediaNonLinear::retrieveAll()
adbutler.vastMedia.nonLinear.list()
Example Request
curl "https://api.adbutler.com/v1/vast-media/non-linear?limit=2" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTMediaNonLinear = \AdButler\VASTMediaNonLinear::retrieveAll(array(
"limit" => 2
));
echo $vASTMediaNonLinear;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.vastMedia.nonLinear.list({
limit: 2
}, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastMedia.nonLinear.list({
limit: 2
}).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/vast-media/non-linear",
"data": [
{
"object": "vast_media_non_linear",
"self": "/v1/vast-media/non-linear/5964",
"id": 5964,
"banner": 2554,
"type": null,
"maintain_aspect_ratio": false,
"creative": {
"type": "image_url",
"source": null
},
"scalable": false,
"expanded_width": 0,
"expanded_height": 0,
"ad_parameters": null,
"min_suggested_duration": 0,
"width": 100,
"height": 100,
"encode_parameters": "none"
},
{
"object": "vast_media_non_linear",
"self": "/v1/vast-media/non-linear/5962",
"id": 5962,
"banner": 2553,
"type": null,
"maintain_aspect_ratio": false,
"creative": {
"type": "image_url",
"source": null
},
"scalable": false,
"expanded_width": 0,
"expanded_height": 0,
"ad_parameters": null,
"min_suggested_duration": 0,
"width": 100,
"height": 100,
"encode_parameters": "none"
}
]
}
AdButler\VASTMediaNonLinear JSON: {
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/vast-media/non-linear",
"data": [
{
"object": "vast_media_non_linear",
"self": "/v1/vast-media/non-linear/5964",
"id": 5964,
"banner": 2554,
"type": null,
"maintain_aspect_ratio": false,
"creative": {
"type": "image_url",
"source": null
},
"scalable": false,
"expanded_width": 0,
"expanded_height": 0,
"ad_parameters": null,
"min_suggested_duration": 0,
"width": 100,
"height": 100,
"encode_parameters": "none"
},
{
"object": "vast_media_non_linear",
"self": "/v1/vast-media/non-linear/5962",
"id": 5962,
"banner": 2553,
"type": null,
"maintain_aspect_ratio": false,
"creative": {
"type": "image_url",
"source": null
},
"scalable": false,
"expanded_width": 0,
"expanded_height": 0,
"ad_parameters": null,
"min_suggested_duration": 0,
"width": 100,
"height": 100,
"encode_parameters": "none"
}
]
}
Returns a list of all the VAST non-linear medias. Most recent VAST medias appear first in the list.
Returns
Returns an object with a data
property that contains a list of up to the specified limit and/or offset of objects. Each entry in data
is a vast-media
object, and if no objects were found the list will be empty.
VAST Placement
Introduction
A VAST placement represents the relationship between a VAST banner or VAST campaign and a VAST zone or VAST channel. A VAST placement will also have a schedule that outlines its serving behaviour
The vast_placement
response object has the following fields.
Example Response
{
"object": "vast_placement",
"self": "/v1/vast_placements/7698",
"id": 7698,
"zone": 85772,
"channel": 0,
"schedule": 12209,
"advertisement": {
"id": 2579,
"type": "vast_banner"
},
"active": true,
"cpm": 2,
"cpc": 0,
"cpa": 0,
"fixed_cost": 0,
"payout_percent": 0,
"use_channel_priority": true,
"priority": "standard",
"max_frequency": 0,
"max_frequency_period": 0,
"max_frequency_type": "start"
}
AdButler\VASTPlacement JSON: {
"object": "vast_placement",
"self": "/v1/vast_placements/7698",
"id": 7698,
"zone": 85772,
"channel": 0,
"schedule": 12209,
"advertisement": {
"id": 2579,
"type": "vast_banner"
},
"active": true,
"cpm": 2,
"cpc": 0,
"cpa": 0,
"fixed_cost": 0,
"payout_percent": 0,
"use_channel_priority": true,
"priority": "standard",
"max_frequency": 0,
"max_frequency_period": 0,
"max_frequency_type": "start"
}
Field | Type | Description |
---|---|---|
object |
string |
A string denoting the object type which is always |
self |
string |
The relative URL of the current resource which is always of the form |
id |
integer |
The resource identifier (ID). |
advertisement |
object |
An object containing vast_banner or vast_campaign identifier (ID) and type. |
zone |
integer |
If assigned to a zone, this is the VAST zone ID. |
channel |
integer |
If assiged to a channel, this is the VAST channel ID. |
schedule |
integer |
The VAST schedule identifier (ID). |
active |
boolean |
Whether to actively serve ads in the zones ( |
cpm |
decimal |
CPM of the placement. |
cpc |
decimal |
CPC of the placement. |
cpa |
decimal |
CPA of the placement. |
fixed_cost |
decimal |
Fixed cost of the placement. |
payout_percent |
decimal |
The percentage of the ad generated revenue paid out to the publisher. Publisher payout is ideal for profit sharing where the revenue is split between money earned by the advertiser and money earned by the publisher. Defaults to |
use_channel_priority |
boolean |
Whether to use the priority of the channel or set a specific priority. |
priority |
integer |
Priority allows you to prefer serving of some ads over others in a campaign or channel. Possible values in descending order are |
max_frequency |
integer |
A limit to the number of times a user is allowed to trigger a specific event, given by |
max_frequency_period |
integer |
The number of days after which the |
max_frequency_type |
string |
The specific event that will be counted by the frequency capping. One of: |
Create a VAST Placement
Definition
POST https://api.adbutler.com/v1/vast-placements
\AdButler\VASTPlacement::create()
adbutler.vastPlacements.create()
Example Request
curl "https://api.adbutler.com/v1/vast-placements" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X POST \
-d '{
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTPlacement = \AdButler\VASTPlacement::create(array(
));
echo $vASTPlacement;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var postData = {
};
// using callbacks
adbutler.vastPlacements.create(postData, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastPlacements.create(postData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "vast_placement",
"self": "/v1/vast_placements/7698",
"id": 7698,
"zone": 85772,
"channel": 0,
"schedule": 12209,
"advertisement": {
"id": 2579,
"type": "vast_banner"
},
"active": true,
"cpm": 2,
"cpc": 0,
"cpa": 0,
"fixed_cost": 0,
"payout_percent": 0,
"use_channel_priority": true,
"priority": "standard",
"max_frequency": 0,
"max_frequency_period": 0,
"max_frequency_type": "start"
}
AdButler\VASTPlacement JSON: {
"object": "vast_placement",
"self": "/v1/vast_placements/7698",
"id": 7698,
"zone": 85772,
"channel": 0,
"schedule": 12209,
"advertisement": {
"id": 2579,
"type": "vast_banner"
},
"active": true,
"cpm": 2,
"cpc": 0,
"cpa": 0,
"fixed_cost": 0,
"payout_percent": 0,
"use_channel_priority": true,
"priority": "standard",
"max_frequency": 0,
"max_frequency_period": 0,
"max_frequency_type": "start"
}
Creates a new VAST Placement.
Field | Type | Description |
---|---|---|
advertisement* |
object |
An object containing vast_banner or vast_campaign identifier (ID) and type. |
schedule* |
integer |
The VAST schedule identifier (ID). |
zone |
integer |
If assigned to a zone, this is the VAST zone ID. |
channel |
integer |
If assiged to a channel, this is the VAST channel ID. |
active |
boolean |
Whether to actively serve ads in the zones ( |
cpm |
decimal |
CPM of the placement. |
cpc |
decimal |
CPC of the placement. |
cpa |
decimal |
CPA of the placement. |
fixed_cost |
decimal |
Fixed cost of the placement. |
payout_percent |
decimal |
The percentage of the ad generated revenue paid out to the publisher. Publisher payout is ideal for profit sharing where the revenue is split between money earned by the advertiser and money earned by the publisher. Defaults to |
use_channel_priority |
boolean |
Whether to use the priority of the channel or set a specific priority. |
priority |
integer |
Priority allows you to prefer serving of some ads over others in a campaign or channel. Possible values in descending order are |
max_frequency |
integer |
A limit to the number of times a user is allowed to trigger a specific event, given by |
max_frequency_period |
integer |
The number of days after which the |
max_frequency_type |
string |
The specific event that will be counted by the frequency capping. One of: |
* = required field
Returns
Returns a vast_placement
object if the request succeeded, or an error if something went terribly wrong.
Retrieve a VAST Placement
Definition
GET https://api.adbutler.com/v1/vast-placements/{PLACEMENT-ID}
\AdButler\VASTPlacement::retrieve()
adbutler.vastPlacements.retrieve()
Example Request
curl "https://api.adbutler.com/v1/vast-placements/7698" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTPlacement = \AdButler\VASTPlacement::retrieve( 7698 );
echo $vASTPlacement;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.vastPlacements.read(7698, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastPlacements.read(7698).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "vast_placement",
"self": "/v1/vast_placements/7698",
"id": 7698,
"zone": 85772,
"channel": 0,
"schedule": 12209,
"advertisement": {
"id": 2579,
"type": "vast_banner"
},
"active": true,
"cpm": 2,
"cpc": 0,
"cpa": 0,
"fixed_cost": 0,
"payout_percent": 0,
"use_channel_priority": true,
"priority": "standard",
"max_frequency": 0,
"max_frequency_period": 0,
"max_frequency_type": "start"
}
AdButler\VASTPlacement JSON: {
"object": "vast_placement",
"self": "/v1/vast_placements/7698",
"id": 7698,
"zone": 85772,
"channel": 0,
"schedule": 12209,
"advertisement": {
"id": 2579,
"type": "vast_banner"
},
"active": true,
"cpm": 2,
"cpc": 0,
"cpa": 0,
"fixed_cost": 0,
"payout_percent": 0,
"use_channel_priority": true,
"priority": "standard",
"max_frequency": 0,
"max_frequency_period": 0,
"max_frequency_type": "start"
}
You can retrieve the information about an existing VAST placement by giving the placement ID that was returned in the VAST placement object upon creation. You will see at the most 10 VAST placements in the response. You can change this default limit by appending ?limit=25
if you want this request to return 25 VAST placements.
Returns
Returns a vast_placement
object if the request succeeded, or an error if something went terribly wrong.
Update a VAST Placement
Definition
PUT https://api.adbutler.com/v1/vast-placements/{PLACEMENT-ID}
\AdButler\VASTPlacement->save()
adbutler.vastPlacements.update()
Example Request
curl "https://api.adbutler.com/v1/vast-placements/7698" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTPlacement = \AdButler\VASTPlacement::retrieve( 7698 );
$vASTPlacement->save();
echo $vASTPlacement;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var updateData = {
};
// using callbacks
adbutler.vastPlacements.update(7698, updateData, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastPlacements.update(7698, updateData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "vast_placement",
"self": "/v1/vast_placements/7698",
"id": 7698,
"zone": 85772,
"channel": 0,
"schedule": 12209,
"advertisement": {
"id": 2579,
"type": "vast_banner"
},
"active": true,
"cpm": 2,
"cpc": 0,
"cpa": 0,
"fixed_cost": 0,
"payout_percent": 0,
"use_channel_priority": true,
"priority": "standard",
"max_frequency": 0,
"max_frequency_period": 0,
"max_frequency_type": "start"
}
AdButler\VASTPlacement JSON: {
"object": "vast_placement",
"self": "/v1/vast_placements/7698",
"id": 7698,
"zone": 85772,
"channel": 0,
"schedule": 12209,
"advertisement": {
"id": 2579,
"type": "vast_banner"
},
"active": true,
"cpm": 2,
"cpc": 0,
"cpa": 0,
"fixed_cost": 0,
"payout_percent": 0,
"use_channel_priority": true,
"priority": "standard",
"max_frequency": 0,
"max_frequency_period": 0,
"max_frequency_type": "start"
}
You can update a specific VAST placement by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the VAST placement creation request.
Field | Type | Description |
---|---|---|
advertisement |
object |
An object containing vast_banner or vast_campaign identifier (ID) and type. |
schedule |
integer |
The VAST schedule identifier (ID). |
zone |
integer |
If assigned to a zone, this is the VAST zone ID. |
channel |
integer |
If assiged to a channel, this is the VAST channel ID. |
active |
boolean |
Whether to actively serve ads in the zones ( |
cpm |
decimal |
CPM of the placement. |
cpc |
decimal |
CPC of the placement. |
cpa |
decimal |
CPA of the placement. |
fixed_cost |
decimal |
Fixed cost of the placement. |
payout_percent |
decimal |
The percentage of the ad generated revenue paid out to the publisher. Publisher payout is ideal for profit sharing where the revenue is split between money earned by the advertiser and money earned by the publisher. Defaults to |
use_channel_priority |
boolean |
Whether to use the priority of the channel or set a specific priority. |
priority |
integer |
Priority allows you to prefer serving of some ads over others in a campaign or channel. Possible values in descending order are |
max_frequency |
integer |
A limit to the number of times a user is allowed to trigger a specific event, given by |
max_frequency_period |
integer |
The number of days after which the |
max_frequency_type |
string |
The specific event that will be counted by the frequency capping. One of: |
Returns
Returns a vast_placement
object if the request succeeded, or an error if something went terribly wrong.
Delete a VAST Placement
Definition
DELETE https://api.adbutler.com/v1/vast-placements/{PLACEMENT-ID}
\AdButler\VASTPlacement->delete()
adbutler.vastPlacements.delete()
Example Request
curl "https://api.adbutler.com/v1/vast-placements/7698" \
-H "Authorization: Basic {API_KEY}" \
-X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTPlacement = \AdButler\VASTPlacement::retrieve( 7698 );
$vASTPlacement->delete();
echo $vASTPlacement;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.vastPlacements.delete(7698, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastPlacements.delete(7698).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"id": 7698,
"delete": true
}
AdButler\VASTPlacement JSON: {
"id": 7698,
"delete": true
}
Permanently deletes a VAST placement. if successful, this operation cannot be undone so be very sure when deleting one.
Returns
Returns a VAST placement ID if the request succeeded, or an error if something went terribly wrong.
List all VAST Placements
Definition
GET https://api.adbutler.com/v1/vast-placements
\AdButler\VASTPlacement::retrieveAll()
adbutler.vastPlacements.list()
Example Request
curl "https://api.adbutler.com/v1/vast-placements?limit=2" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTPlacement = \AdButler\VASTPlacement::retrieveAll(array(
"limit" => 2
));
echo $vASTPlacement;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.vastPlacements.list({
limit: 2
}, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastPlacements.list({
limit: 2
}).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/vast-placements",
"data": [
{
"object": "vast_placement",
"self": "/v1/vast_placements/7658",
"id": 7658,
"zone": 85756,
"channel": 0,
"schedule": 12153,
"advertisement": {
"id": 2553,
"type": "vast_banner"
},
"active": true,
"cpm": 2,
"cpc": 0,
"cpa": 0,
"fixed_cost": 0,
"payout_percent": 0,
"use_channel_priority": true,
"priority": "standard",
"max_frequency": 0,
"max_frequency_period": 0,
"max_frequency_type": "start"
},
{
"object": "vast_placement",
"self": "/v1/vast_placements/7659",
"id": 7659,
"zone": 85757,
"channel": 0,
"schedule": 12154,
"advertisement": {
"id": 2554,
"type": "vast_banner"
},
"active": true,
"cpm": 2,
"cpc": 0,
"cpa": 0,
"fixed_cost": 0,
"payout_percent": 0,
"use_channel_priority": true,
"priority": "standard",
"max_frequency": 0,
"max_frequency_period": 0,
"max_frequency_type": "start"
}
]
}
AdButler\VASTPlacement JSON: {
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/vast-placements",
"data": [
{
"object": "vast_placement",
"self": "/v1/vast_placements/7658",
"id": 7658,
"zone": 85756,
"channel": 0,
"schedule": 12153,
"advertisement": {
"id": 2553,
"type": "vast_banner"
},
"active": true,
"cpm": 2,
"cpc": 0,
"cpa": 0,
"fixed_cost": 0,
"payout_percent": 0,
"use_channel_priority": true,
"priority": "standard",
"max_frequency": 0,
"max_frequency_period": 0,
"max_frequency_type": "start"
},
{
"object": "vast_placement",
"self": "/v1/vast_placements/7659",
"id": 7659,
"zone": 85757,
"channel": 0,
"schedule": 12154,
"advertisement": {
"id": 2554,
"type": "vast_banner"
},
"active": true,
"cpm": 2,
"cpc": 0,
"cpa": 0,
"fixed_cost": 0,
"payout_percent": 0,
"use_channel_priority": true,
"priority": "standard",
"max_frequency": 0,
"max_frequency_period": 0,
"max_frequency_type": "start"
}
]
}
Returns a list of all the VAST placements. Most recent VAST placements appear first in the list.
Returns
Returns an object with a data
property that contains a list of up to the specified limit and/or offset of objects. Each entry in data
is a vast_placement
object, and if no objects were found the list will be empty.
Retrieve VAST placement conversion tag
Definition
GET https://api.adbutler.com/v1/vast-placements/{PLACEMENT-ID}/conversion-tag
\AdButler\VASTPlacementConvTag::retrieve()
adbutler.vastPlacements.conversionTag.retrieve()
Example Request
curl "https://api.adbutler.com/v1/vast-placements/ID/conversion-tag/7698" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTPlacementConvTag = \AdButler\VASTPlacementConvTag::retrieve( 7698 );
echo $vASTPlacementConvTag;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.vastPlacements.conversionTag.read(7698, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastPlacements.conversionTag.read(7698).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Retrieves an HTML tag which can be used to track conversions for the provided VAST placement.
Query Parameters
Parameter | Description |
---|---|
protocol |
Whether to use |
Returns
Example Response
{
"object": "conv_tag",
"url": "/v1/vast-placements/7698/conversion-tag",
"data": {
"src": "https://servedbyadbutler.com.vm.test/vconvtrack.spark?MID=108607&vastPlacementID=7698",
"html": "<img src='https://servedbyadbutler.com.vm.test/vconvtrack.spark?MID=108607&vastPlacementID=7698' width='1' height='1' border='0' />"
}
}
AdButler\VASTPlacementConvTag JSON: {
"object": "conv_tag",
"url": "/v1/vast-placements/7698/conversion-tag",
"data": {
"src": "https://servedbyadbutler.com.vm.test/vconvtrack.spark?MID=108607&vastPlacementID=7698",
"html": "<img src='https://servedbyadbutler.com.vm.test/vconvtrack.spark?MID=108607&vastPlacementID=7698' width='1' height='1' border='0' />"
}
}
Field | Type | Description |
---|---|---|
object |
string |
A string denoting the object type which is always |
url |
string |
The relative URL of the current resource which is always of the form |
data |
array |
The data object containing the conversion tag. |
Returns a conv_tag
object if the request succeeded, or an error if something went terribly wrong.
VAST Tracking
Introduction
The VAST Tracking endpoint allows you to bind your own custom tracking links to different VAST events. When these are active the video player will fire both our tracking and your custom tracking at the same time the event occurs.
The vast_tracking
response object has the following fields.
Example Response
{
"object": "vast_tracking",
"self": "/v1/vast_tracking/1554",
"id": 1554,
"banner_id": 2579,
"type": "midpoint",
"link": "http://www.google.com"
}
AdButler\VASTTracking JSON: {
"object": "vast_tracking",
"self": "/v1/vast_tracking/1554",
"id": 1554,
"banner_id": 2579,
"type": "midpoint",
"link": "http://www.google.com"
}
Field | Type | Description |
---|---|---|
object |
string |
A string denoting the object type which is always |
self |
string |
The relative URL of the current resource which is always of the form |
id |
integer |
The resource identifier (ID). |
banner_id |
integer |
The ID of the VAST Banner that your tracking events will be attached to. |
type |
string |
The event type to track. One of: |
link |
string |
Your URL to be pinged at the time of the event. |
Create a VAST Tracking
Definition
POST https://api.adbutler.com/v1/vast-tracking
\AdButler\VASTTracking::create()
adbutler.vastTracking.create()
Example Request
curl "https://api.adbutler.com/v1/vast-tracking" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"banner_id": 2579,
"type": "midpoint",
"link": "http://www.google.com"
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTTracking = \AdButler\VASTTracking::create(array(
"banner_id" => 2579,
"type" => "midpoint",
"link" => "http://www.google.com"
));
echo $vASTTracking;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var postData = {
"banner_id": 2579,
"type": "midpoint",
"link": "http://www.google.com"
};
// using callbacks
adbutler.vastTracking.create(postData, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastTracking.create(postData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "vast_tracking",
"self": "/v1/vast_tracking/1554",
"id": 1554,
"banner_id": 2579,
"type": "midpoint",
"link": "http://www.google.com"
}
AdButler\VASTTracking JSON: {
"object": "vast_tracking",
"self": "/v1/vast_tracking/1554",
"id": 1554,
"banner_id": 2579,
"type": "midpoint",
"link": "http://www.google.com"
}
Creates a new VAST Tracking.
Field | Type | Description |
---|---|---|
banner_id* |
integer |
The ID of the VAST Banner that your tracking events will be attached to. |
type* |
string |
The event type to track. One of: |
link* |
string |
Your URL to be pinged at the time of the event. |
* = required field
Returns
Returns a vast_tracking
object if the request succeeded, or an error if something went terribly wrong.
Retrieve a VAST Tracking
Definition
GET https://api.adbutler.com/v1/vast-tracking/{TRACKING-ID}
\AdButler\VASTTracking::retrieve()
adbutler.vastTracking.retrieve()
Example Request
curl "https://api.adbutler.com/v1/vast-tracking/1554" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTTracking = \AdButler\VASTTracking::retrieve( 1554 );
echo $vASTTracking;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.vastTracking.read(1554, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastTracking.read(1554).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "vast_tracking",
"self": "/v1/vast_tracking/1554",
"id": 1554,
"banner_id": 2579,
"type": "midpoint",
"link": "http://www.google.com"
}
AdButler\VASTTracking JSON: {
"object": "vast_tracking",
"self": "/v1/vast_tracking/1554",
"id": 1554,
"banner_id": 2579,
"type": "midpoint",
"link": "http://www.google.com"
}
You can retrieve the information about an existing VAST tracking by giving the tracking ID that was returned in the VAST tracking object upon creation. You will see at the most 10 VAST tracking in the response. You can change this default limit by appending ?limit=25
if you want this request to return 25 VAST tracking.
Returns
Returns a vast_tracking
object if the request succeeded, or an error if something went terribly wrong.
Update a VAST Tracking
Definition
PUT https://api.adbutler.com/v1/vast-tracking/{TRACKING-ID}
\AdButler\VASTTracking->save()
adbutler.vastTracking.update()
Example Request
curl "https://api.adbutler.com/v1/vast-tracking/1554" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
"banner_id": 2579,
"type": "midpoint",
"link": "http://www.google.com"
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTTracking = \AdButler\VASTTracking::retrieve( 1554 );
$vASTTracking->banner_id = 2579;
$vASTTracking->type = "midpoint";
$vASTTracking->link = "http://www.google.com";
$vASTTracking->save();
echo $vASTTracking;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var updateData = {
"banner_id": 2579,
"type": "midpoint",
"link": "http://www.google.com"
};
// using callbacks
adbutler.vastTracking.update(1554, updateData, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastTracking.update(1554, updateData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "vast_tracking",
"self": "/v1/vast_tracking/1554",
"id": 1554,
"banner_id": 2579,
"type": "midpoint",
"link": "http://www.google.com"
}
AdButler\VASTTracking JSON: {
"object": "vast_tracking",
"self": "/v1/vast_tracking/1554",
"id": 1554,
"banner_id": 2579,
"type": "midpoint",
"link": "http://www.google.com"
}
You can update a specific VAST tracking by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the VAST tracking creation request.
Field | Type | Description |
---|---|---|
banner_id |
integer |
The ID of the VAST Banner that your tracking events will be attached to. |
type |
string |
The event type to track. One of: |
link |
string |
Your URL to be pinged at the time of the event. |
Returns
Returns a vast_tracking
object if the request succeeded, or an error if something went terribly wrong.
Delete a VAST Tracking
Definition
DELETE https://api.adbutler.com/v1/vast-tracking/{TRACKING-ID}
\AdButler\VASTTracking->delete()
adbutler.vastTracking.delete()
Example Request
curl "https://api.adbutler.com/v1/vast-tracking/1554" \
-H "Authorization: Basic {API_KEY}" \
-X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTTracking = \AdButler\VASTTracking::retrieve( 1554 );
$vASTTracking->delete();
echo $vASTTracking;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.vastTracking.delete(1554, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastTracking.delete(1554).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"id": 1554,
"delete": true
}
AdButler\VASTTracking JSON: {
"id": 1554,
"delete": true
}
Permanently deletes a VAST tracking. if successful, this operation cannot be undone so be very sure when deleting one.
Returns
Returns a VAST tracking ID if the request succeeded, or an error if something went terribly wrong.
List all VAST Tracking
Definition
GET https://api.adbutler.com/v1/vast-tracking
\AdButler\VASTTracking::retrieveAll()
adbutler.vastTracking.list()
Example Request
curl "https://api.adbutler.com/v1/vast-tracking?limit=2" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$vASTTracking = \AdButler\VASTTracking::retrieveAll(array(
"limit" => 2
));
echo $vASTTracking;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.vastTracking.list({
limit: 2
}, function(err, response) {
console.log(response);
});
// using promises
adbutler.vastTracking.list({
limit: 2
}).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/vast-tracking",
"data": [
{
"object": "vast_tracking",
"self": "/v1/vast_tracking/1493",
"id": 1493,
"banner_id": 2553,
"type": "midpoint",
"link": "http://www.google.com"
},
{
"object": "vast_tracking",
"self": "/v1/vast_tracking/1494",
"id": 1494,
"banner_id": 2554,
"type": "midpoint",
"link": "http://www.google.com"
}
]
}
AdButler\VASTTracking JSON: {
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/vast-tracking",
"data": [
{
"object": "vast_tracking",
"self": "/v1/vast_tracking/1493",
"id": 1493,
"banner_id": 2553,
"type": "midpoint",
"link": "http://www.google.com"
},
{
"object": "vast_tracking",
"self": "/v1/vast_tracking/1494",
"id": 1494,
"banner_id": 2554,
"type": "midpoint",
"link": "http://www.google.com"
}
]
}
Returns a list of all the VAST tracking. Most recent VAST tracking appear first in the list.
Returns
Returns an object with a data
property that contains a list of up to the specified limit and/or offset of objects. Each entry in data
is a vast_tracking
object, and if no objects were found the list will be empty.
Channels
Introduction
Channels allow advertisers to easily assign their campaigns to multiple zones usually having a particular focus (e.g sports) and perhaps owned by different publishers. This is desirable when a campaign with the same assignment settings is to be assigned to a large number of zones.
The channel
response object has the following fields.
Example Response
{
"object": "channel",
"self": "/v1/channels/866",
"id": 866,
"name": "Demo Channel",
"priority": "standard",
"zones": [
{
"id": 104144,
"type": "banner_zone"
}
]
}
AdButler\Channel JSON: {
"object": "channel",
"self": "/v1/channels/866",
"id": 866,
"name": "Demo Channel",
"priority": "standard",
"zones": [
{
"id": 104144,
"type": "banner_zone"
}
]
}
Attributes | Type | Description |
---|---|---|
object |
string |
A string denoting the object type which is always |
self |
string |
The relative URL of the current resource which is always of the form |
id |
integer |
The current resource identifier (ID). |
name |
string |
A descriptive name of the channel. |
priority |
string |
The serving priority of the channel. |
zones |
array/null |
The list of zones assigned to the current resource. |
Create a channel
Definition
POST https://api.adbutler.com/v1/channels
\AdButler\Channel::create()
adbutler.channels.create()
Example Request
curl "https://api.adbutler.com/v1/channels" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"name": "Demo Channel",
"priority": "standard"
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$channel = \AdButler\Channel::create(array(
"name" => "Demo Channel",
"priority" => "standard"
));
echo $channel;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var postData = {
"name": "Demo Channel",
"priority": "standard"
};
// using callbacks
adbutler.channels.create(postData, function(err, response) {
console.log(response);
});
// using promises
adbutler.channels.create(postData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "channel",
"self": "/v1/channels/866",
"id": 866,
"name": "Demo Channel",
"priority": "standard",
"zones": [
{
"id": 104144,
"type": "banner_zone"
}
]
}
AdButler\Channel JSON: {
"object": "channel",
"self": "/v1/channels/866",
"id": 866,
"name": "Demo Channel",
"priority": "standard",
"zones": [
{
"id": 104144,
"type": "banner_zone"
}
]
}
Creates a new channel.
Field | Type | Description |
---|---|---|
name* |
string |
A descriptive name of the channel. |
priority |
string |
Priority allows you to prefer serving of some ads over others in a channel. Possible values in descending order are |
* = required field
Returns
Returns a channel
object if the request succeeded, or an error if something went terribly wrong.
Retrieve a channel
Definition
GET https://api.adbutler.com/v1/channels/{CHANNEL-ID}
\AdButler\Channel::retrieve()
adbutler.channels.retrieve()
Example Request
curl "https://api.adbutler.com/v1/channels/866" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$channel = \AdButler\Channel::retrieve( 866 );
echo $channel;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.channels.read(866, function(err, response) {
console.log(response);
});
// using promises
adbutler.channels.read(866).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "channel",
"self": "/v1/channels/866",
"id": 866,
"name": "Demo Channel",
"priority": "standard",
"zones": [
{
"id": 104144,
"type": "banner_zone"
}
]
}
AdButler\Channel JSON: {
"object": "channel",
"self": "/v1/channels/866",
"id": 866,
"name": "Demo Channel",
"priority": "standard",
"zones": [
{
"id": 104144,
"type": "banner_zone"
}
]
}
You can retrieve the information about an existing channel by giving the channel ID that was returned in the channel object upon creation. You will see at the most 10 channels in the response. You can change this default limit by appending ?limit=25
if you want this request to return 25 channels.
Returns
Returns a channel
object if the request succeeded, or an error if something went terribly wrong.
Update a channel
Definition
PUT https://api.adbutler.com/v1/channels/{CHANNEL-ID}
\AdButler\Channel->save()
adbutler.channels.update()
Example Request
curl "https://api.adbutler.com/v1/channels/866" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
"name": "Demo Channel",
"priority": "standard"
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$channel = \AdButler\Channel::retrieve( 866 );
$channel->name = "Demo Channel";
$channel->priority = "standard";
$channel->save();
echo $channel;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var updateData = {
"name": "Demo Channel",
"priority": "standard"
};
// using callbacks
adbutler.channels.update(866, updateData, function(err, response) {
console.log(response);
});
// using promises
adbutler.channels.update(866, updateData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "channel",
"self": "/v1/channels/866",
"id": 866,
"name": "Demo Channel",
"priority": "standard",
"zones": [
{
"id": 104144,
"type": "banner_zone"
}
]
}
AdButler\Channel JSON: {
"object": "channel",
"self": "/v1/channels/866",
"id": 866,
"name": "Demo Channel",
"priority": "standard",
"zones": [
{
"id": 104144,
"type": "banner_zone"
}
]
}
You can update a specific channel by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the channel creation request.
Field | Type | Description |
---|---|---|
name |
string |
A descriptive name of the channel. |
priority |
string |
Priority allows you to prefer serving of some ads over others in a channel. Possible values in descending order are |
Returns
Returns a channel
object if the request succeeded, or an error if something went terribly wrong.
Delete a channel
Definition
DELETE https://api.adbutler.com/v1/channels/{CHANNEL-ID}
\AdButler\Channel->delete()
adbutler.channels.delete()
Example Request
curl "https://api.adbutler.com/v1/channels/866" \
-H "Authorization: Basic {API_KEY}" \
-X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$channel = \AdButler\Channel::retrieve( 866 );
$channel->delete();
echo $channel;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.channels.delete(866, function(err, response) {
console.log(response);
});
// using promises
adbutler.channels.delete(866).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"id": 866,
"delete": true
}
AdButler\Channel JSON: {
"id": 866,
"delete": true
}
Permanently deletes a channel. If successful, this operation cannot be undone so be very sure when deleting one.
Returns
Returns a channel ID if the request succeeded, or an error if something went terribly wrong.
List all channels
Definition
GET https://api.adbutler.com/v1/channels
\AdButler\Channel::retrieveAll()
adbutler.channels.list()
Example Request
curl "https://api.adbutler.com/v1/channels?limit=2" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$channel = \AdButler\Channel::retrieveAll(array(
"limit" => 2
));
echo $channel;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.channels.list({
limit: 2
}, function(err, response) {
console.log(response);
});
// using promises
adbutler.channels.list({
limit: 2
}).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/channels",
"data": [
{
"object": "channel",
"self": "/v1/channels/853",
"id": 853,
"name": "Demo Channel",
"priority": "standard",
"zones": null
},
{
"object": "channel",
"self": "/v1/channels/852",
"id": 852,
"name": "Demo Channel",
"priority": "standard",
"zones": null
}
]
}
AdButler\Channel JSON: {
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/channels",
"data": [
{
"object": "channel",
"self": "/v1/channels/853",
"id": 853,
"name": "Demo Channel",
"priority": "standard",
"zones": null
},
{
"object": "channel",
"self": "/v1/channels/852",
"id": 852,
"name": "Demo Channel",
"priority": "standard",
"zones": null
}
]
}
Returns a list of all the channels. Most recent channels appear first in the list.
Returns
Returns an object with a data
property that contains a list of up to the specified limit and/or offset of objects. Each entry in data
is a channel
object, and if no objects were found the list will be empty.
Channel Zone Assignments
Introduction
A channel zone assignment represents the relationship between a channel and a zone.
The channel_zone_assignment
response object has the following fields.
Example Response
{
"object": "channel_zone_assignment",
"self": "/v1/channel-zone-assignments/20185",
"id": 20185,
"channel": 866,
"zone": {
"id": 104144,
"type": "banner_zone"
}
}
AdButler\ChannelZoneAssignment JSON: {
"object": "channel_zone_assignment",
"self": "/v1/channel-zone-assignments/20185",
"id": 20185,
"channel": 866,
"zone": {
"id": 104144,
"type": "banner_zone"
}
}
Field | Type | Description |
---|---|---|
object |
string |
A string denoting the object type which is always |
self |
string |
The relative URL of the current resource which is always of the form |
id |
integer |
The current resource identifier (ID). |
channel |
integer |
The channel identifier (ID). |
zone |
array |
An object containing banner, email, or text zone identifier (ID) and type. |
Create a channel zone assignment
Definition
POST https://api.adbutler.com/v1/channel-zone-assignments
\AdButler\ChannelZoneAssignment::create()
adbutler.channel-zone-assignments.create()
Example Request
curl "https://api.adbutler.com/v1/channel-zone-assignments" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"channel": 866,
"zone":
{
id: 104144,
type: "banner_zone"
}
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$channelZoneAssignment = \AdButler\ChannelZoneAssignment::create(array(
"channel" => 866,
"zone" =>
[
id => 104144,
type => "banner_zone"
]
));
echo $channelZoneAssignment;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var postData = {
"channel": 866,
"zone":
{
id: 104144,
type: "banner_zone"
}
};
// using callbacks
adbutler.channel-zone-assignments.create(postData, function(err, response) {
console.log(response);
});
// using promises
adbutler.channel-zone-assignments.create(postData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "channel_zone_assignment",
"self": "/v1/channel-zone-assignments/20185",
"id": 20185,
"channel": 866,
"zone": {
"id": 104144,
"type": "banner_zone"
}
}
AdButler\ChannelZoneAssignment JSON: {
"object": "channel_zone_assignment",
"self": "/v1/channel-zone-assignments/20185",
"id": 20185,
"channel": 866,
"zone": {
"id": 104144,
"type": "banner_zone"
}
}
Creates a new channel zone assignment.
Field | Type | Description |
---|---|---|
channel* |
integer |
The channel identifier (ID) to which you wish to assign the zones. |
zone* |
object |
An object containing banner, email, or text zone identifier (ID) and type. |
* = required field
Returns
Returns a channel_zone_assignment
object if the request succeeded, or an error if something went terribly wrong.
Retrieve a channel zone assignment
Definition
GET https://api.adbutler.com/v1/channel-zone-assignments/{CHANNEL-ZONE-ASSIGNMENT-ID}
\AdButler\ChannelZoneAssignment::retrieve()
adbutler.channel-zone-assignments.retrieve()
Example Request
curl "https://api.adbutler.com/v1/channel-zone-assignments/20185" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$channelZoneAssignment = \AdButler\ChannelZoneAssignment::retrieve( 20185 );
echo $channelZoneAssignment;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.channel-zone-assignments.read(20185, function(err, response) {
console.log(response);
});
// using promises
adbutler.channel-zone-assignments.read(20185).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "channel_zone_assignment",
"self": "/v1/channel-zone-assignments/20185",
"id": 20185,
"channel": 866,
"zone": {
"id": 104144,
"type": "banner_zone"
}
}
AdButler\ChannelZoneAssignment JSON: {
"object": "channel_zone_assignment",
"self": "/v1/channel-zone-assignments/20185",
"id": 20185,
"channel": 866,
"zone": {
"id": 104144,
"type": "banner_zone"
}
}
You can retrieve the information about an existing channel zone assignment by giving the channel zone assignment ID that was returned in the channel zone assignment object upon creation. You will see at the most 10 channel zone assignments in the response. You can change this default limit by appending ?limit=25
if you want this request to return 25 channel zone assignments.
Returns
Returns a channel_zone_assignment
object if the request succeeded, or an error if something went terribly wrong.
Delete a channel zone assignment
Definition
DELETE https://api.adbutler.com/v1/channel-zone-assignments/{CHANNEL-ZONE-ASSIGNMENT-ID}
\AdButler\ChannelZoneAssignment->delete()
adbutler.channel-zone-assignments.delete()
Example Request
curl "https://api.adbutler.com/v1/channel-zone-assignments/20185" \
-H "Authorization: Basic {API_KEY}" \
-X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$channelZoneAssignment = \AdButler\ChannelZoneAssignment::retrieve( 20185 );
$channelZoneAssignment->delete();
echo $channelZoneAssignment;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.channel-zone-assignments.delete(20185, function(err, response) {
console.log(response);
});
// using promises
adbutler.channel-zone-assignments.delete(20185).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"id": 20185,
"delete": true
}
AdButler\ChannelZoneAssignment JSON: {
"id": 20185,
"delete": true
}
Permanently deletes a channel zone assignment. If successful, this operation cannot be undone so be very sure when deleting one.
Returns
Returns a channel zone assignment ID if the request succeeded, or an error if something went terribly wrong.
List all channel zone assignments
Definition
GET https://api.adbutler.com/v1/channel-zone-assignments
\AdButler\ChannelZoneAssignment::retrieveAll()
adbutler.channel-zone-assignments.list()
Example Request
curl "https://api.adbutler.com/v1/channel-zone-assignments?limit=2" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$channelZoneAssignment = \AdButler\ChannelZoneAssignment::retrieveAll(array(
"limit" => 2
));
echo $channelZoneAssignment;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.channel-zone-assignments.list({
limit: 2
}, function(err, response) {
console.log(response);
});
// using promises
adbutler.channel-zone-assignments.list({
limit: 2
}).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/channel-zone-assignments",
"data": [
{
"object": "channel_zone_assignment",
"self": "/v1/channel-zone-assignments/130",
"id": 130,
"channel": 161,
"zone": {
"id": 87208,
"type": "banner_zone"
}
},
{
"object": "channel_zone_assignment",
"self": "/v1/channel-zone-assignments/135",
"id": 135,
"channel": 161,
"zone": {
"id": 87209,
"type": "banner_zone"
}
}
]
}
AdButler\ChannelZoneAssignment JSON: {
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/channel-zone-assignments",
"data": [
{
"object": "channel_zone_assignment",
"self": "/v1/channel-zone-assignments/130",
"id": 130,
"channel": 161,
"zone": {
"id": 87208,
"type": "banner_zone"
}
},
{
"object": "channel_zone_assignment",
"self": "/v1/channel-zone-assignments/135",
"id": 135,
"channel": 161,
"zone": {
"id": 87209,
"type": "banner_zone"
}
}
]
}
Returns a list of all the channel zone assignments. Most recent channel zone assignments appear first in the list.
Returns
Returns an object with a data
property that contains a list of up to the specified limit and/or offset of objects. Each entry in data
is a channel_zone_assignment
object, and if no objects were found the list will be empty.
Managers
Introduction
A manager is an individual whom you wish to delegate some responsibility of managing your AdButler account. You can grant as much or as little access based on your needs. Managers can be granted permissions to add and manage other managers, advertisers, or publishers.
The manager
response object has the following fields.
Example Response
{
"object": "manager",
"self": "/v1/managers/608",
"id": 608,
"can_manage_links": true,
"can_manage_media": true,
"can_manage_targets": true,
"can_manage_users": true,
"created_date": "2018-11-28 11:49:46",
"email": "demo.manager@adbutler.com",
"last_accessed": null,
"name": "Demo Manager",
"notes": "",
"position": "some company",
"publisher_access": "none",
"publisher_access_list": [],
"statistics_access": "all"
}
AdButler\Manager JSON: {
"object": "manager",
"self": "/v1/managers/608",
"id": 608,
"can_manage_links": true,
"can_manage_media": true,
"can_manage_targets": true,
"can_manage_users": true,
"created_date": "2018-11-28 11:49:46",
"email": "demo.manager@adbutler.com",
"last_accessed": null,
"name": "Demo Manager",
"notes": "",
"position": "some company",
"publisher_access": "none",
"publisher_access_list": [],
"statistics_access": "all"
}
Field | Type | Description |
---|---|---|
object |
string |
A string denoting the object type which is always |
self |
string |
The relative URL of the current resource which is always of the form |
id |
integer |
The current resource identifier (ID). |
can_manage_links |
boolean |
Whether to allow managing hypermedia links. |
can_manage_media |
boolean |
Whether to allow managing various media. |
can_manage_targets |
boolean |
Whether to allow this user to managing various ad targeting features. |
can_manage_users |
boolean |
Whether to allow managing other accounts. |
created_date |
string |
The date and time when this account was created. |
string |
A valid email of the manager. |
|
last_accessed |
string |
The date and time when this account was last accessed. |
name |
string |
Name of the manager. |
notes |
string |
Aditional notes or information about the manager. |
position |
string |
Position of the manager in the organization. |
publisher_access |
string |
Whether to allow access to some or all of the publishers. |
publisher_access_list |
array |
The list of publishers this manager has been granted access to. |
statistics_access |
string |
Whether to allow viewing statistics or not. |
Create a manager
Definition
POST https://api.adbutler.com/v1/managers
\AdButler\Manager::create()
adbutler.managers.create()
Example Request
curl "https://api.adbutler.com/v1/managers" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"can_manage_links": true,
"can_manage_media": true,
"can_manage_users": true,
"email": "demo.manager@adbutler.com",
"name": "Demo Manager",
"notes": "",
"position": "some company"
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$manager = \AdButler\Manager::create(array(
"can_manage_links" => true,
"can_manage_media" => true,
"can_manage_users" => true,
"email" => "demo.manager@adbutler.com",
"name" => "Demo Manager",
"notes" => "",
"position" => "some company"
));
echo $manager;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var postData = {
"can_manage_links": true,
"can_manage_media": true,
"can_manage_users": true,
"email": "demo.manager@adbutler.com",
"name": "Demo Manager",
"notes": "",
"position": "some company"
};
// using callbacks
adbutler.managers.create(postData, function(err, response) {
console.log(response);
});
// using promises
adbutler.managers.create(postData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "manager",
"self": "/v1/managers/608",
"id": 608,
"can_manage_links": true,
"can_manage_media": true,
"can_manage_targets": true,
"can_manage_users": true,
"created_date": "2018-11-28 11:49:46",
"email": "demo.manager@adbutler.com",
"last_accessed": null,
"name": "Demo Manager",
"notes": "",
"position": "some company",
"publisher_access": "none",
"publisher_access_list": [],
"statistics_access": "all"
}
AdButler\Manager JSON: {
"object": "manager",
"self": "/v1/managers/608",
"id": 608,
"can_manage_links": true,
"can_manage_media": true,
"can_manage_targets": true,
"can_manage_users": true,
"created_date": "2018-11-28 11:49:46",
"email": "demo.manager@adbutler.com",
"last_accessed": null,
"name": "Demo Manager",
"notes": "",
"position": "some company",
"publisher_access": "none",
"publisher_access_list": [],
"statistics_access": "all"
}
Creates a new manager.
Field | Type | Description |
---|---|---|
name* |
string |
The name of the manager. |
email* |
string |
A valid email of the manager. |
password |
string |
A password for the manager account preferrable including uppercase letters and numbers. |
position |
string |
The position of the manager in the organization. |
notes |
string |
Aditional notes or information about the manager. |
can_manage_links |
boolean |
Whether to allow managing hypermedia links. |
can_manage_media |
boolean |
Whether to allow managing various media. |
can_manage_targets |
boolean |
Whether to allow this user to managing various ad targeting features. |
can_manage_users |
boolean |
Whether to allow managing other accounts. |
publisher_access |
string |
Whether to allow this manager access to some or all publishers in the organization. The value must be one of |
publisher_access_list |
array |
The list of publishers to give access to. This field must only be given when |
statistics_access |
string |
Whether to allow viewing the assigned ad serving statistics. The value must be one of |
* = required field
Returns
Returns a manager
object if the request succeeded, or an error if something went terribly wrong.
Retrieve a manager
Definition
GET https://api.adbutler.com/v1/managers/{MANAGER-ID}
\AdButler\Manager::retrieve()
adbutler.managers.retrieve()
Example Request
curl "https://api.adbutler.com/v1/managers/608" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$manager = \AdButler\Manager::retrieve( 608 );
echo $manager;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.managers.read(608, function(err, response) {
console.log(response);
});
// using promises
adbutler.managers.read(608).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "manager",
"self": "/v1/managers/608",
"id": 608,
"can_manage_links": true,
"can_manage_media": true,
"can_manage_targets": true,
"can_manage_users": true,
"created_date": "2018-11-28 11:49:46",
"email": "demo.manager@adbutler.com",
"last_accessed": null,
"name": "Demo Manager",
"notes": "",
"position": "some company",
"publisher_access": "none",
"publisher_access_list": [],
"statistics_access": "all"
}
AdButler\Manager JSON: {
"object": "manager",
"self": "/v1/managers/608",
"id": 608,
"can_manage_links": true,
"can_manage_media": true,
"can_manage_targets": true,
"can_manage_users": true,
"created_date": "2018-11-28 11:49:46",
"email": "demo.manager@adbutler.com",
"last_accessed": null,
"name": "Demo Manager",
"notes": "",
"position": "some company",
"publisher_access": "none",
"publisher_access_list": [],
"statistics_access": "all"
}
You can retrieve the information about an existing manager by giving the manager ID that was returned in the manager object upon creation.
Returns
Returns a manager
object if the request succeeded, or an error if something went terribly wrong.
Update a manager
Definition
PUT https://api.adbutler.com/v1/managers/{MANAGER-ID}
\AdButler\Manager->save()
adbutler.managers.update()
Example Request
curl "https://api.adbutler.com/v1/managers/608" \
-H "Authorization: Basic {API_KEY}" \
-H "Content-Type: application/json" \
-X PUT \
-d '{
"can_manage_links": true,
"can_manage_media": true,
"can_manage_users": true,
"email": "demo.manager@adbutler.com",
"name": "Demo Manager",
"notes": "",
"position": "some company"
}'
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$manager = \AdButler\Manager::retrieve( 608 );
$manager->can_manage_links = true;
$manager->can_manage_media = true;
$manager->can_manage_users = true;
$manager->email = "demo.manager@adbutler.com";
$manager->name = "Demo Manager";
$manager->notes = "";
$manager->position = "some company";
$manager->save();
echo $manager;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
var updateData = {
"can_manage_links": true,
"can_manage_media": true,
"can_manage_users": true,
"email": "demo.manager@adbutler.com",
"name": "Demo Manager",
"notes": "",
"position": "some company"
};
// using callbacks
adbutler.managers.update(608, updateData, function(err, response) {
console.log(response);
});
// using promises
adbutler.managers.update(608, updateData).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "manager",
"self": "/v1/managers/608",
"id": 608,
"can_manage_links": true,
"can_manage_media": true,
"can_manage_targets": true,
"can_manage_users": true,
"created_date": "2018-11-28 11:49:46",
"email": "demo.manager@adbutler.com",
"last_accessed": null,
"name": "Demo Manager",
"notes": "",
"position": "some company",
"publisher_access": "none",
"publisher_access_list": [],
"statistics_access": "all"
}
AdButler\Manager JSON: {
"object": "manager",
"self": "/v1/managers/608",
"id": 608,
"can_manage_links": true,
"can_manage_media": true,
"can_manage_targets": true,
"can_manage_users": true,
"created_date": "2018-11-28 11:49:46",
"email": "demo.manager@adbutler.com",
"last_accessed": null,
"name": "Demo Manager",
"notes": "",
"position": "some company",
"publisher_access": "none",
"publisher_access_list": [],
"statistics_access": "all"
}
You can update a specific manager account by setting the values of the parameters you want to update. If you want a parameter to retain the old value, then just omit it from the request. The update request accepts mostly the same arguments as the manager creation request.
Field | Type | Description |
---|---|---|
name |
string |
The name of the manager. |
string |
A valid email of the manager. |
|
password |
string |
A password for the manager account preferrable including uppercase letters and numbers. |
position |
string |
The position of the manager in the organization. |
notes |
string |
Aditional notes or information about the manager. |
can_manage_links |
boolean |
Whether to allow managing hypermedia links. |
can_manage_media |
boolean |
Whether to allow managing various media. |
can_manage_targets |
boolean |
Whether to allow this user to managing various ad targeting features. |
can_manage_users |
boolean |
Whether to allow managing other accounts. |
publisher_access |
string |
Whether to allow this manager access to some or all publishers in the organization. The value must be one of |
publisher_access_list |
array |
The list of publishers to give access to. This field must only be given when |
statistics_access |
string |
Whether to allow viewing the assigned ad serving statistics. The value must be one of |
Returns
Returns a manager
object if the request succeeded, or an error if something went terribly wrong.
Delete a manager
Definition
DELETE https://api.adbutler.com/v1/managers/{MANAGER-ID}
\AdButler\Manager->delete()
adbutler.managers.delete()
Example Request
curl "https://api.adbutler.com/v1/managers/608" \
-H "Authorization: Basic {API_KEY}" \
-X DELETE
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$manager = \AdButler\Manager::retrieve( 608 );
$manager->delete();
echo $manager;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.managers.delete(608, function(err, response) {
console.log(response);
});
// using promises
adbutler.managers.delete(608).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"id": 608,
"delete": true
}
AdButler\Manager JSON: {
"id": 608,
"delete": true
}
Permanently deletes a manager. if successful, this operation cannot be undone so be very sure when deleting one.
Returns
Returns a manager ID if the request succeeded, or an error if something went terribly wrong.
List all managers
Definition
GET https://api.adbutler.com/v1/managers
\AdButler\Manager::retrieveAll()
adbutler.managers.list()
Example Request
curl "https://api.adbutler.com/v1/managers?limit=2" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$manager = \AdButler\Manager::retrieveAll(array(
"limit" => 2
));
echo $manager;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.managers.list({
limit: 2
}, function(err, response) {
console.log(response);
});
// using promises
adbutler.managers.list({
limit: 2
}).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/managers",
"data": [
{
"object": "manager",
"self": "/v1/managers/595",
"id": 595,
"can_manage_links": true,
"can_manage_media": true,
"can_manage_targets": true,
"can_manage_users": true,
"created_date": "2018-06-28 09:55:56",
"email": "demo.manager@adbutler.com",
"last_accessed": null,
"name": "Demo Manager",
"notes": "",
"position": "some company",
"publisher_access": "none",
"publisher_access_list": [],
"statistics_access": "all"
},
{
"object": "manager",
"self": "/v1/managers/596",
"id": 596,
"can_manage_links": true,
"can_manage_media": true,
"can_manage_targets": true,
"can_manage_users": true,
"created_date": "2018-06-28 10:16:20",
"email": "demo.manager@adbutler.com",
"last_accessed": null,
"name": "Demo Manager",
"notes": "",
"position": "some company",
"publisher_access": "none",
"publisher_access_list": [],
"statistics_access": "all"
}
]
}
AdButler\Manager JSON: {
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/managers",
"data": [
{
"object": "manager",
"self": "/v1/managers/595",
"id": 595,
"can_manage_links": true,
"can_manage_media": true,
"can_manage_targets": true,
"can_manage_users": true,
"created_date": "2018-06-28 09:55:56",
"email": "demo.manager@adbutler.com",
"last_accessed": null,
"name": "Demo Manager",
"notes": "",
"position": "some company",
"publisher_access": "none",
"publisher_access_list": [],
"statistics_access": "all"
},
{
"object": "manager",
"self": "/v1/managers/596",
"id": 596,
"can_manage_links": true,
"can_manage_media": true,
"can_manage_targets": true,
"can_manage_users": true,
"created_date": "2018-06-28 10:16:20",
"email": "demo.manager@adbutler.com",
"last_accessed": null,
"name": "Demo Manager",
"notes": "",
"position": "some company",
"publisher_access": "none",
"publisher_access_list": [],
"statistics_access": "all"
}
]
}
Returns a list of all the manager accounts. Most recent manager accounts appear first in the list.
Returns
Returns an object with a data
property that contains a list of up to the specified limit and/or offset of objects. Each entry in data
is a manager
object, and if no objects were found the list will be empty.
Manual Tracking Links
Introduction
Manual Tracking Links can be used to count clicks and impressions on your banners and campaigns without having to make a new ad request. These are great when you want to track native ads, or serve cached creatives. There are a couple of options for click tracking as well. Depending on which click tracking link you generate, you can choose whether to redirect after the click is recorded or not.
The manual-tracking_links
response object has the following fields.
Example Response
{
"object": "manual_tracking_links",
"url": "/v1/manual-tracking-links",
"data": {
"impression": "https://servedbyadbutler.com/adserve/;ID=108607;size=1x1;type=tpixel;setID=104022;plid=18377;BID=518889708;wt=0;rnd=CACHE_BUSTER_MACRO",
"click_redirect": "https://servedbyadbutler.com/redirect.spark?MID=108607&plid=18377&setID=104022&channelID=0&CID=0&banID=518889708&PID=0&textadID=0&tc=1&type=tclick&mt=1&hc=3d89cd411bde99ea13dc4ed97b19010ae37ca5e1&location=",
"click_callback": "https://servedbyadbutler.com/redirect.spark?MID=108607&plid=18377&setID=104022&channelID=0&CID=0&banID=518889708&PID=0&textadID=0&tc=1&type=tclickcb&mt=1&hc=431d66517f910a228babc10a7df8bd1924562013&location="
}
}
AdButler\ManualTrackingLinks JSON: {
"object": "manual_tracking_links",
"url": "/v1/manual-tracking-links",
"data": {
"impression": "https://servedbyadbutler.com/adserve/;ID=108607;size=1x1;type=tpixel;setID=104022;plid=18377;BID=518889708;wt=0;rnd=CACHE_BUSTER_MACRO",
"click_redirect": "https://servedbyadbutler.com/redirect.spark?MID=108607&plid=18377&setID=104022&channelID=0&CID=0&banID=518889708&PID=0&textadID=0&tc=1&type=tclick&mt=1&hc=3d89cd411bde99ea13dc4ed97b19010ae37ca5e1&location=",
"click_callback": "https://servedbyadbutler.com/redirect.spark?MID=108607&plid=18377&setID=104022&channelID=0&CID=0&banID=518889708&PID=0&textadID=0&tc=1&type=tclickcb&mt=1&hc=431d66517f910a228babc10a7df8bd1924562013&location="
}
}
Field | Type | Description |
---|---|---|
object |
string |
A string denoting the the object type which is always |
url |
string |
The relative URL of this resource which is always of the form |
data |
object |
The data object containing the tracking links. |
Retrieve Manual Tracking Links
Definition
GET https://api.adbutler.com/v1/manual-tracking-links
\AdButler\ManualTrackingLinks::retrieveAll()
adbutler.manualTrackingLinks.list()
Example Request
curl "https://api.adbutler.com/v1/manual-tracking-links" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$manualTrackingLinks = \AdButler\ManualTrackingLinks::retrieve( );
echo $manualTrackingLinks;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.manualTrackingLinks.read(, function(err, response) {
console.log(response);
});
// using promises
adbutler.manualTrackingLinks.read().then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "manual_tracking_links",
"url": "/v1/manual-tracking-links",
"data": {
"impression": "https://servedbyadbutler.com/adserve/;ID=108607;size=1x1;type=tpixel;setID=104022;plid=18377;BID=518889708;wt=0;rnd=CACHE_BUSTER_MACRO",
"click_redirect": "https://servedbyadbutler.com/redirect.spark?MID=108607&plid=18377&setID=104022&channelID=0&CID=0&banID=518889708&PID=0&textadID=0&tc=1&type=tclick&mt=1&hc=3d89cd411bde99ea13dc4ed97b19010ae37ca5e1&location=",
"click_callback": "https://servedbyadbutler.com/redirect.spark?MID=108607&plid=18377&setID=104022&channelID=0&CID=0&banID=518889708&PID=0&textadID=0&tc=1&type=tclickcb&mt=1&hc=431d66517f910a228babc10a7df8bd1924562013&location="
}
}
AdButler\ManualTrackingLinks JSON: {
"object": "manual_tracking_links",
"url": "/v1/manual-tracking-links",
"data": {
"impression": "https://servedbyadbutler.com/adserve/;ID=108607;size=1x1;type=tpixel;setID=104022;plid=18377;BID=518889708;wt=0;rnd=CACHE_BUSTER_MACRO",
"click_redirect": "https://servedbyadbutler.com/redirect.spark?MID=108607&plid=18377&setID=104022&channelID=0&CID=0&banID=518889708&PID=0&textadID=0&tc=1&type=tclick&mt=1&hc=3d89cd411bde99ea13dc4ed97b19010ae37ca5e1&location=",
"click_callback": "https://servedbyadbutler.com/redirect.spark?MID=108607&plid=18377&setID=104022&channelID=0&CID=0&banID=518889708&PID=0&textadID=0&tc=1&type=tclickcb&mt=1&hc=431d66517f910a228babc10a7df8bd1924562013&location="
}
}
You can retrieve tracking links for any of your banners.
Query Parameters
Parameter | Description |
---|---|
placement* |
Refers to the placement which contains the banner that you want tracking links for. |
banner† |
Refers to the specific banner that you want tracking links for. |
type |
Specifies the type of tracking links to generate and can be any of the following values: |
protocol |
Whether to use |
* = required field
✝ = banner
must be specified if the desired banner is in a campaign.
Returns
Returns a manual_tracking_links
object if the request succeeded, or an error if something went terribly wrong.
Flexible Types
Introduction
Flexible types can be assigned to Banner Zones, Image Banners and Banner Campaigns.
A flexble type has a minimum and maximum size, and an aspect ratio which is always maintained.
Read more about them here
The flexible_type
response object has the following fields.
Example Response
{
"object": "flexible-zone-type",
"self": "/v1/zones/flexible-types/1",
"id": "1",
"name": "2x1_xlarge",
"min_width": 900,
"min_height": 450,
"max_width": 1800,
"max_height": 900,
"aspect_ratio": "2:1"
}
AdButler\FlexibleType JSON: {
"object": "flexible-zone-type",
"self": "/v1/zones/flexible-types/1",
"id": 1,
"name": "2x1_xlarge",
"min_width": 900,
"min_height": 450,
"max_width": 1800,
"max_height": 900,
"aspect_ratio": "2:1"
}
Field | Type | Description |
---|---|---|
object |
string |
A string denoting the object type which is always |
self |
string |
The relative URL of the current resource which is always of the form |
id |
string |
The current resource identifier (ID). |
name |
string |
An IAB inspired description of the type of dimensions the Flexible Type has. |
min_width |
integer |
The minimum width in pixels the ad can appear with on screen. |
min_height |
integer |
The minimum height in pixels the ad can appear with on screen. |
max_width |
integer |
The maximum width in pixels the ad can appear with on screen. |
max_height |
integer |
The maxiumum height in pixels the ad can appear with on screen. |
aspect_ratio |
string |
The aspect ratio of the ad, which will be maintained if the placement is resized. |
Retrieve a Flexible Type
Definition
GET https://api.adbutler.com/v1/zones/flexible-types/{FLEXIBLE-TYPE-ID}
\AdButler\FlexibleType::retrieve()
adbutler.zones.flexible-types.isp.retrieve()
Example Request
curl "https://api.adbutler.com/v1/zones/flexible-types/1" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$flexibleType = \AdButler\FlexibleType::retrieve( 1 );
echo $flexibleType;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.zones.flexible-types.isp.read(1, function(err, response) {
console.log(response);
});
// using promises
adbutler.zones.flexible-types.isp.read(1).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "flexible-zone-type",
"self": "/v1/zones/flexible-types/1",
"id": "1",
"name": "2x1_xlarge",
"min_width": 900,
"min_height": 450,
"max_width": 1800,
"max_height": 900,
"aspect_ratio": "2:1"
}
AdButler\FlexibleType JSON: {
"object": "flexible-zone-type",
"self": "/v1/zones/flexible-types/1",
"id": 1,
"name": "2x1_xlarge",
"min_width": 900,
"min_height": 450,
"max_width": 1800,
"max_height": 900,
"aspect_ratio": "2:1"
}
You can retrieve the information about an existing Flexible Type by giving the Flexible Type ID that was returned in the Flexible Type object upon creation. You will see at the most 10 Flexible Types in the response. You can change this default limit by appending ?limit=25
if you want this request to return 25 Flexible Types.
Returns
Returns a flexible_type
object if the request succeeded, or an error if something went terribly wrong.
List all Flexible Types
Definition
GET https://api.adbutler.com/v1/zones/flexible-types
\AdButler\FlexibleType::retrieveAll()
adbutler.zones.flexible-types.isp.list()
Example Request
curl "https://api.adbutler.com/v1/zones/flexible-types?limit=2" \
-H "Authorization: Basic {API_KEY}"
\AdButler\API::init( array("api_key" => "{API_KEY}") );
$flexibleType = \AdButler\FlexibleType::retrieveAll(array(
"limit" => 2
));
echo $flexibleType;
var AdButler = require("adbutler");
var adbutler = new AdButler({
apiKey: "{API_KEY}"
});
// using callbacks
adbutler.zones.flexible-types.isp.list({
limit: 2
}, function(err, response) {
console.log(response);
});
// using promises
adbutler.zones.flexible-types.isp.list({
limit: 2
}).then( function(response) {
console.log(response);
}, function(error) {
console.log(error);
});
Example Response
{
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/zones/flexible-types",
"data": [
{
"object": "flexible-zone-type",
"self": "/v1/zones/flexible-types/1",
"id": "1",
"name": "2x1_xlarge",
"min_width": 900,
"min_height": 450,
"max_width": 1800,
"max_height": 900,
"aspect_ratio": "2:1"
},
{
"object": "flexible-zone-type",
"self": "/v1/zones/flexible-types/2",
"id": "2",
"name": "2x1_small",
"min_width": 300,
"min_height": 150,
"max_width": 450,
"max_height": 225,
"aspect_ratio": "2:1"
}
]
}
AdButler\FlexibleType JSON: {
"object": "list",
"has_more": true,
"limit": 2,
"offset": 0,
"url": "/v1/zones/flexible-types",
"data": [
{
"object": "flexible-zone-type",
"self": "/v1/zones/flexible-types/1",
"id": 1,
"name": "2x1_xlarge",
"min_width": 900,
"min_height": 450,
"max_width": 1800,
"max_height": 900,
"aspect_ratio": "2:1"
},
{
"object": "flexible-zone-type",
"self": "/v1/zones/flexible-types/2",
"id": 2,
"name": "2x1_small",
"min_width": 300,
"min_height": 150,
"max_width": 450,
"max_height": 225,
"aspect_ratio": "2:1"
}
]
}
Returns a list of all the Flexible Types. Most recent Flexible Types appear first in the list.
Returns
Returns an object with a data
property that contains a list of up to the specified limit and/or offset of objects. Each entry in data
is an flexible_type
object, and if no objects were found the list will be empty.