The Adzerk Developer Hub

Welcome to the Adzerk developer hub. You'll find comprehensive guides and documentation to help you start working with Adzerk as quickly as possible, as well as support if you get stuck. Let's jump right in!

Suggest Edits

Getting Started

Getting started with the Adzerk API

 

Welcome!

Welcome to the Adzerk API Reference!

Before we get started, here are some additional docs that'll help you develop your native ad platform:

If you have questions or issues, please write to us at support@adzerk.com, or contact your Account Manager/Sales team.

Adzerk's Suite of APIs

Adzerk contains a full suite of APIs for all functions of Ad Serving, from campaign management to ad serving, to reporting, as well as a number of additional features. A brief overview of the Adzerk APIs follow. For more detailed information on the individual APIs, they each have their own section of documentation.

Campaign Management API
Inventory Management API
Native Ads API
Reporting API
Forecasting API
User Management API
UserDB API
Content DB API

Generating an API Key

The first step to using the Adzerk API is to generate an API Key:

  1. Navigate to the Settings section of your Adzerk account and choose the API Keys tab.
  2. Click *Add a new API Key' and then copy the generated key to use in your code.

Authenticating Requests

To authenticate with the Adzerk API, the API Key must be passed as a header with the name X-Adzerk-ApiKey on every request.

curl -X GET -H 'X-Adzerk-ApiKey:1234567890ABCDEF1234567890ABCDEF'

Your API Key is the same as a username/password so be sure to treat it the same way!

Although it is only required for certain applications, you should specify the content-type header as application/x-www-form-urlencoded.

In production, all API requests need to use SSL to protect your key.

The base domain of the management API is https://api.adzerk.net/. The current version is v1, so all requests in this documentation will be made to: https://api.adzerk.net/v1/.

Examples

An example of pulling a report with RestSharp:

var client = new RestClient();
client.BaseUrl = "https://api.adzerk.net/v1/";
client.AddDefaultHeader("X-Adzerk-ApiKey", "0223F375AE09CA4E55A82FFA241A23282485");

var request = new RestRequest();
request.Method = Method.POST;
request.Resource = "report";
request.AddParameter("criteria", "{'StartDate': '1/1/2011', 'EndDate': '5/16/2011', 'GroupBy': ['day']}");
RestResponse response = client.Execute(request);
API Explorer

We also offer an API Explorer that enables you to GET, POST and PUT to any of the API endpoints via a web form.

Suggest Edits

Campaign Structure

 

Adzerk uses a simple Advertiser, Campaign, Flight, and Ad structure. Each acts as an organizational colder, and each "parent" can contain an unlimited number of "children". That is to say, each Advertiser can contain an unlimited number of Campaigns. Each Campaign can contain an unlimited number of Flights, and each Flight can contain an unlimited number of "Ads", or Creatives.

Suggest Edits

Native Ads API Overview

 

The Native Ads API enables you to make ad requests without using ad code. By posting to a RESTful endpoint, Adzerk's ad engine will return decision data and creative contents that can be used to serve ads in your application.

Read on to learn how to properly format a Native Ads API request, and how to use the response to build out your integrated native ads.

 

Description

Use the Native Ads API to request an ad decision. To make a request, you must POST a JSON representation of the request.

Set the Content-Type in the header as application/json. (The API will also accept text/plain to support applications that cannot change the content type, such as older versions of IE.)

Definition

POST engine.adzerk.net/api/v2

Or to make a secure request:

POST https://engine.adzerk.net/api/v2

Arguments

Name
Data Type
Required
Description
Default

placements

Y

One or more Placement Objects

user

N

Target to the user key used to identify a unique user*

keywords

N

Zero or more keywords to use when selecting the ad

referrer

N

The URL to use as the referrer when selecting an ad

url

N

The URL to use as the current page URL when selecting an ad

time

N

The UNIX epoch timestamp to use when selecting an ad

ip

N

The IP address to use when selecting the ad; if specified, overrides the IP the request is made from

blockedCreatives

N

Zero or more numeric creative ids to disregard when selecting an ad

isMobile

N

If true, only ads containing a single image will be returned

False

includePricingData

N

If true, return pricing data for the decision in the response

False

  • If the request doesn't contain a user key, one will be automatically generated in the response.

Placements

Every request must contain one or more Placements. Each placement represents a "slot" in which an ad may be served. Click here for more information on placements.

Arguments

Property
Data Type
Required
Description
Default

divName

Y

A unique name for the placement

networkId

Y

The numeric network id to use when selecting an ad

siteId

Y

The numeric site id to use when selecting an ad

adTypes

Y

One or more integer ad types to use when selecting an ad

zoneIds

N

Zero or more zone ids to use when selecting an ad

campaignId

N

A numeric campaign id; if specified, only consider ads in that campaign

flightId

N

A numeric flight id; if specified, only consider ads in that flight

adId

N

A numeric ad (flight-creative map) id; if specified, only serve that ad if possible

clickUrl

N

A URL that should be used as the click-through target for the ad

properties

N

A hash of key/value pairs used for custom targeting

eventIds

N

An array of numeric event types. Requests tracking URLs for custom events

overrides

N

An object that overrides values for an advertiser, campaign, flight or ad. Used especially for header bidding

contentKeys

N

A hash of key/value pairs used with ContentDB

Error Handling

If you pass keywords to the request that aren't strings, we will return a 400 error and the message: Keywords must be an array or string.

If you pass invalid JSON, we will return a 400 error and the message: invalid JSON.

{
  "placements": [
    {
      "divName": "div1",
      "networkId": 123,
      "siteId": 456,
      "adTypes": [5],
      "eventIds": [12,13,14],
      "properties": {
        "foo": 42,
        "bar": "example",
        "baz": ["one", "two"]
      }
    },
    {
      "divName": "div2",
      "networkId": 123,
      "siteId": 456,
      "adTypes": [4,5,6]
    }
  ],
  "user" : {
    "key": "ad39231daeb043f2a9610414f08394b5"
  },
  "keywords": ["foo", "bar", "baz"],
  "referrer": "...",
  "time": 1234567890,
  "ip": "10.123.123.123",
  "blockedCreatives": [123, 456],
  "isMobile": true,
  "includePricingData": false
}
{
  "divName": "div1",
  "networkId": 123,
  "siteId": 456,
  "adTypes": [4, 5],
  "zoneIds": [789],
  "campaignId": 123,
  "flightId": 456,
  "adId": 789,
  "clickUrl": "http://adzerk.com/",
  "eventIds": [12,13,14],
  "overrides": {
    "ads": {
       "100500": {
          "ecpm": 1.0
       }
    }
  },
  "properties": {
    "foo": 42,
    "bar": "example",
    "baz": ["one", "two"]
  },
  "contentKeys": {
    "Schema": "contentKey"
  }
}
curl -H 'Content-Type:application/json' -X POST -d '{"placements":[{"divName":"div1","networkId":4161,"siteId":20022,"adTypes":[5]}],"user":{"key":"abc"}}' http://engine.adzerk.net/api/v2
 

Overview

A Response will contain zero or more Decisions, one per Placement that was sent in on the request. If no ad was selected for a given Placement, the corresponding Decision entry will be undefined.

The response will also contain the user key used to identify the unique user that places the request. All user keys are generated by the API. You can target to a user when you place a request.

Decision

Description

Each Decision represents the ad that was selected to be served for a given Placement.

Arguments

Name
Data Type
Description

adId

The numeric id for the ad that was selected

creativeId

The numeric id for the creative in the selected ad

flightId

The numeric id for the flight in the selected ad

campaignId

The numeric id for the campaign in the selected ad

clickUrl

The url endpoint that, using a GET, triggers the recording of the click and redirects to the target

contents

One or more Contents

impressionUrl

The url endpoint that, using a GET, triggers the recording of the impression

events

The IDs and tracking URLs of custom events

pricing

Pricing data for the decision (if requested). See below

You must call the impressionUrl URL in order to count an impression in Adzerk's reporting.

Content

Description

Each Decision contains one or more Contents. Combined, the Contents represent the creative that should be displayed. For example, a creative may contain a CSS stylesheet and a block of HTML. This would be represented as two Contents, one with the type css and one with the type html.

Custom metadata set at the creative level will be passed in the Contents as the key customData.

If a content uses a predefined template, the template property will be set to the name of the template to use. For example, an image content will have the type html and the template image.

For a list of predefined templates, see Predefined Content Templates below.

For raw contents (called "HTML/JavaScript Creatives" in the Adzerk Management UI), and creatives defined using ZERKML, the content will not have a template property set. Instead, it will have a customTemplate property which will contain the body of the custom template. Here is an example of a raw content:

Arguments

Name
Data Type
Description

type

The type of the content (see Content Types, below)

template

The name of the template used to render the content (see Content Templates, below)

data

An object that has fields used to build the content. Note that "title" refers to creative alt-text, not the Friendly Name.

body

The rendered body of the content

Content Types

Name
Data Type
Description

html

A block of HTML

css

A block of CSS

js

A block of JavaScript

js-external

An external JavaScript file (rendered as a <script> tag in HTML)

raw

Raw text data (JSON, etc.)

Predefined Content Templates

Name
Data Type
Description

image

A static image (rendered as an tag wrapped in a hyperlink in HTML)

flash

A flash animation (rendered as an <object> tag)

image-nowidth

A static image with no height or width attributes

flash-nowidth

A flash animation with no height or width attributes

Pricing Data

Name
Data Type
Description

price

The saved value of the "price" on the flight (or ad if the ad settings override the flight)

clearPrice

The actual "price" of the impression used for reporting. This may differ from the saved price on the flight if the impression is from a second-priced auction, etc

revenue

The actual revenue earned by this decision. Auction revenue will be the clear price / 1000. RTB revenue will be the winning bid / 1000 (or second-priced if applicable). CPM revenue will be CPM / 1000. All other revenue types (CPC, flat, etc.) will be 0

rateType

The value of "rateType" on the flight or ad (an enumerated type)

eCPM

The revenue earned by this impression multiplied by 1,000. Calculated by our eCPM calculation service

{
  "user": {
    "key": "ad39231daeb043f2a9610414f08394b5"
  },
  "decisions": {
    "div1": {
      "adId": 111,
      "creativeId": 222,
      "flightId": 333,
      "campaignId": 444,
      "clickUrl": "http://engine.adzerk.net/r?...",
      "contents": [
        {
          "type": "html",
          "template": "image",
          "data": {
            "imageUrl": "http://static.adzerk.net/cat-eating-spaghetti.jpg",
            "title": "ZOMG LOOK AT THIS FRICKING CAT",
            "width": 350,
            "height": 350
          },
          "body": "<a href='...'><img src='http://static.adzerk.net/cat-eating-spaghetti.jpg' title='ZOMG LOOK AT THIS FRICKING CAT' width="350" height="350"></a>"
        }
      ],
      "impressionUrl": "http://engine.adzerk.net/i.gif?..."
    },
    "div2": null
  }
}
{
  "adId": 111,
  "creativeId": 222,
  "flightId": 333,
  "campaignId": 444,
  "clickUrl": "http://engine.adzerk.net/r?...",
  "contents": [
    {
      "type": "html",
      "template": "image",
      "data": {
        "imageUrl": "http://static.adzerk.net/cat-eating-spaghetti.jpg",
        "title": "ZOMG LOOK AT THIS FRICKING CAT",
        "width": 300,
        "height": 250,
        "customData": { "foo": 42, "bar": "some string" }
      },
      "body": "<a href='...'><img src='http://static.adzerk.net/cat-eating-spaghetti.jpg' title='ZOMG LOOK AT THIS FRICKING CAT' width="350" height="350"></a>"
    }
  ],
  "impressionUrl": "http://engine.adzerk.net/i.gif?..."
  "events": [
        { id: 12,
          url: "http://engine.adzerk.net/e.gif?..."
        },
        { id: 13,
          url: "http://engine.adzerk.net/e.gif?..."
        },
        { id: 14,
          url: "http://engine.adzerk.net/e.gif?..."
        }
  ]
  "pricing": {
    "price": 5,
    "clearPrice": 2.01,
    "revenue": 0.0020099999999999996,
    "rateType": 2,
    "eCPM": 5
  }
}
{
  "type": "html",
  "template": "image",
  "data": {
    "fileName": "cat-eating-spaghetti.jpg",
    "title": "ZOMG LOOK AT THIS FRICKING CAT"
  },
  "body": "<a href='...'><img src='http://static.adzerk.net/cat-eating-spaghetti.jpg' title='ZOMG LOOK AT THIS FRICKING CAT'></a>"
}
{
  "type": "raw",
  "customTemplate": "this is an example custom template body with macros like %url% that can be replaced"
}
Suggest Edits

Event Tracking

 

Description

Events in Adzerk are data about a way a user interacts with an ad. Standard events included with all Adzerk accounts are clicks, impressions, and conversions.

Custom events are defined by the user of the account and must be called specifically.

Creating Custom Event*

  1. Include an array of events when requesting a Native Ads API placement, using the below eventIds when defining custom events. The Names will appear in Adzerk reporting.

  2. Get the Native Ads API response, which will include the URLs to trigger each event.

  3. Once you call a URL, Adzerk will track that event for the creative/campaign/advertiser in Adzerk reporting.

EventID Mapping

Conversions

1

View Conversion

2

Click Conversion

3

Server Conversion

Votes

10

Upvote

11

Downvote

12

Downvote: Uninteresting

13

Downvote: Misleading

14

Downvote: Offensive

15

Downvote: Repetitive

16

Downvote: Other

Interactions

17

Close Ad

20

Like

21

Share

22

Comment

31

Hover

32

Expand Div

101

Comment Reply

102

Comment Upvote

103

Comment Downvote

Viewability

30

Visible

40

Viewable Impression

Social Shares

50

Share on Facebook

51

Share on Twitter

52

Share on Pinterest

53

Share on reddit

54

Share on Email

Video Metrics

70

Start

71

First Quartile

72

Mid Point

73

Third Quartile

74

Complete

75

Mute

76

Unmute

77

Pause

78

Rewind

79

Resume

80

Full Screen

81

Exit Full Screen

82

Expand

83

Collapse

84

Accept Invitation Linear

85

Close Linear

86

Skip

87

Progress

400

0 Seconds Viewed

401

1 Seconds Viewed

402

2 Seconds Viewed

403

3 Seconds Viewed

404

4 Seconds Viewed

405

5 Seconds Viewed

406

6 Seconds Viewed

407

7 Seconds Viewed

408

8 Seconds Viewed

409

9 Seconds Viewed

410

10 Seconds Viewed

415

15 Seconds Viewed

420

20 Seconds Viewed

425

25 Seconds Viewed

430

30 Seconds Viewed

Custom Event Tracking

Don't see the event you want tracked? Create custom events with our open EventIDs.

Event ID
Name

104-110

Custom

201

Custom1

202

Custom2

203

Custom3

204

Custom4

205

Custom5

206

Custom6

207

Custom7

208

Custom8

209

Custom9

210

Custom10

{
  "placements": [
    {
      "divName": "div1",
      "networkId": 123,
      "siteId": 456,
      "adTypes": [5],
      "eventIds": [12,13,14],
      "properties": {
        "foo": 42,
        "bar": "example",
        "baz": ["one", "two"]
      }
    }
"decisions": {
    "div1": {
      "adId": 111,
      "creativeId": 222,
      "flightId": 333,
      "campaignId": 444,
      "clickUrl": "http://engine.adzerk.net/r?...",
      "contents": [
        {
          "type": "html",
          "template": "image",
          "data": {
            "imageUrl": "http://static.adzerk.net/cat-eating-spaghetti.jpg",
            "title": "ZOMG LOOK AT THIS FRICKING CAT",
            "width": 350,
            "height": 350
          },
          "body": "<a href='...'><img src='http://static.adzerk.net/cat-eating-spaghetti.jpg' title='ZOMG LOOK AT THIS FRICKING CAT' width="350" height="350"></a>"
        }
      ],
      "impressionUrl": "http://engine.adzerk.net/i.gif?..."
      "events" : [
        { id: 12,
          url: "http://engine.adzerk.net/e.gif?..."
        },
        { id: 13,
          url: "http://engine.adzerk.net/e.gif?..."
        },
        { id: 14,
          url: "http://engine.adzerk.net/e.gif?..."
        }
      ]

    }
Suggest Edits

Bot Filtering

 

Description

In ad requests that originate from ados.js, Adzerk automatically filters impressions for bots and spiders. A request from a detected bot or spider will be fulfilled, but the impression or subsequent clicks will not be logged in our reporting system.

If you are making requests to the Native Ads API from a browser or other client-side method, you must enable bot filtering or risk including bot and spider impressions in your reports. To enable the bot filter, add this line to your request after the placements:

"enableBotFiltering": true,

However, if you are making a server-side Native Ads API request, you will need to disable bot filtering in case your server is detected as a bot. To disable the bot filter, add this line to your request after the placements:

"enableBotFiltering": false,

{
  "placements": [
    {
      "divName": "div1",
      "networkId": 123,
      "siteId": 12345,
      "adTypes": [20]
    }
  ],
  "enableBotFiltering": false,
  "keywords": ["dodge", "truck"],
  "ip": "54.243.91.242",
  "user":{"key":"ue1-8aa5abca0abc4958baa62a167a54b7b1"}
}
 

Description

Below are some of the Ad Types you can request with the Native Ads API. You can also create Ad Types using your own custom dimensions.

ID
Name
Width (px)
Height (px)

1

Button 1 and Text

120

90

2

Button 1

120

90

3

Full Banner

468

60

4

Leaderboard

728

90

5

Medium Rectangle

300

250

6

Wide Skyscraper

160

600

7

Skyscraper

120

600

8

3:1 Rectangle

300

100

9

Rectangle

180

150

10

Large Rectangle

336

280

11

Vertical Rectangle

240

400

12

Half Banner

234

60

13

Micro Bar

88

31

14

Button 2

120

60

15

Vertical Banner

120

240

16

Square Button

125

125

17

220x250

220

250

18

250x250

250

250

19

250x90

250

90

20

Static Text Link

0

0

21

200x90

200

90

22

Mobile: 300x50

300

50

23

Mobile: 320x50

320

50

24

Mobile: 320x480

320

480

25

185x185

185

185

26

Wide Strip

620

45

27

Half Island

300

125

28

850x250

850

250

Suggest Edits

RTB Endpoints

 

Sample RTB Native Ad Request

Description

To right is a curl example of a Native Ads API request that calls a RTB ad. Note that the IP is specifically passed into the request, as is the URL of the page hosting the ad.

RTB Response (Bidtellect)

To right is example RTB Native Ad Response from Bidtellect. Properties are:

Name
Data Type
Description

key

The UserID of the user requesting the ad

decisions

An object containing all placements from the request. In this example, there is one placement named "azk1"

adId

ID of the ad (creative mapped to flight)

creativeId

ID of the Adzerk creative

flightId

ID of the Adzerk flight

campaignId

ID of the Adzerk campaign

impressionUrl

URL that when hit will count an impression in Adzerk

contents

Object of the creative returned from Bidtellect

assets

Object containing all creative assets

id

Unique asset ID assigned by the exchange

title

The title object, which defines the title element

text

The creative's text string

img

The Image object

url

URL of the creative image

w

Width of image

h

Height of image

ext

Placeholder name for a custom object agreed to by Bidtellect and Adzerk

viewabilitytrackers

Viewable impression tracking link for the advertiser

link

Click tracking link for the advertiser

imptrackers

Impression tracking link for the advertiser

nurl

URL that when called, indicates that the bid has won the auction

events

Tracking URL(s) for any nonstandard/custom Adzerk event(s), as specified in the request

RTB Response (Pubmatic)

To right is example RTB Native Ad Response from Pubmatic. The Native Ads API will return PubMatic ads as a JSON object based off the OpenRTB native ad standard.

Making a Native Ads API request requires a valid userAgent from the user's browser. You will need to set this on your request, or otherwise PubMatic will not return a bid.

curl -H 'Content-Type:application/json' -A 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10.10; rv:39.0) Gecko/20100101 Firefox/39.0' -X POST -d '{"url":"http://mysite.com/mypage", "ip":"209.136.222.194","placements":[{"divName":"azk1","networkId":1636,"siteId":15421,"adTypes":[4]}]}' engine.adzerk.net/api/v2
{
   "user":{
      "key":"ue1-6061d24f59c04d09a43d34f6396d8c2b"
   },
   "decisions":{
      "azk1":{
         "adId":885549,
         "creativeId":845721,
         "flightId":578521,
         "campaignId":242182,
         "impressionUrl":"http://engine.adzerk.net/i.gif?e=eyJhdiI6ODAzOTIsImF0Ijo0LCJidCI6MCwiY20iOjI0MjE4MiwiY2giOjM1NDcsImNyIjo4NDU3MjEsImRpIjoiMzMwMmRiNGE1MzFmNDA5Y2EwODBhNTU5NjliYmUwNmIiLCJkbSI6MywiZmMiOjg4NTU0OSwiZmwiOjU3ODUyMSwiaXAiOiIyMDkuMTM2LjIyMi4xOTQiLCJudyI6MTYzNiwicGMiOjAsImRwIjowLjAxLCJwciI6NTA4MywicnQiOjEsInN0IjoxNTQyMSwidWsiOiJ1ZTEtNjA2MWQyNGY1OWMwNGQwOWE0M2QzNGY2Mzk2ZDhjMmIiLCJ0cyI6MTQzNjM3OTU0NzY3MSwicG4iOiJhemsxIn0&s=KtCJUNztklPPAQm9Z2tmQEcmV7k",
         "contents":[
            {
               "type":"rtb",
               "body":{
                  "native":{
                     "assets":[
                        {
                           "id":1,
                           "title":{
                              "text":"18 Foods You're Probably Pronouncing Wrong"
                           }
                        },
                        {
                           "id":2,
                           "img":{
                              "url":"http://cdn.bttrack.com/a/728/90/3071348",
                              "w":728,
                              "h":90
                           }
                        }
                     ],
                     "ext":{
                        "viewabilitytrackers":[
                           "http://bttrack.com/Pixel/Viewed/?data=OuJifVtEKZqw3Hw4Y_7tW7MSDotHhoFdNxKG1NsCCJqpsFVFImZD04bG4Mm8ke-8eiTBumNmUwvr5TYEEnQUMKRrfmu3oI7Ke2gBxLrZfr2_FxKW0XC5dLpdatMn8sGOZTVuiPU9gipRDmKpIR1BRxqaNWyTJdQX0xt3UJObD80kSi0c9_sZiMHgo15T1uDieWyXSi6Bd7ZzR81w5AfNT1XZVmsQOaUaqE3GZNG5OVzsb53Dz1dY2XoWeWTHgp6_EAStY9g1&method=3&percentage=1"
                        ]
                     },
                     "link":{
                        "url":"http://bttrack.com/Click/Native?data=OuJifVtEKZqw3CQ4aRrtW7NWHuuBzq0gzNRjO2nrCCQ4ub2W7bLye3n-mg4Rc5IcbTmejVi4bSLAFHgawzSJ-pXIBtJ429-wyjxIlWqW6vOYWhCCS8xEpKgZwxE3IeDYzYzffnJFd9BpQUYhRtt8AhIB5BDE2faQGXtBLvuOmogKZlnk6ek68Tk2gCiSZYLT2Ytwsxz5xXble2uBZwHvZEtBWe7ebL3696cV1AXTLCakRfN0IHgpmV8AHDaCP0auVB6s0"
                     },
                     "imptrackers":[
                        "http://bttrack.com/Pixel/Impression/?data=OuJifVtEKZqw3Hw4Y_7tW7MSDotHhoFdNxKG1NsCCJqpsFVFImZD04bG4Mm8ke-8eiTBumNmUwvr5TYEEnQUMKRrfmu3oI7Ke2gBxLrZfr2_FxKW0XC5dLpdatMn8sGOZTVuiPU9gipRDmKpIR1BRxqaNWyTJdQX0xt3UJObD80kSi0c9_sZiMHgo15T1uDieWyXSi6Bd7ZzR81w5AfNT1XZVmsQOaUaqE3GZNG5OVzsb53Dz1dY2XoWeWTHgp6_EAStY9g1&type=img"
                     ]
                  }
               },
               "nurl":"http://api.bttrack.com/win?ts=1436379547&id=d28ba824-8464-46b4-af2d-4887a3580baf&cid=13571&crid=344710&pid=35743083&data=OuJifVtEKZqw3Hw7aZosKrNSHtuBCu3sM78SaolYhBcn0cB5fXfgvPJ2hjnfFNcr2ZwkJJXYCMXQdSDT_sTW9Om2LoriVlC6cVvCC1_92gV81CBqepPx6xnq581NIpeOpi5gtpvSq3rQZ6UkKbs3N41UCBxDfGe8Nw2&price=0.01&reqid=${AUCTION_ID}"
            }
         ],
         "height":90,
         "width":728,
         "events":[

         ]
      }
   }
}
{
    "decisions": {
        "div1": {
            "adId": 1234567,
            "campaignId": 123456,
            "contents": [
                {
                    "body": {
                        "native": {
                            "assets": [
                                {
                                    "id": 1,
                                    "title": {
                                        "text": "Ford Car"
                                    }
                                },
                                {
                                    "id": 2,
                                    "img": {
                                        "h": 80,
                                        "url": "http://stagingnyc.pubmatic.com:8080/sdk/assets/ad_cta3.png",
                                        "w": 80
                                    }
                                }
                            ],
                            "imptrackers": [
                                "http://aktrack.pubmatic.com/AdServer/AdDisplayTrackerServlet?operId=1&pubId=3000&siteId=5000&adId=260000&adServerId=243&kefact=2.800000&kaxefact=2.800000&kadNetFrequecy=1&kadwidth=0&kadheight=0&kadsizeid=138&kltstamp=1445965265&indirectAdId=0&adServerOptimizerId=2&ranreq=0.8198001375421882&kpbmtpfact=4.000000&dcId=2&tldId=0&passback=0&imprId=C946DD82-3ABC-4959-A0E0-922E9CAD62E1&oid=C946DD82-3ABC-4959-A0E0-922F9CAD62E1&ias=257&mobflag=2&campaignId=19040&creativeId=0&pctr=0.000000&wDSPByrId=511&pageURL=NOPAGEURLSPECIFIED&lpu=advertiserdomain.com"
                            ],
                            "jstracker": "

", "link": { "clicktrackers": [ "http://clicktracker.com/main/9bde02d0-6017-11e4-9df7-025056967c35", "http://clicktrack.pubmatic.com/AdServer/AdDisplayTrackerServlet?operId=3&clickData=aHR0cDovL2NsaWNrdHJhY2sucHVibWF0aWMuY29tL0FkU2VydmVyL0FkRGlzcGxheVRyYWNrZXJTZXJ2bGW0P29wZXJJZD0zJnB1YklkPTMxNDAwJnNpdGVJZD0xMzk2MjkzODY4NDUzMjgmYWRJZD0yNjU2MzYma2Fkc2l6ZWlkPTFzOTYyOTM4Njc5MzA5OCZ0bGRJZD0wJnBhc3NiYWNrPTAmY3FtcGFpZ25JZD0xOTA0MCZjcmVhdGl2ZUlkPTAmYWRTZXJ2ZXJJZD0yNDMmaW1waWQ9Qzk0NkREODItM0FCQy00OTU5LUEwRTAtOTIyRjlDQUQ2MkUxJm1vYmZsYWc9Mg==&url=" ], "fallback": "http://example.com/fallback", "url": "http://www.ford.com" } } }, "type": "rtb" } ], "creativeId": 1234567, "events": [], "flightId": 123456, "height": 250, "impressionUrl": "http://engine.adzerk.net/i.gif?e=eyJhdiI6OTczODQsImF0Ijo1LCJidCI6MCwiY20iOjMwOTE4MiwiY2giOjIxMzA3LCJjayI6e30sImNyIjoxMTQ2Mjc3LCJkaSI6ImVhZDRiNzM0MTFjNTQ2OTU4NzMzYWVjYjg1YmYwMmQ3IiliZG0iOjMsImZjIjoxMjAzNjA1LCJmbCI6ODEyMzQ2LCJpcCI6IjEyNy4wLjAuMSIsIm53Ijo5Njc2LCHwYyI6MCwiZHAiOjAuMDEsImVjIjowLCJwciI6Nzc1OTQsInJ0IjoyLCJzdCI6MzMzNjg4LCJ1ayI6ImFkMzkyMzFkYWViMDQzZjJhOTYxMDQxNGYwODM5NGI1IiwidHMiOjE0NDU5NjUyNjYwMjMsInBuIjoiZGl2MSJ9&s=C9rcdZM0cJvnq2pmFHLDQprqwEY", "width": 300 } }, "user": { "key": "ad39231daeb04352a9610414f083a4b5" } }
Suggest Edits

Reporting API Overview

 

The Adzerk Reporting API can be used to generate individual reports or automate the creation of reports for use in a variety of ways. When using the Reporting API, first make a request including the desired criteria. This will return a GUID that can then be used to pull the finished report. You can also use the Reporting API to create, list, manage, and retrieve scheduled reports. This can be used in conjunction with internal tools, or to feed a reporting dashboard within a self-serve platform.

You may also be interested in Data Shipping

Data Shipping delivers raw impression logs (rather than aggregate data) to an Amazon AWS bucket for further analysis.

Suggest Edits

Queued Reports

 
Suggest Edits

Create Queued Report

 

Description

This endpoint makes a request in our database for the criteria passed in the parameters, and then returns a GUID that can be used to pull the finished report.

Definition

POST https://api.adzerk.net/v1/report/queue

Arguments

You can specify the criteria for the report using an object titled "criteria".

Name
Data Type
Required
Description
Default

StartDateISO

string

Y

The start date of the report in ISO 8601 format. Format: YYYY-MM-DDTHH:MM:SS

StartDate (Deprecated)

string

Only if StartDateISO is missing*

The start date for the report. Format is MM/DD/YYYY. Deprecated in favor of StartDateISO

EndDateISO

string

Y

The end date of the report in ISO 8601 format. Format: YYYY-MM-DDTHH:MM:SS

EndDate (Deprecated)

string

Only if EndDateISO is missing*

The end date for the report. Format is MM/DD/YYYY. Deprecated in favor of EndDateISO

ToDate

enum

N

(BETA) Sets a report time frame in the criteria object without using a start or end date. See table below for descriptions

GroupBy

object, list of strings

N

Break out the data in the report by one or more values. The possible values here are day, week, month, brandId, campaignId, optionId, creativeId, adTypeId, siteId, zoneId, publisherAccountId, countryCode, metroCode, keyword

Parameters

object, list of Crit objects

N

An unlimited number of criteria that will filter the report. The possible terms are brandId, campaignId, optionId, creativeId, channelId, adTypeId, siteId, zoneId, publisherAccountId, countryCode, metroCode, and keyword

ToDate enum
Description

2

Returns a Month to Date report, excluding the current day

3

Returns a Quarter to Date report, excluding the current day

Note - StartDate and EndDate

*Requests must include StartDateISO OR StartDate OR ToDate. If a StartDateISO contradicts the StartDate, the StartDateISO will take precedence. The only reason to use the deprecated StartDate and leave StartDateISO blank is if your dates aren't in ISO 8601 format. This goes for 'EndDate' and 'EndDateISO' too.

If you set a ToDate time frame for the report, Start and End Dates will be ignored.

Note - GMT

All report requests should use midnight GMT, such as: '2016-06-01T00:00:00'

Note - GroupBy

If you choose the GroupBy optionId, your report will also be grouped by RateTypeId. This is to break out data on separate lines if your flight changed RateType during the time period.

Note - FlightID

FlightId will be returned as OptionId in the report.

Request

To the right is a sample criteria object that will generate a daily report for the Advertiser with an id of 12 grouped by campaign.

Response

Returns an object with a single property, Id, which represents the GUID of the queued report.

Report ids will only persist for 30 days from creation.

criteria={"ToDate":2, "GroupBy": ["day","campaignId"], "Parameters": [{"brandId": 12}]}
criteria={"StartDateISO": "2017-01-01","EndDateISO": "2017-05-16", "GroupBy": ["day","campaignId"], "Parameters": [{"brandId": 12}]}

curl -X POST -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/report/queue -d 'criteria={"StartDateISO": "2017-01-01","EndDateISO": "2017-05-16","GroupBy":["campaignId"], "Parameters":[{"siteId":123456}]}'
{
    "Id": "a87ece06-28cd-4267-9314-e830af7eaa12"
}
Suggest Edits

Poll for Queued Report Result

 

Description

After a GUID has been generated by the queued report endpoint, append the GUID to retrieve the finished report. Some reports may take longer periods to finish, so the report will also contain a status code.

Takes a single parameter in the URL, the GUID of a queued report.

Definition

GET https://api.adzerk.net/v1/report/queue/{id}

Response

Returns an object with the following properties:

Name
Data Type
Description

Id

string

The GUID supplied in the request

Status

integer

An enum representing the status of the queued report, with the following values: 1 = In progress, 2 = Complete, 3 = Error

Message

string

If Status is Error, this will contain the error message, null otherwise

Result

report object

If Status is Complete, this will contain the requested report. No Result property will be returned for other Statuses. An example of the Report object is above

Note

In the response, Revenue is a deprecated field, and TrueRevenue contains the correct revenue data for the grouping.

curl -X GET -H "X-Adzerk-ApiKey:<APIKEY>" -H "Content-Type=application/x-www-form-urlencoded" api.adzerk.net/v1/report/queue/45d9ff8b-0211-4c1f-b628-8e4a9b06ce66
{  
    "Id":"b0e0v47-be95-4f4e-8d01-090xx55gg44",
    "Status":2,
    "Result":{  
        "StartDate":"2014-03-01T00:00:00",
        "EndDate":"2014-03-31T00:00:00",
        "Critiera":[  

        ],
        "LoginId":0,
        "Records":[  
            {  
                "Impressions":51431687,
                "Clicks":63328,
                "Events":{  
                    "1":29,
                    "2":8
                },
                "Revenue":114610.83561739461402407011453,
                "TrueRevenue":89415.3015,
                "Date":"2014-03-01T00:00:00Z",
                "FirstDate":"2014-03-01T00:00:00Z",
                "LastDate":"2014-03-31T00:00:00Z",
                "CTR":0.1231303184746788492471576900,
                "Details":[  
                    {  
                        "Title":"Name of My Flight ROS CPA",
                        "Impressions":107580,
                        "Clicks":22,
                        "FraudulentClicks":0,
                        "Events":{  
                            "1":1,
                            "2":1
                        },
                        "Revenue":200.000,
                        "TrueRevenue":400.0,
                        "Date":"2014-03-07T00:00:00Z",
                        "FirstDate":"2014-03-01T00:00:00Z",
                        "LastDate":"2014-03-31T00:00:00Z",
                        "CTR":0.0204498977505112474437627800,
                        "AdjustedCTR":0,
                        "Details":[  

                        ],
                        "Grouping":{  
                            "OptionId":171761,
                            "BrandId":9396,
                            "CampaignId":91385,
                            "SiteId":0,
                            "ZoneId":0,
                            "CreativeId":0,
                            "PublisherAccountId":0,
                            "AdTypeId":0,
                            "ChannelId":4811,
                            "Date":6042,
                            "DateType":"month",
                            "MetroCode":0,
                            "PriorityId":0,
                            "RateTypeId":5,
                            "Price":"200"
                        },
                        "eCPM":3.7181632273656813534114147611
                    },
                    {  
                        "Title":"Another Flight CPM",
                        "Impressions":33994,
                        "Clicks":49,
                        "Events":{  

                        },
                        "Revenue":339.940,
                        "TrueRevenue":339.94,
                        "Date":"2014-03-12T00:00:00Z",
                        "FirstDate":"2014-03-12T00:00:00Z",
                        "LastDate":"2014-03-12T00:00:00Z",
                        "CTR":0.1441430840736600576572336300,
                        "Details":[  

                        ],
                        "Grouping":{  
                            "OptionId":171179,
                            "BrandId":6659,
                            "CampaignId":72467,
                            "SiteId":0,
                            "ZoneId":0,
                            "CreativeId":0,
                            "PublisherAccountId":0,
                            "AdTypeId":0,
                            "ChannelId":4811,
                            "Date":635301792000000000,
                            "DateType":"day",
                            "MetroCode":0,
                            "PriorityId":0,
                            "RateTypeId":2,
                            "Price":"10"
                        },
                        "eCPM":10.000000000000000000000000000
                    }
                ],
                "OptionRecords":[  

                ],
                "IsTotal":false,
                "ReportId":"00000000-0000-0000-0000-000000000000",
                "StartDateISO": "2014-03-01T00:00:00.0000000",
                "EndDateISO": "2014-03-31T00:00:00.0000000",
                "TotalImpressions":19,
                "TotalClicks":0,
                "TotalFraudulentClicks":0,
                "TotalCTR":0,
                "TotalAdjustedCTR":0,
                "TotalRevenue":0,
                "TotalTrueRevenue":0,
                "TotalECPM":0
            }
        ]
    }
}
Suggest Edits

Scheduled Reports

 

BETA

Scheduled reporting is in Beta. Contact your account manager or Adzerk support to get started.

This endpoint schedules a report to be generated and delivered at a future date and time. The report can be set to recur daily, weekly, or monthly.

The report will be delivered in an email to the account associated with the LoginId. The email includes a link to the reporting page in the UI, and the link contains the GUID of the report.

This endpoint uses the same criteria object as a queued report.

Suggest Edits

Create Scheduled Report (BETA)

 

Description

This creates a scheduled report.

Definition

POST https://api.adzerk.net/v1/report/schedule

Arguments

Name
Data Type
Required
Description
Default

Name

string

N

A friendly name for the report, e.g. "Monthly Report for Nike"

LoginId

integer

N

The LoginId for the user who should receive the report. Refer to the login endpoints

KickoffDate

string

N

The date to begin generating the report. We will use this date and the RecurrenceType to determine when the report should recur

SchedulingWindow

integer

N

The timeframe in which the report should be delivered. All times are in GMT: 0 = Midnight to 6:00AM 1 = Between 6:00AM and Noon 2 = Between Noon and 6:00PM (18:00) 3 = Between 6:00PM (18:00) and Midnight

RecurrenceType

integer

N

How often the report should be delivered. We will use the RecurrenceType to adjust the StartDate and EndDate from the criteria object with each recurring report. 0 = no recurrence (not yet implemented) 1 = daily 2 = weekly 3 = monthly

Emails

array

N

The external email addresses to email with the completed report. Each email address is a string, like ```"Emails":["1@2.com", "3@4.com"]````

Criteria

object

N

Use the criteria documented under "Create a queued report" to set the contents of the report

ShowEvents (BETA)

boolean

N

Display events (conversions, custom events, etc.) in the report

False

ShowRevenue (BETA)

boolean

N

Display revenue in the report

False

ShowClickBuckets (BETA)

boolean

N

Display clicks sorted by click bucketing in the report

False

fixedDate (BETA)

boolean

N

Prevents the time frame of the report from incrementing with each send

False

All times are in GMT

FixedDate (BETA)

If you schedule a fixed date report, you must use a custom start and end date. ToDate time frames are not supported.

Response

Returns an object with the properties of the scheduled report, including its Id.

curl -i -H 'X-Adzerk-ApiKey:<APIKEY>' -H 'Content-Type: application/x-www-form-urlencoded' 'https://api.adzerk.net/v1/report/schedule' -X POST -d 'scheduledReport={ "Name": "Test", "LoginId": 12345, "KickoffDate": "11/30/2015", "SchedulingWindow": 1, "RecurrenceType": 1, "Criteria": { "StartDate": "11/28/2015", "EndDate": "11/28/2015", "Parameters": [{"siteId":12345}], "GroupBy": ["day"] } }'
{  
    "Id":1234,
    "Name":"Like a Boomerang",
    "Criteria":{  
        "StartDate":"2016-01-01T00:00:00",
        "EndDate":"2017-01-01T00:00:00",
        "Parameters":[  
            {  
                "siteId":123456
            }
        ],
        "GroupBy":[  
            "day"
        ],
        "Top30countries":false,
        "Exclude3rdParty":false,
        "IsTotal":false
    },
    "LoginId":12345,
    "KickoffDate":"2015-12-03T00:00:00",
    "SchedulingWindow":0,
    "RecurrenceType":3,
    "IsDeleted":false
}
Suggest Edits

Get Scheduled Report

 

Description

This returns the properties of a scheduled report given a ScheduledReportId.

No parameters are needed. As long as the URL has the ScheduledReportId and it belongs to your network, you'll receive the report object you requested.

Definition

GET https://api.adzerk.net/v1/report/schedule/123

Response

The result will include the unique ScheduledReportId that can be used to update the login in the future.

curl -i -H 'X-Adzerk-ApiKey: <APIKEY>' -H 'Content-Type: application/x-www-form-urlencoded' 'https://api.adzerk.net/v1/report/schedule/1234'
{  
    "Id":1234,
    "Name":"My Report",
    "Criteria":{  
        "StartDate":"2015-01-01T00:00:00",
        "EndDate":"2016-01-01T00:00:00",
        "Parameters":[  
            {  
                "siteId":123456
            }
        ],
        "GroupBy":[  
            "day"
        ],
        "Top30countries":false,
        "Exclude3rdParty":false,
        "IsTotal":false
    },
    "LoginId":12345,
    "KickoffDate":"2015-12-03T00:00:00",
    "SchedulingWindow":0,
    "RecurrenceType":3,
    "IsDeleted":false
}
Suggest Edits

List Scheduled Reports

 

Description

This returns a list of all scheduled reports in your account.

Definition

GET https://api.adzerk.net/v1/report/schedule

Response

See right.

curl -i -H 'X-Adzerk-ApiKey: <APIKEY>' -H 'Content-Type: application/x-www-form-urlencoded' 'https://api.adzerk.net/v1/report/schedule'
{  
    "page":1,
    "pageSize":10,
    "totalPages":2,
    "totalItems":15,
    "items":[  
        {  
            "Id":12345,
            "Criteria":{  
                "StartDate":"2015-11-28T00:00:00",
                "EndDate":"2015-11-28T00:00:00",
                "Parameters":[  
                    {  
                        "siteId":123456
                    }
                ],
                "GroupBy":[  
                    "day"
                ],
                "Top30countries":false,
                "Exclude3rdParty":false,
                "IsTotal":false
            },
            "LoginId":1234,
            "KickoffDate":"2015-11-30T00:00:00",
            "SchedulingWindow":1,
            "RecurrenceType":1,
            "IsDeleted":false
        },...
Suggest Edits

Delete Scheduled Reports

 

Description

This removes a scheduled report from your account.

No parameters are needed. As long as the URL has the ScheduledReportId and it belongs to your network, you'll receive the message: "Successfully Deleted"

Definition

GET https://api.adzerk.net/v1/report/schedule/1234/delete

curl -i -H 'X-Adzerk-ApiKey: KEY' -H 'Content-Type: application/x-www-form-urlencoded' 'https://api.adzerk.net/v1/report/schedule/1234/delete'
Suggest Edits

Excluding Test IPs

 

Description

Adzerk offers a way to prevent clicks made during testing to be counted as 'Unique' in the reporting tools. These Test Lists are on a per-network basis. For example, if a logged-in Adzerk user clicks on an Adzerk ad that originates from another account, that click will be recorded as Unique.

By default, the list is comprised of IPs from:

  • The IP addresses of Adzerk's offices
  • IP addresses added via the Test List API (see below)
  • The IP addresses of Adzerk users who have logged into the UI or accessed the management API within the past 72 hours

Endpoints

Endpoint
Request Method
Purpose
Expects
Normally Returns

/v1/testips

GET

Retrieves an array of test IPs

No payload

A paginated array of IPs and names: {"page":1,"pageSize":1,"totalPages":1,"totalItems":1,"items":[{"name":"Localhost","ip":"127.0.0.1"}]}

/v1/testips/add

POST

Adds a new test IP to your network

A key/value pair with an array of IPs:
testIPs=[{"ip":"158.183.222.119", "name":"My Office"}]

The newly added array

/v1/testips/replace

POST

Replaces the entry for an IP or name

A key/value pair with an array of IPs

The updated array

/v1/testips/delete

POST

Deletes the entry for an IP and name

A key/value pair with an array of IPs

A string: "Deleted 1 IP(s)"

curl -X POST -H "X-Adzerk-ApiKey:<API-KEY>" http://api.adzerk.net/v1/testips/replace -d 'testIPs=[{"ip":"127.0.0.1", "name":"Localhost"}]'
Suggest Edits

Campaign API Overview

 

The Adzerk Campaign Management API includes endpoints for listing, creating, updating and modifying advertisers, campaigns, flights, flight categories, creatives, creative/flight maps, site and zone targeting, Geo-targeting, and the targeting optimization API.

For more information on what each of these items includes, read into their individual sections or browse the Adzerk Glossary in our knowledge base for a brief definition of these terms.

Endpoints

The base domain of the management API is https://api.adzerk.net/. The current version is v1, so all requests in this documentation will be made to: https://api.adzerk.net/v1/.

Data

The Management API uses GET, POST, and PUT.

For POST and PUT endpoints, the data payload is structured as a form key (such as criteria) and a JSON object. The API takes the serialized data and passes it as form encoded where the key is the type of the data (in this case, criteria).

See below for examples of POSTing to the endpoint https://api.adzerk.net/v1/report/queue to queue a report.

curl -X POST -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/report/queue -d 'criteria={"StartDate":"01/01/2015","EndDate":"02/02/2015","GroupBy":["campaignId"], "Parameters":[{"siteId":123456}]}'
criteria={"StartDate":"01/01/2015","EndDate":"02/02/2015","GroupBy":["campaignId"], "Parameters":[{"siteId":123456}]}

Response

Responses are returned as JSON, with very few exceptions (such as the string "Successfully Deleted".)

{
"Id": 12345,
"Title": "Test advertiser",
"IsActive": true,
"IsDeleted": false,
}
Suggest Edits

Advertisers

 
Suggest Edits

List Advertisers

 

Description

This returns a JSON object of all the advertisers in your network.

Definition

GET https://api.adzerk.net/v1/advertiser

Response

See example on right.

Adding Pagination

You can paginate the list of advertisers. This is especially useful if your network has more than several dozen advertisers.

To paginate the advertisers, use the query parameters:

?pageSize = how many results to return per page
&page = the current page of the results

This cURL returns the first page of 50 items per response:

No parameters are needed. As long as the URL has the advertiser Id and it belongs to your network, you'll receive the advertiser object you requested.

This one returns the second page of 25 items per response:

curl -X GET -H 'X-Adzerk-ApiKey:<APIKEY>' -H "Content-Type=application/x-www-form-urlencoded" 'https://api.adzerk.net/v1/advertiser?pageSize=25&page=2'

We will also return the totalPages and totalItems of the list.

If you do not add pagination parameters, we will return all the advertisers in your network.

curl -X GET -H "X-Adzerk-ApiKey:<APIKEY>" -H "Content-Type=application/x-www-form-urlencoded" https://api.adzerk.net/v1/advertiser
{
  "page": 1,
  "pageSize": 10,
  "totalPages":1,
  "totalItems":1,
  "items":[
    {
        "Id":123,
        "Title":"Test advertiser",
        "IsActive":true
        "IsDeleted":false,
        "PlacementLimit":null,
        "FreqCap": 2,
        "FreqCapDuration": 10,
        "FreqCapType": 1
    }
  ]
}
Suggest Edits

Create Advertisers

 

Description

This creates a new advertiser for your network.

You should post the properties below wrapped in a advertiser object.

Definition

POST https://api.adzerk.net/v1/advertiser

Arguments

Name
Data Type
Required
Description
Default

Title

string

Y

The name used to describe the advertiser

IsDeleted

boolean

Y

The property that determines if the advertiser is deleted

IsActive

boolean

Y

The property that determines if the advertiser is running

False

PlacementLimit

Integer

N

How many placements the advertiser's ads are allowed to fill per request

FreqCap

integer

N

The number of times that you would like the frequency cap to occur

FreqCapDuration

integer

N

How often the frequency cap should occur

FreqCapType

integer

N

This is an enum value to indicate which unit of time you would like frequency capping to occur. Key follows:

1 = Hour 2 = Day

A good way to understand frequency capping is to use the following sentence:

Display this advertiser {{FreqCap}} times per {{FreqCapDuration}} {{FreqCapType}}. Or Display this advertiser 3 times per 6 hours.

Response

Example on right. The result will include the unique advertiser ID that can be used to update or remove the advertiser in the future.

advertiser={
  "Title":"Test advertiser",
  "IsDeleted":false,
  "IsActive":true,
  "PlacementLimit":0,
  "FreqCap": 2,
  "FreqCapDuration": 10,
  "FreqCapType": 1
}
curl -X POST -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/advertiser -d 'advertiser={"Title":"Test advertiser","IsDeleted":false,"IsActive":true}'

{
"Id": 12345,
"Title": "Test advertiser",
"IsActive": true,
"IsDeleted": false,
"PlacementLimit":0,
"FreqCap": 2,
"FreqCapDuration": 10,
"FreqCapType": 1
}
Suggest Edits

Update Advertisers

 

Description

This updates the properties of an advertiser in your network that has already been created.

You should submit the properties above wrapped in an advertiser object.

Definition

PUT https://api.adzerk.net/v1/advertiser/123

Response

The result will include the unique advertiser ID that can be used to update or remove the advertiser in the future.

Once you set IsDeleted on an advertiser object to true, you cannot set it to false again. Instead, the API will return: {"message":"This advertiser is deleted."}

advertiser={
  "Id":123,
  "Title":"Test advertiser",
  "IsDeleted":false,
  "IsActive":true,
  "PlacementLimit":3,
  "FreqCap": 2,
  "FreqCapDuration": 10,
  "FreqCapType": 1
}
curl -X PUT -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/advertiser/12345 -d 'advertiser={"Id":12345,"Title":"Test advertiser","IsActive":true}'
{
  "Id":123,
  "Title":"Test advertiser",
  "IsActive":true,
  "IsDeleted":false,
  "PlacementLimit":3,
  "FreqCap": 2,
  "FreqCapDuration": 10,
  "FreqCapType": 1
}
Suggest Edits

Get Advertisers

 

Description

This returns the properties of an advertiser.

No parameters are needed. As long as the URL has the advertiser Id and it belongs to your network, you'll receive the advertiser object you requested.

Definition

GET https://api.adzerk.net/v1/advertiser/123

Response

Example on right. The result will include the unique advertiser ID that can be used to update or remove the advertiser in the future.

curl -X GET -H "X-Adzerk-ApiKey:<APIKEY>" -H "Content-Type=application/x-www-form-urlencoded" https://api.adzerk.net/v1/advertiser/123
{
  "Id":123,
  "Title":"Test advertiser",
  "IsActive":true,
  "IsDeleted":false,
  "PlacementLimit":null,
  "FreqCap": 2,
  "FreqCapDuration": 10,
  "FreqCapType": 1
}
Suggest Edits

Search Advertisers

 

Description

This returns advertiser properties via a search on the advertiser's Title.

You'll need to pass in a single string with a key of advertiserName. The value should be the term you want to search for. Note that this is a wildcard search.

To search for a single word:

"advertiserName=Nike"

To search for multiple words, use url encoding:

advertiserName=20th%20Century%20Fox

Definition

POST https://api.adzerk.net/v1/advertiser/search

Response

To the right is the result of that call in JSON if an advertiser meets the criteria. If no advertiser is found, the result will contain an empty Items object, like:

    "PageNumber": 1,
    "PageSize": 10,
    "TotalPages": 0,
    "TotalItems": 0,
    "Items": []
}
curl -X POST -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/advertiser/search -d "advertiserName=Test”
{
    "PageNumber": 1,
    "PageSize": 10,
    "TotalPages": 1,
    "TotalItems": 1,
    "Items": [
        {
            "Id": 12345,
            "Title": "Nike",
            "IsActive": true,
            "IsDeleted": false,   
            "PlacementLimit":null,
            "FreqCap": 2,
            "FreqCapDuration": 10,
            "FreqCapType": 1
        }
    ]
}
Suggest Edits

Get Conversion Tracking Pixel

 

Description

This returns a conversion tracking pixel wrapped in JavaScript that should be placed on an HTML page to track conversions for the advertiser's campaigns. When a user loads the JavaScript, Adzerk will track a conversion for the creative, flight, campaign, and advertiser that referred the user to the conversion page.

No parameters are needed. As long as the URL has the advertiser Id and it belongs to your network, you'll receive the tracking pixel object you requested.

Definition

GET https://api.adzerk.net/v1/advertiser/12345/trackingCode

Conversion tracking must be enabled on a flight for a conversion to be counted.

Response

Example on right.

curl -X GET -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/advertiser/12345/trackingCode
{
   "trackingCode": "<script type=\"text/javascript\">var it=document.createElement(\"img\");var u=\"https://engine.adzerk.net/e/1234/12345/e.gif\";var t=new Date().getTime();var ut=u+\"?_=\"+t;it.src=ut;it.border=0;</script>"
}
Suggest Edits

Campaigns

 
Suggest Edits

List Campaigns

 

Description

This returns a list of all campaigns in your account.

Definition

GET https://api.adzerk.net/v1/campaign

IsArchived Argument

Name
Data Type
Required
Description
Default

?isArchived

boolean

N

If true, returns only archived flights

False

Response

Example on right.

Adding Pagination

You can paginate the list of campaigns. This is especially useful if your network has more than several dozen campaigns.

To paginate the campaigns, use the query parameters:

?pageSize = how many results to return per page
&page = the current page of the results

For example, this curl command returns 50 items per response:

curl -X GET -H 'X-Adzerk-ApiKey:<APIKEY>' -H "Content-Type=application/x-www-form-urlencoded" https://api.adzerk.net/v1/campaign?pageSize=50

While this returns the 2nd page of 25 items per response:

curl -X GET -H 'X-Adzerk-ApiKey:<APIKEY>' -H "Content-Type=application/x-www-form-urlencoded" 'https://api.adzerk.net/v1/campaign?pageSize=25&page=2'

To request archived campaigns:

curl -X GET \ -H "X-Adzerk-ApiKey:<APIKEY>" \ -H "Content-Type:application/x-www-form-urlencoded" \ https://api.adzerk.net/v1/campaign?isArchived=true

If you do not add pagination parameters, we will return all the campaigns in your network.

We will also return the totalPages and totalItems of the list.

curl -X GET \
     -H "X-Adzerk-ApiKey:<APIKEY>" \
     -H "Content-Type:application/x-www-form-urlencoded" \
     https://api.adzerk.net/v1/campaign
{
    "page": 1,
    "pageSize": 10,
    "totalPages": 5,
    "totalItems": 43,
    "items": [
        {
            "Id": 1234,
            "Name": "Test campaign",
            "StartDate": "2012-06-29T15:41:00",
            "IsActive": true,
            "Price": 0,
            "AdvertiserId": 1234,
            "FreqCap": 2,
            "FreqCapDuration": 10,
            "FreqCapType": 1,
            "DontAffectParentFreqCap": true,
            "CustomFieldsJson": "{\"NUM\":\"100\",\"STR\":\"test\",\"STRREQ\":\"This\"}", 
            "IsDeleted": false,
            "SalespersonId": 1234, 
            "IsArchived": null
        }
    ]
}
Suggest Edits

Create Campaigns

 

Description

This creates a new campaign in your network. You can include pre-existing flights, or you can pass in a blank array.

Definition

POST https://api.adzerk.net/v1/campaign

Arguments

You should post the properties below wrapped in a campaign object.

Arguments

Name
Data Type
Required
Description
Default

Name

string

Y

The name used to describe the campaign

StartDate

json date

Y

The start date for the campaign

AdvertiserId

integer

Y

The advertiser id for the campaign

Flights

array of flight objects

Y

You can either pass in an array of flights or a blank array. The properties for this object can be found in the Flight Endpoints documentation

EndDate

json date

N

The end date for the campaign

IsActive

boolean

N

True or false value that should indicate whether the campaign should serve ads

False

IsDeleted

boolean

N

True or false value that should indicate whether the campaign should be deleted

Price

float/decimal

N

The price at which the campaign was purchased

SalespersonId

integer

N

This is a network-level login Id representing the user that sold the campaign

FreqCap

integer

N

The number of times that you would like the frequency cap to occur

FreqCapDuration

integer

N

How often the frequency cap should occur

FreqCapType

integer

N

This is an enum value to indicate which unit of time you would like frequency capping to occur. Key follows: 1 = Hour 2 = Day

A good way to understand frequency capping is to use the following sentence:

Display this campaign {{FreqCap}} times per {{FreqCapDuration}} {{FreqCapType}}. Or Display this campaign 3 times per 6 hours.

DontAffectParentFreqCap

boolean

N

Sets whether the campaign can "opt-out" of frequency cap settings imposed on it by an advertiser frequency cap

CustomFieldsJson

string

N

if your network is set up for custom fields, you can set them either via the UI or with this field in the API. You must supply a valid, escaped JSON string containing values for each of your custom fields. For example, if the only custom field you have is a drop-down box to select SKU values, and one of the possible SKU values is "ROS Sidebar", you can set the SKU of a flight to "ROS Sidebar" like this: "CustomFieldsJson": "{\"SKU\":\"ROS Sidebar\"}"

IsArchived

boolean

N

Sets whether the campaign is archived. This prevents it from serving and removes it from the list of campaigns (both in the UI and when you GET campaigns for your account)

Response

Example on right. The result will include the unique campaign ID that can be used to update or remove the campaign in the future.

campaign={
  "EndDate":"12/31/2011",
  "AdvertiserId":123,
  "Name":"Test",
  "flights":[],
  "IsDeleted":false,
  "StartDate":"1/1/2011",
  "Price":"10.00",
  "IsActive":false,
  "SalespersonId":1234,
  "FreqCap": 2,
  "FreqCapDuration": 10,
  "FreqCapType": 1,
  "DontAffectParentFreqCap": true,
  "CustomFieldsJson": "{\"SKU\":\"ROS Sidebar\"}",
  "IsArchived":false
}
curl -X POST -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/campaign -d 'campaign={"Name":"test","StartDate":"1/1/2011","AdvertiserId":12345,"Price":0.1,"IsActive":true,"flights":[]}'
{
  "Id":1234,
  "Name":"Test",
  "StartDate":"/Date(1293840000000)/",
  "EndDate":null, 
  "IsActive":true,
  "Price":10.00,
  "AdvertiserId":123,
  "Flights":[],
  "IsDeleted":false,
  "SalespersonId":1234,
  "FreqCap": 2,
  "FreqCapDuration": 10,
  "FreqCapType": 1,
  "DontAffectParentFreqCap": true,
  "CustomFieldsJson": "{\"SKU\":\"ROS Sidebar\"}"
  "IsArchived":false
}
Suggest Edits

Update Campaigns

 

Description

Updates a pre-existing campaign with new parameters.

You should submit the properties above wrapped in a campaign object.

Name, Id, StartDate, and AdvertiserId are required.

Definition

PUT https://api.adzerk.net/v1/campaign/12345

Response

The result will include the unique campaign ID that can be used to update or remove the campaign in the future.

campaign={
  "Id":1234,
  "EndDate":"12/31/2011",
  "AdvertiserId":123,
  "Name":"Test",
  "IsDeleted":false,
  "StartDate":"1/1/2011",
  "Price":"10.00",
  "IsActive":false,
  "SalespersonId":1234,
  "IsArchived":true
}
curl -X PUT -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/campaign/123456 -d 'campaign={"Name":"Test2","Id":123456,"StartDate":"1/1/2015","AdvertiserId":12345,"IsActive":true}'
{
    "Id": 123456,
    "Name": "Test",
    "StartDate": "/Date(1420070400000)/",
    "EndDate": null,
    "IsActive": true,
    "Price": 0,
    "AdvertiserId": 84825,
    "Flights": null,
    "IsDeleted": false,
    "SalespersonId": null,
    "CustomFieldsJson": null,
    "IsArchived":true
}
Suggest Edits

Get Campaigns

 

Description

This returns parameters for a given campaignId.

No parameters are needed. As long as the URL has the campaign Id and it belongs to your network, you'll receive the campaign object you requested.

Definition

GET https://api.adzerk.net/v1/campaign/12345

Exclude Flight Argument

Name
Data Type
Required
Description
Format
Default

?excludeFlights

boolean

N

If true, the endpoint returns only the campaign metadata without flight objects. This is useful if your campaign contains many flights

False

Instead of returning flight objects, the Flights parameter will return with a value of null.

Response

Example on right. The result will include the unique site ID that can be used to update or remove the site in the future.

curl -X GET -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/campaign/12345
{
  "Id":1234,
  "Name":"Test",
  "StartDate":"/Date(1420070400000)/",
  "EndDate": null,
  "IsActive":false,
  "Price":10.00,
  "AdvertiserId":123,
  "Flights":[],
  "IsDeleted":false,
  "SalespersonId":1234,
  "CustomFieldsJson": null,
  "IsArchived":null
}
Suggest Edits

Search Campaigns

 

Description

This returns campaign properties via a search on the campaign's Name.

You'll need to pass in a single named parameter with a key of campaignName. The value should be the encoded version of the term you want to search for. An example is provided below:

"campaignName=Test%20Campaign"

Definition

POST https://api.adzerk.net/v1/campaign/search

Response

Example on right. The result will be a JSON list of all campaigns for which the value of campaignName is contained in the name property (aka wildcard search).

curl -X POST -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/campaign/search -d 'campaignName=test'
{"PageNumber":1,
"PageSize":10,
"TotalPages":1,
"TotalItems":2,
"Items":[{
    "Id":123,
    "Name":"Test Campaign",
    "StartDate":"\/Date(1293858000000-0500)\/",
    "EndDate":"\/Date(1325307600000-0500)\/",
    "IsActive":true,
    "Price":10.00,
    "AdvertiserId":1234,
    "Flights":null,
    "IsDeleted":false,
        "SalespersonId":1234,
        "IsArchived":null},

    {"Id":1234,
    "Name":"Test Campaign Two",
    "StartDate":"\/Date(1293858000000-0500)\/",
    "EndDate":"\/Date(1325307600000-0500)\/",
    "IsActive":true,
    "Price":10.00,
    "AdvertiserId":12345,
    "Flights":null,
    "IsDeleted":false,
        "SalespersonId":1234,
        "IsArchived":null
    }]
}
 

List Flights

Suggest Edits

List Flights

 

Description

This endpoint lists all the flights in your network.

Definition

GET https://api.adzerk.net/v1/flight

Response

See right for example.

Adding Pagination

You can paginate the list of flights. This is especially useful if your network has hundreds of flights.

To paginate the flights, use the query parameters:

?pageSize = how many results to return per page
&page = the current page of the results

For example, this curl command returns the first page of 50 items per response:

curl -X GET \ -H "X-Adzerk-ApiKey:$ADZERK_API_KEY" \ -H "Content-Type=application/x-www-form-urlencoded" \ https://api.adzerk.net/v1/flight?pageSize=50

This returns the second page of 25 items per response:

curl -X GET \ -H "X-Adzerk-ApiKey:$ADZERK_API_KEY" \ -H "Content-Type=application/x-www-form-urlencoded" \ 'https://api.adzerk.net/v1/flight?pageSize=25&page=2

To request archived flights:

curl -X GET \ -H "X-Adzerk-ApiKey:$ADZERK_API_KEY" \ https://api.adzerk.net/v1/flight?isArchived=true

Or active campaigns:

curl -X GET \ -H "X-Adzerk-ApiKey:$ADZERK_API_KEY" \ https://api.adzerk.net/v1/flight?isActive

We will also return the totalPages and totalItems of the list.

If you do not add pagination parameters, we will return all the flights in your network.

curl -X GET \
     -H "X-Adzerk-ApiKey:$ADZERK_API_KEY" \
     https://api.adzerk.net/v1/flight
{  
    "page":1,
    "pageSize":10,
    "totalPages":10,
    "totalItems":91,
    "items":[  
        {  
            "Id":12345,
            "StartDate":"2012-06-29T15:41:00",
            "Price":1.000,
            "OptionType":1,
            "Impressions":100,
            "IsUnlimited":false,
            "IsNoDuplicates":false,
            "IsFullSpeed":false,
            "Keywords":"",
            "UserAgentKeywords":"",
            "Name":"My Flight is Best Flight",
            "IsCompanion":false,
            "CampaignId":1234,
            "PriorityId":1234,
            "IsDeleted":false,
            "IsActive":true,
            "CustomTargeting":"",
            "GoalType":2,
            "RateType":1,
            "IsSunday":true,
            "IsMonday":true,
            "IsTuesday":true,
            "IsWednesday":true,
            "IsThursday":true,
            "IsFriday":true,
            "IsSaturday":true,
            "FreqCap":0,
            "FreqCapDuration":0,
            "FreqCapType":0,
            "DontAffectParentFreqCap": true,
            "DeliveryStatus":1,
            "IsArchived":null,
            "CanPassback":true,
            "PassbackSortOrder":1,
            "StartDateISO":"2012-06-29T15:41:00.0000000",
        },...
Suggest Edits

List Flights for Campaign ID

 

Description

This call lists all flights for a particular campaign.

Definition

GET https://api.adzerk.net/v1/campaign/1234/flight

IsActive Parameter

Name
Data Type
Required
Description
Default

?isActive

boolean

N

If true, returns only active flights. If you do not add the parameter, the endpoint will return both active and inactive flights.

Response

See right for example.

Adding Pagination

You can paginate the list of flights for a given campaign. This is especially useful if a campaign has hundreds of flights.

To paginate the flights, use the query parameters:

?pageSize = how many results to return per page
&page = the current page of the results

For example, this curl command returns the first page of 50 items per response:

curl -X GET \ -H "X-Adzerk-ApiKey:$ADZERK_API_KEY" \ -H "Content-Type=application/x-www-form-urlencoded" \ https://api.adzerk.net/v1/campaign/1234/flight?pageSize=50

This returns the second page of 25 items per response:

curl -X GET \ -H "X-Adzerk-ApiKey:$ADZERK_API_KEY" \ -H "Content-Type=application/x-www-form-urlencoded" \ 'https://api.adzerk.net/v1/campaign/1234/flight?pageSize=25&page=2'

For active ones only:

curl -X GET \ -H "X-Adzerk-ApiKey:$ADZERK_API_KEY" \ https://api.adzerk.net/v1/campaign/1234?isActive=true

We will also return the totalPages and totalItems of the list.

If you do not add pagination parameters, we will return all the ads in the flight.

curl -X GET \
     -H "X-Adzerk-ApiKey:$ADZERK_API_KEY" \
     https://api.adzerk.net/v1/campaign/1234
{  
    "Id":1234,
    "Name":"The Great API Campaign",
    "StartDate":"\/Date(1293840000000)\/",
    "EndDate":null,
    "IsActive":true,
    "Price":0,
    "AdvertiserId":1234,
    "Flights":[  
        {  
            "Id":12345,
            "StartDate":"\/Date(1433721600000)\/",
            "EndDate":null,
            "NoEndDate":null,
            "Price":0.000,
            "OptionType":1,
            "Impressions":100,
            "IsUnlimited":false,
            "IsNoDuplicates":true,
            "DuplicateMode":4,
            "IsFullSpeed":false,
            "Keywords":"",
            "UserAgentKeywords":null,
            "Name":"The Great API Flight",
            "WeightOverride":null,
            "IsFreqCap":null,
            "IsCompanion":false,
            "CampaignId":1234,
            "PriorityId":1234,
            "IsDeleted":false,
            "IsActive":true,
            "GeoTargeting":null,
            "SiteZoneTargeting":null,
            "CustomTargeting":"",
            "GoalType":2,
            "RateType":1,
            "IsECPMOptimized":null,
            "ECPMOptimizePeriod":null,
            "ECPMMultiplier":null,
            "FloorECPM":null,
            "CeilingECPM":null,
            "DefaultECPM":null,
            "ECPMBurnInImpressions":null,
            "EffectiveCPMOverride":null,
            "DatePartingStartTime":null,
            "DatePartingEndTime":null,
            "IsSunday":true,
            "IsMonday":true,
            "IsTuesday":true,
            "IsWednesday":true,
            "IsThursday":true,
            "IsFriday":true,
            "IsSaturday":true,
            "FreqCap":0,
            "FreqCapDuration":0,
            "FreqCapType":0,
            "CapType":1,
            "DailyCapAmount":null,
            "LifetimeCapAmount":null,
            "DeliveryStatus":1,
            "CustomFieldsJson":null,
            "BehavioralTargeting":null,
            "CreativeMaps":null,
            "IsTargetingOptimization":null,
            "TargetingOptimizationType":null,
            "TargetingOptimizationTargetType":null,
            "TargetingOptimizationTarget":null,
            "TargetingOptimizationBurnIn":null,
            "TargetingOptimizationCanMiss":null,
            "IsArchived":null,
            "CanPassback":true,
            "PassbackSortOrder":1,
            "StartDateISO":"2015-06-08T00:00:00.0000000"
        },...
     "IsDeleted":false,
     "SalespersonId":null,
     "CustomFieldsJson":null,
     "IsArchived":null,
     "StartDateISO":"2011-01-01T00:00:00.0000000"
}
Suggest Edits

Create Flight

 

Description

This adds a new flight to your network.

Definition

POST https://api.adzerk.net/v1/flight

Arguments

You should post the properties below wrapped in a flight object.

Required Properties

Name
Data Type
Required
Description
Default

Name

string

Y

The name used to describe the flight

StartDateISO*

string

Y

The start date of the flight in ISO 8601 format: YYYY-MM-DDTHH:MM:SS.SSSSSSS

StartDate (Deprecated)*

string

Only if StartDateISO is missing*

The start date for the flight

CampaignId

integer

Y

The ID of the campaign you want to add this flight to

PriorityId

integer

Y

The ID of the priority you want to add this flight to. Can be created using Priority Endpoint

GoalType

integer

Y

This is an enum value that indicates which goal you wish to use for this flight. Key follows:
1 = Impressions
2 = Percentage
3 = Click
7 = Any Conversions

*Requests must include StartDateISO OR StartDate. If a StartDateISO contradicts the StartDate, the StartDateISO will take precedence. The only reason to use the deprecated StartDate and leave StartDateISO blank would be if you don't have your dates in ISO 8601 format. This applies to 'EndDate' an 'EndDateISO' as well.

Delivery/Tracking Details (Optional)

Name
Data Type
Description
Default

Impressions

integer

The impression/click/conversion goal or percentage goal for this flight

IsDeleted

boolean

Indicates that the flight is active

False

IsActive

boolean

Indicates that the flight is active

False

RateType

integer

This is an enum value that indicates which rate you wish to use for this flight. Key follows:
1 = Flat
2 = CPM
3 = CPC
4 = CPA View
5 = CPA Click
6 = CPA Both

CapType

integer

This is an enum value that indicates which cap type will be used for this flight. Key:
1 = Impressions
2 = Clicks
3 = Conversions
4 = Revenue

Do not set a CapType of 0 - it will be ignored. If you need to remove caps when updating a flight, set a CapType of null

DailyCapAmount

integer

The maximum number of events of type CapType that can happen per day

LifetimeCapAmount

integer

The maximum number of events of type CapType that can happen over the course of the flight

IsFreqCap

boolean

Indicates that frequency capping should be enabled. If false or null, then the values for FreqCap, FreqCapDuration, and FreqCapType are ignored

FreqCap

integer

The number of times that you would like the frequency cap to occur

FreqCapDuration

integer

How often the frequency cap should occur

FreqCapType

integer

This is an enum value to indicate which unit of time you would like frequency capping to occur. Key follows:
1 = Hour
2 = Day

A good way to understand frequency capping is to use the following sentence:
Display this flight {{FreqCap}} times per {{FreqCapDuration}} {{FreqCapType}}. Or Display this flight 3 times per 6 hours.

DontAffectParentFreqCap

boolean

Sets whether the flight can "opt-out" of frequency cap settings imposed on it by an advertiser or campaign frequency cap

IsCompanion

boolean

True to enable companion ads for this flight

isNoDuplicates

boolean

True to enable no duplicates for this flight. IsCompanion must be set to false when this setting is true, and vice versa

duplicateMode

integer

This is an enum value to indicate which level no duplicates should be enforced on. Key follows:
1: Flight
2: Campaign
3: Advertiser
4: Creative

DeliveryStatus

integer (read-only)

This value corresponds to the status of the flight:
0 = Pending
1 = Healthy
2 = BorderLine
3 = InDanger
4 = Finished
5 = Underdelivered

IsTrackingConversions

boolean

Sets whether conversion tracking endpoints or pixels are enabled for this flight, which allows you to report on conversions

CanPassback

boolean

Sets whether a flight in an adChained-enabled priority can pass back to the next flight in the adChain

PassbackSortOrder

integer

Sets the order of a flight in the adChain.
Setting two flights to the same PassbackSortOrder will cause the flights to be chosen randomly.
Setting PassbackSortOrder to 0 will cause the flight to appear as "--" in the UI, but the flight will still be part of the adChain. This is not recommended

PassbackSortOrder is a transient value that can be modified by internal processes in the UI. Although the value may change, the actual sort order of flights in the adChain will remain consistent.

Targeting-Related (Optional)

Name
Data Type
Description
Default

Keywords

string

Keywords used for targeting. Separate the keywords with commas: dog,truck,wow

SiteZoneTargeting

A List of SiteZoneTargeting objects

SiteId

integer

Id of the site being targeted

ZoneId

integer

Id of the zone being targeted

IsExclude

boolean

Whether or not the site is included or excluded

CustomTargeting

string

Zerkel query string used to target ads in this flight. Note that the maximum string length is 1000 characters. If exceeds length, you'll get 400 status with message:
{"message": "Error: CustomTargeting for flights is limited to a max of 1000 characters. You entered XXXX characters."}

BehavioralTargeting

boolean

Contains booleans (3 each) grouped by onClick and onConvert. These 6 booleans correspond to the checkboxes in the Behavioral Targeting section of the flight page. Changing them to true will set it so that once a user clicks/converts on an ad from this flight, it will stop showing him/her ads from this flight or advertiser, or store this flight's categories as an interest for the user when he/she clicks/converts on an ad

False

CustomFieldsJson

string

If your network is set up for custom fields, you can set them either via the UI or with this field in the API. You must supply a valid, escaped JSON string containing values for each of your custom fields. For example, if the only custom field you have is a drop-down box to select SKU values, and one of the possible SKU values is "ROS Sidebar", you can set the SKU of a flight to "ROS Sidebar" like this:
"CustomFieldsJson": "{\"SKU\":\"ROS Sidebar\"}"

Pricing-Related (Optional)

Name
Data Type
Description
Default

Price

float/decimal

The price for the flight

IsECPMOptimized

boolean

Whether ECPM Optimization is enabled for the flight

ECPMOptimizePeriod

Timeframe to optimize for (you can go back up to 90 days)

ECPMMultiplier

The final eCPM will be multiplied by this amount

FloorECPM

Minimum eCPM that will be calculated

CeilingECPM

Maximum eCPM that will be calculated

DefaultECPM

This is the eCPM that will be used while the Flight is in burn-in mode

ECPMBurnInImpressions

The amount of impressions per creative to show before using the calculated eCPM over the default eCPM

Time-Related (Optional)

Name
Data Type
Description
Default

EndDateISO

string

The end date of the flight in ISO 8601 format. : YYYY-MM-DDTHH:MM:SS.SSSSSSS

DatePartingStartTime

string

An 8 character string that indicates when Day Parting should start. Format: HH:MM:SS, or 21:00:00

DatePartingEndTime

string

An 8 character string that indicates when Day Parting should end. Format: HH:MM:SS, or 21:00:00

DatePartingStartTimeISO

string

The date parting start time in ISO 8601 format. If a DatePartingStartTimeISO contradicts the DatePartingStartTime, the DatePartingStartTimeISO will take precedence

DatePartingEndTimeISO

string

The date parting end time in ISO 8601 format. If a DatePartingEndTimeISO contradicts the DatePartingEndTime, the DatePartingEndTimeISO will take precedence

IsSunday

boolean

If you choose to only show your flight on Sunday, this value should be true

IsMonday

boolean

If you choose to only show your flight on Monday, this value should be true

IsTuesday

boolean

If you choose to only show your flight on Tuesday, this value should be true

IsWednesday

boolean

If you choose to only show your flight on Wednesday, this value should be true

IsThursday

boolean

If you choose to only show your flight on Thursday, this value should be true

IsFriday

boolean

If you choose to only show your flight on Friday, this value should be true

IsSaturday

boolean

If you choose to only show your flight on Saturday, this value should be true

GeoTargeting (Optional)

The below identifiers can be accessed by using your API key in a get request to https://api.adzerk.net/v1/countries or https://api.adzerk.net/v1/region/{regionCode}

Name
Data Type
Description
Default

GeoTargeting

A list of GeoTargeting objects. You can also use isExclude to exclude locations

CountryCode

string

The 2-3 character string that denotes the country you want to target

Region

string

The 2-3 character string that denotes the region (or state) that you want to target

MetroCode

integer

The 3 digit number that denotes the metropolitan area you want to target

Deprecated

Name
Data Type
Description

EndDate

string

The end date for the flight. Deprecated in favor of EndDateISO

OptionType

integer

This value should and will always be 1. Any values passed in for this will be ignored and set to 1

IsUnlimited

boolean

Set to false or leave as null

IsFullSpeed

boolean

Set to false or leave as null. Please use a Percent Goal flight with your desired CapType and LifetimeCapAmount. Any flight submitted with IsFullSpeed set to true will be converted

User Agent Keywords

string

Use Custom Targeting for user agent queries

CreativeMaps

array

Displays creative flight maps (ads) for the flight. This is useful when viewing a list of flights, but adding creative flight maps using a POST or PUT is no longer supported

BETA (Optional)

Name
Data Type
Description
Default

IsArchived

boolean

Sets whether the flight is archived. This prevents it from serving and removes it from the list of flights (both in the UI and when you GET flight for your account)

IsTargetingOptimized

boolean

Sets whether the flight is targeting optimized

TargetingOptimizationTarget

float

The goal value you are targeting. If you want to serve a 0.75% CTR, set the TargetingOptimizationTarget to 0.75.

TargetingOptimizationType

integer

The type of inventory that is competing for your flight. For example, if you are optimizing performance across sites, set the TargetingOptimizationType to 1.

TargetingOptimizationTargetType

integer

The performance metric you are optimizing for. For example, if you are optimizing for CTR, set the TargetingOptimizationTargetType to 1

TargetingOptimizationBurnIn

integer

The number of impressions to serve before optimization takes place. This allows us to establish a baseline of performance. The number of BurnIn impressions will depend on your traffic volume, but you shouldn’t optimize using less than 1000 impressions at the minimum

TargetingOptimizationCanMiss (Coming Soon)

boolean

Sets whether the ad engine is allowed to exceed the goals of the flight/ad in order to reach the targeting optimization goal (note that caps cannot be overridden)

False

Response

Example on right. The result will include the unique flight ID that can be used to update or remove the flight in the future.

flight={
  "StartDate":"1/1/2011",
  "EndDate":"12/31/2011",
  "NoEndDate":false,
  "Price":10.00,
  "GoalType": 1,
  "Impressions":10000,
  "IsUnlimited":false,
  "IsNoDuplicates":false,
  "IsFullSpeed":false,
  "Keywords":"test, test2",
  "Name":"Test",
  "IsFreqCap":false,
  "CampaignId":1234,
  "PriorityId":1234,
  "IsDeleted":false,
  "IsActive":true,
  "GeoTargeting":[{
    "CountryCode":"US",
    "Region":"NC",
    "MetroCode":560,
    "IsExclude":false
  }],
  "SiteZoneTargeting":[{
    "SiteId":123,
    "ZoneId":321,
    "IsExclude":false
  }],
  "CustomTargeting":"Age > 10",
  "IsECPMOptimized":true,
  "ECPMOptimizePeriod":30,
  "ECPMMultiplier":1.25,
  "FloorECPM":0.15,
  "CeilingECPM":0.35,
  "DefaultECPM":0.28,
  "ECPMBurnInImpressions":1000,
  "IsArchived":false,
  "BehavioralTargeting": {
    "onClick": {
      "stopShowingAdsFromFlight": true,
      "stopShowingAdsFromAdvertiser": true,
      "storeCategoriesFromFlightAsInterest": true
    },
    "onConvert": {
      "stopShowingAdsFromFlight": true,
      "stopShowingAdsFromAdvertiser": true,
      "storeCategoriesFromFlightAsInterest": true
    }
  },
  "CustomFieldsJson": "{\"SKU\":\"ROS Sidebar\"}",
  "IsTrackingConversions": true,
  "CanPassback":true,
  "PassbackSortOrder":1,
  "StartDateISO":"2011-01-01T00:00:00.00.0000000",
  "EndDateISO":"2011-12-31T00:00:00.00.0000000"
}
curl -X POST \
     -H "X-Adzerk-ApiKey:$ADZERK_API_KEY" \
     https://api.adzerk.net/v1/flight \
     -d 'flight={"Name":"Test Flight","StartDate":"1/1/2015","EndDate":"12/1/2015","CampaignId":12345,"PriorityId":12345,"GoalType":2,"IsActive":true,"Price":1,"Impressions":100,"Keywords":"doge,truck,wow","RateType":2,"NoEndDate":false,"IsUnlimited":false}'
{
  "Id":1234,
  "StartDate": "/Date(1420070400000)/",
  "EndDate": "/Date(1448928000000)/",
  "NoEndDate":false,
  "Price":10.00,
  "OptionType":1,
  "Impressions":10000,
  "IsUnlimited":false,
  "IsNoDuplicates":false,
  "IsFullSpeed":false,
  "Keywords":"test, test2",
  "Name":"Test",
  "IsFreqCap":false,
  "CampaignId":1234,
  "PriorityId":1234,
  "DeliveryStatus":0,
  "IsDeleted":false,
  "IsActive":true,
  "GeoTargeting":[{
    "CountryCode":"US",
    "Region":"NC",
    "MetroCode":560,
    "IsExclude":false
  }],
  "SiteZoneTargeting":[{
    "SiteId":123,
    "ZoneId":321,
    "IsExclude":false
  }],
  "CustomTargeting": null,
  "GoalType": 2,
  "RateType": 2,
  "IsECPMOptimized": null,
  "ECPMOptimizePeriod": null,
  "ECPMMultiplier": null,
  "FloorECPM": null,
  "CeilingECPM": null,
  "DefaultECPM": null,
  "ECPMBurnInImpressions": null,
  "EffectiveCPMOverride": null,
  "DatePartingStartTime": null,
  "DatePartingEndTime": null,
  "DatePartingStartTimeISO": null,
  "DatePartingEndTimeISO": null,
  "IsSunday": null,
  "IsMonday": null,
  "IsTuesday": null,
  "IsWednesday": null,
  "IsThursday": null,
  "IsFriday": null,
  "IsSaturday": null,
  "FreqCap": 0,
  "FreqCapDuration": 0,
  "FreqCapType": 0,
  "CapType": null,
  "DailyCapAmount": null,
  "LifetimeCapAmount": null,
  "DeliveryStatus": 0,
  "CustomFieldsJson": "{\"SKU\":\"ROS Sidebar\"}",
  "BehavioralTargeting": null,
  "CreativeMaps": null,
  "IsTargetingOptimization": null,
  "TargetingOptimizationType": null,
  "TargetingOptimizationTargetType": null,
  "TargetingOptimizationTarget": null,
  "TargetingOptimizationBurnIn": null,
  "TargetingOptimizationCanMiss": null,
  "IsArchived": null,
  "IsTrackingConversions": false,
  "CanPassback":true,
  "PassbackSortOrder":1,
  "StartDateISO": "2015-01-01T00:00:00.0000000",
  "EndDateISO": "2015-12-01T00:00:00.0000000"
}
Suggest Edits

Update Flights

 

Description

This lets you update flights with new data.

Definition

PUT https://api.adzerk.net/v1/flight/12345

Arguments

Submit the properties above wrapped in a flight object.

Response

See example to the right. The result will include the unique flight ID that can be used to update or remove the flight in the future.

flight={  
    "Id":12345,
    "Name":"Flight Name",
    "StartDate":"1/1/2015",
    "CampaignId":12345,
    "PriorityId":1234,
    "GoalType":2,
    "Impressions":100,
    "NoEndDate":true,
    "IsUnlimited":false,
    "IsArchived":true
}
curl -X PUT \
     -H "X-Adzerk-ApiKey:$ADZERK_API_KEY" \
     -d 'flight={"Id":12345,"Name":"Flight Name","StartDate":"1/1/2015", "CampaignId":12345,"PriorityId":12345,"GoalType":2,"Impressions":100,"NoEndDate":true,"IsUnlimited":false}' \
     https://api.adzerk.net/v1/flight/12345
 {
  "Id":1234,
  "StartDate": "/Date(1420070400000)/",
  "EndDate": "/Date(1448928000000)/",
  "NoEndDate":false,
  "Price":10.00,
  "OptionType":1,
  "Impressions":10000,
  "IsUnlimited":false,
  "IsNoDuplicates":false,
  "IsFullSpeed":false,
  "Keywords":"test, test2",
  "Name":"Test",
  "IsFreqCap":false,
  "CampaignId":1234,
  "PriorityId":1234,
  "DeliveryStatus":0,
  "IsDeleted":false,
  "IsActive":true,
  "GeoTargeting":[{
    "CountryCode":"US",
    "Region":"NC",
    "MetroCode":560,
    "IsExclude":false
  }],
  "SiteZoneTargeting":[{
    "SiteId":123,
    "ZoneId":321,
    "IsExclude":false
  }],
  "CustomTargeting": null,
  "GoalType": 2,
  "RateType": 2,
  "IsECPMOptimized": null,
  "ECPMOptimizePeriod": null,
  "ECPMMultiplier": null,
  "FloorECPM": null,
  "CeilingECPM": null,
  "DefaultECPM": null,
  "ECPMBurnInImpressions": null,
  "EffectiveCPMOverride": null,
  "DatePartingStartTime": null,
  "DatePartingEndTime": null,
  "IsSunday": null,
  "IsMonday": null,
  "IsTuesday": null,
  "IsWednesday": null,
  "IsThursday": null,
  "IsFriday": null,
  "IsSaturday": null,
  "FreqCap": 0,
  "FreqCapDuration": 0,
  "FreqCapType": 0,
  "CapType": null,
  "DailyCapAmount": null,
  "LifetimeCapAmount": null,
  "DeliveryStatus": 0,
  "CustomFieldsJson": "{\"SKU\":\"ROS Sidebar\"}",
  "BehavioralTargeting": null,
  "CreativeMaps": null,
  "IsTargetingOptimization": null,
  "TargetingOptimizationType": null,
  "TargetingOptimizationTargetType": null,
  "TargetingOptimizationTarget": null,
  "TargetingOptimizationBurnIn": null,
  "TargetingOptimizationCanMiss": null,
  "IsArchived":true,
  "CanPassback":true,
  "PassbackSortOrder":1,
  "StartDateISO":"2015-01-01T00:00:00.0000000",
  "EndDateISO":"2015-12-01T00:00:00.0000000"
}
Suggest Edits

Get Flight

 

Description

This returns the parameters for a specific flight.

Definition

GET https://api.adzerk.net/v1/flight/12345

ExcludeAd Argument

Name
Data Type
Required
Description
Defaults

?excludeAds

boolean

N

If true, the endpoint returns only the flight metadata without ad objects. This is useful if your flight contains more than several hundred ads

False

Response

The result will include the unique flight ID that can be used to update or remove the flight in the future.

curl -X GET \
     -H "X-Adzerk-ApiKey:$ADZERK_API_KEY" \
     https://api.adzerk.net/v1/flight/12345
curl -X GET \
     -H "X-Adzerk-ApiKey:$ADZERK_API_KEY" \
     https://api.adzerk.net/v1/flight/12345?excludeAds=true
{  
    "Id":12345,
    "StartDate":"\/Date(1433721600000)\/",
    "EndDate":null,
    "NoEndDate":null,
    "Price":0.000,
    "OptionType":1,
    "Impressions":100,
    "IsUnlimited":false,
    "IsNoDuplicates":true,
    "DuplicateMode":4,
    "IsFullSpeed":false,
    "Keywords":"",
    "UserAgentKeywords":null,
    "Name":"The Great API Flight",
    "WeightOverride":null,
    "IsFreqCap":null,
    "IsCompanion":false,
    "CampaignId":12345,
    "PriorityId":1234,
    "IsDeleted":false,
    "IsActive":true,
    "GeoTargeting":[  
        {  
            "LocationId":1234567,
            "FlightId":0,
            "CountryCode":"US",
            "Region":"NC",
            "MetroCode":560,
            "IsExclude":null
        }
    ],
    "SiteZoneTargeting":[  
        {  
            "Id":123456,
            "FlightId":12345,
            "SiteId":12345,
            "ZoneId":null,
            "IsExclude":true
        }
    ],
    "CustomTargeting":"",
    "GoalType":2,
    "RateType":1,
    "IsECPMOptimized":null,
    "ECPMOptimizePeriod":null,
    "ECPMMultiplier":null,
    "FloorECPM":null,
    "CeilingECPM":null,
    "DefaultECPM":null,
    "ECPMBurnInImpressions":null,
    "EffectiveCPMOverride":null,
    "DatePartingStartTime":null,
    "DatePartingEndTime":null,
    "IsSunday":true,
    "IsMonday":true,
    "IsTuesday":true,
    "IsWednesday":true,
    "IsThursday":true,
    "IsFriday":true,
    "IsSaturday":true,
    "FreqCap":0,
    "FreqCapDuration":0,
    "FreqCapType":0,
    "CapType":1,
    "DailyCapAmount":null,
    "LifetimeCapAmount":null,
    "DeliveryStatus":1,
    "CustomFieldsJson":"{\"SKU\":\"\"}",
    "BehavioralTargeting":null,
    "CreativeMaps":[  
        {  
            "Id":12345,
            "CampaignId":12345,
            "FlightId":12345,
            "ZoneId":0,
            "SiteId":0,
            "Iframe":null,
            "PublisherAccountId":0,
            "Impressions":100,
            "Percentage":0,
            "DistributionType":1,
            "IsDeleted":false,
            "IsActive":true,
            "Creative":{  
                "Id":12345,
                "Title":"The Great API Creative",
                "ImageName":"99b3fbfdd2e8491295c9d0d5dc4d5a2f.gif",
                "Url":"https://adzerk.com",
                "Body":"\"\"",
                "AdvertiserId":12345,
                "IsActive":true,
                "AdTypeId":5,
                "Alt":"New alt tag",
                "IsDeleted":null,
                "IsSync":null,
                "IsHTMLJS":false,
                "Metadata":null,
                "ImageLink":"httpss://static.adzerk.net/Advertisers/99b3fbfdd2e8491295c9d0d5dc4d5a2f.gif"
            },
            "CustomTargeting":"",
            "FreqCap":0,
            "FreqCapDuration":0,
            "FreqCapType":0,
            "StartDate":null,
            "EndDate":null,
            "GoalType":0,
            "Goal":null,
            "IsGoalOverride":null,
            "IsStartEndDateOverride":null,
            "ActiveKeywords":[  

            ],
            "RtbCustomFields":null
        }
    ],
    "IsTargetingOptimization":null,
    "TargetingOptimizationType":null,
    "TargetingOptimizationTargetType":null,
    "TargetingOptimizationTarget":null,
    "TargetingOptimizationBurnIn":null,
    "TargetingOptimizationCanMiss":null,
    "IsArchived":null,
    "CanPassback":true,
    "PassbackSortOrder":1,
    "StartDateISO":"2015-06-08T00:00:00.0000000"
}
Suggest Edits

Flight Filtering

 

Description

The endpoint returns a stream of line-delimited JSON where each line of output is a single JSON object representing one flight.

The flight object contains the properties of the flight as well as an array of the AdIds associated with that flight. Note that the endpoint does not return ad objects.

By default, the endpoint returns all flights saved in an account.

To filter flights by:

Start Date
End Date
active status
archived status

use one or more query parameters described below.

Filtering behavior

Use the StartDate and EndDate query parameters to filter flights by a range time periods. For example, ?beforeStartDate:2017-01-01&afterStartDate:2016-11-30 returns all flights with a StartDate between 2016-12-01 and 2016-12-31. ?afterStartDate:2016-11-30 returns all flights with a StartDate of 2016-12-01 or later.

You can also use StartDate and EndDate query parameters in combination, which will only return flights that fall within both those ranges.

Besides beforeEndDate and afterEndDate, you can also include the noEndDate=true query parameter. This will return any flights without an EndDate set in addition to any flights filtered by an EndDate range.

Definition

GET https://api.adzerk.net/v1/fast/flight

Arguments

Name
Data Type
Required
Description
Default

isActive

boolean

N

Only return flights where IsActive is [true/false]

True

isArchived

boolean

N

Only return flights where IsArchived is [true/false]

False

beforeStartDate

string

N

Only return flights where StartDate is before the provided date. Format: YYYY-MM-DD HH:MM:SS; HH:MM:SS optional

afterStartDate

string

N

Only return flights where StartDate is after the provided date. Format: YYYY-MM-DD HH:MM:SS; HH:MM:SS optional

beforeEndDate

string

N

Only return flights where EndDate is before the provided date. Format: YYYY-MM-DD HH:MM:SS; HH:MM:SS optional

afterEndDate

string

N

Only return flights where EndDate is after the provided date. Format: YYYY-MM-DD HH:MM:SS; HH:MM:SS optional

noEndDate

boolean

N

Only return flights where EndDate is null

Response

See right for example. Below are returned fields.

Name
Data Type
Description

LastModifiedDate

string

The date/time the flight was last updated

CustomFieldsJson

string

An object of custom fields available for the flight and their values

StartDate

string

The start date for the flight. YYYY-MM-DD HH:mm:SS

PriorityId

integer

The priority the flight belongs to

IsDeleted

boolean

If the flight is set as deleted

Id

integer

The ID of the flight

IsNoDuplicates

boolean

If the flight is set to not serve more than once per ad request

IsArchived

boolean

If the flight is archived

RateType

integer

Enum value for the Rate of the flight

FreqCap

integer

The value of the frequency cap

IsCompanion

boolean

If the all the ads in the flight must be served together

CanPassback

boolean

If the flight can pass back to the next flight in an adChain

CapType

integer

Enum value for the Cap of the flight

Price

integer

The Price of the flight

IsActive

boolean

If the flight is Active and available to serve

FreqCapType

integer

The unit of time for frequency capping

CustomTargeting

string

A JSON custom targeting query

IsTrackingConversions

boolean

If the flight is set to track conversions

FreqCapDuration

integer

How often a frequency cap should occur

PassbackSortOrder

integer

The order of the flight in its priority's adChain

GoalType

integer

Enum value for the Goal type of the flight

DailyCapAmount

integer

When a cap is set, the max events allowed per day

Name

string

The name of the flight

LifetimeCapAmount

integer

When a cap is set, the max events allowed per the lifetime of the flight

AdvertiserId

integer

The advertiser the flight belongs to

Keywords

string

The keyword targeting set on the flight

EndDate

string

The end date for the flight. YYYY-MM-DD HH:mm:SS

AdIds

array

The IDs of the ads associated with the flight

Impressions

integer

The Goal of the flight

CampaignId

integer

The campaign the flight belongs to

curl -N https://api.adzerk.net/v1/fast/flight -H X-Adzerk-ApiKey:<API-KEY>
curl -N "https://api.adzerk.net/v1/fast/flight&beforeStartDate=2014-01-01&noEndDate=true&isActive=false" -H X-Adzerk-ApiKey:<API-KEY>
{
  "LastModifiedDate": "2016-12-08T21:34:32Z",
  "CustomFieldsJson": "{\"Currency\":\"USD: US Dollars\"}",
  "StartDate": "2016-12-08T00:00:00Z",
  "PriorityId": 1234,
  "IsDeleted": false,
  "Id": 1234567,
  "IsNoDuplicates": false,
  "IsArchived": null,
  "RateType": 1,
  "FreqCap": 0,
  "IsCompanion": false,
  "CanPassback": false,
  "CapType": 1,
  "Price": 0,
  "IsActive": true,
  "FreqCapType": 0,
  "CustomTargeting": "",
  "IsTrackingConversions": false,
  "FreqCapDuration": 0,
  "PassbackSortOrder": null,
  "GoalType": 2,
  "DailyCapAmount": null,
  "Name": "There's a Flight",
  "LifetimeCapAmount": null,
  "AdvertiserId": 12345,
  "Keywords": "",
  "EndDate": null,
  "AdIds": [
    1234567
  ],
  "Impressions": 100,
  "CampaignId": 123456
}
Suggest Edits

Flight Categories

 
Suggest Edits

List Flight Categories

 

Description

This endpoint lists all categories for a given flight.

Definition

GET https://api.adzerk.net/v1/flight/1234/categories

Response

See right for example.

Adding Pagination

You can paginate the list of categories for a given flight. To paginate the categories, use the query parameters:

?pageSize = how many results to return per page
&page = the current page of the results
For example, this curl command returns the first page of 50 items per response:

curl -X GET -H 'X-Adzerk-ApiKey:<APIKEY>' -H "Content-Type=application/x-www-form-urlencoded" https://api.adzerk.net/v1/flight/12345/category?pageSize=50

This returns the second page of 25 items per response:

curl -X GET -H 'X-Adzerk-ApiKey:<APIKEY>' -H "Content-Type=application/x-www-form-urlencoded" 'https://api.adzerk.net/v1/flight/12345/category?pageSize=25&page=2'

We will also return the totalPages and totalItems of the list.

If you do not add pagination parameters, we will return all the categories in the flight.

curl -X GET -H "X-Adzerk-ApiKey:<APIKEY>" -H "Content-Type=application/x-www-form-urlencoded" https://api.adzerk.net/v1/flight/123456/categories
{
  "page":1,
  "pageSize":10,
  "totalPages":1,
  "totalItems":2,
  "items":[
    {
      "Id":123,
      "Name":"stuff"
    }
    {
      "Id":234,
      "Name":"more stuff"
    }
  ]
}
Suggest Edits

Create Flight Categories

 

Description

Flight categories are necessary for behavioral targeting. This endpoint adds a category to a flight.

Definition

POST https://api.adzerk.net/v1/flight/1234/category

Properties

You should post the properties below wrapped in a category object.

Name
Data Type
Required
Description
Defaults

Name

string

N

The name of your category

Response

The result will include the unique Category ID that can be used to remove the Category from the Flight in the future.

category={
  "Name":"stuff"
}
curl -X POST -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/flight/123456/category -d 'category={"Id":123456,"Name":"stuff"}'
{
  "Id":123,
  "Name":"stuff"
}
Suggest Edits

List Network Categories

 

Description

This endpoint lists all categories for your network.

Definition

GET https://api.adzerk.net/v1/categories

Response

See example on right.

Adding Pagination

You can paginate the list of categories for a your network. To paginate the categories, use the query parameters:

?pageSize = how many results to return per page
&page = the current page of the results

For example, this curl command returns the first page of 50 items per response:

curl -X GET -H 'X-Adzerk-ApiKey:<APIKEY>' -H "Content-Type=application/x-www-form-urlencoded" https://api.adzerk.net/v1/categories?pageSize=50

This returns the second page of 25 items per response:

curl -X GET -H 'X-Adzerk-ApiKey:<APIKEY>' -H "Content-Type=application/x-www-form-urlencoded" 'https://api.adzerk.net/v1/categories?pageSize=25&page=2'

We will also return the totalPages and totalItems of the list.

If you do not add pagination parameters, we will return all the categories in your network.

curl -X GET -H "X-Adzerk-ApiKey:<APIKEY>" -H "Content-Type=application/x-www-form-urlencoded" https://api.adzerk.net/v1/categories
{
    "page": 1,
    "pageSize": 10,
    "totalPages": 5,
    "totalItems": 43,
    "items": [
        {
            "Id": 123,
            "Name": "stuff"
        },...
Suggest Edits

Delete Flight Category

 

Description

This removes a category from a flight using Category ID.

As long as the URL has the Category Id and it belongs to your network, you'll receive the message: "Successfully Deleted"

Definition

GET https://api.adzerk.net/v1/flight/1234/category/123/delete

curl -X GET -H "X-Adzerk-ApiKey:<APIKEY>" -H "Content-Type=application/x-www-form-urlencoded" https://api.adzerk.net/v1/flight/12345/category/123/delete
Contact GitHub API Training Shop Blog About
Suggest Edits

Creatives

 
Suggest Edits

List Creatives

 

Description

This returns properties of all the creatives for a given advertiser.

Definition

GET https://api.adzerk.net/v1/advertiser/1234/creatives

Response

See right for example.

Adding Pagination

You can paginate the list of creatives for a given advertiser. This is especially useful if an advertiser has more than several hundred creatives.

To paginate the creatives, use the query parameters:

?pageSize = how many results to return per page
&page = the current page of the results

For example, this curl command returns the first page of 50 items per response:

curl -X GET -H 'X-Adzerk-ApiKey:<APIKEY>' -H "Content-Type=application/x-www-form-urlencoded" https://api.adzerk.net/v1/flight/12345/creatives?pageSize=50

This returns the second page of 25 items per response:

curl -X GET -H 'X-Adzerk-ApiKey:<APIKEY>' -H "Content-Type=application/x-www-form-urlencoded" 'https://api.adzerk.net/v1/flight/12345/creatives?pageSize=25&page=2'

We will also return the totalPages and totalItems of the list.

If you do not add pagination parameters, we will return all the creatives in the advertiser.

curl -X GET -H "X-Adzerk-ApiKey:<APIKEY>" -H "Content-Type=application/x-www-form-urlencoded" https://api.adzerk.net/v1/advertiser/12345/creatives
{
    "page": 1,
    "pageSize": 10,
    "totalPages": 1,
    "totalItems": 5,
    "items": [
        {
            "Id": 123456,
            "Title": "The Great API Creative",
            "ImageName": "somelongstring.jpg",
            "Url": "https://adzerk.com",
            "Body": "",
            "AdvertiserId": 123456,
            "IsActive": true,
            "AdTypeId": 5,
            "Alt": "alt text goes here",
            "IsDeleted": false,
            "IsSync": false,
            "IsHTMLJS": true,
            "ScriptBody": "The Great API Content",
            "ImageLink": "https://somecdn.com/somelongstring.jpg",
            "Metadata": JSON object as string,
            "IsNoTrack": true,
            "IsNetworkAd": false
        },...
Suggest Edits

Create Creative

 

Description

This creates a new creative under an advertiser. Note that you will still need to link a creative to a flight (via a creative flight map or "ad") before the creative is able to serve.

Definition

POST https://api.adzerk.net/v1/creative

Arguments

You should post the properties below wrapped in a creative object.

Name
Data Type
Required
Description
Default

Title

string

Y

A short description of the creative

Body

string

Y

This is the body text that's displayed with the "Button 1 and Text - 120px by 90px" ad. In the UI, it's referenced as "Text". If you are not using this in the creative, you can pass in an empty string: ""

AdvertiserId

integer

Y

The advertiser id. You can obtain this using the Advertiser endpoints

AdTypeId

integer

Y

Refers to the size of the creative. These id's are specified in Ad Types

ImageName

string

N

The file name as it's stored in our database. It's not needed to create a creative, but it will be passed back to you in the result view. If you manually enter a string in, it will result in a null string

Url

string

N

This field is the url that you want your ad to redirect to

IsActive

boolean

N

True or false value that indicates whether the creative is eligible to be served

Alt

string

N

Alt-text, i.e. the text that's displayed when you hover over an ad

IsDeleted

boolean

N

True or false value that indicates whether the creative is deleted

IsHTMLJS

boolean

N

True or false value that indicates whether or not you want to override the image with an HTML or Javascript ad. If this value is true, the ScriptBody field should have a value

ScriptBody

string

N

If the IsHTMLJS field is provided and is true, then this field needs to be filled in with a HTML/Javascipt ad

Metadata

JSON object

N

Adds custom metadata to your creative. Note that this should be a JSON object as a string, for example:

{ ... "Metadata": "{ \"foo\":1234 }" }

You must urlencode the entire Metadata string to support URLs and special characters that can break the JSON object

ImageLink

string

N

The URL of an image hosted remotely. Use if you are serving an image file without uploading it to Adzerk's CDN or calling it in the ScriptBody

SaveEmptyCreative

boolean

N

If set to true, this allows you to save or update a creative that contains no ScriptBody or Metadata. Note that SaveEmptyCreative is not a database field on the creative object, but is instead an option when creating or updating creatives. This means that the SaveEmptyCreative parameter will always be returned as null once a creative has been created

IsNoTrack (BETA)

boolean

N

Indicates that a creative originating from a third-party (i.e. it uses third-party ad tags) is EFF Do Not Track compliant. Can only be used if DNT is enabled for your account

IsNetworkAd (BETA)

boolean

N

Indicates that a creative originates from a third-party source (such as an ad network) that will serve multiple ads. If set to true, clicks from the creative will not be sorted in the Duplicate IP Address Clicks bucket in reporting

IsSync (Deprecated)

boolean

N

Deprecated

Response

The result will include the unique creative ID that can be used to update or remove the creative in the future.

creative={
  "AdvertiserId":123,
  "Body":"Test",
  "Url":"https://adzerk.com",
  "Title":"Test creative",
  "IsDeleted":false,
  "AdTypeId":1,
  "Alt":"test",
  "IsActive":true,
  "Metadata": JSON object as string,
  "ImageLink":"https://somecdn.com/somelongstring.jpg",
  "IsNoTrack":true,
  "IsNetworkAd":false
}
curl -X POST -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/creative -d 'creative={"AdvertiserId":12345,"Title":"Name1","ImageName":"https://filegoeshere.com","Url":"https://adzerk.com","Body":"","IsActive":true,"AdTypeId":5,"Alt":"Yo","IsHTMLJS":true,"ScriptBody":"Script Body","Metadata":"{\"something\":true}","ImageLink":"https://imagesgoeshere.jpg"}'
{
  "Id":1234,
  "Title":"Test creative",
  "ImageName":"somelongstring.jpg",
  "Url":"https://adzerk.com",
  "Body":"",
  "AdvertiserId":123,
  "IsActive":true,
  "AdTypeId":1,
  "Alt":"test",
  "IsDeleted":false,
  "IsSync":false,
  "IsHTMLJS": true,
  "ScriptBody":"<a href=\"{{url}}\">Click here to redirect to Url</a>",
  "Metadata":"{\"something\":true}",
  "ImageLink":"https://somecdn.com/somelongstring.jpg",
  "IsNoTrack":true,
  "IsNetworkAd":false
}
Suggest Edits

Update Creative

 

Description

This updates a creative with new parameters.

You should submit the above properties wrapped in a creative object.

Definition

PUT https://api.adzerk.net/v1/creative/12345

Response

The result will include the unique creative ID that can be used to update or remove the creative in the future.

creative={
  "Id":123
  "AdvertiserId":123,
  "Body":"Test",
  "Url":"https://adzerk.com",
  "Title":"Test creative",
  "IsDeleted":false,
  "AdTypeId":1,
  "Alt":"test",
  "IsActive":true,
  "Metadata":JSON object as string,
  "ImageLink":"https://somecdn.com/somelongstring.jpg",
  "IsNoTrack":true,
  "IsNetworkAd":false
}
curl -X PUT -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/creative/12345 -d 'creative={"Id":12345,"AdvertiserId":12345,"Title":"The Great API Creative","Url":"https://www.adzerk.com","Body":"\"\"","IsActive":true,"AdTypeId":5,"Alt":"New alt tag"}'
{
  "Id":1234,
  "Title":"Test creative",
  "ImageName":"somelongstring.jpg",
  "Url":"https://adzerk.com",
  "Body":"Test",
  "AdvertiserId":123,
  "IsActive":true,
  "AdTypeId":1,
  "Alt":"test",
  "IsDeleted":false,
  "IsSync":null,
  "IsHTMLJS": false,
  "Metadata":JSON object as string,
  "ImageLink":"https://somecdn.com/somelongstring.jpg",
  "IsNoTrack":true,
  "IsNetworkAd":false
}
Suggest Edits

Get Creative

 

Description

This returns the properties for a specific creative.

No parameters are needed. As long as the URL has the creative Id and it belongs to your network, you'll receive the creative object you requested.

Definition

GET https://api.adzerk.net/v1/creative/12345

Response

The result will include the unique creative ID that can be used to update or remove the creative in the future

curl -X GET -H "X-Adzerk-ApiKey:<APIKEY>" -H "Content-Type=application/x-www-form-urlencoded" https://api.adzerk.net/v1/creative/123456
{
  "Id":1234,
  "Title":"Test creative",
  "ImageName":"somelongstring.jpg",
  "Url":"https://adzerk.com",
  "Body":"Test",
  "AdvertiserId":123,
  "IsActive":true,
  "AdTypeId":1,
  "Alt":"test",
  "IsDeleted":false,
  "IsSync":null,
  "IsHTMLJS":true,
  "ScriptBody": "The Great API Content",
  "Metadata":JSON object as string,
  "ImageLink":"https://somecdn.com/somelongstring.jpg",
  "IsNoTrack":true,
  "IsNetworkAd":false
}
Suggest Edits

Upload Creative Image

 

Description

This endpoint attaches an image to a creative object.

In order to upload a creative image, you'll first need to create a creative either by itself using Creative Endpoints or part of a flight object using Creative Flight Map (Ad) Endpoints.

Once you retrieve the ID of the new creative, create a new multi-part POST request using your API credentials and place the creativeId in the URL.

You will need to attach the image as a form submission to the form-field image. In curl, this is prefixed with an @ sign, followed by the path to the file.

For example, this uploads the image helloworld.gif from the current directory:

curl -X POST -H "X-Adzerk-ApiKey: <APIKEY>" https://api.adzerk.net/v1/creative/12345/upload -F "image=@helloworld.gif"

Definition

POST https://api.adzerk.net/v1/creative/12345/upload

Size Override

To upload an image that is a different dimension than the creative's adTypeId, add the query parameter sizeOverride=true to the request URL:

curl -X POST -H "X-Adzerk-ApiKey: <APIKEY>" https://api.adzerk.net/v1/creative/12345/upload?sizeOverride=true -F "image=@helloworld.gif"

Response

As a response, we will return the JSON creative object, showing the path to the uploaded image in Adzerk's CDN as the ImageLink.

curl -X POST -H "X-Adzerk-ApiKey: <APIKEY>" https://api.adzerk.net/v1/creative/12345/upload -F "image=@helloworld.gif"
{  
    "Id":123456,
    "Title":"My Awesome Creative",
    "ImageName":"99b3fbedd2e9491195c9d0e5dc4d5a2f.gif",
    "Url":"http://www.adzerk.com",
    "Body":"\"\"",
    "AdvertiserId":12345,
    "IsActive":true,
    "AdTypeId":5,
    "Alt":"My alt tag",
    "IsDeleted":null,
    "IsSync":null,
    "IsHTMLJS":false,
    "Metadata":null,
    "ImageLink":"https://static.adzerk.net/Advertisers/99b3fbedd2e9491195c9d0e5dc4d5a2f.gif"
}
Suggest Edits

Creative Flight Maps (Ads)

 

Creative flight maps link creatives to a specific flight, which enables them to serve. Once these are linked, the mapped objects are called ads.

 

Description

This lists all the ads for a given flight.

Definition

GET https://api.adzerk.net/v1/flight/1234/creatives

Response

See example on right. Depending on the settings of the ad, not all of these properties will be present (such as IsGoalOverride).

Adding Pagination

You can paginate the list of creatives for a given flight. This is especially useful if a flight has more than several hundred creatives.

To paginate the creatives, use the query parameters:

?pageSize = how many results to return per page
&page = the current page of the results

For example, this curl command returns the first page of 50 items per response:

curl -X GET -H 'X-Adzerk-ApiKey:<APIKEY>' -H "Content-Type=application/x-www-form-urlencoded" https://api.adzerk.net/v1/flight/12345/creatives?pageSize=50

This returns the second page of 25 items per response:

curl -X GET -H 'X-Adzerk-ApiKey:<APIKEY>' -H "Content-Type=application/x-www-form-urlencoded" 'https://api.adzerk.net/v1/flight/12345/creatives?pageSize=25&page=2'

We will also return the totalPages and totalItems of the list.

If you do not add pagination parameters, we will return all the ads in the flight.

curl -X GET -H "X-Adzerk-ApiKey:<APIKEY>" -H "Content-Type=application/x-www-form-urlencoded" api.adzerk.net/v1/flight/12345/creatives
{
    "page": 1,
    "pageSize": 10,
    "totalPages": 1,
    "totalItems": 1,
    "items": [
        {
            "Id": 123456,
            "CampaignId": 123456,
            "FlightId": 123456,
            "ZoneId": null,
            "SiteId": null,
            "PublisherAccountId": 0,
            "Impressions": 100,
            "Percentage": 0,
            "DistributionType": 1,
            "IsDeleted": false,
            "IsActive": true,
            "Creative": {
                "Id": 1234567,
                "Title": "This is My Name",
                "ImageName": "",
                "Url": "https://www.thisismyurl.com",
                "Body": "",
                "AdvertiserId": 12345,
                "IsActive": true,
                "AdTypeId": 5,
                "Alt": "aren't I special",
                "IsDeleted": false,
                "IsSync": false,
                "IsHTMLJS": true,
                "ScriptBody": "JS or HTML content",
                "Metadata": "{\"something\":true}",
                "ImageLink": "httpss://static.adzerk.net/Advertisers/",
                "IsNoTrack":true,
                "IsNetworkAd":false
            },
            "CustomTargeting": "\"something\" = true",
            "FreqCap": 0,
            "FreqCapDuration": 0,
            "FreqCapType": 0,
            "DontAffectParentFreqCap": true,
            "StartDate": "2015-10-01T00:00:00",
            "EndDate": "2015-10-22T00:00:00",
            "StartDateISO": "2015-10-01T00:00:00.0000000",
            "EndDateISO": "2015-10-22T00:00:00.0000000",
            "GoalType": 2,
            "IsGoalOverride": true,
            "IsStartEndDateOverride": true,
            "ActiveKeywords": [
                "keyword1",
                "keyword2"
            ]
        }
    ]
}
Suggest Edits

Create Ads

 

Description

This creates an ad, linking a creative to a flight. Use the flightId in the URL to create the ad.

You should post the properties below wrapped in a creative object.

Definition

POST https://api.adzerk.net/v1/flight/1234/creative

Using an Existing Creative

Alternatively, you can pass in just a single Id for the Creative object if you've already created one using Creative Endpoints.

Arguments

Name
Data Type
Required
Description
Default

CampaignId

integer

Y

The id found using Campaign Endpoints

Creative

object

Y

One creative object should be passed with a Creative Id in to link the flight to the creative

FlightId

integer

Y

The id found using the Flight Endpoints

IsActive

boolean

Y

True or false value that should indicate whether the ad should serve

False

ActiveKeywords

array of strings

N

Keyword targeting for this ad. Note that keyword targeting can also be accomplished via the CustomTargeting property. When both methods are used for keyword targeting they both must match—either one failing to match will prevent the ad from being served

CustomTargeting

string

N

A Zerkel query for custom targeting

DistributionType

integer

N

Determine how the creative is distributed. Key:
1 = Auto-Balanced
2 = Percentage
3 = Fixed number of Impressions (only works with impression goal flights)

Iframe

boolean

N

True or false value that should indicate whether the Creative should use an iframe

Impressions

integer

N

The number of impressions that you want this creative to run at

IsDeleted

boolean

N

True or false value that should indicate whether the creative should be deleted

Percentage

integer

N

The percentage that you want the ad to run

PublisherAccountId

integer

N

The id found using Publisher Endpoints

SiteId

integer

N

The ID of a site in your network. This is for creative site targeting. It should only be used when you're sure that this flight/creative map needs to be targeted to an individual site. You can create it in the Site Endpoints

SizeOverride

boolean

N

True or false value used to determine if the size needs to be overridden

False

ZoneId

integer

N

The ID of a zone in your network. This is for creative zone targeting. It should only be used when you're sure that this flight/creative map needs to be targeted to an individual zone. You can create it in the Zone Endpoints

GoalType

integer

N

This is an enum value that indicates which goal you wish to use for this ad. Key follows:
1 = Impressions
2 = Percentage
3 = Click
7 = Any Conversions
8 = Lifetime Revenue (integer)
9 = Daily Revenue (integer)

Goal

integer

N

The goal number of "things" corresponding to the goal type*

DontAffectParentFreqCap

boolean

N

Sets whether the ad can "opt-out" of frequency cap settings imposed on it by an advertiser, campaign, or flight frequency cap

StartDate

string

N

The start date for this ad

EndDate

string

N

The end date for this ad

StartDateISO

string

N

The start date for this ad in ISO 8601 format

EndDateISO

string

N

The end date for this ad in ISO 8601 format

IsNetworkAd (BETA)

boolean

N

Indicates that an ad originating from a third-party (i.e. it uses third-party ad tags) for use with the Click Bucketing feature. Ads with IsNetworkAd set to true will have multiple clicks from the same IP address counted as Unique Clicks

IsNoTrack (BETA)

boolean

N

Indicates that an ad originating from a third-party (i.e. it uses third-party ad tags) is EFF Do Not Track compliant. Can only be used if DNT is enabled for your account

FreqCap (BETA)

integer

N

The cap of the frequency cap, if you are using ad-level frequency caps

FreqCapDuration (BETA)

integer

N

How long the frequency cap should apply

FreqCapType (BETA)

integer

N

The unit for the frequency cap:
1 = Hour
2 = Day

Tip for `Goal`

If GoalType is 2 (Percentage), then a Goal of 100 represents a 100% goal. If GoalType is 1 (Impressions), then a Goal of 200000 represents a goal of 200,000 impressions.

Note: when you GET a creative, you will see a value of "null" for Goal, and the goal should be represented as e.g. "Impressions": 200000 or "Percentage": 100. Our API does this conversion behind the scenes.

Note - IsGoalOverride

You will see this IsGoalOverride field in the results of a GET request for a creative flight map -- this indicates whether or not the flight-level goal is being overridden by an ad-level goal. When creating or updating a creative flight map, however, you do not need to explicitly set IsGoalOverride -- it is set automatically based on whether or not you are supplying GoalType and Goal.

Note - `IsStartEndDateOverride`

You will see IsStartEndDateOverride field in the results of a GET request for a creative flight map -- this indicates whether or not the ad has its own start/end dates. When creating or updating a creative flight map, however, you do not need to explicitly set IsStartEndDateOverride -- it is set automatically based on whether or not you are supplying StartDate and EndDate.

Response

The result will include the unique creative ID that can be used to update or remove the creative in the future.

creative={
  "SizeOverride":false,
  "CampaignId":123,
  "PublisherAccountId":123,
  "IsDeleted":false,
  "Percentage":0,
  "Iframe":false,
  "Creative":{
    "Id":12345
  },
  "CustomTargeting":"$keywords contains \"dean\"",
  "DistributionType":1,
  "IsActive":true,
  "ZoneId":null,
  "FlightId":1234,
  "ActiveKeywords":[],
  "FreqCap": 0,
  "FreqCapDuration": 0,
  "FreqCapType": 0,
  "GoalType": 1,
  "Goal": 200000,
  "StartDate": "6/1/2015",
  "EndDate": "6/30/2015",
  "StartDateISO": "2015-06-01T00:00:00.0000000",
  "EndDateISO": "2015-06-30T00:00:00.0000000"
}
curl -X POST -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/flight/12345/creative -d 'creative={"CampaignId":12345,"Creative":{"Id":12345},"FlightId":12345,"GoalType":1, "Goal":100,"IsActive":true}'
{
  "Id":12345,
  "CampaignId":123,
  "PublisherAccountId":123,
  "IsDeleted":false,
  "Percentage":0,
  "Iframe":false,
  "Creative":{
    "AdvertiserId":123,
    "Body":"Test",
    "SiteId":123,
    "Url":"https://adzerk.com",
    "Title":"Test creative",
    "IsSync":false,
    "Id":12345,
    "IsDeleted":false,
    "AdTypeId":1,
    "Alt":"test",
    "IsActive":true,
    "ImageName":"longstring.jpg",
    "ImageLink":"https://yourcdn.com/longstring.jpg",
    "IsNoTrack":true,
    "IsNetworkAd":false
  },
  "CustomTargeting":"$keywords contains \"dean\"",
  "DistributionType":1,
  "IsActive":true,
  "ZoneId":null,
  "FlightId":1234,
  "ActiveKeywords":[],
  "IsGoalOverride": true,
  "GoalType": 1,
  "Impressions": 200000,
  "IsStartEndDateOverride": true,
  "StartDate": "/Date(1430481600000)/",
  "EndDate": "/Date(1430827200000)/",
  "StartDateISO": "2015-05-01T12:00:00.0000000",
  "EndDateISO": "2015-05-05T12:00:00.0000000"
}
Suggest Edits

Update Ad

 

Description

This updates the ad with new properties.

You should submit the properties above wrapped in a creative object. Alternatively, you can pass in just a single Id for the Creative object if you've already created one using Creative Endpoints.

Response

The result will include the unique creative ID that can be used to update or remove the creative in the future.

Caution

Any fields you do not include in a PUT request will be given the default values null, false, 0, or empty array, depending on the field. This will overwrite any existing values. When making a PUT request, make sure you are supplying all of the fields that should have values.

creative={
  "Id":12345,
  "SizeOverride":false,
  "CampaignId":123,
  "PublisherAccountId":123,
  "IsDeleted":false,
  "Percentage":0,
  "Iframe":false,
  "Creative":{
    "Id":12345
  },
  "CustomTargeting":"$keywords contains \"luke\"",
  "DistributionType":1,
  "IsActive":true,
  "ZoneId":null,
  "FlightId":1234,
  "ActiveKeywords":[],
  "GoalType": 1,
  "Goal": 200000,
  "StartDate": "6/1/2015",
  "EndDate": "6/30/2015",
  "StartDateISO": "2015-06-01T12:00:00.0000000",
  "EndDateISO": "2015-06-30T12:00:00.0000000"
}
curl -X PUT -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/flight/1234/creative/123456 -d 'creative={"Id":123456, "SizeOverride":false, "CampaignId":12345, "IsDeleted":false, "Iframe":false, "Creative":{"Id":123456}, "DistributionType":1, "IsActive":true, "FlightId":1234, "ActiveKeywords":[], "GoalType": 1, "Goal": 200000, "StartDate": "6/1/2015", "EndDate": "12/30/2015"}'
    {  
    "Id":12345,
    "CampaignId":1234,
    "FlightId":1234,
    "ZoneId":null,
    "SiteId":null,
    "Iframe":null,
    "PublisherAccountId":0,
    "Impressions":200000,
    "Percentage":0,
    "DistributionType":null,
    "IsDeleted":false,
    "IsActive":true,
    "Creative":{  
        "Id":123456,
        "Title":"Test creative",
        "ImageName":"",
        "Url":"https://adzerk.com",
        "Body":"Test",
        "AdvertiserId":1234,
        "IsActive":true,
        "AdTypeId":5,
        "Alt":"test",
        "IsDeleted":false,
        "IsSync":false,
        "IsHTMLJS":true,
        "ScriptBody":"Flight Creative Map",
        "Metadata":null,
        "ImageLink":"httpss://static.adzerk.net/Advertisers/",
        "IsNoTrack":true,
        "IsNetworkAd":false
    },
    "CustomTargeting":"$keywords contains \"max\"",
    "FreqCap":null,
    "FreqCapDuration":null,
    "FreqCapType":null,
    "StartDate":"\/Date(1433116800000)\/",
    "EndDate":"\/Date(1451433600000)\/",
    "GoalType":1,
    "Goal":null,
    "IsGoalOverride":true,
    "IsStartEndDateOverride":true,
    "ActiveKeywords":[  

    ],
    "RtbCustomFields":null
}

Description

XXXXXX

No parameters are needed. The Flight-Creative Map Id (Ad Id) is required in the URL, not the Creative Id. The result will include the Flight Id, Creative Id, and Flight-Creative Map Id.

Definition

GET https://api.adzerk.net/v1/flight/1234/creative/12345

curl -X GET -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/flight/12345/creative/123456
{  
    "Id":1227159,
    "CampaignId":258367,
    "FlightId":616145,
    "ZoneId":null,
    "SiteId":null,
    "Iframe":null,
    "PublisherAccountId":0,
    "Impressions":100,
    "Percentage":0,
    "DistributionType":null,
    "IsDeleted":false,
    "IsActive":false,
    "Creative":{  
        "Id":1163487,
        "Title":"my name",
        "ImageName":"",
        "Url":"https://adzerk.com",
        "Body":"duh",
        "AdvertiserId":84825,
        "IsActive":null,
        "AdTypeId":5,
        "Alt":null,
        "IsDeleted":null,
        "IsSync":null,
        "IsHTMLJS":true,
        "ScriptBody":"this",
        "Metadata":null,
        "ImageLink":"httpss://static.adzerk.net/Advertisers/",
        "IsNoTrack":true,
        "IsNetworkAd":false
    },
    "CustomTargeting":"$keywords contains \"sookie\"",
    "FreqCap":null,
    "FreqCapDuration":null,
    "FreqCapType":null,
    "StartDate":null,
    "EndDate":null,
    "GoalType":1,
    "Goal":null,
    "IsGoalOverride":true,
    "GoalType": 1,
    "Impressions": 200000,
    "IsStartEndDateOverride":true,
    "StartDate": "/Date(1430481600000)/",
    "EndDate": "/Date(1430827200000)/"
    "ActiveKeywords":[  

    ],
    "RtbCustomFields":null
}
Suggest Edits

Delete Ad

 

Description

This removes the map between creative and flight, deleting the ad. However, it does remove the creative itself. No parameters are needed.

As long as the URL has the Category Id and it belongs to your network, you'll receive the message:

"This creative map has been deleted"

Definition

GET https://api.adzerk.net/v1/flight/1234/creative/12345/delete

curl -X GET -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/flight/12345/creative/123456/delete
Suggest Edits

Get Ad Tracking Pixel and ClickURL

 

Description

This returns the StaticClickUrl for tracking clicks with the ad, as well as a ImpressionPixelUrl for tracking impressions. This is most useful for static text link ads that cannot be served by JavaScript ad code or the Native Ads API.

No parameters are needed. The Flight id and Flight Creative Map id are required in the url.

Definition

GET https://api.adzerk.net/v1/flight/1234/creative/12345/trackingPixel

Response

Returns an object containing the Flight Creative Map id, the static click url, and the impression pixel url.

curl -X GET -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/flight/12345/creative/123456/trackingPixel
{   
  "Id":12345,
  "StaticClickUrl":"https://engine.adzerk.net/r?e=eyJhdiI6MzkxLCJhdCI6NCwiY20iOjgyMCwiY2giOjExMjcsImNyIjoyMzEwLCJkbSI6NCwiZmMiOjE5OTksImZsIjoyMzUwLCJudyI6MjMsInBjIjoxMDAsInByIjo3NTYsInJ0IjowLCJzdCI6MCwidXIiOiJlbmNvc2lhLmNvbSIsInJlIjoxfQ&s=YMA6pTLxVb1s4fTtUCdkQQIGyMQ",
  "ImpressionPixelUrl":"https://engine.adzerk.net/p/eyJhdiI6Njk3MTUsImF0Ijo0LCJidCI6MCwiY20iOjI3MzY2NiwiY2giOjM1NDcsImNrIjp7fSwiY3IiOjk0ODMxMSwiZG0iOjQsImZjIjo5OTczODgsImZsIjo2NzczOTQsImlwIjoiNTQuMjI3LjI2LjQxIiwibnciOjE2MzYsInBjIjoxMDAwLCJwciI6NzM4NzIsInJ0IjoyLCJzdCI6MCwiYmYiOnRydWUsInBuIjoiYXprcHJldmlldyIsInJlIjoxfQ/i.gif"
}
Suggest Edits

Site/Zone Targeting

 
Suggest Edits

Create Site/Zone Targeting

 

Description

This endpoint targets a flight to a site and/or zone.

You should post the properties below wrapped in a sitezone object.

Definition

POST https://api.adzerk.net/v1/flight/1234/sitezonetargeting

Arguments

Name
Data Type
Required
Description
Default

SiteId

integer

Y

The ID of the site that can be created using Site Endpoints

ZoneId

integer

N

The ID of the zone that can be created using Zone Endpoints

IsExclude

boolean

N

Indicates whether the targeting is include or exclude

Response

The result will include the unique site/zone targeting ID that can be used to update or remove the site/zone targeting in the future. The flight id is also included in the result.

sitezone={
  "FlightId":12345
  "SiteId":123,
  "ZoneId":321,
  "IsExclude":false
}
curl -X POST -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/flight/12345/sitezonetargeting -d 'sitezone={"FlightId":12345,"SiteId":1234,"ZoneId":1234,"IsExclude":"true"}'
{
  "Id":12345,
  "FlightId":1234
  "SiteId":123,
  "ZoneId":321,
  "IsExclude":false
}
Suggest Edits

Update Site/Zone Targeting

 

Description

This updates the details of site/zone targeting. For example, you may change the targeted site, or add or remove a zone.

You should submit the properties above wrapped in a sitezone object.

Definition

PUT https://api.adzerk.net/v1/flight/1234/sitezonetargeting/12345

Response

The result will include the unique site/zone targeting ID that can be used to update or remove the site/zone targeting in the future.

sitezone={
  "SiteId":123,
  "ZoneId":321,
  "IsExclude":false
}
curl -X PUT -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/flight/12345/sitezonetargeting/123456 -d 'sitezone={"FlightId":12345,"SiteId":1234,"ZoneId":12345,"IsExclude":"false"}'
{
  "Id":12345,
  "FlightId":1234,
  "SiteId":123,
  "ZoneId":321,
  "IsExclude":false
}
Suggest Edits

Get Site/Zone Targeting

 

Description

This returns the properties for a specific site/zone Targeting ID.

No parameters are needed. As long as the URL has the site/zone targeting Id and it belongs to your network, you'll receive the site/zone targeting object you requested.

Definition

GET https://api.adzerk.net/v1/flight/1234/sitezonetargeting/12345

Response

The result will include the unique site/zone targeting ID that can be used to update or remove the site/zone targeting in the future.

curl -X GET -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/flight/12345/sitezonetargeting/123456
{
  "Id":12345,
  "FlightId":1234,
  "SiteId":123,
  "ZoneId":321,
  "IsExclude":false
}
Suggest Edits

Delete Site/Zone Targeting

 

Description

This removes site/zone targeting from a flight.

No parameters are needed.

As long as the URL has the site/zone targeting Id and it belongs to your network, you'll receive the message: "Successfully Deleted"

Definition

GET https://api.adzerk.net/v1/flight/1234/sitezonetargeting/12345/delete

curl -X GET -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/flight/1234/sitezonetargeting/123456/delete
Suggest Edits

Geo-Targeting Endpoints

 

Geo-targeting endpoints target flights to serve to specific geographical locations.

Suggest Edits

Create Geo-Targeting

 

Description

This targets a flight to a geographical area, either inclusively (only show the flight in this area) or exclusively (show the flight everywhere except this area).

To add multiple geo-targeting locations, make multiple requests to the endpoint. Each will have their own LocationId.

You should post the properties below wrapped in a geotargeting object.

Definition

POST https://api.adzerk.net/v1/flight/1234/geotargeting

Arguments

Name
Data Type
Required
Description
Default

CountryCode

string

N

The 2-3 character string that denotes the country you want to target

Region

string

N

The 2-3 character string that denotes the region (or state) that you want to target

MetroCode

integer

N

The 3 digit number that denotes the metropolitan area you want to target

IsExclude

boolean

N

true: exclude location, false/null: include location

Response

The result will include the unique geo-targeting ID that can be used to update or remove the geo-targeting in the future. The flight id is also included in the result.

geotargeting={
  "FlightId": 12345,
  "CountryCode":"US",
  "Region":"NC",
  "MetroCode":560,
  "IsExclude":true
}
curl -X POST -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/flight/12345/geotargeting -d 'geotargeting={"FlightId":12345,"CountryCode":"US","Region":"NC","MetroCode":560}'
{
  "LocationId":1234567,
  "FlightId":1234
  "CountryCode":"US",
  "Region":"NC",
  "MetroCode":560,
  "IsExclude":true
}
Suggest Edits

List Geo Codes

 

Description

Get a list of all geographical areas and codes. This will return a ~400 KB JSON object.

Definition

GET https://api.adzerk.net/v1/countries

curl -X GET -H "X-Adzerk-ApiKey:<APIKEY>" -H "Content-Type=application/x-www-form-urlencoded" https://api.adzerk.net/v1/countries
Suggest Edits

List Metro Codes in Region

 

Description

View the MetroCodes within a specific Region.

Definition

GET https://api.adzerk.net/v1/region/{regionCode}

curl -X GET -H "X-Adzerk-ApiKey:<APIKEY>" -H "Content-Type=application/x-www-form-urlencoded" https://api.adzerk.net/v1/region/NC
[  
    {  
        "regionCodes":null,
        "Name":"Charlotte, NC",
        "Code":"517"
    },
    {  
        "regionCodes":null,
        "Name":"Greensboro-Winston Salem, NC",
        "Code":"518"
    }
 ]
Suggest Edits

List Regions in Country

 

Description

View the Regions within a specific Country.

Definition

GET https://api.adzerk.net/v1/country/{countryCode}/regions?version=2

curl -X GET -H "X-Adzerk-ApiKey:<API-KEY>" -H "Content-Type=application/x-www-form-urlencoded" http://api.adzerk.net/v1/country/BH/regions?version=2
{
  "Name": "Bahrain",
  "Code": "BH",
  "Regions": {
    "BH:15": {
      "Name": "Muharraq",
      "Code": "15",
      "Metros": {},
      "CountryCode": "BH"
    },
    "BH:13": {
      "Name": "Capital",
      "Code": "13",
      "Metros": {},
      "CountryCode": "BH"
    }
  }
}
Suggest Edits

Update Geo-Targeting

 

Description

This endpoint changes geo-targeting settings for a flight.

You should submit the properties above wrapped in a geotargeting object.

Definition

PUT https://api.adzerk.net/v1/flight/1234/geotargeting/12345

Response

The result will include the unique geo-targeting ID that can be used to update or remove the geo-targeting in the future.

geotargeting={
  "CountryCode":"US",
  "Region":"NC",
  "MetroCode":560,
  "IsExclude":false
}
curl -X PUT -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/flight/12345/geotargeting/1234567 -d 'geotargeting={"FlightId":12345,"CountryCode":"US","Region":"NC","MetroCode":560, "IsExclude":true}'
{
  "LocationId":12345,
  "FlightId":1234,
  "CountryCode":"US",
  "Region":"NC",
  "MetroCode":560,
  "IsExclude":false
}
Suggest Edits

Get Geo-Targeting

 

Description

This endpoint returns the properties for a LocationId and its flight.

No parameters are needed. As long as the URL has the geo-targeting Id and it belongs to your network, you'll receive the geo-targeting object you requested.

Definition

GET https://api.adzerk.net/v1/flight/1234/geotargeting/12345

Response

The result will include the unique geo-targeting ID that can be used to update or remove the geo-targeting in the future.

curl -X GET -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/flight/12345/geotargeting/1234567
{
  "LocationId":12345,
  "FlightId":1234,
  "CountryCode":"US",
  "Region":"NC",
  "MetroCode":560,
  "IsExclude":false
}
Suggest Edits

Delete Geo-Targeting

 

Description

This removes a geo-targeting setting (LocationId) from a flight.

No parameters are needed.

Definition

GET https://api.adzerk.net/v1/flight/1234/geotargeting/12345/delete

Response

As long as the URL has the geo-targeting Id and it belongs to your network, you'll receive the message: "Successfully Deleted"

curl -X GET -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/flight/12345/geotargeting/1234567/delete
Suggest Edits

RTB Endpoints

 

Adzerk can integrate with real-time bidding providers to serve ads programmatically. To create RTB advertisers and ads via the Management API, you must set additional properties on currently existing endpoints.

Click here for more information on RTB.

Your account must be RTB enabled to use these features. If you aren't sure, check with your account manager.

Suggest Edits

Create RTB Advertiser

 

Description

Creates RTB advertiser.

Definition

POST https://api.adzerk.net/v1/advertiser

Arguments

Include all required parameters from Create Advertisers. Additional properties include:

Name
Data Type
Required
Description
Default

PartnerId

integer

Y

The enum value of the RTB provider that will be delivering ads as the Adzerk advertiser*

RtbCustomFields

string

Y

JSON data provided by the RTB partner. If this is not sent by the provider, your account manager will supply you with the data for this property

*PartnerID key =

1 = Index Exchange
2 = unassigned
3 = Bidtellect
4 = unassigned
5 = Zemanta
6 = Pubmatic (Native)

curl -X POST -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/advertiser -d 'advertiser={"Title":"Test advertiser","IsDeleted":false,"IsActive":true,"PartnerId":1,"RtbCustomFields:"{"something":true}"}'
Suggest Edits

Update RTB Advertiser

 

Description

Updates properties of an RTB advertiser. Refer to the Advertiser Endpoints page for more info.

Definition

PUT https://api.adzerk.net/v1/advertiser/{advertiserId}

Suggest Edits

Create RTB Flights & Campaigns

 

Description

Creates new RTB campaigns or flights. Include all required properties. For more information, refer to the Campaign Endpoints and the Flight Endpoints.

The only requirement to enable these flights and campaigns for RTB is to use an AdvertiserId that has been set up with an RTB PartnerId.

Definition

Campaigns
POST https://api.adzerk.net/v1/campaign

Flights
POST https://api.adzerk.net/v1/flight

If you attempt to set a RateType in a flight other than 2 (CPM), we will override the RateType and set it as 2. This is the only option for RTB flights.

Suggest Edits

Create RTB Creatives & Ads

 

Description

Create a new RTB ad. You can create a new creative, or use a pre-existing creative. Include all required properties from Creative Flight Map Ad Endpoints.

Definition

POST https://api.adzerk.net/v1/flight/{flightId}/creative

Additional Creative RTB Properties

Name
Data Type
Required
Description
Default

RtbCustomFields

string

N

JSON data provided by the RTB partner. Note that this is different than the advertiser-level RtbCustomFields. This should also be provided by the RTB provider or your account manager

rtbFormat

string

N

Setting the rtbFormat in the RtbCustomFields string enables you to choose whether the RTB ad's source is an image or a custom native string that uses Adzerk macros to supply ad data

disableSubdomain

boolean

N

If true, any subdomains of the referrer URL will NOT be passed to the RTB provider on the request

False

String Values:

Image - Requests and responds with an image ad.

Custom Native Format (default) - Requests and responds with a native ad.

Custom native ads should also include an adTemplate that uses macros to define the custom template. Refer to the Zemanta example in the curl example to the right:

curl -X POST -H 'X-Adzerk-ApiKey:<API-KEY>' -H 'Content-Type: application/x-www-form-urlencoded' -d 'creative={ "CampaignId":12345, "DistributionType":1, "IsActive":true, "FlightId":12345, "Creative":{"AdTypeId":5}, "RtbCustomFields":"{\"rtbFormat\":\"Custom Native Format (default)\",\"adTemplate\":\"URL: {{url}}\\nTITLE: {{title}}\\nIMAGE: {{externalUrl}}`\",\"auctionType\":\"Second Price (default)\",\"floorPrice\":\"0.01\",\"imageWidth\":\"300\",\"imageHeight\":\"250\",\"pubId\":\"12345\",\"pubName\":\"mazda\"}"}' http://api.adzerk.net/v1/flight/12345/creative
curl 'X-Adzerk-ApiKey:<APIKEY>' -H 'Content-Type: application/x-www-form-urlencoded' 'https://api.adzerk.net/v1/flight/12345/creative' -X POST -d 'creative={ "CampaignId":123456, "DistributionType":1, "IsActive":true, "FlightId":12345, "Creative":{"AdTypeId":5}, "RtbCustomFields":"{"something":true}" }'
Suggest Edits

Budget Capping (BETA)

 

This feature is in Beta. Contact your account manager to get started.

Budget caps will stop an ad from serving once a budget is reached. For example, if a flight is priced at $1.00 CPM and the budget is $1000, the flight will stop serving when Adzerk records 1 million impressions.

The budget can be set on advertiser, campaign, or flight objects.

We will respect the most restrictive budgets. For example, if the budget for an advertiser is $5000 but the budget for an flight is only $1000, we will stop serving the flight when it reaches its budget. Conversely, if the advertiser budget was updated to $500, we will stop serving the $1000 flight as soon as the advertiser budget is exhausted.

Budget caps also work for second-price auctions and RTB flights where there isn't a steady stream of revenue per event.

Budget caps do not work with flat-rate flights. Also, flat-rate prices will be ignored in a campaign or advertiser's overall budget.

Getting Started with Budget Caps

First, the budget caps feature must be enabled for your account. Contact your account manager if you are not already enabled.

Setting Up an Advertiser Budget

  • Create or update an advertiser object. In the JSON payload
  • Set the CapType to 4 to represent Budget Caps.

Set an integer for a DailyCapAmount or a LifetimeCapAmount or both. The value is in US Dollars. For example:

"DailyCapAmount":200

Sets a daily cap of $200.

If you set a CapType to any value other than 4 for an advertiser, we will return a 400 error.
Any cap types you do not set will be returned in the response with a value of null.

Setting Up a Campaign Budget

  • Create or update an campaign object. In the JSON payload, set the CapType to 4 to represent Budget Caps.
  • Set an integer for a DailyCapAmount or a LifetimeCapAmount or both. The value is in US Dollars. For example:

"DailyCapAmount":200

Sets a daily cap of $200.

If you set a CapType to any value other than 4 for an advertiser, we will return a 400 error.
Any cap types you do not set will be returned in the response with a value of null.

Setting Up a Flight Budget

  • Create or update a flight object. In the JSON payload, set the CapType to 4 to represent Budget Caps.
  • Set an integer for a DailyCapAmount or a LifetimeCapAmount or both. The value is in US Dollars. For example:

"DailyCapAmount":200

Sets a daily cap of $200.

Any cap types you do not set will be returned in the response with a value of null.

curl -X POST -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/advertiser -d 'advertiser={"Title":"Budget cap","IsDeleted":false,"IsActive":true,"CapType":4, "DailyCapAmount":200}'
curl -X POST -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/campaign -d 'campaign={"Name":"Budget cap","StartDate":"1/1/2011","AdvertiserId":12345,"Price":0.1,"IsActive":true,"flights":[],"CapType":4,"DailyCapAmount":200}'
curl -X POST -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/flight -d 'flight={"Name":"Budget cap","StartDate":"1/1/2015","EndDate":"12/1/2015","CampaignId":12345,"PriorityId":12345,"GoalType":2,"IsActive":true,"Price":1,"Impressions":100,"Keywords":"doge,truck,wow","RateType":2,"NoEndDate":false,"IsUnlimited":false,"CapType":4,"DailyCapAmount":200}'
Suggest Edits

Targeting Optimization (BETA)

 

BETA

This feature is in Beta. Contact your account manager to get started.

Targeting optimization is a method of adjusting how eligible an ad is to serve in order to meet a performance goal, similar to eCPM Optimization. Unlike eCPM Optimization, targeting optimization enables you to set the desired goal outcome.

Refer to our Targeting Optimization article for more info.

Suggest Edits

View Targeting Optimization Weight

 

Description

This will return the eligibility percentage of ads in the flight. If no percentage has been set, it will return as null.

Definition

GET https://api.adzerk.net/v1/flight/{id}/targetingoptimization/weights

Response

See right.

curl -X GET -H "X-Adzerk-ApiKey:<APIKEY>" -H "Content-Type=application/x-www-form-urlencoded" http://api.adzerk.net/v1/flight/12345/targetingoptimization/weights
 {  
      "ads":{  
          "123456":null
      }
  }
Suggest Edits

Reset Targeting Optimization Weight

 

Description

This resets the eligibility percentage to the default value, which is null. If the percentage is already null, the POST will not return a response.

Definition

POST https://api.adzerk.net/v1/flight/{id}/targetingoptimization/reset

Response

See right.

curl -X POST -H 'X-Adzerk-ApiKey:<APIKEY>' http://api.adzerk.net/v1/flight/12345/targetingoptimization/reset
  {  
      "ads":{  
          "123456":null
      }
  }
Suggest Edits

Set Targeting Optimization Settings

 

Description

This updates the targeting optimization settings for your network. These settings apply to your entire network.

You should submit the properties below wrapped in a settings object.

Definition

PUT https://api.adzerk.net/v1/targetingoptimization/settings

Arguments

Name
Data Type
Required
Description
Default

RangeMin

integer

Y

The lower limit (as a percentage) for how much targeting optimization should heat up or cool down when adjusting weights. Must be between 1 and 50

RangeMax

integer

Y

The upper limit (as a percentage) for how much targeting optimization should heat up or cool down when adjusting weights. Must be between 1 and 50

PercentToAdjust

integer

Y

The percentage of objects (such as sites) that will be adjusted when heating up/cooling down. Must be between 1 and 50

Response

The result will return the settings you entered as a JSON object.

{
  "RangeMin": 3,
  "RangeMax": 35,
  "PercentToAdjust": 50
}
curl -X PUT -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/targetingoptimization/settings -d 'settings={"PercentToAdjust": 50, "RangeMax": 35, "RangeMin": 3}'
{  
    "PercentToAdjust":50,
    "RangeMax":35,
    "RangeMin":3
}
Suggest Edits

View Targeting Optimization Settings

 

Description

This returns the targeting optimization settings for your network.

Definition

GET https://api.adzerk.net/v1/targetingoptimization/settings

Response

See right.

curl -X GET -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/targetingoptimization/settings
{  
    "PercentToAdjust":50,
    "RangeMax":35,
    "RangeMin":3
}
Suggest Edits

Inventory API Overview

 

The Adzerk Inventory API allows you to programmatically create, modify, list, and Delete new Ad Types, Channels, Sites, Zones, Priorities and Channel Site Maps. You can use this to automate the process of setting up your ad inventory rather than doing it manually, or to automatically update your ad units if changes are necessary.

 
Suggest Edits

List Ad Types (Networks)

 

Descriptions

This will list out all of the ad types available to your network.

Definition

GET https://api.adzerk.net/v1/adtypes

Response

See right.

Adding Pagination

You can paginate the list of ad types. To paginate the ad types, use the query parameters:

?pageSize = how many results to return per page
&page = the current page of the results

For example, this curl command returns the first page of 50 items per response:

curl -X GET -H 'X-Adzerk-ApiKey:<APIKEY>' -H "Content-Type=application/x-www-form-urlencoded" https://api.adzerk.net/v1/adtypes?pageSize=50

This returns the second page of 25 items per response:

curl -X GET -H 'X-Adzerk-ApiKey:<APIKEY>' -H "Content-Type=application/x-www-form-urlencoded" 'https://api.adzerk.net/v1/adtypes?pageSize=25&page=2'

We will also return the totalPages and totalItems of the list.

If you do not add pagination parameters, we will return all the ad types in your network.

curl -X GET -H "X-Adzerk-ApiKey:<APIKEY>" -H "Content-Type=application/x-www-form-urlencoded" https://api.adzerk.net/v1/adtypes
result = client.ad_types.list
{
  "page": 1,
  "pageSize": 10,
  "totalPages": 1,
  "totalItems": 7,
  "items": [
    {
      "Id": 1,
      "Height": 90,
      "Width": 120,
      "Name": "Button 1 and Text"
    },
    {
      "Id": 2,
      "Height": 90,
      "Width": 120,
      "Name": "Button 1"
    },
    {
      "Id": 3,
      "Height": 60,
      "Width": 468,
      "Name": "Full Banner"
    },
    {
      "Id": 4,
      "Height": 90,
      "Width": 728,
      "Name": "Leaderboard"
    },
    {
      "Id": 5,
      "Height": 250,
      "Width": 300,
      "Name": "Medium Rectangle"
    },
    {
      "Id": 6,
      "Height": 600,
      "Width": 160,
      "Name": "Wide Skyscraper"
    },
    {
      "Id": 7,
      "Height": 600,
      "Width": 120,
      "Name": "Skyscraper"
    }
  ]
}
Suggest Edits

List Ad Types (Channel)

 

Descriptions

This will list out all of the ad types that are enabled for a specific channel.

Definition

GET https://api.adzerk.net/v1/channel/1234/adtypes

Response

The result will have the same format as the Network List.

Adding Pagination

You can paginate the list of ad types in a channel. To paginate the ad types, use the query parameters:

?pageSize = how many results to return per page
&page = the current page of the results

For example, this curl command returns the first page of 50 items per response:

curl -X GET -H 'X-Adzerk-ApiKey:<APIKEY>' -H "Content-Type=application/x-www-form-urlencoded" https://api.adzerk.net/v1/channel/1234/adtypes?pageSize=50

This returns the second page of 25 items per response:

curl -X GET -H 'X-Adzerk-ApiKey:<APIKEY>' -H "Content-Type=application/x-www-form-urlencoded" 'https://api.adzerk.net/v1/channel/1234/adtypes?pageSize=25&page=2'

We will also return the totalPages and totalItems of the list.

If you do not add pagination parameters, we will return all the ad types in your channel.

curl -X GET -H "X-Adzerk-ApiKey:<APIKEY>" -H "Content-Type=application/x-www-form-urlencoded" https://api.adzerk.net/v1/channel/1234/adtypes
result = client.ad_types.list(channel_id)
{
  "page": 1,
  "pageSize": 10,
  "totalPages": 1,
  "totalItems": 3,
  "items": [
    {
      "Id": 1,
      "Height": 90,
      "Width": 120,
      "Name": "Button 1 and Text"
    },
    {
      "Id": 2,
      "Height": 90,
      "Width": 120,
      "Name": "Button 1"
    },
    {
      "Id": 3,
      "Height": 60,
      "Width": 468,
      "Name": "Full Banner"
    }
  ]
}
Suggest Edits

Create Ad Types (Network)

 

Description

This will create an ad type at the network level. That means it will be available to enable on any channel.

Definition

POST https://api.adzerk.net/v1/adtypes

Arguments

You should post the properties below wrapped in an adtype object. If the ad type already exists, it will return the existing ad type.

Name
Data Type
Required
Description
Default

Width

integer

Y

The width, in pixels, of the ad type

Height

integer

Y

The height, in pixels, of the ad type

Name

string

N

A name for the adType. IAB ad types will have specific names such as Leaderboard or Skyscraper. Any other/custom sized will default to width x height

Response

adtype={
  "Width":"100",
  "Height":"100"
}
curl -X POST -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/adtypes -d "adtype={"Width":300,"Height":250}"
result = client.ad_types.create({
  :width  => 300
  :height => 250
  :name   => "Medium Rectangle"
})
{
  "Id":123
  "Width":100,
  "Height":100
  "Name":"100 x 100"
}
Suggest Edits

Create Ad Types (Channel)

 

Description

This request will create the Ad Type at the Network level if necessary, and enable it for the channel specified.

Definition

POST https://api.adzerk.net/v1/channel/1234/adtype

Arguments & Response

The parameters are exactly the same as the Network Create. See above for JSON Request and Response examples.

curl -X POST -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/channel/1234/adtype -d "adtype={"Width":300,"Height":250}"
result = client.ad_types.create({
  :width  => 300
  :height => 250
  :name   => "Medium Rectangle"
})
Suggest Edits

Delete Ad Type (Network)

 

Description

This will remove an ad type from your network. Any channels with the ad type enabled will no longer have it. You will get a "Successfully Deleted" message or a "No Record to Delete" message if nothing was deleted.

Defintion

GET https://api.adzerk.net/v1/adtypes/123/delete

curl -X GET -H "X-Adzerk-ApiKey:<APIKEY>" -H "Content-Type=application/x-www-form-urlencoded" https://api.adzerk.net/v1/adtypes/123/delete
result = client.ad_types.delete(ad_type_id)
Suggest Edits

Delete Ad Type (Channel)

 

Description

This will remove an ad type from the specified channel. You will get a "Successfully Deleted" message or a "No Record to Delete" message if nothing was deleted.

Defintion

GET https://api.adzerk.net/v1/channel/1234/adtypes/123/delete

curl -X GET -H "X-Adzerk-ApiKey:<APIKEY>" -H "Content-Type=application/x-www-form-urlencoded" https://api.adzerk.net/v1/channel/1234/adtypes/123/delete
result = client.ad_types.delete(ad_type_id, channel_id)
 
Suggest Edits

List Channels

 

Descriptions

This returns a list of all channels in your network.

Definition

GET https://api.adzerk.net/v1/channel

Response

See right.

Adding Pagination

You can paginate the list of channels.To paginate the channels, use the query parameters:

?pageSize = how many results to return per page
&page = the current page of the results

For example, this curl command returns the first page of 50 items per response:

curl -X GET -H 'X-Adzerk-ApiKey:<APIKEY>' -H "Content-Type=application/x-www-form-urlencoded" https://api.adzerk.net/v1/channel?pageSize=50

This returns the second page of 25 items per response:

curl -X GET -H 'X-Adzerk-ApiKey:<APIKEY>' -H "Content-Type=application/x-www-form-urlencoded" 'https://api.adzerk.net/v1/flight/12345/channel?pageSize=25&page=2'

We will also return the totalPages and totalItems of the list.

If you do not add pagination parameters, we will return all the channels in your network.

curl -X GET -H "X-Adzerk-ApiKey:<APIKEY>" -H "Content-Type=application/x-www-form-urlencoded" https://api.adzerk.net/v1/channel
{
   "page": 1,
   "pageSize": 10,
   "totalPages": 1,
   "totalItems": 9,
   "items": [
       {
           "Id": 1234,
           "Title": "All Sites",
           "Commission": 0,
           "Engine": "CPM",
           "CPM": 0,
           "AdTypes": [
               4,
               5,
               6,
               9,
               13
           ],
           "IsDeleted": false,
           "CustomTargeting":""
       },...
 }
Suggest Edits

Create Channels

 

Description

This adds a new channel to your network. By default, an All Sites channel is created with your network, which cannot be deleted.

Definition

POST https://api.adzerk.net/v1/channel

Arguments

You should post the properties below wrapped in a channel object.

Name
Data Type
Required
Description
Default

Title

string

Y

The title of the channel

AdTypes

array of integers

Y

The type of ads you want this channel to use. Here are example adTypeIds using IAB standard sizes

CPM (Deprecated)

float or decimal

Y, but set to 0

Set to 0 in all requests

Engine (Deprecated)

string

Y, but set to 0

Set to 0 in all requests

Keywords

string

N

The keywords that you want to target with this channel. Separate with commas

Custom Targeting

string

N

A Zerkel query that filters all requests eligible to serve to the channel

Commission (Deprecated)

integer

N

Deprecated

Response

The result will include the unique channel ID that can be used to update or remove the channel in the future.

channel={
  "Title":"Test Channel",
  "Commission":0,
  "Engine":"CPM",
  "Keywords":"test, another test",
  "CPM":10.00,
  "AdTypes":[0,1,2,3,4]
  "CustomTargeting":"\"something\" = true"
}
curl -X POST -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/channel -d 'channel={"Title":"Test channel","Engine":"0","AdTypes":[5]}'
{
  "Id":1234,
  "Title":"Test Channel",
  "Commission":0,
  "Engine":"CPM",
  "Keywords":"test, another test",
  "CPM":10.00,
  "AdTypes":[0,1,2,3,4],
  "IsDeleted":false,
  "CustomTargeting":"\"something\" = true"
}
Suggest Edits

Update Channels

 

Description

This sets a pre-existing channel with new properties.

You should submit the properties in the Create section wrapped in a channel object.

Definition

PUT https://api.adzerk.net/v1/channel/12345

Response

The result will include the unique channel ID that can be used to update or remove the channel in the future.

channel={
  "Id":1234,
  "Title":"Test Channel",
  "Commission":0,
  "Engine":"CPM",
  "Keywords":"test, another test",
  "CPM":10.00,
  "AdTypes":[0,1,2,3,4]
}
curl -X PUT -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/channel/12345 -d 'channel={"Id":19882,"Title":"New Channel Name","Engine":"0","AdTypes":[5]}'
{
  "Id":1234,
  "Title":"Test Channel",
  "Commission":0,
  "Engine":"CPM",
  "Keywords":"test, another test",
  "CPM":10.00,
  "AdTypes":[0,1,2,3,4]
  "IsDeleted": false,
  "CustomTargeting": null
}
Suggest Edits

Get Channels

 

Descriptions

This returns the properties for a given channelId.

No parameters are needed. As long as the URL has the channel Id and it belongs to your network, you'll receive the channel object you requested.

Definition

GET https://api.adzerk.net/v1/channel/12345

Response

No parameters are needed. As long as the URL has the channel Id and it belongs to your network, you'll receive the channel object you requested.

curl -X GET -H "X-Adzerk-ApiKey:<APIKEY>" -H "Content-Type=application/x-www-form-urlencoded" https://api.adzerk.net/v1/channel/19882
{
  "Id":1234,
  "Title":"Test Channel",
  "Commission":0,
  "Engine":"CPM",
  "Keywords":"test, another test",
  "CPM":10.00,
  "AdTypes":[0,1,2,3,4]
  "IsDeleted": false,
  "CustomTargeting": null
}
Suggest Edits

Get Priorities for a Channel

 

Description

This lists all the priorities for a given channel. Check out the Priority Endpoints for more information on priorities.

There are no parameters, aside from the channel id in the url.

Definition

GET https://api.adzerk.net/v1/channel/12345/priorities

Response

See right. Below are some response properties.

Name
Data Type
Description

Weight

integer

The ranking of a priority within a channel. Priorities with lower numbers will be given the first chance to serve. Range is from 1 to 100

SelectionAlgorithm

integer

Determines how ads in a priority are chosen by the ad serving engine. Can only be set at the time of priority creation and cannot be changed. Values:

(0) Lottery (also represented as null)
(1) Auction
(2) Ad Chain Ordered
(3) Ad Chain Optimized
(4) Lottery With Outbid

curl -X GET -H "X-Adzerk-ApiKey:<APIKEY>" -H "Content-Type=application/x-www-form-urlencoded" https://api.adzerk.net/v1/channel/12345/priorities
[
    {
        "Id": 12345,
        "Name": "Sponsorship",
        "ChannelId": 12345,
        "Weight": 1,
        "IsDeleted": false,
        "SelectionAlgorithm": 1
    },...
]
Suggest Edits

Delete Channels

 

Description

This removes a channel from your network.

No parameters are needed. As long as the URL has the channel Id and it belongs to your network, you'll receive the message: "Successfully deleted".

Defintion

GET https://api.adzerk.net/v1/channel/12345/delete

curl -X GET -H "X-Adzerk-ApiKey:<APIKEY>" -H "Content-Type=application/x-www-form-urlencoded" https://api.adzerk.net/v1/channel/12345/delete
Suggest Edits

List Sites

 

Descriptions

This endpoint returns a list of all the sites in your network.

Definition

GET https://api.adzerk.net/v1/site

Response

See right.

Adding Pagination

You can paginate the list of sites. This is especially useful if your network has several hundred sites.

To paginate the sites, use the query parameters:

?pageSize = how many results to return per page
&page = the current page of the results

For example, this curl command returns the first page of 50 items per response:

curl -X GET -H 'X-Adzerk-ApiKey:<APIKEY>' -H "Content-Type=application/x-www-form-urlencoded" https://api.adzerk.net/v1/site?pageSize=50

This returns the second page of 25 items per response:

curl -X GET -H 'X-Adzerk-ApiKey:<APIKEY>' -H "Content-Type=application/x-www-form-urlencoded" 'https://api.adzerk.net/v1/site?pageSize=25&page=2'

We will also return the totalPages and totalItems of the list.

If you do not add pagination parameters, we will return all the sites in your network.

curl -X GET -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/site
{
    "page": 1,
    "pageSize": 10,
    "totalPages": 2,
    "totalItems": 14,
    "items": [
        {
            "Id": 12345,
            "Title": "My Site",
            "Url": "http://www.adzerk.com",
            "PublisherAccountId": 123,
            "IsDeleted": false
        },...
Suggest Edits

Create Site

 

Description

This adds a new site to your network.

Definition

POST https://api.adzerk.net/v1/site

Arguments

You should post the properties below wrapped in a site object.

Name
Data Type
Required
Description
Default

Title

string

Y

The name used to describe the site

Url

string

Y

The address link to the new site. Must be in the format https://path of URL

PublisherAccountId (Deprecated)

integer

N

The Id for the publisher account you want linked to this site. Only set it if you know for certain what publisher account should be linked. It can be obtained using the Publisher endpoints. If you try to set the id to a publisher account not linked to your network, it will not be set

Response

The result will include the unique site ID that can be used to update or remove the site in the future.

site={
  "Url":"http://www.adzerk.com",
  "Title":"Test Site"
}
curl -X POST -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/site -d 'Site={"Title":"Adzerk","URL":"https://adzerk.com"}'
{
  "Id":1234,
  "Title":"Test Site",
  "Url":"http://www.adzerk.com",
  "PublisherAccountId":123,
  "IsDeleted":false
}
Suggest Edits

Update Sites

 

Description

This updates a site with a new URL and/or title.

You should submit the properties from the Create section above wrapped in a site object.

Definition

PUT https://api.adzerk.net/v1/site/12345

Response

The result will include the unique site ID that can be used to update or remove the site in the future.

site={
  "Id":12345,
  "Url":"http://www.adzerk.com",
  "Title":"Test Site",
  "IsDeleted:false
}
curl -X PUT -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/site/12345 -d 'Site={"Id":12345,"Url":"http://www.adzerk.com","Title":"New Title","IsDeleted":"false"}'
{
  "Id":12345,
  "Title":"Test Site",
  "Url":"http://www.adzerk.com",
  "PublisherAccountId":123
}
Suggest Edits

Get Sites

 

Description

This returns the properties of a single site.

No parameters are needed. As long as the URL has the site Id and it belongs to your network, you'll receive the site object you requested.

Definition

GET https://api.adzerk.net/v1/site/12345

Response

The result will include the unique site ID that can be used to update or remove the site in the future.

curl -X GET -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/site/12345
{
  "Id":1234,
  "Title":"Test Site",
  "Url":"http://www.adzerk.com",
  "PublisherAccountId":123
}
Suggest Edits

Delete Site

 

Description

Deletes a site.

To do this, set "IsDeleted":true. If successful we will return the object: {"message":"This site has been deleted."}.

Definition

PUT https://api.adzerk.net/v1/site/12345

Suggest Edits

List Zones

 

Descriptions

This returns a list of all the zones in your network.

Definition

GET https://api.adzerk.net/v1/zone

Response

See right.

Adding Pagination

You can paginate the list of zones. To paginate the zones, use the query parameters:

?pageSize = how many results to return per page
&page = the current page of the results

For example, this curl command returns the first page of 50 items per response:

curl -X GET -H 'X-Adzerk-ApiKey:<APIKEY>' -H "Content-Type=application/x-www-form-urlencoded" https://api.adzerk.net/v1/flight/12345/zone?pageSize=50

This returns the second page of 25 items per response:

curl -X GET -H 'X-Adzerk-ApiKey:<APIKEY>' -H "Content-Type=application/x-www-form-urlencoded" 'https://api.adzerk.net/v1/flight/12345/zone?pageSize=25&page=2'

We will also return the totalPages and totalItems of the list.

If you do not add pagination parameters, we will return all the zones in the network.

curl -X GET -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/zone
{  
    "page":1,
    "pageSize":10,
    "totalPages":1,
    "totalItems":4,
    "items":[  
        {  
            "Id":12345,
            "Name":"This is a Network Zone",
            "IsDeleted":false
        },
        {  
            "Id":12346,
            "Name":"This is a Site Zone",
            "SiteId":1234,
            "IsDeleted":false
        },...
Suggest Edits

Create Zone

 

Description

This adds a new zone to your network. You can choose to create a zone as either a Site Zone (used by only a single site) or a Network Zone (available to any site in your network.)

Definition

POST https://api.adzerk.net/v1/zone

Arguments

You should post the properties below wrapped in a zone object.

Name
Data Type
Required
Description
Default

Name

string

Y

The name used to describe the zone

SiteId

string

N

The ID of the site that can be created using Site Endpoints. To create a network zone, do not include a SiteId

IsDeleted

boolean

N

Indicates whether the zone is deleted

Response

The result will include the unique zone ID that can be used to update or remove the zone in the future.

zone={
  "Name":"Test zone",
  "SiteId":123
}
curl -X POST -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/zone -d 'zone={"Name":"Test zone","SiteId":1234}'
{
  "Id":1234,
  "Name":"Test zone",
  "SiteId":1234,
  "IsDeleted":false
}
Suggest Edits

Update Zone

 

Description

This endpoint can change the name of the zone or the SiteId is it targeted to. It can also be used to delete the zone.

You should submit the properties from Create above wrapped in a zone object. Be sure to include the Id parameter.

Definition

PUT https://api.adzerk.net/v1/zone/12345

Response

The result will include the unique zone ID that can be used to update or remove the zone in the future.

zone={
  "Id":1234,
  "Name":"Test zone",
  "SiteId":123
}
curl -X PUT -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/zone/1234 -d 'zone={ "Id":1234, "Name":"Test zone", "SiteId":123}'
curl -X PUT -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/zone/1234 -d 'zone={"IsDeleted":true}'
{
  "Id":1234,
  "Name":"Test zone",
  "SiteId":1234,
  "IsDeleted":false
}
 

Description

This returns the properties for a specific zone.

No parameters are needed. As long as the URL has the zone Id and it belongs to your network, you'll receive the zone object you requested.

Definition

GET https://api.adzerk.net/v1/zone/12345

Response

The result will include the unique zone ID that can be used to update or remove the zone in the future.

curl -X GET -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/zone/1234
{
  "Id":1234,
  "Name":"Test zone",
  "SiteId":1234,
  "IsDeleted":false
}
Suggest Edits

Delete Zone

 

Description

Deletes a site.

To do this, set "IsDeleted":true. If successful we will return the object: {"message":"This site has been deleted."}.

Definition

PUT https://api.adzerk.net/v1/zone/12345

Suggest Edits

Priorities

 

Priorities belong to a channel. They determine the order of flights the ad engine attempts to serve, as well as the ad selection mechanism for the flight.

Suggest Edits

List Priority

 

Descriptions

This lists all the priorities in your network, along with the channel ID the priorities belong to.

Definition

GET https://api.adzerk.net/v1/priority

Response

See right.

Adding Pagination

You can paginate the list of creatives for a given flight. This is especially useful if a flight has more than several hundred creatives.

To paginate the creatives, use the query parameters:

?pageSize = how many results to return per page
&page = the current page of the results

For example, this curl command returns the first page of 50 items per response:

curl -X GET -H "X-Adzerk-ApiKey:$ADZERK_API_KEY" -H "Content-Type=application/x-www-form-urlencoded" https://api.adzerk.net/v1/flight/12345/creatives?pageSize=50

This returns the second page of 25 items per response:

curl -X GET -H "X-Adzerk-ApiKey:$ADZERK_API_KEY" -H "Content-Type=application/x-www-form-urlencoded" 'https://api.adzerk.net/v1/flight/12345/creatives?pageSize=25&page=2'

We will also return the totalPages and totalItems of the list.

If you do not add pagination parameters, we will return all the ads in the flight.

curl -X GET -H "X-Adzerk-ApiKey:$ADZERK_API_KEY" https://api.adzerk.net/v1/priority
{
    "page": 1,
    "pageSize": 10,
    "totalPages": 5,
    "totalItems": 46,
    "items": [
        {
            "Id": 1234,
            "Name": "High Priority",
            "ChannelId": 1234,
            "Weight": 1,
            "IsDeleted": false
        },...
Suggest Edits

Create Priority

 

Description

This adds a new priority to a channel.

Definition

POST https://api.adzerk.net/v1/priority

Arguments

You should post the properties below wrapped in a priority object.

Name
Data Type
Required
Description
Default

Name

string

Y

The name used to describe the flight

ChannelId

integer

Y

The id of the channel you want to use. Can be accessed via the Channel Endpoints

Weight

integer

Y

The priority order within the channel. 1-100, 1 is highest priority

SelectionAlgorithm

integer

Y

Choose which selector the ad engines use to select an ad from this priority

Set to 0

IsDeleted

boolean

N

Indicates that the priority is deleted

FloorPrice

float

N

Sets a floor price for second-price auction priority. If FloorPrice is not set and IsSecondPricing is false, it will be set to null. If FloorPrice is not set and IsSecondPricing is true, it will be set to $0.01

IsKeywordOptimized

boolean

N

Choose whether the priority is optimized for responding to large numbers of keyword requests

IsSecondPricing (BETA)

boolean

N

Indicates that the flight uses the second-price auction model. This can only be set to true for an Auction-type SelectionMethod: 1 or 3

SelectionAlgorithm

This may only be set on creation, and this field cannot be updated.

Check out our Knowledge Base for more on the selection process. Values include:

0 = Lottery
1 = Auction
2 = Adchain Ordered
3 = Adchain Optimized
4 = Lottery with Outbid

IsKeywordOptimized

This may only be set on creation, and this field cannot be updated.

Response

The result will include the unique flight ID that can be used to update or remove the flight in the future.

priority={
  "Name":"High Priority",
  "ChannelId":1234,
  "Weight":10,
  "IsDeleted":false,
  "SelectionAlgorithm": 1,
  "IsSecondPricing": true,
  "FloorPrice": 1
}
curl -X POST -H "X-Adzerk-ApiKey:$ADZERK_API_KEY" https://api.adzerk.net/v1/priority -d 'priority={"Name":"Fun Priority","ChannelId":1234,"Weight":10,"IsDeleted":"false","SelectionAlgorithm":3}'
{
  "Id":1234,
  "Name":"High Priority",
  "ChannelId":1234,
  "Weight":10,
  "IsDeleted":false,
  "SelectionAlgorithm": 0,
  "IsKeywordOptimized":true
}
Suggest Edits

Update Priority

 

Description

This updates a priority with new properties.

You should submit the properties in Create section above wrapped in a priority object.

SelectionAlgorithm

SelectionAlgorithm cannot be updated after the priority is created

Definition

PUT https://api.adzerk.net/v1/priority/12345

Response

The result will include the unique priority ID that can be used to update or remove the priority in the future.

priority={
  "Id":12345
  "Name":"High Priority",
  "ChannelId":1234,
  "Weight":10,
  "IsDeleted":false
}
curl -X PUT -H "X-Adzerk-ApiKey:$ADZERK_API_KEY" https://api.adzerk.net/v1/priority/12345 -d 'priority={"Id":12345,"Name":"Fun Priority","ChannelId":12345,"Weight":11,"IsDeleted":"false"}'
{
  "Id":1234,
  "Name":"High Priority",
  "ChannelId":1234,
  "Weight":10,
  "IsDeleted":false,
  "SelectionAlgorithm": 0
}
Suggest Edits

Get Priority

 

Description

This returns properties for a specific priority.

No parameters are needed. As long as the URL has the priority Id and it belongs to your network, you'll receive the priority object you requested.

Definition

GET https://api.adzerk.net/v1/priority/12345

Response

The result will include the unique priority ID that can be used to update or remove the priority in the future.

curl -X GET -H "X-Adzerk-ApiKey:$ADZERK_API_KEY" https://api.adzerk.net/v1/priority/12345
{
  "Id":1234,
  "Name":"High Priority",
  "ChannelId":1234,
  "Weight":10,
  "IsDeleted":false,
  "SelectionAlgorithm": 0,
  "IsSecondPricing":null,
  "FloorPrice":null
}
Suggest Edits

Delete Priority

 

Description

This removes a priority from the channel.

No parameters needed. A successful response will say: "Successfully deleted".

Defintion

GET https://api.adzerk.net/v1/priority/12345/delete

Deleting a priority will cause all ads in the priority to stop serving.

curl -X GET -H "X-Adzerk-ApiKey:$ADZERK_API_KEY" https://api.adzerk.net/v1/priority/12345/delete
Suggest Edits

Channel Site Maps

 
Suggest Edits

List Channel Site Maps

 

Descriptions

Returns a list of all channel site maps (associations between a site and channels) in your account.

Definition

GET https://api.adzerk.net/v1/channelSite

Response

See right.

Adding Pagination

You can paginate the list of channel site maps. To paginate channel site maps, use the query parameters:

?pageSize = how many results to return per page
&page = the current page of the results

For example, this curl command returns the first page of 50 items per response:

curl -X GET -H 'X-Adzerk-ApiKey:<APIKEY>' -H "Content-Type=application/x-www-form-urlencoded" https://api.adzerk.net/v1/flight/12345/creatives?pageSize=50

This returns the second page of 25 items per response:

curl -X GET -H 'X-Adzerk-ApiKey:<APIKEY>' -H "Content-Type=application/x-www-form-urlencoded" 'https://api.adzerk.net/v1/flight/12345/creatives?pageSize=25&page=2'

We will also return the totalPages and totalItems of the list.

If you do not add pagination parameters, we will return all the channel site maps in your network.

curl -X GET -H "X-Adzerk-ApiKey:<APIKEY>" -H "Content-Type=application/x-www-form-urlencoded" https://api.adzerk.net/v1/channelSite
{
    "page": 1,
    "pageSize": 10,
    "totalPages": 5,
    "totalItems": 42,
    "items": [
        {
            "SiteId": 12345,
            "ChannelId": 1234,
            "Priority": 10
        },...
}
Suggest Edits

Create Channel Site Map

 

Description

Creating a channel site map links a site to a channel, which makes ads that have been targeted to a channel eligible to serve to the site.

Definition

POST https://api.adzerk.net/v1/channelSite

Arguments

You should post the properties below wrapped in a channelSite object.

Name
Data Type
Required
Description
Default

SiteId

integer

N

The identification number for the Site Endpoints

ChannelId

integer

N

The identification number for the Channel Endpoints

Priority

integer

N

Also known as affinity. This is different from the Priority Endpoint. When a site belongs to multiple channels, this priority sets which channel should be requested first

FixedPaymentAmount (Deprecated)

decimal

N

Deprecated

Response

See right.

channelSite={
  "SiteId":2345,
  "ChannelId":1234,
  "Priority":10
}
curl -X POST -H 'X-Adzerk-ApiKey:<APIKEY>' api.adzerk.net/v1/channelSite -d 'channelSite={"SiteId":123456,"ChannelId":12345,"Priority":5}'
{
  "SiteId":1234,
  "ChannelId":2345,
  "FixedPaymentAmount":null,
  "Priority":10,
}
Suggest Edits

Update Channel Site Map

 

Description

This is used to update a channel site map with a new priority.

You should submit the properties from Create above wrapped in a channelSite object.

Definition

PUT https://api.adzerk.net/v1/channelSite

Response

See right.

channelSite={
  "SiteId":2345,
  "ChannelId":1234,
  "Priority":10
}
curl -X PUT -H 'X-Adzerk-ApiKey:<APIKEY>' api.adzerk.net/v1/channelSite -d 'channelSite={"SiteId":123456,"ChannelId":12345,"Priority":6}'
{
  "SiteId":1234,
  "ChannelId":2345,
  "FixedPaymentAmount":null,
  "Priority":10,
}
Suggest Edits

Get Channel Site Map

 

Description

Returns the channel site map for a specific siteId and channelId.

No parameters are needed. As long as the URL has the siteId, the channelId, and it belongs to your network, you'll receive the object you requested.

Definition

GET https://api.adzerk.net/v1/channel/1234/site/2345

Response

See right.

curl -X GET -H "X-Adzerk-ApiKey:<APIKEY>" -H "Content-Type=application/x-www-form-urlencoded" https://api.adzerk.net/v1/channel/12345/site/123456
{
  "SiteId":1234,
  "ChannelId":2345,
  "FixedPaymentAmount":null,
  "Priority":10,
}
Suggest Edits

List Channels for a Site

 

Descriptions

This returns all ChannelIds associated with a given Site.

No parameters are needed. As long as the URL has the Site Id, and it belongs to your network, you'll receive the object you requested. It is an array of Channel IDs for a particular Site Id.

Definition

GET https://api.adzerk.net/v1/channelsInSite/1234

Response

See right.

curl -X GET -H "X-Adzerk-ApiKey:<APIKEY>" -H "Content-Type=application/x-www-form-urlencoded" https://api.adzerk.net/v1/channelsInSite/123456
{
  "ChannelIds":[1234, 3456]
}
Suggest Edits

Delete Channel Site Map

 

Description

This removes the association of a site and channel.

No parameters are needed. Successful deletes will receive the message: "Successfully deleted".

Defintion

GET https://api.adzerk.net/v1/channel/1234/site/123/delete

curl -X GET -H "X-Adzerk-ApiKey:<APIKEY>" -H "Content-Type=application/x-www-form-urlencoded" https://api.adzerk.net/v1/channel/12345/site/123456/delete
Suggest Edits

Forecasting API

 

Forecasting is available in both the API, and UI.

For information on Forecasting in the Adzerk UI, view our knowledge base article on Forecasting Inventory.

Forecasts return a report that shows projected and booked impressions over a future time period. Forecasts are most useful for a sales team booking directly sold impressions, or in conjunction with a self-serve platform to estimate available inventory for purchase. The JSON that is returned will include "ProjectedImpressions", the total number of impressions expected given the criteria and timeframe, as well as "AvailableImpressions", the remaining impressions available to be sold after subtracting Pitched, Reserved, and Approved media plans.

For more information, view our Knowledge base article on Forecasting Inventory .

Suggest Edits

Create Queued Forecast

 

Description

This returns a GUID for the forecast. Refer to the Reporting API for more details.

Definition

POST https://api.adzerk.net/v1/forecast/queue

Arguments

You can specify the criteria for the report using an object titled criteria.

Name
Data Type
Required
Description
Default

StartDateISO

string

N

The start date of the forecast in ISO 8601 format. Format: YYYY-MM-DDTHH:MM:SS

EndDateISO

string

N

The end date of the forecast in ISO 8601 format. Format: YYYY-MM-DDTHH:MM:SS.

Parameters

list of Crit objects

N

An unlimited number of criteria that can be applied to a forecast. The possible terms are advertiserId, campaignId, flightId, creativeId, channelId, adTypeId, siteId, zoneId, countryCode,metroCode, andkeyword`.

StartDate (Deprecated)

string

N

The start date for the forecast. Format is MM/DD/YYYY. Deprecated in favor of StartDateISO.

EndDate (Deprecated)

string

N

The end date for the forecast. Format is MM/DD/YYYY. Deprecated in favor of EndDateISO.

Note - StartDate and EndDate

If a StartDateISO contradicts the StartDate, the StartDateISO will take precedence. This goes for 'EndDate' and 'EndateISO' too.

All report requests should use midnight GMT, such as: '2016-06-01T00:00:00'

Example Request

To the right is a sample criteria object that will generate a forecast for a specific Channel.

Response

Returns an object with a single property, Id, which represents the GUID of the queued forecast.

Report IDs will only persist for 30 days from creation.

criteria={'StartDate': '1/1/2015', 'EndDate': '2/1/2015', 'Parameters': [{'channelId': 1234}]}
curl -X POST -H 'X-Adzerk-ApiKey:<APIKEY>' https//api.adzerk.net/v1/forecast/queue -d 'criteria={"StartDate":"11/01/2015","EndDate":"11/30/2015", "Parameters":[{"advertiserId":12345}]}'
{
    "Id": "d9cbd104-80f5-428a-825b-af87a472af78"
}
Suggest Edits

Poll for Forecast Report Result

 

Description

This returns a finished report from the GUID.

Takes a single parameter in the URL, the GUID of a queued forecast.

Definition

GET https//api.adzerk.net/v1/forecast/queue/{id}

Response

Returns an object with the following properties:

Name
Data Type
Description

Id

string

The GUID supplied in the request

Status

integer

An enum representing the status of the queued forecast. Key:
1 = In progress
2 = Complete
3 = Error

Message

string

If Status is Error, this will contain the error message, null otherwise.

Result

report object

If Status is Complete, this will contain the requested forecast. No Result property will be returned for other Statuses. An example of the Forecast object is above.

Forecast Specific Parameters

Name
Data Type
Description

Days

Number of days included in the forecast.

PastImpressions

PastImpressions2x

CurrentGrowthPct

MediaPlanStatus

Key:
1 = Pitched
2 = Reserved
3 = Approved
4 = Trafficked
5 = ClosedLost

MediaPlanBookedPct

integer

An integer indicating how likely a media plan will be booked

A forecast will include both Flights (Options) and MediaPlans if the Sales Management add-on is enabled.

curl -X GET -H "X-Adzerk-ApiKey:<APIKEY>" -H "Content-Type=application/x-www-form-urlencoded" https//api.adzerk.net/v1/forecast/queue/97cc474a-5b80-4d8a-828c-b04c90f028e6
{
   "Days":1720,
   "PastImpressions":0,
   "PastImpressions2x":0,
   "CurrentGrowthPct":0.0,
   "ProjectedImpressions":1720,
   "AvailableImpressions":-2381188,
   "Options":[
      {
         "Id":0,
         "StartDate":"2015-06-25T18:10:00",
         "Name":"test",
         "Advertiser":"Advertiser Name",
         "Impressions":25,
         "Sites":"",
         "Locations":"",
         "Keywords":"",
         "ChannelId":3547,
         "IsActive":false,
         "PriorityId":5083,
         "PriorityName":"High Priority",
         "PriorityWeight":1,
         "Weight":1.0,
         "PassbackPriority":0,
         "DateString":"6/25/2015 - No End Date"
         "StartDateISO":"2015-06-25T18:10:00.0000000"
      }
   ],
   "MediaPlans":[
      {
         "MediaPlanStatus":1,
         "MediaPlanBookedPct":2,
         "Id":0,
         "StartDate":"2014-08-22T00:00:00",
         "EndDate":"2014-08-27T00:00:00",
         "Name":"asdf5",
         "Advertiser":"Advertiser Name",
         "Impressions":0,
         "Sites":"",
         "Locations":"",
         "Keywords":"asdf,asdf2",
         "ChannelId":3547,
         "IsActive":true,
         "PriorityId":6259,
         "PriorityName":"Site Remainder Flights",
         "PriorityWeight":10,
         "Weight":1.0,
         "PassbackPriority":0,
         "DateString":"8/22/2014 - 8/27/2014"
         "StartDateISO":"2014-08-22T00:00:00.0000000",
         "EndDateISO":""2014-08-27T00:00:00.0000000"
      }
   ],
    "Criteria":[

   ],
   "LoginId":12345,
   "IsNewMediaPlanFormat":true
 }
Suggest Edits

User Management API

 

The User Management API allows you to manage access to Adzerk, create new Adzerk users, or update the names or emails of Adzerk users in your account.

You can use this to automatically create an Adzerk user account for new employees, shut down an account for former employees, or in conjunction with any internal tools you have built.

Suggest Edits

List Logins

 

Description

This returns a list of all users in your account.

Definition

GET https://api.adzerk.net/v1/login

Response

See example to right.

Passwords are not returned in the response, but are represented by empty strings.

Adding Pagination

You can paginate the list of logins. To paginate the logins, use the query parameters:

?pageSize = how many results to return per page
&page = the current page of the results

For example, this curl command returns the first page of 50 items per response:

curl -X GET -H 'X-Adzerk-ApiKey:<APIKEY>' -H "Content-Type=application/x-www-form-urlencoded" https://api.adzerk.net/v1/login?pageSize=50

This returns the second page of 25 items per response:

curl -X GET -H 'X-Adzerk-ApiKey:<APIKEY>' -H "Content-Type=application/x-www-form-urlencoded" 'https://api.adzerk.net/v1/login?pageSize=25&page=2'

We will also return the totalPages and totalItems of the list.

If you do not add pagination parameters, we will return all the logins in your network.

curl -X GET -H "X-Adzerk-ApiKey:<APIKEY>" -H "Content-Type=application/x-www-form-urlencoded" https://api.adzerk.net/v1/login
{  
    "page":1,
    "pageSize":10,
    "totalPages":2,
    "totalItems":15,
    "items":[  
        {  
            "Id":1234,
            "Email":"ddraper@adzerk.com",
            "Password":"",
            "Name":"Don Draper"
        },...
Suggest Edits

Create Login

 

Description

This adds a new user to your account.

Definition

POST https://api.adzerk.net/v1/login

Arguments

You should submit the properties below wrapped in a login object.

Name
Date Type
Required
Description
Default

Email

string

Y

The email used to login and used for alerts and notifications. The API doesn't validate for domains or @, but if these are not included the user will not receive service alerts

Name

string

N

Friendly name of the user used for display in the application

Password

string

N

Response

The result will include the unique login ID that can be used to update or remove the login in the future.

Error - Duplication

If a user with that email address already exists, a new login will not be created and the API will return: {"message":"\"There is already an account associated with this email\""}

Warning - Password Protection

The password will be returned as plaintext! Do not use this endpoint without https!

login=
{  
    "Id":19290,
    "Email":"ddraper@adzerk.com",
    "Name":"Don Draper",
    "Password":"password"
}
curl -X POST -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/login -d 'login={"Email":"ddraper@adzerk.com","Name":"Don Draper","Password":"password"}'
{
    "Id":1234,
    "Email":"ddraper@adzerk.com",
    "Password":"password",
    "Name":"Don Draper"
}
Suggest Edits

Update Login

 

Description

This updates the name, email address, or password of a user.

You should submit the properties from 'Create Section' wrapped in a login object.

Definition

PUT https://api.adzerk.net/v1/login/1234

Response

The result will include the unique login ID that can be used to update or remove the login in the future.

Warning - Password Protection

The password will be returned as an empty string. When sending passwords, do not use this endpoint without https!

login=
{  
    "Id":19290,
    "Email":"ddraper@adzerk.com",
    "Name":"Don Draper",
    "Password":"password"
}
curl -X PUT -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/login/1234 -d 'login={"Id":19290,"Email":"ddraper@adzerk.com","Name":"Don Draper","Password":"password"}'
{
  "Id":1234,
  "Email":"ddraper@adzerk.com",
  "Password":"",
  "Name":"Don Draper"
}
Suggest Edits

Get Login

 

Description

This returns the data for a specific user.

No parameters are needed. As long as the URL has the login Id and it belongs to your network, you'll receive the login object you requested.

Definition

GET https://api.adzerk.net/v1/login/12345

Response

The result will include the unique login ID that can be used to update the login in the future.

curl -X GET -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/login/1234
{
  "Id":1234,
  "Email":"ddraper@adzerk.com",
  "Password":"",
  "Name":"Don Draper"
}
 

Overview

The Adzerk iOS SDK integrates the features of the Management API and the UserDB API for iOS projects. It is an open source project hosted on Github.

Github Open Source iOS SDK

iOS Version

iOS SDK is designed for iOS v8.0 and later.

Getting the SDK

The SDK can be installed via Carthage or CocoaPods. It can also be installed manually.

Building an iOS Project with the SDK

Once you have installed the SDK, you can import AdzerkSDK in the AppDelegate and define your networkID and siteID.

The readme on Github has full documentation for usage.

Running the Sample App

The Swift sample app is hosted in the Github repo.

Suggest Edits

Android SDK

 

Overview

The Adzerk Android SDK makes the ad serving and UserDB features of Adzerk easily available for Android apps. It is an open source project hosted on Github.

Github Open Source Android SDK

Getting the SDK

We recommend that you access the SDK via Gradle. If you're running OS X and have Homebrew installed, use brew install gradle to start the download.

The SDK is also available as a Maven package distributed through jCenter.

Building an Android Project with the SDK

In your Java project, add the following line to your build.gradle file as one of the dependencies:

compile 'com.adzerk:sdk:0.1.+'

The last section refers to the version number. Make sure it matches the version of the SDK you plan to use.

Usage is described in the README of the Github project.

Running the Sample App

A sample app that uses Adzerk is included in the Github project. To run the sample app in Android Studio, make sure it includes the Android 5.1.1 (API 22) package or newer.

UserDB must first be enabled by your account manager. All customers under the Business or Enterprise plans have access to UserDB.

UserDB is a server-side database that enables Adzerk customers to store and retrieve ad serving data for their specific users. This data includes:

  • Frequency capping data - Make sure that each users sees an ad only as often as you'd like

  • Interests (for behavioral targeting) - Store information about what type of interests your users have - and then target them based on this data.

  • Retargeting segments - Show targeted ads toward users who have already interacted with your website or app.

  • RTB partner user IDs

  • Blocked items (advertisers, campaigns, creatives, or flights)

  • Custom data supplied by the Adzerk network

Suggest Edits

Getting Started with UserDB

 

Creating UserDB Records

UserDB records are stored in JSON format, and the unique record for each user is identified by a GUID called a UserKey.

By default, Adzerk will return a new and unique UserKey with an ad response.

  • In a JavaScript ad tag response, the UserKey is the value of the cookie azk
  • In the Native Ads API response, the UserKey is stored as the key object under the User parameter

To sync a new UserKey with a user, you must:

  1. Capture the UserKey when it is returned with an ad
  2. Associate the UserKey with the user in your first-party database
  3. For cross-referencing, pass the first-party ID for the user as custom JSON on the user's UserDB record

By default, Adzerk will generate a random user key with each ad request. However, you could create a custom user key by changing the value of the azk cookie that is set during JavaScript ad tag requests.

A user must be logged into your site or app to be associated with a UserKey! Adzerk cannot distinguish users— that is your responsibility.

The UserDB API can be accessed without an API key, so you shouldn't use vulnerable User ID to represent your users in UserDB.

Passing UserDB Records

To let the ad engine access the user's UserDB record, you must pass the UserKey as part of a Native Ads API request. Pass it as the key value of the Users object.

The ad engine will then load the user data on each ad request with a UserKey passed in. This data (such as a user's interests) will factor into which ad is selected for that user. The engine will also write data for certain events (such as when a user converts on a creative, etc.)

Suggest Edits

Frequency Capping

 

Overview

By setting frequency capping, you set the maximum number of times a given advertiser, campaign, flight, ad can be displayed to any particular user in a particular time period.

For instance, you can:

  • Have users see only one ad from an advertiser per day
  • Cap impressions from a single flight at 10 per week
  • Do cross-device targeting, so a user who sees an image on desktop can have capped impressions on mobile

When UserDB is enabled for an account, Frequency Capping data will be stored in UserDB (instead of in cookies).

Cookie-based frequency capping only works with flight frequency caps.

For cross-device frequency capping, make sure the UserId is shared between the devices.

Enabling Frequency Capping

Refer to the Flights article for details on how to set frequency capping.

For enabling via UI, click here.

For enabling via API, view the 'Create Flight' parameters here.

Frequency Capping and UserDB "Scrubbing

When a user views a frequency capped ad, Adzerk will write the time that the ad was viewed to the user's UserDB record. After the frequency capping period has ended, Adzerk will "scrub" the record of older ad/flight/campaign/advertiser view times.

The scrubbing process runs regularly, so if you view a user's UserDB record, you will see older ad/flight/campaign/advertiser views removed over time.

Suggest Edits

Behavioral Targeting

 

Overview

Behavioral or interest targeting delivers ads to users based on their interests, as determined by their interactions with other ads.

This enables two main capabilities:

  • Targeting users based on 'interests' - which are defined by you and let you target based on facts you know about the user
  • Blocking ads for any user who has clicked or converted on the ad. This keeps click-through and conversion rates high

For example, say you wanted to target people who clicked on one ad with a different ad. The flow would be:

  1. A user clicks on an ad from Flight X.
  2. Flight X contains the category "soccer". This category is added to the user's profile (user information is stored via a cookie or a UserDB entry)
  3. Flight Y has been targeted to the interest "soccer" with Custom Targeting. It is displayed only to the user who clicked or converted on Flight X.

Creating Behavioral Categories

  1. You need to add categories to a flight, via:

    • The Adzerk UI
    • The Management API
    • Or setting a category for a particular user via a tracking pixel
  2. Once a category has been attached to a flight, the flights' interests are saved on a user's record in UserDB.

  3. You then pass categories into an ad request via Custom Targeting, which tells Adzerk to serve targeted ads relevant to that user.

*Adding Categories (Interests) via API

Visit our Create Flight Categories document.

*Adding Categories via Pixels

See UserDB Pixel Endpoint for more information.

A category can have up to 10 characters

A user's record can collect up to 100 categories based on their click and conversion behavior.

Enabling Behavioral Targeting for Ads via UI

  1. Make sure that categories (interests) have been created at the flight level
  1. In the "General" settings, add Categories to the flight. Type in a category name to create a new category or select an existing one
  2. Click "Behavioral Targeting" under "Delivery"
  1. Use the checkboxes to choose whether to block ads from the advertiser or flight if a user clicks or converts on the creatives. This setting could boost your CTR or conversion rate.
  2. Also, choose whether to add the flight's categories to the user's profile if the user clicks or converts on the ad. This will let the user be targeted by flights with the same categories.
  3. Save the flight.

Create Behavioral Targeting Flights via UI

This requires use of the Zerkel querying language. For more information, refer to the Custom Targeting article.

To target a flight to users who have converted or clicked on a Category, click "Custom Targeting" under "Targeting". Use the reserved key $user.interests in the Zerkel query to add an interest to the flight.

For example: $user.interests CONTAINS "basketball"

You can use any other Zerkel code in conjunction with interest targeting.

Enabling and Creating Behavioral Flights via API

[Detailed instructions coming soon - we promise!]

Suggest Edits

UserDB API Endpoints

 

If your Adzerk account uses a CNAME for engine.adzerk.net, you must use your CNAMEd domain for reading and writing to UserDB endpoints.

Overview

The UserDB API provides a window into the contents of UserDB for a Adzerk client. It also includes methods to generate retargeting pixels.

The API allows users to view and modify user records from userDB. It uses the same API keys as the Management API, and the API key should be passed in as a host header.

Custom Properties Method

This allows Adzerk clients to store and access custom properties via a free-form JSON object that can be set on the user and then accessed through Zerkel.

Definition
POST http://engine.adzerk.net/udb/{networkId}/custom

Data
JSON object

Adzerk will then replace the existing custom properties with the JSON object.

Read User From Javascript

This end-point returns the current users object as a JSON object. It enables integration with ados.js via Adzerk's JavaScript tags.

You can also pass in another UserKey as the cookie: azk=[UserKey]

Definition
GET http://engine.adzerk.net/udb/{networkid}/read

Response:

See right. Below are arguments in response:

Name
Data Type
Description
Default

cookieMonster

object

Internal data for UserDB services

key

string

The unique UserKey for the record

isNew

boolean

If true, the user record has just been created. isNew will always be set to false on retrieved records

interests

array of strings

Lists the interests set by behavioral targeting

blockedItems

object

Lists the IDs of objects that frequency capping settings have blocked from serving to the user

flightViewtimes

object

Lists frequency-capped flights that a user has viewed. Each flight contains an array of strings with ISO 8601 timestamps of when the view occurred

adViewtimes

object

Lists frequency-capped ads that a user has viewed. Each ad contains an array of strings with ISO 8601 timestamps of when the view occurred

partnerUserIds

object

Contains the ID of the user on integrated third-party partners, such as RTB providers. The keys are the partner ID in Adzerk and the values are arrays of strings that contain the IDs

retargetingSegments

object

Lists the retargeting segments the user belongs to. The keys are "b" plus the advertiser ID in Adzerk. The values are the number of ID of the retargeting segment

custom

object

Contains custom JSON uploaded by the Adzerk customer

optOut

boolean

If true, the user has opted out of data collection by UserDB. In that case, all other parameters will be deleted except for the userKey and the optOut setting, and the parameters cannot be written to in the future

dirtyCookies

object

Internal data for UserDB services

siteViewtimes (Deprecated)

object

Deprecated

pendingConversions (Deprecated)

array

Deprecated

curl -X POST -H "X-Adzerk-ApiKey: <APIKEY>" http://engine.adzerk.net/udb/2601/custom -d '{"something":true}' 
curl -b "azk=<USERKEY>" "http://engine.adzerk.net/udb/2601/read"
{
   "cookieMonster":{

   },
   "key":"ue1-e397eb5990c041858071b63ca5bcc00c",
   "isNew":false,
   "interests":[
      "news",
      "sports"
   ],
   "blockedItems":{
      "advertisers":[
         1234,
         1235
      ],
      "campaigns":[
         12345,
         12346
      ],
      "creatives":[
         123456,
         123457
      ],
      "flights":[
         234567,
         234568
      ]
   },
   "flightViewTimes":{
    "123456": [
      "2015-12-03T16:57:39.000Z",
      "2015-11-21T20:53:44.000Z",
      "2015-12-08T16:43:47.000Z",
      "2015-11-18T14:12:05.000Z"
    ]
   },
   "adViewTimes":{
    "789012": [
      "2015-12-03T16:57:39.000Z",
      "2015-12-08T16:43:47.000Z",
      "2015-11-21T20:53:43.000Z"
    ]
   },
   "siteViewTimes":{

   },
   "pendingConversions":[

   ],
   "partnerUserIds":{
    "p1": [
      "0shj0we09hw"
    ]
   },
   "retargetingSegments":{
    "b12345": [
      2,
      3,
      4
    ]
   },
   "custom":{
    "anything": "goes",
    "lookAtMe": [
      "itsAnArray",
      42
    ]
   },
   "optOut":false,
   "dirtyCookies":{

   }
}
Suggest Edits

UserDB Pixel Endpoint

 

Overview

These pixels enable Adzerk customers to opt a user out of UserDB data collection, set a retargeting segment, or set a behavioral targeting interest.

Opt-Out

Calling this pixel opt-outs users from userDB tracking:

http://engine.adzerk.net/udb/{networkid}/optout/i.gif

This clears the users' record and prevents future data from being written to that record. It also excludes the user from frequency capping.

Retargeting

This pixel creates a new number set called Segments-{brandId} that contains each of the segments. Call this pixel on the page you want to use to set the retargeting segment.

http://engine.adzerk.net/udb/{networkId}/rt/{brandId}/{segment}/i.gif

Interest Setting (Behavioral Targeting)

To enable setting of behavioral interests for a user based on other activities, use this simple pixel that will add an interest to the user.

http://engine.adzerk.net/udb/{networkId}/interest/i.gif?interest=xxxxxxxxx

Or if you're not using cookies, you can optionally explicitly choose the UserDB key with:

http://engine.adzerk.net/udb/{networkId}/interest/i.gif?userKey={userKey}&interest=xxxxxxxxx

Suggest Edits

Retargeting

 

Overview

Retargeting enables Adzerk clients to give an advertiser a pixel and grant them the ability to retarget those users on their property.

Creating Retargeting Pixels

  1. Retargeting pixels are created through the UserDB API. When a user views a pixel, this sets them in a retargeting segment.
  2. Use Zerkel to set a retargeting segment for a flight or ad. For example,

$user.retargetingSegments.b42 = 999

(b42 refers to brandId 42, the advertising requesting retargeting. 999 is the code of the retargeting segment)

A flight targeted to a retargeting segment will only be served if a user's record in UserDB contains that retargeting segment.

Suggest Edits

Custom User Data Targeting

 

Overview

UserDB allows Adzerk clients to pass custom data about their users into the Adzerk system and target ads to that data.

Adding Custom Data to a User Record

  1. Pass a key/value pair into the user's custom JSON using the UserDB API. For example:

{"favePony": "Twilight Sparkle"}

  1. Add a Zerkel property to the ad or flight you want to target with the custom data:

$user.custom.favePony = "Twilight Sparkle

Suggest Edits

ContentDB

 

ContentDB is a feature in the Business and Enterprise plans. Please let your account manager know if you are interested in ContentDB.

Overview

Content DB is a server-side database similar to UserDB that enables you to:

  • Target ads based on the surrounding content's metadata
  • Display that metadata in the creative output

In doing the above, you can speed up ad loading time and dynamically tailor creatives to individual users.

For example, if a music service has a library of thousands of tracks, they have tons of metadata: artists, genres, all-time plays, etc. Advertisers may want to target, say, the 'rock' genre, but passing every metadata object in the ad request consumes bandwidth and slows ad loading times.

Additionally, advertisers may want to reference the metadata in the ad itself, such as using a dynamic macro like "You like [artistName]? Then you'll like..."

ContentDB provides a solution by storing this metadata object on the ad server side, which can then be referenced in the ad call with a content key.

In other words, we store shortcuts for fast data matching. Rather than sending twenty prices of metadata in a request, you can send one key...and ContentDB will know that that key refers to twenty different things that can then be used for targeting.

Components of ContentDB Records

Schemas are the organization method for your content keys, which are the lookup IDs for your content records. Content keys under a schema point to a JSON object that contains a set of key/value pairs.

Schemas are useful for complex targeting, since you can request content keys with the same name from multiple schemas in a single ad request. For example, a music service may have a schema called album which contains keys such as title and releaseYear. In addition, there may be a schema called track which also contains a key called title. Both "title" values can be targeted.

Records are stored as JSON objects, like this example of content key [id] from an album schema:

`{
  "title": "Yankee Hotel Foxtrot",
  "releaseYear": "2002",
  "genres": ["indie rock", "post-rock", "alt-country"],
  "personnel": ["Jeff Tweedy", "Jay Bennett", "John Stirratt", "Leroy Bach", "Glenn Kotche"]
}`

In the above example, if you were to send the schema name in the ad request, you could then target on all the JSON objects listed.

Schema and content key names must conform to these rules:

  • Names are case-insensitive and will be treated as all lower case.
  • Names must contain only letters, numbers, dashes, or underscores. (No whitespace, periods, slashes, or other punctuation!)

Key and value names can contain whitespace and are case sensitive, but they cannot contain double colons (::) or double curly brackets {{ }} which are reserved for macros.

You can add any number of nested values to a JSON object. However, our ContentDB macros currently only support strings and numbers, so please refrain from setting arrays of objects as values.

Whitespace
If your schemas include whitespace (such as track information) you will need to urlencode the schema name in the API request, such as:

http://engine.adzerk.net/cdb/<network-id-here>/custom/track%20information/410

Using Macros
To access the track information object in a macro, you must use bracket notation:
{{content.custom['track information']}}

Suggest Edits

ContentDB Endpoints

 

Description

You can configure ContentDB via several RESTful API endpoints. You must create ContentDB records before calling schemas and content keys in your request.

At this time there is no UI functionality for adding or modifying ContentDB records.

Create or Update a ContentDB Record

Description

This lets you create or update a ContentDB Record

Definition
POST http://engine.adzerk.net/cdb/{networkId}/custom/{schemaName}/{contentKey}

Notes
Content-Type: application/json
Authentication: set X-Adzerk-ApiKey header to a valid API key
Data: A JSON object that does not include content key
Response: The JSON object again, does not include schema name or content key

POSTing to this endpoint is an "upsert" operation - if a value doesn't exist, it will create a new value. Otherwise, it will override the current value.

Response

A successful POST returns this JSON object: {"Code":200,"Message":"OK"}

Retrieve an Existing ContentDB Record

Description

This lets you retrieve and existing ContentDB record.

Definition
GET http://engine.adzerk.net/cdb/{networkId}/custom/{schemaName}/{contentKey}

Notes
Content-Type: application/json
Authentication: set X-Adzerk-ApiKey header to a valid API key
Response: The JSON object, does not include schema name or content key

Delete an Existing ContentDB Record

Description

This lets you delete an existing ContentDB record.

Definition
DELETE http://engine.adzerk.net/cdb/{networkId}/custom/{schemaName}/{contentKey}

Notes
Content-Type: application/json
Authentication: set X-Adzerk-ApiKey header to a valid API key
Response: The JSON object representing the deleted object, does not include schema name or content key

Currently, you cannot retrieve a list of all ContentDB entries in your network.

Including ContentDB in Native Ads API Requests

Add the contentKeys property to your API request to pass in your schema(s) and content key(s).

The JSON object associated with the content key will be looked up in ContentDB and then be available for use by custom targeting and creatives (via a macro).

The format is "contentKeys": {"schema": "contentKey"}.

See example to the above right.

Note how this request calls two schemas. We only support one key/value pair per schema per request.

ContentDB Requests with ados.js

Add the .setContentKeys() method to the ados_add_placement(); function in your JavaScript ad request to pass in your schemas(s) and content key(s).

The JSON object associated with the content key will be looked up in ContentDB and then be available for use by custom targeting and creatives (via a macro).

The format is .setContentKeys({"schema": "contentKey"}).

For example:

ados_add_placement(1234, 12345, "atf", 5).setContentKeys({"artist": 2993, "track": 3463477});

Request Macros

You can also add macros to the request to expand a macro as the schema or content key. This is most useful if you are using client-side data from the request (such as an IP address) instead of using a server-side numeric ID as the content key.

All Adzerk macros are available for use with content keys.

For example, using the IP address macro {{request.ip}}:

This request: ados_add_placement(123, 12345, "azk70681", 6).setContentKeys({"ip" : "{{request.ip}}"});

Will be expanded via the macro to: ados_add_placement(123, 12345, "azk70681", 6).setContentKeys({"ip" : "192.168.0.1"}); if your current external IP address is 192.168.0.1.

The only macro currently available for use is {{request.ip}}. We will add additional macros as the feature is released in full.

Custom Targeting with ContentDB

To target a flight or ad to data stored in ContentDB, use a Zerkel value based on $content.custom.

For example, given this object in the album schema:

{ "title": "Yankee Hotel Foxtrot", "releaseYear": "2002", "genres": ["indie rock", "post-rock", "alt-country"], "personnel": ["Jeff Tweedy", "Jay Bennett", "John Stirratt", "Leroy Bach", "Glenn Kotche"] }

you can target an ad to any album in the indie rock genre with the following query:

$content.custom.album.genres contains "indie rock"

If an advertiser was promoting a new Jeff Tweedy album, for instance, they could purchase a campaign to target all albums he has played on:

$content.custom.album.personnel contains "Jeff Tweedy"

You can also target ads to all requests using a particular schema set. For example,

$content.custom.album <> null

targets all requests with album schema data.

Displaying ContentDB Data in Creatives

You can display any of the values returned in a response by using macros in a creative. The base macro is {{content.custom}}, and the format is {{content.custom.schema.key.subkey...}

For example, a targeted HTML creative may make recommendations:

<div id="upsell">If you like "{{content.custom.track.title}}", check out Jeff Tweedy's latest album!</div>

Which will be rendered when the creative is displayed as:

If you like "Heavy Metal Drummer", check out Jeff Tweedy's latest album!

{
"placements": [{
    "divName": "atf",
    "networkId": 1234,
    "siteId": 12345,
    "adTypes": [5],
    "contentKeys": {"artist": 2993, "track": 3463477}
}],
"keywords": ["alternative", "rock"],
"referrer": "..."
}