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

API Introduction

 

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

Welcome!

Adzerk contains a full suite of APIs to build a customizable ad server. A brief overview of these APIs is below.

API
Description

Calls Adzerk's Ad Decision Engine to fill an ad request. Returns JSON so you can construct a customized ad unit

Pull data directly into your system

Automatically create/update campaigns and ads in bulk

Automatically create/update web properties in bulk

Your 1st-party server-side Data Management Platform

Tool for estimating volume you'll see for a given set of targeting criteria

A server-side database that speeds up response times by storing metadata about the ad

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/.

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

List Pagination

 

Overview

You can paginate any LIST endpoint. Pagination means you can limit the number of total results.

Query Parameters

Parameter
Description

?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'

Other

  • 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.

Suggest Edits

Decision API Overview

 

The Decision 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 Decision API request, and how to use the response to populate your ad units.

 
post
 

Description

Use the Decision 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

Required

Property
Description

placements
(object)

One or more Placement Objects. Required.

Optional

Property
Description

user
(object)

keywords
(array)

Keywords for Keyword Targeting

url
(string)

The current page URL

referrer
(string)

The referrer URL

time
(string)

The UNIX epoch timestamp

ip
(string)

The IP address. Required for Geo-Targeting

blockedCreatives
(array)

Numeric creative ids to disregard for ad selection

isMobile
(boolean)

If true, only ads containing a single image will be returned. Default = false.

includePricingData
(boolean)

If true, return pricing data for the decision in the response. Default = false

notrack
(boolean)

If true, only return ads that are set to honor Do Not Track. Default = false

enableBotFiltering
(boolean)

If making a server-side request, set to false. Defaults to true. Ensures server isn't seen as a bot. See here for more info

If the request doesn't contain a user key, one will be automatically generated in the response. UserKeys are important for Frequency Capping and UserDB.

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

Required

Property
Description

divName
(string)

A unique name for the placement defined by you. Required

networkId
(integer)

The numeric network id. Required

siteId
(integer)

The numeric site id. Required

adTypes
(array)

One or more integer ad types. More info here. Required

Optional

Property
Description

zoneIds
(array)

Zone IDs to use

campaignId
(integer)

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

flightId
(integer)

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

adId
(integer)

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

clickUrl
(string)

The ad's click-through URL

properties
(object)

A hash of key/value pairs used for Custom Targeting

eventIds
(array)

An array of numeric event types. Requests tracking URLs for custom events. See here for Event Tracking IDs

overrides
(object)

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

contentKeys
(object)

A hash of key/value pairs used with ContentDB

Error Handling

Message
Reason(s)

Out of n% placements on the request, none were valid

  • The siteId has been deleted
  • The siteId is not active
  • No siteId on the request

Keywords must be an array or string

Keywords are not a string or an array of strings

invalid JSON

JSON is not valid

{
  "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,
  "enableBotFiltering": 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
Suggest Edits

Client-Side Requests and CORS

 

The Decision API supports CORS for AJAX requests. Github's documentation has a good overview of CORS.

If you make client-side requests to the Decision API and expect cookies in the response, you must pass the XHR headers described below.

The CORS preflight request looks like this:

curl -i https://engine.adzerk.net/api/v2/ -H "Origin: http://example.com/page.html" -X OPTIONS
HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: accept, origin, content-type, content-length
Access-Control-Allow-Methods: GET,PUT,POST,DELETE,OPTIONS
Access-Control-Allow-Origin: http://example.com/page.html
Date: Fri, 09 Jun 2017 20:33:34 GMT
Server: nginx/1.1.19
X-Powered-By: Express
Content-Length: 0
Connection: keep-alive

You must pass withCredentials: true on xhrFields in the request to enable cross-domain requests. See the jQuery example below:

<script src="https://code.jquery.com/jquery-2.2.4.min.js"></script>
<script>
$.ajax({
  data: JSON.stringify({
    placements: [
      {
        divName: "testDiv",
        networkId: 1234,
        siteId: 123456,
        adTypes: [5]
      }
    ]
  }),
  dataType: "json",
  method: "POST",
  url: "https://engine.adzerk.net/api/v2",
  xhrFields: {
    withCredentials: true
  },
  success: function(data) {
    $("#testDiv").text(data.decisions.testDiv.contents[0].body);
  }
})
</script>
<div id="testDiv">this text will be replaced by an ad</div>

The cookie returned in a response is the azk cookie with a user's User Key as its value. Refer to the User DB documentation for more info.

The cookie will originate from the domain used to make the request. If you use a white-labeled domain to call the Decision API, you should expect cookies from that domain.

 

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

Property
Description

adId
(integer)

The Ad's ID

creativeId
(integer)

The Creative's ID

flightId
(integer)

The Flight's ID

campaignId
(integer)

The Campaign's ID

clickUrl
(string)

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

contents
(object)

One or more Contents

impressionUrl
(string)

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

events
(object)

The IDs and tracking URLs of custom events

pricing
(object)

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

Property
Description

type
(string)

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

template
(string)

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

data
(object)

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

body
(string)

The rendered body of the content. This is the scriptbody from Create Creative, or the JS/HTML section in the UI

Data Object

Property
Description

imageURL
(string)

The URL of the hosted Adzerk image

title
(string)

The Friendly Name of the ad

width
(integer)

The width associated with the Ad Type

height
(integer)

The height associated with the Ad Type

customData
(object)

The JSON object inserted into the metadata of the ad

Content Types

Name
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
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

price
(float)

The Flight's price (or ad's if its settings override Flight)

clearPrice
(float)

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
(float)

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
(enum)

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

eCPM
(float)

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",
          "body": "Example",
          "template": "image",
          "data": {
            "imageUrl": "http://static.adzerk.net/cat-eating-spaghetti.jpg",
            "title": "ZOMG LOOK AT THIS FRICKING CAT",
            "width": 350,
            "height": 350,
            "customData": {
                  "headline": "Test Headline",
                  "cta": "Download Here"
            }
          },
          "body": "<a href='...'><img src='http://static.adzerk.net/Advertisers/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": {
                  "headline": "Test Headline",
                  "cta": "Download Here"
            }
        },
      "body": "<a href='...'><img src='http://static.adzerk.net/Advertisers/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/Advertisers/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

RTB Endpoints

 

Sample RTB Native Ad Request

Description

To the right is a curl example of a Decision API request that calls a RTB (Real Time Bidding) 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 Decision Response from Bidtellect. Properties are:

Property
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 Decision Response from Pubmatic. The Decision API will return PubMatic ads as a JSON object based off the OpenRTB native ad standard.

Making a Decision 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 create Custom Reports and Scheduled Reports. See our Reporting API instructions for more info.

You may also be interested in Data Shipping

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

Suggest Edits

Queued Reports

 

Queued Reports are the API equivalent of Custom Reports in the UI. Queued Reports are a two step process. You first need to use the Create Queued Report to get the Report GUID, then ping Poll for Queued Report Result endpoint to get the actual data.

Suggest Edits

Create Queued Report

 
post
 

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. See our Custom Report Fields, Custom Report Columns, and Reporting API Instructions for more info.

Definition

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

Arguments

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

Required

Property
Description

StartDateISO
(string)

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

EndDateISO
(string)

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

StartDate
(string) - deprecated

The start date for the report. Format is MM/DD/YYYY. Required only if 'StartDateISO` is missing.

EndDate
(string) - deprecated

The end date for the report. Format is MM/DD/YYYY. Required only if 'EndDateISO` is missing

GroupBy
(object, list of strings)

One of the following is required for a Date Group: day, week, month, or empty array (for total).

Note - StartDate and EndDate

Requests must include StartDateISO OR StartDate. StartDateISO overrides StartDate if different. Only use the deprecated StartDate if you don't have your dates in ISO 8601 format. This applies to 'EndDate' and 'EndDateISO' too.

Note - GMT

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

Reports that are grouped by Keyword AND Country or Metro AND include a longer than 31 day time span are too large to be queued.

Optional

Property
Description

GroupBy
(object, list of strings)

Break out the data in the report by one or more values. More info here

Parameters
(object, list of Crit objects)

An unlimited number of criteria that will filter the report. More info here

ToDate
(enum) - beta

Sets a report time frame in the criteria object without using a start or end date. See below table.

For GroupBy, you can group by day, week, month, brandId, campaignId, optionId, creativeId, adTypeId, siteId, zoneId, publisherAccountId, countryCode, metroCode, keyword

For Parameters, 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

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

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 persist for 30 days

Report Creation Errors

All errors are wrapped in an {"Error"} object.

Error Code
JSON Response
Error Description

500

"Server Error"

Report queuing is unavailable. Check the status page for details. If none are available, contact Adzerk support

403

"Invalid API key"

No API key in request, or the key does not belong to an account

400

"Missing required parameter: criteria"

No criteria object in the request

400

{"Validation errors": {"JSON parse error": <error-detail-string>}}

Invalid JSON passed in the request. Includes a string with the parsing error

400

{"Validation errors": {"End": "Start must precede end"}}

The Start Date is after the End Date

400

{"Validation errors": {"Date range": "Exactly one of the following must be provided: 1. Both StartDate and EndDate. 2. Both StartDateISO and EndDateISO. 3. ToDate."}}

No Date-related parameters are supplied

400

{"Validation errors": {"StartDate": "StartDate must not be specified when StartDateISO is."}}

Both StartDate and StartDateISO are supplied

400

{"Validation errors": {"EndDate": "EndDate must not be specified when EndDateISO is."}}

Both EndDateandEndDateISO` are supplied

400

{"Validation errors": {"ToDate": "Start and end dates must not be specified when ToDate is."}}

ToDate is supplied, but so are other Date-related parameters

400

{"Validation errors":{"StartDate":{"reason":"Invalid date format: 'xxxxx' is malformed at 'xxxxx'. Dates should be formatted like MM/dd/yyyy, e.g. 12/31/2016"}

StartDate or EndDate are not formatted correctly

400

{"Validation errors":{"StartDateISO":{"reason":"Invalid date format: 'xxxxx' is malformed at 'xxxxx'. Dates should be formatted like yyyy-MM-dd'T'HH:mm:SS, e.g. 2016-12-31T00:00:00"}

StartDateISO or EndDateISO are not formatted correctly

400

{"Validation errors":{"GroupBy":{"reason":"GroupBy not an array"}}}

A parameter (such as GroupBy) uses the wrong data type

400

{"Validation errors":{"GroupBy":{"reason":"GroupBy contains some elements that are not strings.","elements":[1234,"campaignId"]}}}

One of the GroupBy elements uses the wrong data type

400

{"Validation errors":{"GroupBy":{"fields":["flightid"],"reason":"Invalid GroupBy fields. Valid values must be one of 'adtypeid', 'brandid', 'campaignid', 'countrycode', 'creativeid', 'day', 'keyword', 'metrocode', 'month', 'optionid', 'publisheraccountid', 'siteid', 'week', 'zoneid'."}}}

Invalid GroupBy element

400

{"Validation errors":{"Parameters":{"reason":"Parameters not an array.","value":1234}}}

Parameters is not an object

400

{"Validation errors":{"Parameters":[{"param":{},"reason":"parameter object must have one property"}]}}

Parameters must have at least one property

400

{"Validation errors":{"Parameters":[{"name":"foo","reason":"invalid parameter name"}]}}

Parameter property does not exist

400

{"Validation errors":{"Parameters":[{"parameter":"SiteId","bad-value":"foo","reason":"id parameter value must be a positive integer"}]}}

Parameter value must be an integer

400

{"Validation errors":{"Parameters":[{"parameter":"metroCode","bad-value":1000,"reason":"metroCode, countryCode, and keyword values must be strings"}]}}

Parameter value must be a string (in the case of metroCode, countryCode, and keyword)

400

{"Validation errors":{"ReportTooLarge":"A report grouping by Keyword and either Country or Metro cannot exceed a one month (31 day) span."}}}

Reports that are grouped by Keyword and Country/Metro AND include a longer than 31 day time span cannot be queued.

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

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

Poll for Queued Report Result

 
get
 

Description

After a GUID has been generated by the Create 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/{{GUID}}

Response

Returns an object with the following properties:

Property
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. Description of the Result is below.

Result properties:

Property
Description

IsTotal
(boolean)

If true, the report uses the Total time period

LoginId
(integer)

An internal Login ID used for generating the report

Title
(string)

Deprecated

Grouping
(array)

The time groupings (such as month) and the GroupBys (such as siteId) of the report

Critiera [sic]
(object)

Key/value pairs of the filters applied to the report. For example: [{"brandId": 12345}]

ReportId
(string)

Deprecated

RecordTitle
(string)

Deprecated

StartDate
(string)

In the format of YYYY-MM-DDTHH:MM:SS. Deprecated in favor of StartDateISO

StartDateISO
(string)

In the format of YYYY-MM-DDTHH:MM:SS.0000000

EndDate
(string)

In the format of YYYY-MM-DDTHH:MM:SS. Deprecated in favor of EndDateISO

EndDateISO
(string)

In the format of YYYY-MM-DDTHH:MM:SS.0000000

TotalTestBucketClicks
(integer)

If test IP addresses have been added to click bucketing settings, the total number of clicks from those IPs

TotalDuplicateIPBucketClicks
(integer)

Total number of clicks originating from the same IP address

TotalRawBucketClicks
(integer)

Total number of raw clicks, valid and invalid (i.e. no click bucketing)

TotalSupiciousBucketClicks
(integer)

Total number of clicks originating from suspicious sources (such as bots, etc.)

TotalInvalidUABucketClicks
(integer)

Total number of clicks originating from an invalid user agent

TotalDuplicateImpressionBucketClicks
(integer)

Total number of clicks originating from the same impression

TotalUniqueBucketClicks
(integer)

Total number of clicks originating from a unique and valid source

TotalClicks
(integer)

Total number of clicks (as calculated without using click bucketing)

TotalCTR
(float)

Total clickthrough rate (derived from TotalClicks)

TotalUniqueCTR
(float)

Total clickthrough rate (derived from TotalUniqueBucketClicks)

TotalRevenue
(float)

Total revenue. Deprecated in favor of TotalTrueRevenue

TotalTrueRevenue
(float)

Total revenue

TotalECPM
(float)

Total eCPM

TotalImpressions
(integer)

Total impressions

TotalRequests
(integer)

(BETA) Total requests for the placements. (Does not include Passback and RTB Requests)

TotalRtbMatchedRequests
(integer)

(BETA) Number of times RTB partner(s) received a request AND a user was matched, regardless of whether they bid

TotalRtbRequests
(integer)

(BETA) Number of times RTB partner(s) received a request, regardless of whether they bid

TotalRtbBidRequests
(integer)

(BETA) Number of times Adzerk received a bid from a RTB provider

TotalPassbackRequests
(integer)

(BETA) If an ad response includes an ad in an adChain priority, Passback Requests counts all the flights in the adChain considered for the selection

TotalFillRate
(float)

(BETA) TotalImpressions divided by TotalRequests as a percentage

OptionRecords
(array)

Deprecated

Records
(array)

All additional (non-total) details of the report. Description of Records is below.

Records array:

There is a unique object in the Records array per time period in the DateType. For example, a report with a 6 months time frame that is grouped by month will contain 6 objects in the Records array. This object is labeled by FirstDate and LastDate strings in the format YYYY-MM-DDTHH:MM:SS.

The object contains the same types of click and impression data etc. as the Total properties in the Result object. In addition, there is also an Events object that counts custom events by EventId.

Inside the object is a Details array. Each GroupBy in the report is broken out as a unique object in Details, including its own clicks and impressions pertinent to that GroupBy. The Grouping object inside that object states which GroupBy is being applied.

The report on the right has an example of Records, Details, and Grouping.

Conversions are represented in reports as Read-Only EventIds. Unlike other custom events, these EventIds can NOT be used to generate a tracking link in a Decision request.

1 = View Conversion
2 = Click Conversion
3 = Server Conversion

Some fields in the example response, such as the request reporting fields, are additional features. Contact your account manager for more information.

curl -X GET -H "X-Adzerk-ApiKey:<APIKEY>" -H "Content-Type=application/x-www-form-urlencoded" https://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,
                "RtbBidRequests": 0,
                "RtbRequests": 0,
                "PassbackRequests": 0,
                "Requests": 1920036,
                "RtbMatchedRequests": 0,
                "FillRate": 7.373,
                "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,
                "TotalCTR":0,
                "TotalAdjustedCTR":0,
                "TotalRevenue":0,
                "TotalTrueRevenue":0,
                "TotalECPM":0,
                "TotalRtbMatchedRequests": 0,
                "TotalRtbRequests": 0,
                "TotalRequests": 500,
                "TotalPassbackRequests": 0,
                "TotalFillRate": 3,
                "TotalRtbBidRequests": 0
            }
        ]
    }
}
Suggest Edits

Scheduled Reports

 

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 e-mail to the account associated with the LoginId. You can optionally also include other e-mails to send the report to.

The e-mail 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)

 
post
 

Description

This creates a Scheduled Report.

Definition

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

Arguments

Technically, there are no required fields. However, the recommended fields will ensure that your Report has all the necessary fields to be recurring.

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

You'll want to wrap in a scheduledReport object.

Recommended

Properties
Description

Name
(string)

A friendly name for the report

LoginId
(integer)

The LoginId for the user who should receive the report. This is the ID that's returned in the User Management API endpoints. You can pull a list here

KickoffDate
(string)

The date to begin generating the report. We will use this date and the RecurrenceType to determine when the report should recur. Use format MM/DD/YYYY

SchedulingWindow
(integer)

The timeframe in which the report should be delivered. All times are in GMT. Key
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)

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. Key:
0 = no recurrence (not yet implemented)
1 = daily
2 = weekly
3 = monthly

Criteria
(object)

Use same criteria from Queued Reports

Optional

Properties
Description

Emails
(array)

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

ShowEvents
(boolean)

Display events (conversions, custom events, etc.). Default is false

ShowRevenue
(boolean)

Display revenue. Default is false

ShowClickBuckets
(boolean)

Display clicks sorted by click bucketing. Default is false

fixedDate
(boolean)

Prevents the time frame of the report from incrementing with each send. Default is false

All times are in GMT

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 ScheduledReportId in the id field.

scheduledReport={ 
  "Name": "Daily Report for Nike", 
  "LoginId": 12345, 
  "KickoffDate": "11/30/2015", 
  "SchedulingWindow": 1, 
  "RecurrenceType": 1,
  "Criteria": {
       "StartDate":"2014-03-01T00:00:00",
       "EndDate":"2014-03-31T00:00:00",
       "Parameters": [{"siteId":12345}], 
       "GroupBy": ["day"] 
  } 
}
curl -i -H 'X-Adzerk-ApiKey:<APIKEY>' -H 'Content-Type: application/x-www-form-urlencoded' 'https://api.adzerk.net/v1/report/schedule' -X POST --data-urlencode '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":"Daily Report for Nike",
    "Criteria":{  
        "StartDate":"2017-01-01T00:00:00",
        "EndDate":"2017-01-31T00:00:00",
        "Parameters":[  
            {  
                "siteId":123456
            }
        ],
        "GroupBy":[  
            "day"
        ],
        "Top30countries":false,
        "Exclude3rdParty":false,
        "IsTotal":false
    },
    "LoginId":12345,
    "KickoffDate":"2017-01-01T00:00:00",
    "SchedulingWindow":1,
    "RecurrenceType":1,
    "IsDeleted":false
}
Suggest Edits

Get Scheduled Report

 
get
 

Description

This returns the properties of a scheduled report given a ScheduledReportId (the id from the Create Schedule Reports Response).

No parameters are needed except ScheduledReportId in URL.

Definition

GET https://api.adzerk.net/v1/report/schedule/{{ScheduledReportID}}

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":"Daily Report for Nike",
    "Criteria":{  
        "StartDate":"2017-01-01T00:00:00",
        "EndDate":"2017-01-31T00:00:00",
        "Parameters":[  
            {  
                "siteId":123456
            }
        ],
        "GroupBy":[  
            "day"
        ],
        "Top30countries":false,
        "Exclude3rdParty":false,
        "IsTotal":false
    },
    "LoginId":1234,
    "KickoffDate":"2017-01-31T00:00:00",
    "SchedulingWindow":1,
    "RecurrenceType":1,
    "IsDeleted":false
}
Suggest Edits

List Scheduled Reports

 
get
 

Description

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

Definition

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

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":"2017-01-01T00:00:00",
                "EndDate":"2017-01-31T00:00:00",
                "Parameters":[  
                    {  
                        "siteId":123456
                    }
                ],
                "GroupBy":[  
                    "day"
                ],
                "Top30countries":false,
                "Exclude3rdParty":false,
                "IsTotal":false
            },
            "LoginId":1234,
            "KickoffDate":"2017-01-01T00:00:00",
            "SchedulingWindow":1,
            "RecurrenceType":1,
            "IsDeleted":false
        },...
Suggest Edits

Delete Scheduled Reports

 
get
 

Description

This removes a scheduled report from your account.

No parameters are needed, except ScheduledReportId in the URL. If successful, you'll receive the message: "Successfully Deleted"

Definition

GET https://api.adzerk.net/v1/report/schedule/{{ScheduledReportID}}/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. This helps with the accuracy of the reports, so that your internal clicks aren't skewing the data.

Use the below endpoints to update what Test IPs are in Adzerk's system.

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

Definition: http://api.adzerk.net/v1/{{INSERT_BELOW}}

For the POST endpoints, wrap in a testIPs object. Use Key/Value pairs for ip and name, like:

testIPs=[{"ip":"158.183.222.119", "name":"My Office"}]
Endpoint
Request Method
Purpose
Expects
Normally Returns

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"}]}

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

testips/replace

POST

Replaces the entry for an IP or name

A key/value pair with an array of IPs

The updated array

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

Real Time Reporting API

 

The Real Time Reporting API delivers reporting data about advertisers, campaigns, flights and ads within minutes of events being recorded in our system. While this data is not as comprehensive as Adzerk Reporting or Data Shipping, it enables near-instant feedback on the performance of your ads.

Real Time Reporting API data is a cumulative count of all the impressions, clicks, etc. since either:

  • The creation of your advertiser/campaign/etc.
  • June 1, 2016

To get data for a custom time period, use the parameters described in the endpoints. Data for a custom period is provided only for the past 90 days.

Real Time Reporting data is delivered as a JSON object.

Real time data is updated approximately every five minutes.

Error Handling

If you request an Id that does not exist using the GET endpoints, you will receive a 400 and the message:

{
  "message": "does not exist"
}

If you request an Id that does not exist using the POST endpoint, the data for that Id will not be returned in the object, but other Ids will be returned.

If you request a custom time period outside the past 90 day range, you will receive a 400 and the message:

{
  "message": "cannot request data more than 90 days old"
}

If you request a start date past the end, you will receive a 400 and the message:

{
  "message":"start date must be before end date"
}
Suggest Edits

Get Advertiser Counts

 
get
 

Description

This returns real time reporting data for an advertiser.

No parameters are required, except "Advertiser ID" in URL.

Several query parameters are optional:

days - (integer) Returns data for the number of days since the current day. You can request a maximum of 90 days of data and a minimum of 0. days=0 returns data for the current day.

start - (string) in the format of YYYY-MM-DD. Returns data starting from the date specified. Must be within the past 90 days. If no end is included, this will return data up to the current day.

end - (string) in the format of YYYY-MM-DD. Returns data ending at the date specified. Must be within the past 90 days.

If days and start/ end are both present in a request (not recommended) start/ end will take precedence.

See example requests on the right.

If no query parameters are included, the endpoint returns the lifetime of data for the Id.

Definition

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

curl -X GET -H 'X-Adzerk-ApiKey:<API-KEY>' https://api.adzerk.net/v1/instantcounts/advertiser/123
curl -X GET -H 'X-Adzerk-ApiKey:<API-KEY>' https://api.adzerk.net/v1/instantcounts/advertiser/123?days=42
curl -X GET -H 'X-Adzerk-ApiKey:<API-KEY>' 'https://api.adzerk.net/v1/instantcounts/advertiser/123?start=2017-04-18&end=2017-04-20'
{
  "advertisers": {
    "123": {
      "impressions": 3097,
      "conversions": 12,
      "revenue": 49.11279,
      "clicks": 149
    }
  }
}
{
  "advertisers": {
    "123": {
      "2017-04-18": {
        "impressions": 1,
        "conversions": 1,
        "revenue": 0,
        "clicks": 0
      },
      "2017-04-19": {
        "impressions": 2,
        "conversions": 0,
        "revenue": 0,
        "clicks": 2
      },
      "2017-04-20": {
        "impressions": 3,
        "conversions": 0,
        "revenue": 0,
        "clicks": 0
      },
      "total": {
        "impressions": 6,
        "conversions": 1,
        "revenue": 0,
        "clicks": 2
      }
    }
  }
}
Suggest Edits

Get Campaign Counts

 
get
 

Description

This returns real time reporting data for a campaign.

No parameters are needed, except "Campaign ID" in URL.

Several query parameters are optional:

days - (integer) Returns data for the number of days since the current day. You can request a maximum of 90 days of data and a minimum of 0. days=0 returns data for the current day.

start - (string) in the format of YYYY-MM-DD. Returns data starting from the date specified. Must be within the past 90 days. If no end is included, this will return data up to the current day.

end - (string) in the format of YYYY-MM-DD. Returns data ending at the date specified. Must be within the past 90 days.

If days and start/ end are both present in a request (not recommended) start/ end will take precedence.

See example requests on the right.

If no query parameters are included, the endpoint returns the lifetime of data for the Id.

Definition

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

curl -X GET -H 'X-Adzerk-ApiKey:<API-KEY>' https://api.adzerk.net/v1/instantcounts/campaign/123
curl -X GET -H 'X-Adzerk-ApiKey:<API-KEY>' https://api.adzerk.net/v1/instantcounts/campaign/123?days=42
curl -X GET -H 'X-Adzerk-ApiKey:<API-KEY>' 'https://api.adzerk.net/v1/instantcounts/campaign/123?start=2017-04-18&end=2017-04-20'
{
  "campaigns": {
    "123": {
      "impressions": 123,
      "conversions": 0,
      "revenue": 0.117,
      "clicks": 0
    }
  }
}
{
  "campaigns": {
    "123": {
      "2017-04-18": {
        "impressions": 1,
        "conversions": 1,
        "revenue": 0,
        "clicks": 0
      },
      "2017-04-19": {
        "impressions": 2,
        "conversions": 0,
        "revenue": 0,
        "clicks": 2
      },
      "2017-04-20": {
        "impressions": 3,
        "conversions": 0,
        "revenue": 0,
        "clicks": 0
      },
      "total": {
        "impressions": 6,
        "conversions": 1,
        "revenue": 0,
        "clicks": 2
      }
    }
  }
}
Suggest Edits

Get Flight Counts

 
get
 

Description

This returns real time reporting data for a flight.

No parameters are needed, except "Flight ID" in URL.

Several query parameters are optional:

days - (integer) Returns data for the number of days since the current day. You can request a maximum of 90 days of data and a minimum of 0. days=0 returns data for the current day.

start - (string) in the format of YYYY-MM-DD. Returns data starting from the date specified. Must be within the past 90 days. If no end is included, this will return data up to the current day.

end - (string) in the format of YYYY-MM-DD. Returns data ending at the date specified. Must be within the past 90 days.

If days and start/ end are both present in a request (not recommended) start/ end will take precedence.

See example requests on the right.

If no query parameters are included, the endpoint returns the lifetime of data for the Id.

Definition

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

curl -X GET -H 'X-Adzerk-ApiKey:<API-KEY>' https://api.adzerk.net/v1/instantcounts/flight/123
curl -X GET -H 'X-Adzerk-ApiKey:<API-KEY>' https://api.adzerk.net/v1/instantcounts/flight/123?days=42
curl -X GET -H 'X-Adzerk-ApiKey:<API-KEY>' 'https://api.adzerk.net/v1/instantcounts/flight/123?start=2017-04-18&end=2017-04-20'
{
  "flights": {
    "123": {
      "impressions": 123,
      "conversions": 0,
      "revenue": 0.117,
      "clicks": 0
    }
  }
}
{
  "flights": {
    "123": {
      "2017-04-18": {
        "impressions": 1,
        "conversions": 1,
        "revenue": 0,
        "clicks": 0
      },
      "2017-04-19": {
        "impressions": 2,
        "conversions": 0,
        "revenue": 0,
        "clicks": 2
      },
      "2017-04-20": {
        "impressions": 3,
        "conversions": 0,
        "revenue": 0,
        "clicks": 0
      },
      "total": {
        "impressions": 6,
        "conversions": 1,
        "revenue": 0,
        "clicks": 2
      }
    }
  }
}
Suggest Edits

Get Ad Counts

 
get
 

Description

This returns real time reporting data for an ad.

No parameters are needed, except "Ad ID" in URL.

Several query parameters are optional:

days - (integer) Returns data for the number of days since the current day. You can request a maximum of 90 days of data and a minimum of 0. days=0 returns data for the current day.

start - (string) in the format of YYYY-MM-DD. Returns data starting from the date specified. Must be within the past 90 days. If no end is included, this will return data up to the current day.

end - (string) in the format of YYYY-MM-DD. Returns data ending at the date specified. Must be within the past 90 days.

If days and start/ end are both present in a request (not recommended) start/ end will take precedence.

See example requests on the right.

If no query parameters are included, the endpoint returns the lifetime of data for the Id.

Definition

GET https://api.adzerk.net/v1/instantcounts/ad/123

curl -X GET -H 'X-Adzerk-ApiKey:<API-KEY>' https://api.adzerk.net/v1/instantcounts/ad/123
curl -X GET -H 'X-Adzerk-ApiKey:<API-KEY>' https://api.adzerk.net/v1/instantcounts/ad/123?days=42
curl -X GET -H 'X-Adzerk-ApiKey:<API-KEY>' 'https://api.adzerk.net/v1/instantcounts/ad/123?start=2017-04-18&end=2017-04-20'
{
  "ads": {
    "123": {
      "impressions": 123,
      "conversions": 0,
      "revenue": 0.117,
      "clicks": 0
    }
  }
}
{
  "ads": {
    "123": {
      "2017-04-18": {
        "impressions": 1,
        "conversions": 1,
        "revenue": 0,
        "clicks": 0
      },
      "2017-04-19": {
        "impressions": 2,
        "conversions": 0,
        "revenue": 0,
        "clicks": 2
      },
      "2017-04-20": {
        "impressions": 3,
        "conversions": 0,
        "revenue": 0,
        "clicks": 0
      },
      "total": {
        "impressions": 6,
        "conversions": 1,
        "revenue": 0,
        "clicks": 2
      }
    }
  }
}
Suggest Edits

Get Bulk Counts

 
post
 

Description

This returns real time reporting data for more than one advertiser, campaign, flight, or ad. You can request as many as you need from each category.

The required parameter is a JSON object containing the Ids you want to get counts for:

{"advertisers": [123,456], "campaigns": [789,123], "flights": [456,789], "ads": [123,456]}

You are also required to pass the header 'Content-Type:application/json'.

To request data broken out by day, you can add the optional top-level key days to the object to return data for the past number of days (current data is 0). Its value is an integer:

{"advertisers": [123,456], "campaigns": [789,123], "flights": [456,789], "ads": [123,456],"days":42}

Or, you can add the top-level keys start and end to specify a date range. Their values are a string in the format YYYY-MM-DD:

{"advertisers": [123,456], "campaigns": [789,123], "flights": [456,789], "ads": [123,456],"start":"2017-04-20", "end":"2017-04-21"}

We will only return data for the past 90 days when requesting days. If you do not specify days, start, or end, will return lifetime data.

If days and start/ end are both present in a request (not recommended) start/ end will take precedence.

curl -X POST -H 'X-Adzerk-ApiKey:<API-KEY>' -H 'Content-Type:application/json' https://api.adzerk.net/v1/instantcounts/bulk -d '{"advertisers": [123], "campaigns": [456], "flights": [789], "ads": [123], "start":"2016-04-20", "end":"2016-04-21"}'
curl -X POST -H 'X-Adzerk-ApiKey:<API-KEY>' -H 'Content-Type:application/json' https://api.adzerk.net/v1/instantcounts/bulk -d '{"advertisers": [123,456], "campaigns": [789,123], "flights": [456,789], "ads": [123,456]}'

curl -X POST -H 'X-Adzerk-ApiKey:<API-KEY>' -H 'Content-Type:application/json' https://api.adzerk.net/v1/instantcounts/bulk -d '{"advertisers": [123,456], "campaigns": [789,123], "flights": [456,789], "ads": [123,456], "days":42}'
{
  "advertisers": {
    "123": {
      "impressions": 3097,
      "conversions": 12,
      "revenue": 49.11279,
      "clicks": 149
    },
    "456": {
      "impressions": 100,
      "conversions": 0,
      "revenue": 0.011,
      "clicks": 0
    }
  },
  "campaigns": {
    "789": {
      "impressions": 100,
      "conversions": 0,
      "revenue": 0.011,
      "clicks": 0
    },
    "123": {
      "impressions": 123,
      "conversions": 0,
      "revenue": 0.117,
      "clicks": 0
    }
  },
  "flights": {
    "456": {
      "impressions": 0,
      "conversions": 0,
      "revenue": 0,
      "clicks": 0
    },
    "789": {
      "impressions": 106,
      "conversions": 0,
      "revenue": 0.106,
      "clicks": 0
    }
  },
  "ads": {
    "123": {
      "impressions": 0,
      "conversions": 0,
      "revenue": 0,
      "clicks": 0
    },
    "456": {
      "impressions": 106,
      "conversions": 0,
      "revenue": 0.106,
      "clicks": 0
    }
  }
}
{
  "advertisers": {
    "123": {
      "2017-04-20": {
        "impressions": 1,
        "conversions": 0,
        "revenue": 0,
        "clicks": 0
      },
      "2017-04-21": {
        "impressions": 1,
        "conversions": 0,
        "revenue": 0,
        "clicks": 0
      },
      "total": {
        "impressions": 2,
        "conversions": 0,
        "revenue": 0,
        "clicks": 0
      }
    }
  },
  "campaigns": {
    "456": {
      "2017-04-20": {
        "impressions": 4,
        "conversions": 0,
        "revenue": 0,
        "clicks": 0
      },
      "2017-04-21": {
        "impressions": 5,
        "conversions": 0,
        "revenue": 0,
        "clicks": 1
      },
      "total": {
        "impressions": 9,
        "conversions": 0,
        "revenue": 0,
        "clicks": 1
      }
    }
  },
  "flights": {
    "789": {
      "2017-04-20": {
        "impressions": 2,
        "conversions": 0,
        "revenue": 0,
        "clicks": 0
      },
      "2017-04-21": {
        "impressions": 2,
        "conversions": 1,
        "revenue": 0,
        "clicks": 0
      },
      "total": {
        "impressions": 4,
        "conversions": 1,
        "revenue": 0,
        "clicks": 0
      }
    }
  },
  "ads": {
    "123": {
      "2017-04-20": {
        "impressions": 10,
        "conversions": 0,
        "revenue": 0,
        "clicks": 0
      },
      "2017-04-21": {
        "impressions": 2,
        "conversions": 0,
        "revenue": 1.0,
        "clicks": 0
      },
      "total": {
        "impressions": 12,
        "conversions": 0,
        "revenue": 1.0,
        "clicks": 0
      }
    }
  }
}
Suggest Edits

Campaign API Overview

 

The Adzerk Campaign Management API lets you create, update, list, get, search, and delete:

Advertisers
Campaigns
Flights
Creatives
Ads
Geo-Targeting
Flight Categories
Site/Zone Targeting
Targeting Optimization

Please visit our Campaigns Overview page for a deeper explanation of the Campaigns section breakdown.

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.

Response

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

criteria={"StartDate":"01/01/2015","EndDate":"02/02/2015","GroupBy":["campaignId"], "Parameters":[{"siteId":123456}]}
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}]}'
{
"Id": 12345,
"Title": "Test advertiser",
"IsActive": true,
"IsDeleted": false,
}
Suggest Edits

Advertisers

 

Advertisers are the people/businesses whose ads will be shown. More information here.

Suggest Edits

Create Advertisers

 
post
 

Description

This creates a new advertiser.

Definition

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

Arguments

Please refer to our Creating an Advertiser instructions for more information.

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

Required

Property
Description

Title
(string)

The advertiser name. Required

IsDeleted
(boolean)

Whether advertiser is deleted. Always set to false when creating. Required

IsActive
(boolean)

Where advertiser is running. Always set to true when creating. Defaults to false. Required

When creating an Advertiser, always set IsDeleted = False and IsActive = True

Optional

Property
Description

PlacementLimit
(boolean)

How many placements the advertiser's ads can fill per request

FreqCap
(integer)

The number of times that you would like the frequency cap to occur. Set-up instructions here

FreqCapDuration
(integer)

How often the frequency cap should occur. Set-up instructions here

FreqCapType
(integer)

The unit of time you would like frequency capping to occur. Key follows: 1 = Hour 2 = Day. Set-up instructions here

CapType
(integer)

Set to CapType = 4. Advertisers can only budget cap on revenue metric. Do not set to 0 - if removing, set to null

DailyCapAmount
(integer)

The max daily revenue

LifetimeCapAmount
(integer)

The max lifetime revenue

Response

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

advertiser={
  "Title":"Captain America",
  "IsDeleted":false,
  "IsActive":true,
  "PlacementLimit":0,
  "FreqCap": 2,
  "FreqCapDuration": 10,
  "FreqCapType": 1,
  "CapType": 4,
  "DailyCapAmount": 5000,
  "LifetimeCapAmount": 50000
}
curl -X POST -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/advertiser --data-urlencode 'advertiser={"Title":"Captain American","IsDeleted":false,"IsActive":true}'

{
"Id": 12345,
"Title": "Captain America",
"IsDeleted": false,
"IsActive": true,
"PlacementLimit":0,
"FreqCap": 2,
"FreqCapDuration": 10,
"FreqCapType": 1,
"CapType": 4,
"DailyCapAmount": 5000,
"LifetimeCapAmount": 50000
}
Suggest Edits

Update Advertisers

 
put
 

Description

This updates settings for a given advertiser. Make sure the URL has the right "Advertiser ID".

Definition

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

Arguments

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

The example to the right takes the Create Advertisers example and updates the PlacementLimit to 4.

Id, Title, and IsActive are required fields for the Update Advertisers request. You can update any field except the id.

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":12345,
  "Title":"Captain America",
  "IsDeleted":false,
  "IsActive":true,
  "PlacementLimit":4
}
curl -X PUT -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/advertiser/12345 --data-urlencode 'advertiser={"Id":12345,"Title":"Captain America","IsActive":true}'
{
  "Id":12345,
  "Title":"Captain America",
  "IsActive":true,
  "IsDeleted":false,
  "PlacementLimit":4,
  "FreqCap": 2,
  "FreqCapDuration": 10,
  "FreqCapType": 1,
  "CapType": 4,
  "DailyCapAmount": 5000,
  "LifetimeCapAmount": 50000
}
Suggest Edits

List Advertisers

 
get
 

Description

This returns a JSON object of all your advertisers.

Definition

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

{
  "page": 1,
  "pageSize": 10,
  "totalPages":1,
  "totalItems":1,
  "items":[
    {
        "Id":123,
        "Title":"Captain America",
        "IsActive":true,
        "IsDeleted":false,
        "PlacementLimit":null,
        "FreqCap": 2,
        "FreqCapDuration": 10,
        "FreqCapType": 1,
        "CapType": 4,
        "DailyCapAmount": 5000,
        "LifetimeCapAmount": 50000
    }
  ]
}
Suggest Edits

Get Advertisers

 
get
 

Description

This returns the properties of an advertiser.

No parameters are needed, except "Advertiser ID" in URL.

Definition

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

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

 
post
 

Description

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

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 --data-urlencode "advertiserName=Nike”
{
    "PageNumber": 1,
    "PageSize": 10,
    "TotalPages": 1,
    "TotalItems": 1,
    "Items": [
        {
            "Id": 12346,
            "Title": "Nike",
            "IsActive": true,
            "IsDeleted": false,   
            "PlacementLimit":0,
            "FreqCap": 2,
            "FreqCapDuration": 10,
            "FreqCapType": 1
        }
    ]
}
Suggest Edits

Get Conversion Tracking Pixel

 
get
 

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. Make sure the URL has the right "Advertiser ID".

Definition

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

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

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

 

Campaigns live under an advertiser and enable them to run separate campaigns with different targeting, ads, flight dates, etc. More info here.

Suggest Edits

Create Campaigns

 
post
 

Description

This creates a new campaign under an advertiser.

Definition

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

Arguments

Please refer to our Creating a Campaign instructions for more info.

You should post the properties below wrapped in a campaign object. You can include pre-existing flights, or you can pass in a blank array for flights.

Required

Property
Description

AdvertiserId
(integer)

The advertiser's id for the campaign. Required.

Name
(string)

The campaign name. Required.

StartDate
(JSON date)

The start date. Required, but not used for anything. Just put as 1/1/2017.

Flights
(array)

You can either pass in an array of flights or a blank array. See Create Flight endpoint. Required.

StartDate is required but no longer used (Start Dates are now tied to Flights/Ads). Anything you put here will be ignored, so we recommend putting in 1/1/2017 for all requests.

Optional General Settings

Property
Description

IsActive
(boolean)

Whether campaign should be active (serving ads). Defaults to false

IsDeleted
(boolean)

Whether campaign should be deleted. Do not use when creating a campaign.

IsArchived
(boolean)

Whether campaign should be archived. Do not use when creating a campaign.

Frequency Capping - Optional - Click here for set-up guide.

Property
Description

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)

Enum value for how often frequency capping should occur. 1 = Hour 2 = Day

DontAffectParentFreqCap
(integer)

"Opts-out" campaign from advertiser-level frequency cap settings

Budget Capping - Optional - Learn more here.

Property
Description

CapType
(integer)

Set to CapType = 4. Campaigns can only budget cap on revenue metric. Do not set to 0 - if removing, set to null

DailyCapAmount
(integer)

The max daily revenue

LifetimeCapAmount
(integer)

The max lifetime revenue

Not Commonly Used / Deprecated

Property
Description

SalespersonId
(integer)

Network-level login Id of salesperson

CustomFieldsJson
(string)

Sets the value of custom fields based on a custom fields schema. Must contact support before use. More info here

Price (deprecated)
(float/decimal)

Deprecated

EndDate
(JSON date)

End date. No longer used (End Dates are now at Flight or Ad level)

StartDateISO

Deprecated (Start Dates at Flight/Ad level)

EndDateISO

Deprecated (Start Dates at Flight/Ad leve)

Response

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

campaign={
  "AdvertiserId":12345,
  "Name":"Exploding Kittens",
  "StartDate":"1/1/2017",
  "flights":[],
  "IsActive":true,
  "FreqCap": 2,
  "FreqCapDuration": 10,
  "FreqCapType": 1,
  "DontAffectParentFreqCap": true,
  "CapType": 4,
  "DailyCapAmount": 5000,
  "LifetimeCapAmount": 50000
}
curl -X POST -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/campaign --data-urlencode 'campaign={"Name":"Exploding Kittens","StartDate":"1/1/2017","AdvertiserId":12345,"IsActive":true,"flights":[]}'
{
  "Id":56789,
  "Name":"Exploding Kittens",
  "StartDate":"/Date(1293840000000)/",
  "EndDate": "/Date(1293840000000)/",
  "IsActive":true,
  "Price":null,
  "AdvertiserId":12345,
  "Flights":[],
  "IsDeleted":false,
  "SalespersonId":null,
  "FreqCap": 2,
  "FreqCapDuration": 10,
  "FreqCapType": 1,
  "DontAffectParentFreqCap": true,
  "CapType": 4,
  "DailyCapAmount": 5000,
  "LifetimeCapAmount": 50000,
  "IsArchived":false
}
Suggest Edits

Update Campaigns

 
put
 

Description

Updates a campaign.

Make sure the URL has the right "Campaign ID", which you received in the Create Campaigns response.

Definition

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

Arguments

You should submit properties wrapped in a campaign object.

Id, AdvertiserId, Name, StartDate, and IsActive are required fields for the Update Campaigns request. You can update any field except the id.

The example to the right takes the Create Campaigns examples and updates isActive from true to false.

When updating a campaign, you MUST use the AdvertiserId of the campaign when it was created. Campaigns cannot change advertisers in Adzerk.

campaign={
  "Id":56789,
  "AdvertiserId":12345,
  "Name":"Exploding Kittens",
  "StartDate":"3/11/2017",
  "IsActive":false
}
curl -X PUT -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/campaign/123456 --data-urlencode 'campaign={"Name":"Exploding Kittens","Id":56789,"StartDate":"3/11/2017","AdvertiserId":12345,"IsActive":false}'
{
    "Id": 56789,
    "Name": "Exploding Kittens",
    "StartDate": "/Date(1420070400000)/",
    "EndDate": null,
    "IsActive": false,
    "Price": null,
    "AdvertiserId": 12345,
    "Flights": null,
    "IsDeleted": false,
    "SalespersonId": null,
    "CustomFieldsJson": null,
    "IsArchived":false
}
Suggest Edits

List Campaigns

 
get
 

Description

This returns a list of all campaigns in your account.

Definition

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

IsArchived Argument - Optional

Property
Description

?isArchived
(boolean)

If true, returns only archived flights

Additional Pagination

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

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": 56789,
            "Name": "Exploding Kittens",
            "StartDate": "2017-03-01T15:41:00",
            "IsActive": true,
            "Price": null,
            "AdvertiserId": 12345,
            "FreqCap": 2,
            "FreqCapDuration": 10,
            "FreqCapType": 1,
            "DontAffectParentFreqCap": true,
            "CustomFieldsJson": null,
            "IsDeleted": false,
            "SalespersonId": null, 
            "IsArchived": null
        }
    ]
}
Suggest Edits

Get Campaigns

 
get
 

Description

This returns parameters for a campaign using its "Campaign ID".

No parameters are needed, except "Campaign ID" in URL.

Definition

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

Exclude Flight Argument - Optional

Property
Description

?excludeFlights
(boolean)

If true, returns only campaign metadata without flight objects. Defaults to false

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

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

Search Campaigns

 
post
 

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 --data-urlencode 'campaignName=Nike'
{"PageNumber":1,
"PageSize":10,
"TotalPages":1,
"TotalItems":2,
"Items":[{
    "Id":12366,
    "Name":"Nike Shoes",
    "StartDate":"\/Date(1293858000000-0500)\/",
    "EndDate":"\/Date(1325307600000-0500)\/",
    "IsActive":true,
    "Price":null,
    "AdvertiserId":12345,
    "Flights":null,
    "IsDeleted":false,
        "SalespersonId":null,
        "IsArchived":null},

    {"Id":12367,
    "Name":"Nike Hats",
    "StartDate":"\/Date(1293858000000-0500)\/",
    "EndDate":"\/Date(1325307600000-0500)\/",
    "IsActive":true,
    "Price":null,
    "AdvertiserId":12345,
    "Flights":null,
    "IsDeleted":false,
        "SalespersonId":null,
        "IsArchived":null
    }]
}
 

Flights live under campaigns and enable the breaking out of further targeting options. More info here.

Suggest Edits

Create Flight

 
post
 

Description

This adds a new flight to a campaign.

Definition

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

Arguments

Please refer to our Creating a Flight instructions for more information.

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

Required

Property
Description

Name
(string)

The flight name. Required.

StartDateISO*
(string)

Start date in ISO 8601 format: YYYY-MM-DDTHH:MM:SS.SSSSSSS. Required.

StartDate
(string) - deprecated

Start Date (Deprecated). Used only if StartDateISO is missing. Format: MM/DD/YYY

CampaignId
(integer)

The flight's campaign's ID. Required.

PriorityId
(integer)

The priority ID. Required.

GoalType
(integer)

Your target goal metric. Key follows:
1 = Impressions 2 = Percentage 3 = Click 8 = Revenue (auction priority only) 9 = Daily Revenue (auction priority only). Instructions are here. Required.

Requests must include StartDateISO OR StartDate. StartDateISO overrides StartDate if different. Only use the deprecated StartDate if you don't have your dates in ISO 8601 format. This applies to 'EndDate' and 'EndDateISO' too.

General Settings - Optional

Property
Description

EndDateISO
(string)

End date in ISO 8601 format: `YYYY-MM-DDTHH:MM:SS.SSSSSSS

EndDate
(string) - deprecated

End Date (Deprecated). Used only if EndDateISO is missing. Format: MM/DD/YYY

NoEndDate
(boolean)

If true, Flight doesn't have an end date. Will override the EndDateISO if true.

Impressions
(integer)

The Goal Amount. Instructions are here

IsDeleted
(boolean)

Whether campaign should be deleted. Do not use when creating a campaign. Defaults to false

IsActive
(boolean)

Whether campaigns should be active or not. Defaults to false

RateType
(integer)

The Rate value - instructions here. Key: 1 = Flat 2 = CPM 3 = CPC 4 = CPA View 5 = CPA Click

Price
(float/decimal)

The Price value - instructions here

CapType
(integer)

The cap type metric. Instructions here. Key:
1 = Impressions 2 = Clicks 3 = Conversions 4 = Revenue. Do not set to 0 - if removing, set to null

DailyCapAmount
(integer)

The maximum # of CapType per day. Instructions here

LifetimeCapAmount
(integer)

The maximum # of CapType per lifetime. Instructions here.

Frequency Capping - Optional - Click here for set-up guide

Property
Description

IsFreqCap
(boolean)

Set to true if doing capping. If false or null, then the below fields 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)

Which unit of time you would like frequency capping to occur. Key: 1 = Hour 2 = Day

DontAffectParentFreqCap
(boolean)

Optional. If true, opts-it out of frequency cap settings imposed at advertiser or campaign level

Delivery Settings - Optional

Property
Description

IsCompanion
(boolean)

If true, enables companion ads

isNoDuplicates
(boolean)

If true, enables no duplicates

duplicateMode
(integer)

Indicates which level no duplicates should be enforced on. Key follows: 1: Flight 2: Campaign 3: Advertiser 4: Creative

DeliveryStatus
(integer - read only)

Status of the flight. Key: 0 = Pending 1 = Healthy 2 = BorderLine 3 = InDanger 4 = Finished 5 = Underdelivered

IsTrackingConversions
(boolean)

If true, enables conversion tracking endpoints/pixels

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

IsCompanion must be set to false when IsNoDuplicates is true, and vice versa.

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.

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

Targeting (Optional)

Property
Description

Keywords
(string)

Keywords used for targeting. Instructions here

CustomTargeting
(string)

Zerkel string for Custom targeting. Instructions here

CustomFieldsJson
(string)

Sets the value of custom fields based on a custom fields schema. Must contact support before use. More info here

The maximum string length for CustomTargeting is 1000 characters. If exceeds length, you'll get 400 error status.

Behavioral Targeting Object - Optional

The Behavioral object is used for Interest/Behavioral Targeting and Excluding Ads Based on Behavior.

The BehavioralTargeting object contains six boolean statements, three under onClick and three under onConvert. All default to false. All are optional.

Property
Description

onClick: {"stopShowingAdsFromFlight":XX}

Stops showing ads from flight if someone clicks

onClick: {"stopShowingAdsFromAdvertiser":XX}

Stops showing ads from advertiser if someone clicks

onClick: {storeCategoriesFromFlightAsInterest":XX}

Saves the category of the flight to UserDB, tied to user, based on click

onConvert: {"stopShowingAdsFromFlight":XX}

Stops showing ads from flight if someone converts

onConvert: {"stopShowingAdsFromAdvertiser":XX}

Stops showing ads from advertiser if someone converts

onConvert: {"storeCategoriesFromFlightAsInterest":XX}

Saves the category of the flight to UserDB, tied to user, based on conversion

Site/Zone Targeting Object - Optional

Properties under SiteZoneTargeting object

Property
Description

SiteId
(integer)

ID of targeted site

ZoneId
(integer)

ID of targeted zone

IsExclude
(boolean)

Whether or not the site is included or excluded

eCPM (Optional)

Property
Description

IsECPMOptimized
(boolean)

Whether ECPM Optimization is enabled

ECPMOptimizePeriod
(integer)

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

ECPMMultiplier
(float)

The final eCPM will be multiplied by this amount

FloorECPM
(float)

Minimum eCPM

CeilingECPM
(float)

Maximum eCPM

DefaultECPM
(float)

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

ECPMBurnInImpressions
(impressions)

Impressions per creative to show before using the calculated eCPM over the default eCPM

EffectiveECPMOverride
(float)

Sets a manual override to a flight's CPM, e.g. so a Flat Rate flight can compete in an auction priority

Hour and Day Parting - Optional - See here for set-up instructions

Property
Description

DatePartingStartTimeISO
(string)

The date parting start time in ISO 8601 format: HH:MM:SS

DatePartingEndTimeISO
(string)

The date parting end time in ISO 8601 format: HH:MM:SS

IsSunday
(string)

Whether to show ads on Sunday or not. Default = null

IsMonday
(string)

Whether to show ads on Monday or not. Default = null

IsTuesday
(string)

Whether to show ads on Tuesday or not. Default = null

IsWednesday
(string)

Whether to show ads on Wednesday or not. Default = null

IsThursday
(string)

Whether to show ads on Thursday or not. Default = null

IsFriday
(string)

Whether to show ads on Friday or not. Default = null

IsSaturday
(string)

Whether to show ads on Saturday or not. Default = null

GeoTargeting (Optional) - See here for set-up instructions.

These fields live wrapped in a GeoTargeting object.

Property
Description

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
(string)

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

IsExclude
(boolean)

Set to false or null if you want to target; true if you want to exclude

BETA - Optional

Property
Description

IsArchived
(boolean)

Whether flight is archived or not

IsTargetingOptimized
(boolean)

Whether 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 (boolean) -coming soon

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). Defaults to false

Deprecated

Property
Description

DatePartingStartTime
(string)

Referred to start time in format: HH:MM:SS, or 21:00:00

DatePartingEndTime
(string)

Referred to end time in format: HH:MM:SS, or 21:00:00

OptionType
(integer)

Defaults to 1. Anything else ignored.

IsUnlimited
(boolean)

Set false or leave null.

IsFullSpeed
(boolean)

Set false or leave null.

User Agent Keywords
(string)

Referred to custom targeting for user agent queries. See Reserved Keys for how to do it instead.

CreativeMaps
(array)

Adding creative flight maps using a POST or PUT is no longer supported

WeightOverride

A calculated value for ad balancing. Does not need to be entered.

Response

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

flight={
  "Name":"Jazzercise North Carolina Weekends",
  "StartDateISO":"2017-05-01T00:00:00.00.0000000",
  "EndDateISO":"2017-12-31T00:00:00.00.0000000",
  "CampaignId":1234,
  "PriorityId":1234,
  "GoalType": 1,
  "Impressions":10000,
  "RateType": 2,
  "Price":5,
  "CapType": 1,
  "DailyCapAmount": 5000,
  "LifetimeCapAmount": 50000,
  "IsActive":true,
  "Keywords":"jazz \n exercise",
  "CustomTargeting":"(Age > 35 and Gender = \"female\")",
  "GeoTargeting":[{
    "CountryCode":"US",
    "Region":"NC",
    "MetroCode":560,
    "IsExclude":false
  }],
    "SiteZoneTargeting":[{
    "SiteId":123,
    "ZoneId":321,
    "IsExclude":false
  }],
  "IsActive":true,
  "IsFreqCap":true,
  "FreqCap": 2,
  "FreqCapDuration": 10,
  "FreqCapType": 1,
  "DontAffectParentFreqCap": true,
  "IsCompanion":true,
  "IsNoDuplicates":false,  
  "IsTrackingConversions": true,
  "CanPassback":true,
  "PassbackSortOrder":1,
  "IsArchived":false,
  "IsSunday": true,
  "IsMonday": false,
  "IsTuesday": false,
  "IsWednesday": false,
  "IsThursday": false,
  "IsFriday": false,
  "IsSaturday": true,
  "IsECPMOptimized":true,
  "ECPMOptimizePeriod":30,
  "ECPMMultiplier":1.25,
  "FloorECPM":0.15,
  "CeilingECPM":0.35,
  "DefaultECPM":0.28,
  "ECPMBurnInImpressions":1000,
  "BehavioralTargeting": {
    "onClick": {
      "stopShowingAdsFromFlight": true,
      "stopShowingAdsFromAdvertiser": true,
      "storeCategoriesFromFlightAsInterest": true
    },
    "onConvert": {
      "stopShowingAdsFromFlight": true,
      "stopShowingAdsFromAdvertiser": true,
      "storeCategoriesFromFlightAsInterest": true
    }
  }
}
curl -X POST \
     -H "X-Adzerk-ApiKey:$ADZERK_API_KEY" \
     https://api.adzerk.net/v1/flight \
     --data-urlencode 'flight={"Name":"Jazzercise North Carolina Weekends","StartDateISO":"2017-05-01T00:00:00.00.0000000","EndDateISO":"2017-12-31T00:00:00.00.0000000","CampaignId":1234,"PriorityId":1234,"GoalType":1,"Keywords":"jazz \n exercise"}'
{
  "Id":1234,
  "StartDateISO": "2017-05-01T00:00:00.0000000",
  "EndDateISO": "2017-12-31T00:00:00.0000000",
  "NoEndDate":false,
  "Price":5,
  "Impressions":10000,
  "IsNoDuplicates":false,
  "IsCompanion":true,
  "Keywords":"jazz \n exercise",
  "Name":"Jazzercise North Carolina Weekends",
  "IsFreqCap":true,
  "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": "(Age > 35 and Gender = \"female\")",
  "GoalType": 1,
  "RateType": 2,
  "IsECPMOptimized": true,
  "ECPMOptimizePeriod": 30,
  "ECPMMultiplier": 1.25,
  "FloorECPM": 0.15,
  "CeilingECPM": 0.35,
  "DefaultECPM": 0.28,
  "ECPMBurnInImpressions": 1000,
  "EffectiveCPMOverride": null,
  "DatePartingStartTimeISO": null,
  "DatePartingEndTimeISO": null,
  "IsSunday": true,
  "IsMonday": false,
  "IsTuesday": false,
  "IsWednesday": false,
  "IsThursday": false,
  "IsFriday": false,
  "IsSaturday": true,
  "FreqCap": 2,
  "FreqCapDuration": 10,
  "FreqCapType": 1,
  "CapType": 1,
  "DailyCapAmount": 5000,
  "LifetimeCapAmount": 50000,
  "DeliveryStatus": 0,
  "CustomFieldsJson": null,
  "BehavioralTargeting": {
    "onClick": {
      "stopShowingAdsFromFlight": true,
      "stopShowingAdsFromAdvertiser": true,
      "storeCategoriesFromFlightAsInterest": true
    },
    "onConvert": {
      "stopShowingAdsFromFlight": true,
      "stopShowingAdsFromAdvertiser": true,
      "storeCategoriesFromFlightAsInterest": true
    }
  },
  "IsTargetingOptimization": null,
  "TargetingOptimizationType": null,
  "TargetingOptimizationTargetType": null,
  "TargetingOptimizationTarget": null,
  "TargetingOptimizationBurnIn": null,
  "TargetingOptimizationCanMiss": null,
  "IsArchived": null,
  "IsTrackingConversions": true,
  "CanPassback":true,
  "PassbackSortOrder":1
}
Suggest Edits

Update Flights

 
put
 

Description

This lets you update flights.

Make sure the URL contains the right "Flight ID", which you received in the Create Flights response.

Definition

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

Arguments

Submit the properties above wrapped in a flight object.

Id, Name, StartDateISO, CampaignId, PriorityId, GoalType, Impressions, and IsActive are required fields for the Update Advertisers request. You can update any field except the id.

The example to the right updates the impressions goal amount from 10K (in the Create Flights example) to 20K.

flight={  
    "Id":1234,
    "Name":"Jazzercise North Carolina Weekends",
    "StartDateISO":"2017-05-01T00:00:00.00.0000000",
    "CampaignId":1234,
    "PriorityId":1234,
    "GoalType":1,
    "Impressions":20000
}
curl -X PUT \
     -H "X-Adzerk-ApiKey:$ADZERK_API_KEY" \
     --data-urlencode 'flight={"Id":1234,"Name":"Jazzercise North Carolina Weekends","StartDateISO":"2017-05-01T00:00:00.00.0000000", "CampaignId":1234,"PriorityId":1234,"GoalType":1,"Impressions":20000}' \
     https://api.adzerk.net/v1/flight/1234
flight={
  "Name":"Jazzercise North Carolina Weekends",
  "StartDateISO":"2017-05-01T00:00:00.00.0000000",
  "EndDateISO":"2017-12-31T00:00:00.00.0000000",
  "CampaignId":1234,
  "PriorityId":1234,
  "GoalType": 1,
  "Impressions":20000,
  "RateType": 2,
  "Price":5,
  "CapType": 1,
  "DailyCapAmount": 5000,
  "LifetimeCapAmount": 50000,
  "IsActive":true,
  "Keywords":"jazz \n exercise",
  "CustomTargeting":"(Age > 35 and Gender = \"female\")",
  "GeoTargeting":[{
    "CountryCode":"US",
    "Region":"NC",
    "MetroCode":560,
    "IsExclude":false
  }],
    "SiteZoneTargeting":[{
    "SiteId":123,
    "ZoneId":321,
    "IsExclude":false
  }],
  "IsActive":true,
  "IsFreqCap":true,
  "FreqCap": 2,
  "FreqCapDuration": 10,
  "FreqCapType": 1,
  "DontAffectParentFreqCap": true,
  "IsCompanion":true,
  "IsNoDuplicates":false,  
  "IsTrackingConversions": true,
  "CanPassback":true,
  "PassbackSortOrder":1,
  "IsArchived":false,
  "IsSunday": true,
  "IsMonday": false,
  "IsTuesday": false,
  "IsWednesday": false,
  "IsThursday": false,
  "IsFriday": false,
  "IsSaturday": true,
  "IsECPMOptimized":true,
  "ECPMOptimizePeriod":30,
  "ECPMMultiplier":1.25,
  "FloorECPM":0.15,
  "CeilingECPM":0.35,
  "DefaultECPM":0.28,
  "ECPMBurnInImpressions":1000,
  "BehavioralTargeting": {
    "onClick": {
      "stopShowingAdsFromFlight": true,
      "stopShowingAdsFromAdvertiser": true,
      "storeCategoriesFromFlightAsInterest": true
    },
    "onConvert": {
      "stopShowingAdsFromFlight": true,
      "stopShowingAdsFromAdvertiser": true,
      "storeCategoriesFromFlightAsInterest": true
    }
  }
}
Suggest Edits

List Flights

 
get
 

Description

Lists all the flights in your network.

Definition

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

Response

See right for example.

Additional Pagination

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

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,
            "Price":1.000,
            "Impressions":100,
            "IsNoDuplicates":true,
            "Keywords":"",
            "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":"2017-05-29T15:41:00.0000000",
        },...
Suggest Edits

List Flights for Campaign ID

 
get
 

Description

Lists all flights for a particular campaign using the "Campaign ID".

Definition

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

IsActive Parameter - Optional

Property
Description

?isActive
(boolean)

If true, returns only active flights

Additional Pagination

For active ones only:

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

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,
            "NoEndDate":null,
            "Price":0.000,
            "Impressions":100,
            "IsNoDuplicates":true,
            "DuplicateMode":4,
            "Keywords":"",
            "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,
            "DatePartingStartTimeISO":null,
            "DatePartingEndTimeISO":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,
            "IsTargetingOptimization":null,
            "TargetingOptimizationType":null,
            "TargetingOptimizationTargetType":null,
            "TargetingOptimizationTarget":null,
            "TargetingOptimizationBurnIn":null,
            "TargetingOptimizationCanMiss":null,
            "IsArchived":null,
            "CanPassback":true,
            "PassbackSortOrder":1,
            "StartDateISO":"2017-06-08T00:00:00.0000000",
            "EndDateISO":"2017-12-08T00:00:00.0000000"
        }...
     "IsDeleted":false,
     "SalespersonId":null,
     "CustomFieldsJson":null,
     "IsArchived":null,
     "StartDateISO":"2011-01-01T00:00:00.0000000"
}
Suggest Edits

Get Flight

 
get
 

Description

This returns the parameters for a specific flight using the "Flight ID".
Definition

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

Additional Arguments

Property
Description

?excludeAds
(boolean)

If true, the endpoint returns only the flight metadata without ad objects

CreativeMaps
(array) - response only

Displays creative flight maps (ads) for the flight

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

 
get
 

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 "Ad IDs" 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

No field is required.

Property
Description

isActive
(boolean)

Only return flights where IsActive is [true/false]. Default is true.

isArchived
(boolean)

Only return flights where IsArchived is [true/false]. Default is false.

beforeStartDate
(string)

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

afterStartDate
(string)

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

beforeEndDate
(string)

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

afterEndDate
(string)

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

noEndDate
(boolean)

Only return flights where EndDate is null

Response

See right for example. Below are returned fields.

Property
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's ID

IsDeleted
(boolean)

If the flight is set as deleted

Id
(integer)

The Flight's ID

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 Flight's price

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 Amount 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

Creatives

 

Creatives refer to details about the creative/ad itself, such as the ad size, the format, the URL, etc. More info can be found here. A "creative" in Adzerk is different from an "ad", as an "ad" refers to creatives that are specifically linked to a flight and thus have targeting and are eligible to serve.

If a creative is set to inactive, then all ads (creatives mapped to a flight) are not able to serve even if they are set to active. Make sure creatives AND ads are active before your campaign goes live.

Suggest Edits

Create Creative

 
post
 

Description

This creates a new creative under an advertiser.

In order to have the creative eligible to serve, you'll need to use the Creative Flight Maps (Ads) endpoints, which map the creative to a flight's ad.

If you need to upload the Creative to be hosted on Adzerk's site, you'll need to use the Upload Creative Image endpoint after this step.

Definition

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

Arguments

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

Required

Property
Description

Title
(string)

Short description of creative (in UI, it's called 'Friendly Name'). Required

Body
(string)

This is the body text associated with AdType 1 (in UI it's called "Text"). If you are using a different AdType, pass a blank string: "". Required

AdvertiserId
(integer)

The advertiser id. Required

AdTypeId
(integer)

The ad size's ID. More info here. Required

Unless you are using AdType1, pass in an empty string: "" for body

Optional

Property
Description

ImageName
(string)

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)

The click URL

IsActive
(boolean)

Whether creative is eligible to serve

Alt
(string)

Alt text

IsDeleted
(boolean)

Whether creative is deleted

IsHTMLJS
(boolean)

Whether to override image with HTML or JavaScript ad. If true = the ScriptBody field should have value

ScriptBody
(string)

If IsHTMLJS = true, this field needs to be filled with a HTML/JavaScript ad

Metadata
(JSON object)

Adds custom metadata to your creative. Note that this should be a JSON object in 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.

Maximum character limit of 1000 characters.

ImageLink
(string)

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)

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)

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)

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

IsSync (boolean) - deprecated

Deprecated

Response

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

creative={
  "AdvertiserId":123,
  "Title":"Adzerk Blue Creative",
  "Body":"",
  "AdTypeId":5,
  "Url":"https://adzerk.com",
  "IsDeleted":false,
  "Alt":"Adzerk - Native Ads",
  "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 --data-urlencode 'creative={"AdvertiserId":12345,"Title":"Adzerk Blue Creative","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":"Adzerk Blue Creative",
  "ImageName":"somelongstring.jpg",
  "Url":"https://adzerk.com",
  "Body":"",
  "AdvertiserId":123,
  "IsActive":true,
  "AdTypeId":5,
  "Alt":"Adzerk - Native Ads",
  "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

Upload Creative Image

 
post
 

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 creative's id 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":"Adzerk Blue Creative",
    "ImageName":"99b3fbedd2e9491195c9d0e5dc4d5a2f.gif",
    "Url":"http://www.adzerk.com",
    "Body":"\"\"",
    "AdvertiserId":12345,
    "IsActive":true,
    "AdTypeId":5,
    "Alt":"Adzerk - Native Ads",
    "IsDeleted":null,
    "IsSync":null,
    "IsHTMLJS":false,
    "Metadata":null,
    "ImageLink":"https://static.adzerk.net/Advertisers/99b3fbedd2e9491195c9d0e5dc4d5a2f.gif"
}
Suggest Edits

Update Creative

 
put
 

Description

This updates a creative with new parameters using the "Creative ID".

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

Required parameters include Id, AdvertiserId, Title, Url, Body, IsActive, and AdTypeId

When updating a creative, you MUST use the AdvertiserId of the creative when it was created. Creatives cannot change advertisers in Adzerk.

creative={
  "Id":123
  "AdvertiserId":123,
  "Body":"Test",
  "Url":"https://adzerk.com",
  "Title":"Adzerk Blue Creative",
  "AdTypeId":5,
  "Alt":"Adzerk - Native Ads",
  "IsActive":true
}
curl -X PUT -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/creative/12345 --data-urlencode 'creative={"Id":12345,"AdvertiserId":12345,"Title":"Adzerk Blue Creative","Url":"https://www.adzerk.com","Body":"\"\"","IsActive":true,"AdTypeId":5,"Alt":"Adzerk - Native Ads"}'
{
  "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

List Creatives

 
get
 

Description

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

Definition

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

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": "Adzerk Blue Creative",
            "ImageName": "somelongstring.jpg",
            "Url": "https://adzerk.com",
            "Body": "",
            "AdvertiserId": 123456,
            "IsActive": true,
            "AdTypeId": 5,
            "Alt": "Adzerk - Native Ads",
            "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

Get Creative

 
get
 

Description

This returns the properties for a specific creative.

No parameters are needed, except "Creative ID" in URL.

Definition

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

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":"Adzerk Blue Creative",
  "ImageName":"somelongstring.jpg",
  "Url":"https://adzerk.com",
  "Body":"",
  "AdvertiserId":123,
  "IsActive":true,
  "AdTypeId":5,
  "Alt":"Adzerk - Native Ads",
  "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

Ads (Creative Flight Maps)

 

Ads live under flights and contain information about the creative that will be shown, as well as any additional targeting details that live at the ad-level. An "ad" in Adzerk is different from a "creative", as an "ad" refers to creatives that are specifically linked to a flight and thus have targeting and are eligible to serve.

Learn more about ads here.

"Creative Flight Maps" refers to the tying of a creative to a flight.

Suggest Edits

Create Ads

 
post
 

To make an ad, you'll first need to upload a creative to the system using the Create Creative endpoint. Then, you'll take that CreativeID and pass it as the 'id' for the creative object in the Create Ads ping.

Description

This creates an ad. Make sure that the right "Flight ID" is in the URL.

Definition

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

Arguments

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

Required

Property
Description

CampaignId
(integer)

The Campaign's ID

Creative
(object)

The creativeID you'll get when you create a creative . Required

FlightId
(integer)

The Flight's ID. Required.

IsActive
(boolean)

Whether ad should be eligible to serve. Defaults to false. Required

Optional

Property
Description

ActiveKeywords
(array of strings)

For Keyword Targeting. Instructions here

CustomTargeting
(string)

For Custom Targeting. Instructions here

DistributionType
(integer)

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

Percentage
(integer)

The percentage that you want the ad to run for distribution

Impressions
(integer)

Number of impressions you want to run at for distribution

SiteId
(integer)

Site ID for Site Specific targeting

ZoneId
(integer)

Zone ID for Zone Specific targeting

IsDeleted
(boolean)

Whether it should be deleted

Iframe
(boolean)

Whether Creative should use iFrame

SizeOverride
(boolean)

Whether size needs to be overridden. Defaults to false

IsStartEndDateOverride (boolean)

Whether you are overriding the start and end date

StartDateISO
(string)

The end date for this ad in ISO 8601 format

EndDateISO
(string)

The end date for this ad in ISO 8601 format

IsGoalOverride (boolean)

Whether you are overriding the goal on the ad

RtbCustomFields
(JSON object in a string)

For RTB ads only. It's JSON data provided by the RTB partner. Certain parameters in the object will be required per partner. If you aren't sure what is required, your account manager will supply you with the data for this property

Beta - Optional

Property
Description

GoalType
(integer)

Indicates target goal metric for ad. Key follows:
1 = Impressions
2 = Percentage
3 = Click
7 = Any Conversions
8 = Lifetime Revenue (integer)
9 = Daily Revenue (integer)

Goal
(integer)

The Goal Amount of GoalType

IsNetworkAd
(boolean)

Indicates that ad comes from a 3rd party (i.e. uses 3rd party ad tags) - for use with Click Bucketing. If true = multiple clicks from the same IP address count as Unique Clicks

IsNoTrack
(boolean)

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 Do Not Track is enabled for your account

DontAffectParentFreqCap
(boolean)

"Opts-out" of frequency cap settings imposed on it by above

FreqCap
(integer)

The cap of the frequency cap. Instructions here

FreqCapDuration
(integer)

How long the frequency cap should apply. Instructions here

FreqCapType
(integer)

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

Deprecated

Property

StartDate
(string)

EndDate
(string

PublisherAccountId
(integer)

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 provide a unique "Creative Flight Map Ad ID" that can be used to update/delete ads.

creative={
    "CampaignId":123,
    "Creative":{
    "Id":12345
  },
    "FlightId":1234,
    "IsActive":true,
    "StartDateISO": "2017-05-01T00:00:00.0000000",
    "EndDateISO": "2017-12-05T00:00:00.0000000",
    "ActiveKeywords":["kittens", "cats"],
    "CustomTargeting":"$keywords contains \"dean\"",
    "DistributionType":1,
    "SiteID":1234,
    "ZoneId":12345,
    "IsDeleted":false,
    "Iframe":false,
    "SizeOverride":false,
    "FreqCap": 5,
    "FreqCapDuration": 1,
    "FreqCapType": 2,
    "GoalType": 1,
    "Goal": 200000
}
curl -X POST -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/flight/12345/creative --data-urlencode 'creative={"CampaignId":12345,"Creative":{"Id":12345},"FlightId":12345,"GoalType":1, "Goal":100,"IsActive":true}'
{
  "Id":12345,
  "CampaignId":123,
  "PublisherAccountId":0,
  "IsDeleted":false,
  "Percentage":0,
  "Iframe":false,
  "Creative":{
    "AdvertiserId":123,
    "Body":"",
    "SiteId":123,
    "Url":"https://adzerk.com",
    "Title":"Adzerk Blue Creative",
    "IsSync":false,
    "Id":12345,
    "IsDeleted":false,
    "AdTypeId":1,
    "Alt":"Adzerk - Native Ads",
    "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":["kittens", "cats"],
  "IsGoalOverride": true,
  "GoalType": 1,
  "Impressions": 200000,
  "IsStartEndDateOverride": true,
  "StartDateISO": "2017-05-01T12:00:00.0000000",
  "EndDateISO": "2017-12-05T12:00:00.0000000"
}
Suggest Edits

Update Ad

 
put
 

Description

This updates the ad.

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.

Make sure to use the "Creative Flight Map Ad ID", not the "Creative ID".

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.

Required parameters include Id, SizeOverride, CampaignId, IsDeleted, Iframe, Creative, DistributionType, IsActive, and FlightId

Definition

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

Arguments

The request to the right updates IsActive to false.

creative={
    "Id":12345,
    "CampaignId":123,
    "Creative":{
    "Id":12345
  },
    "FlightId":1234,
    "IsActive":false,
}
curl -X PUT -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/flight/1234/creative/123456 --data-urlencode '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":123,
    "FlightId":1234,
    "ZoneId":1234,
    "SiteId":12345,
    "Iframe":false,
    "PublisherAccountId":0,
    "Impressions":0,
    "Percentage":0,
    "DistributionType":1,
    "IsDeleted":false,
    "IsActive":false,
    "Creative":{  
        "Id":123456,
        "Title":"Adzerk Blue Creative",
        "ImageName":"",
        "Url":"https://adzerk.com",
        "Body":"",
        "AdvertiserId":1234,
        "IsActive":true,
        "AdTypeId":5,
        "Alt":"Adzerk - Native Ads",
        "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 \"dean\"",
    "FreqCap":5,
    "FreqCapDuration":1,
    "FreqCapType":2,
    "StartDate":null,
    "EndDate":null,
    "GoalType":1,
    "Goal":20000,
    "IsGoalOverride":true,
    "IsStartEndDateOverride":true,
    "ActiveKeywords":["kittens", "cats"],
    "RtbCustomFields":null
}
 
get
 

Description

This lists all the ads for a given flight. Make sure the right "Flight ID" is in the URL.

Definition

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

Response

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

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": 12345,
                "Title": "Adzerk Blue Creative",
                "ImageName": "",
                "Url": "https://adzerk.com",
                "Body": "",
                "AdvertiserId": 12345,
                "IsActive": true,
                "AdTypeId": 5,
                "Alt": "Adzerk - Native Ads",
                "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":"$keywords contains \"dean\"",
            "FreqCap": 5,
            "FreqCapDuration": 1,
            "FreqCapType": 2,
            "DontAffectParentFreqCap": true,
            "StartDate": null,
            "EndDate": null,
            "StartDateISO": "2017-01-01T00:00:00.0000000",
            "EndDateISO": "2015-12-05T00:00:00.0000000",
            "GoalType": 1,
            "IsGoalOverride": true,
            "IsStartEndDateOverride": true,
            "ActiveKeywords":["kittens", "cats"],
        }
    ]
}
get
 

Description

This pulls in details about a particular ad. No parameters are needed.

Make sure to use the "Creative Flight Map Ad ID", not the "Creative ID".

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

Get Ad Tracking Pixel and ClickURL

 
get
 

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 Decision API.

No parameters are needed. The "Flight ID" and "Creative Flight Map Ad ID" are required in the url.

Make sure to use the "Creative Flight Map Ad ID", not the "Creative ID".

Definition

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

Response

Returns an object containing the "Creative Flight Map Ad 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

Delete Ad

 
get
 

Description

This deletes the Ad. However, the Creative remains at the Advertiser level, for use in the future in a different Ad.

Make sure to use the "Creative Flight Map Ad ID", not the "Creative ID"

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

Flight Categories

 

Flight Categories requires UserDB, a data management plan under the Business and Enterprise plans.

Flight Categories is used for Interest Targeting. It enables you to target users based on interests they have. For instance, if someone clicked on an ad related to 'basketball', you can record that the user is a basketball fan and then use that info for future targeting.

Suggest Edits

Create Flight Categories

 
post
 

Description

This endpoint creates a category within a flight. Make sure the right "Flight ID" is in the URL.

Definition

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

Properties

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

Property
Description

id
(integer)

The Flight's ID

Name
(string)

The category's name

Response

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

category={
  "Id":1234,
  "Name":"Sports"
}
curl -X POST -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/flight/123456/category --data-urlencode 'category={"Id":1234,"Name":"Sports"}'
{
  "Id":12345,
  "Name":"Sports"
}
Suggest Edits

List Flight Categories

 
get
 

Description

This endpoint lists all categories for a given flight, using its "Flight ID".

Definition

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

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":"Sports"
    }
    {
      "Id":234,
      "Name":"Current Events"
    }
  ]
}
Suggest Edits

List Network Categories

 
get
 

Description

This endpoint lists all categories for your network.

Definition

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

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": "Sports"
        },...
Suggest Edits

Delete Flight Category

 
get
 

Description

This removes a category from a flight, using its "Flight Category ID".

If works, 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 
Suggest Edits

Site/Zone Targeting

 

Sites/Zone target enables the mapping of a Flight to a Zone/Site placement.

Suggest Edits

Create Site/Zone Targeting

 
post
 

Description

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

Definition

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

Arguments

Make sure the URL contains the right FlightID. You should post the properties below wrapped in a sitezone object. Only SiteID is required.

Property
Decription

SiteId
(integer) - required

The site's ID

ZoneId
(integer)

The zone's ID

IsExclude
(boolean)

Whether targeting is excluded or included

Response

The result will include the unique "Site/Zone Targeting ID" that can be used to update or remove the site/zone targeting.

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 --data-urlencode 'sitezone={"FlightId":12345,"SiteId":1234,"ZoneId":1234,"IsExclude":"false"}'
{
  "Id":12345,
  "FlightId":12345,
  "SiteId":123,
  "ZoneId":321,
  "IsExclude":false
}
Suggest Edits

Update Site/Zone Targeting

 
put
 

Description

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

Make sure the URL has the right "Flight ID" and "Site/Zone Targeting ID".

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

Definition

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

sitezone={
  "FlightId":12345,
  "SiteId":123,
  "ZoneId":321,
  "IsExclude":false
}
curl -X PUT -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/flight/12345/sitezonetargeting/123456 --data-urlencode '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

 
get
 

Description

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

No parameters are needed, except "Flight ID" and "Site/Zone Targeting ID" in URL.
Definition

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

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

Delete Site/Zone Targeting

 
get
 

Description

This removes site/zone targeting from a flight.

No parameters are needed, except "Flight ID" and "Site/Zone Targeting ID".

If works, 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 are use to create/update geo-targeting for flights. They are also used for listing out the codes for countries/regions/metros.

For set-up instructions on enabling geo-targeting, please refer to these instructions. .

Suggest Edits

Create Geo-Targeting

 
post
 

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 get their own LocationId.

You should post the properties below wrapped in a geotargeting object. You'll need the Flight's "Flight ID" to update.

Definition

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

Arguments

Property
Description

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

IsExclude
(boolean)

If true: exclude location; False/null: include location

Response

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

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

Update Geo-Targeting

 
put
 

Description

This endpoint changes geo-targeting settings for a flight.

In the URL, make sure to add the right "Flight ID" and "Location ID".

Submit the properties above wrapped in a geotargeting object.

You can update any field except for the "Flight ID".

geotargeting={
  "FlightId": 12345,
  "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 --data-urlencode '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

Delete Geo-Targeting

 
get
 

Description

This removes a geo-targeting setting from a flight.

In GET endpoint, make sure to use the right "Flight ID" and "Location ID".

Definition

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

Response

If works, 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

Get Geo-Targeting

 
get
 

Description

This endpoint returns the properties for a flight's geo-targeting settings.

No parameters are needed, except "Flight ID" and "Location ID" in the URL.

Definition

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

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

List Countries

 
get
 

Description

Get a list of all geographical areas and codes for 'countries'. 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 Regions in Country

 
get
 

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

List Metro Codes in Region

 
get
 

Description

View the MetroCodes within a specific Region. For United States only.

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

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

 
post
 

Description

Creates RTB advertiser.

Definition

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

Arguments

Include all required parameters from Create Advertisers. The below fields are also required.

Property
Description
Required
Type

PartnerId
(integer)

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

Y

integer

RtbCustomFields
(JSON object in a string)

JSON data provided by the RTB partner. Certain parameters in the object will be required per partner. If you aren't sure what is required, your account manager will supply you with the data for this property

Y

JSON object in a string

*PartnerID key =

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

RTB Custom Field
Type
Description
Required For Partners

bidPct

integer

Percentage of requests the advertiser bids on

endpoint

URL

pubId

integer

pubName

string

siteId

integer

timeout

integer

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

Update RTB Advertiser

 
put
 

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

 
post
 

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

 
post
 

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

These are all optional.

Name
Data Type
Required
Type

RtbCustomFields

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

Y

JSON object in a string

rtbFormat

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

Y

string

RTB Custom Field
Type
Description
Required For Partners

adId

integer

adTemplate

string

auctionType

string

bidPct

integer

Percentage of requests the advertiser bids on. Overrides the advertiser-level bidPct if present.

blockedDomains

string

dealId

integer

disableSubdomain

boolean

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

None

floorPrice

integer

imageHeight

integer

imageWidth

integer

matchedUsersOnly

boolean

maxBid

integer

minBid

integer

pubId

integer

pubmaticSiteId

integer

pubName

string

rtbFormat

string

textLength

integer

`rtbValue` String Value
Description

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' --data-urlencode '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 --data-urlencode 'creative={ "CampaignId":123456, "DistributionType":1, "IsActive":true, "FlightId":12345, "Creative":{"AdTypeId":5}, "RtbCustomFields":"{"something":true}" }'
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

 
get
 

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

 
post
 

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

 
put
 

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

All fields are required.

Property
Description

RangeMin
(integer)

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)

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)

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 --data-urlencode 'settings={"PercentToAdjust": 50, "RangeMax": 35, "RangeMin": 3}'
{  
    "PercentToAdjust":50,
    "RangeMax":35,
    "RangeMin":3
}
Suggest Edits

View Targeting Optimization Settings

 
get
 

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

 

Overview

The Adzerk Inventory API allows you to programmatically create, update, list, get, and delete:

Priorities
Channels
Sites
Zones
Ad Sizes / Types

Please refer to our Inventory Overview section for a deeper explanation of Inventory.

 

Channels are containers of sites. While a Channel is required to run, having more than one is optional. Please see our Channels page for more info.

Suggest Edits

Create Channels

 
post
 

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.

Required

Property
Description

Title
(string)

The channel's title. Required

AdTypes
(array of integers)

The Ad Types you want to use. Required

CPM
(float or decimal)

Required, but set to 0 in all requests

Engine (String)

Required, but set to 0 in all requests

IsDeleted (boolean) - optional

Whether it should be deleted. Optional

Make sure to set Engine and CPM (both required) to 0 in all requests

Deprecated

Property

Keywords
(string)

Custom Targeting
(string)

Commission (integer)

Response

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

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

Update Channels

 
put
 

Description

This updates a channel using the ""Channel ID".

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

Definition

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

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

List Channels

 
get
 

Descriptions

This returns a list of all channels in your network.

Definition

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

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": 0,
           "CPM": 0,
           "AdTypes": [
               4,
               5,
               6,
               9,
               13
           ],
           "IsDeleted": false,
           "CustomTargeting":""
       },...
 }
Suggest Edits

Get Channels

 
get
 

Descriptions

This returns the properties for a given "Channel ID".

No parameters are needed.

Definition

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

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":"Finance Sites",
  "Commission":0,
  "Engine":0,
  "Keywords":null,
  "CPM":0,
  "AdTypes":[0,1,2,3,4]
  "IsDeleted": false,
  "CustomTargeting": null
}
Suggest Edits

Get Priorities for a Channel

 
get
 

Description

This lists all the priorities for a given channel.

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.

Property
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

 
get
 

Description

This removes a channel from your network.

No parameters are needed besides the "Channel ID" in the URL.

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

Sites are individual domains you manage - or platforms like Android, iOS, Desktop. They are used to make it easier to target the right ads to the right locations. See our Sites page for more information.

Suggest Edits

Create Site

 
post
 

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.

Required

Property
Description

Title
(string)

The site's name. Required

Url
(string)

The new site's link. Must be in the format https://path of URL. Required

IsDeleted (boolean) - optional

Whether it should be deleted. Optional

Deprecated

Property

PublisherAccountId (integer)

Response

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

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

Update Sites

 
put
 

Description

This updates a site with a new URL and/or title, using the "Site ID".

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

Definition

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

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

List Sites

 
get
 

Descriptions

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

Definition

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

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

Get Sites

 
get
 

Description

This returns the properties of a single site based on "Site ID".

No parameters are needed except "Site ID" in URL.

Definition

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

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

Delete Site

 
put
 

Description

Deletes a site using "Site ID".

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

Required Fields

You must include:

Id
IsDeleted
Title
URL

The URL has to be the actual URL to pass validation

curl -X PUT -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/site/1234 --data-urlencode 'Site={"Id":1234,"IsDeleted":true,"Title":"foo","Url":"http://url.com"}'
Suggest Edits

Site Filtering

 
get
 

Description

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

The site object contains:

  • The Site Id
  • The Site Title
  • IsDeleted
  • The Publisher Account Id (used for grouping sites)
  • The Site Url

By default, the endpoint returns all non-deleted sites saved in an account.

To filter sites by:

  • The Title of the site
  • The Url of the site

Use one or more of the query parameters described below.

Filtering Behavior

  • titleLike - Filters the stream of sites based on the Title. This is a simple match - if the string provided in the query parameter is present anywhere in a site's Title, that site will be returned in the results.

Example: ?titleLike=adzerk

  • urlLike - Filters the stream of sites based on the Url. This is a simple match - if the string provided in the query parameter is present anywhere in a site's Url, that site will be returned in the results.

Example: ?urlLike=adzerk.com

You can also use both query parameters together: ?titleLike=adzerk&urlLike=.com

The filtering is a simple match of the string. Wildcards, regular expressions etc. are not available.

Some special characters need to be urlencoded to be used in the query parameter. For example:

# - %23
% - %25
& - %26

Definition

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

Arguments

Property
Description

titleLike (string)

Filters the stream of sites based on the Title

urlLike (string)

Filters the stream of sites based on the Url

Response

See right for example. Below are returned fields.

Property
Description

Id (int)

The Id of the site

Title (string)

The Title of the site

IsDeleted (boolean)

If true, the site is deleted

PublisherAccountId (int)

The Id of the Publisher Account (used for grouping sites)

Url (string)

The Url of the site

curl -N https://api.adzerk.net/v1/fast/site -H X-Adzerk-ApiKey:<KEY>
curl -N "https://api.adzerk.net/v1/fast/site?titleLike=adzerk&urlLike=.com" -H "X-Adzerk-ApiKey:<KEY>"
{
  "Id": 123456,
  "Title": "Adzerk",
  "IsDeleted": false,
  "PublisherAccountId": 1234,
  "Url": "http://adzerk.com"
}
Suggest Edits

Channel Site Maps

 

In order to run a campaign, you have to have Sites tied to a specific Channels. This API lets you tie a site to a channel.

By default, any site you create AUTOMATICALLY gets added to the default "All Sites" channel. Many of our clients have no need for two channels, so it's quite possible you will never need to use the Channel Site Maps API.

Suggest Edits

Create Channel Site Map

 
post
 

Description

The Channel Site Map endpoint connects a Site to a Channel. By default, any time you create a site, it's automatically added to the "All Sites" channel.

Definition

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

Arguments

You should post the properties below wrapped in a channelSite object. No field is required.

Property
Description

SiteId
(integer)

The site's ID

ChannelId
(integer)

The channel's ID

Priority
(integer)

Also known as affinity. This is different from the Priority associated with Channels. See here for info.

FixedPaymentAmount (decimal) - deprecated

Deprecated

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

Update Channel Site Map

 
put
 

Description

This updates a Site's Channel "Affinity". Refer to Create Channel Site Map for a definition of an Affinity.

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

Required fields are SiteID, ChannelID, and Priority.

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

List Channel Site Maps

 
get
 

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

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

Get Channel Site Map

 
get
 

Description

Returns the channel site map for a specific "Site ID" and "Channel ID".

No parameters are needed. As long as the URL has the "Site ID" and "Channel ID".

Definition

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

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

 
get
 

Descriptions

This returns all "Channel IDs" associated with a given Site.

No parameters are needed, as long as the URL has the "Site ID". It is an array of "Channel IDs" for a particular "Site ID".

Definition

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

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

 
get
 

Description

This removes the association of a site and channel.

No parameters are needed, except "Channel ID" and "Site ID" in URL. 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

Zones refer to specific spots on a site you want to target, such as "Above the Fold" vs "Below the Fold". Refer to our Zones overview for more info.

Suggest Edits

Create Zone

 
post
 

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.

Only name is required. If SiteID is not added, the Zone is added at the Network level.

Property
Description

Name
(string)

The zone's name. Required.

SiteId
(string)

The site's ID. Optional

IsDeleted
(boolean)

Whether zone is deleted. Optional

Response

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

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

Update Zone

 
put
 

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.

Make sure to use the "Zone ID" in the URL.

Definition

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

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

List Zones

 
get
 

Descriptions

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

Definition

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

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":"Adzerk Above the Fold",
            "IsDeleted":false
        },
        {  
            "Id":12346,
            "Name":"Adzerk Below the Fold",
            "SiteId":1234,
            "IsDeleted":false
        },...
 
get
 

Description

This returns the properties for a specific zone.

No parameters are needed, just the "Zone ID" in the URL.

Definition

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

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

Delete Zone

 
put
 

Description

Deletes a zone using "Zone ID" in the URL.

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

curl -X PUT -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/zone/1234 --data-urlencode 'zone={"IsDeleted":true}'
 

In order to create an ad, you have to denote its size, which is used to ensure the right ad gets shown for each placement (versus something that doesn't fit).

More instructions on Ad Types and Sizes is here.

You can use pre-created ad sizes, or create your own.

Suggest Edits

Create Ad Types (Network)

 
post
 

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.

Property
Description

Width

Width (pixels). Required

Height

Height (pixels). Required

Name

Optional name. Defaults to [width] x [height]

Response

In the response you'll get the unique adTypeID in id field.

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

Create Ad Types (Channel)

 
post
 

Description

This endpoint enables an Ad Type for a Channel. If necessary, it'll also create the Ad Type if it doesn't exist.

Definition

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

Arguments & Response

The parameters are the same for the Create Ad Types Network endpoint, except the 'Channel ID' needs to be in the URL.

Property
Description

Width

Width (pixels). Required

Height

Height (pixels). Required

Name

Optional name. Defaults to [width] x [height]

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

List Ad Types (Networks)

 
get
 

Descriptions

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

Definition

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

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)

 
get
 

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

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

Delete Ad Type (Network)

 
get
 

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.

Use the "Ad Type ID" you got from the Create JSON Response.

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)

 
get
 

Description

This will remove an ad type from the specified channel. Use the "Channel ID and "Ad Type ID".

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

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

Create Priority

 
post
 

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.

Required

Property
Description

Name
(string)

The priority's name

ChannelId
(integer)

The Channel's ID

Weight
(integer)

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

SelectionAlgorithm
(integer)

Choose which selector the ad engines use to select an ad from this priority. Defaults to 0 (lottery).

Optional

Property
Description

IsDeleted
(boolean)

Whether priority is deleted

IsKeywordOptimized
(boolean)

Whether its optimized for responding to large number of keyword requests

FloorPrice
(float)

Sets a floor price for second-price auction priority

IsSecondPricing (boolean) - beta

Whether flight uses second-price auction model

PassbackTimeout (int)

Sets the timeout (in ms) for flights passing back in an adChain priority

IsSecondPricing can only be set to true for an Auction-type SelectionMethod of 1 or 3

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

SelectionAlgorithm

This may only be set on creation, and this field cannot be updated. 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 "Priority ID" that can be used to update or remove the priority.

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 --data-urlencode '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

 
put
 

Description

This updates a priority using the "Priority ID".

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

SelectionAlgorithm

SelectionAlgorithm cannot be updated after the priority is created

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 --data-urlencode '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

List Priority

 
get
 

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

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

Get Priority

 
get
 

Description

This returns properties for a specific priority.

No parameters are needed as long as the "Priority ID" is in the URL.

Definition

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

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

 
get
 

Description

This removes a priority from the channel.

No parameters needed, except "Priority ID" in URL. 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

UserDB is a feature in the Business and Enterprise plans.

Overview

UserDB is a server-side data management platform that Adzerk customers can use for advanced targeting and ad optimization.

For more information on user-level targeting and how it works, visit our User-Level Targeting instructions doc.

Major use cases of UserDB include:

  • Interest / Behavioral Targeting = Build segments based on users' interests and past behavior so as to offer highly-valuable targeting options to advertisers.

Example: Adzerk records when a user clicks on ads for beauty products. You can then create a segment (comprised of those clickers) called 'Beauty Product Users' and sell that to advertisers for a premium.

Example #1: When a user completes a sign-up form, you send that info to UserDB - such as age, gender, and location. Moving forward you can let advertisers target that data, like "gender = male" or "age > 25".

  • Excluding Ads Based on Behavior = Record what ads a user has clicked on and stop showing ads from the same Flight or Advertiser.

  • Retargeting = Let advertisers retarget people who have visited their own site.

  • RTB partner user IDs = For use with real-time-bidding campaigns

Creating UserDB Records

UserDB uses a persistent UserKey to store and match data. If you send a new key value in user object of the Decision API every time, there will be no way to match a user with their UserDB key. Therefore, you will need to store the UserKey on your end, match it to your user at time of impression, and pass it in the request.

For creating the UserKey, there are a few options:

You create:

Some common options include:

Persistent Identifier
Pros/Cons

Log-In Username

Generally works across devices

Mobile Identifiers (iOS IDFA; Android GAID)

If an app, easy to find and send; however, not cross-device and can be reset

Internal proprietary identifier

Generally works across devices

The UserKey is in string format and does not need to be an integer

Adzerk creates:

1 If the user field is blank in the ad request, Adzerk will generate a random GUID and send it back in the Decision API Response

  1. You'll need to store this ID and map it to the specific user
  2. In future requests, send this UserKey in the user parameter if you can identify who's seeing the ad

A randomly generated UserKey will look like: ue1-e397eb5990c041858071b63ca5bcc00c. Effectively, it's "ue1" followed by a huge hex number.

Passing the UserKey

For user-level targeting to work, you'll need to send the same persistent UserKey ID as the key value in the user parameter in the Decision API request ever time the user sees an ad.

Adzerk will cross-reference this UserKey with UserDB and see if there's a record associated with the User. If there is a match, this information will be used by the Ad Decision Engine to pick the right ad, based on what type of user-level targeting you have set up.

An example Decision Request with a Userkey (key) included is:

{
  "placements": [
    {
      "divName": "homepage",
      "networkId": 123,
      "siteId": 456,
      "adTypes": [5],
      "eventIds": [12,13,14]
    }
  ],
  "user" : {
    "key": "ad39231daeb043f2a9610414f08394b5"
  }
}

The UserDB API can be accessed without an API key, so you shouldn't use vulnerable User ID to represent your users in UserDB.

If you are recording data and using that for segments, you may need to update your terms with advertisers to reflect this.

Remember: for user-level targeting to work, you will need to pass the persistent UserKey in the user object's key field of the Decision API request. If you send the UserKey, Adzerk's Ad Decision Engine will cross-reference with UserDB when picking the right ad. However, if you are not sending UserKeys - or not using persistent IDs - Adzerk will not be able to match anything to UserDB and user-level targeting won't work.

Suggest Edits

UserDB 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

These UserDB endpoints let you directly update UserDB records - including tying Interests and Custom Properties to a UserKey (key). You can also pull all data associated with your users.

Custom Properties Endpoint

With this you can tie Custom Properties to a specific UserKey.

Definition
POST http://engine.adzerk.net/udb/{networkId}/custom

Arguments

{
"Key":"Value"
}

For instance:

{
"Age":"30"
}

In order to tie the properties to a specific user, you need to add the UserKey (or key field in UserDB) to the start of the Request. This is format "azk=<USERKEY>" or "azk=12314". See the cURL sample to the right for an example request that would set UserKey 234412's "Age" as "30".

Adzerk will replace any existing custom properties with the JSON object.

Interests Endpoint

This pixel endpoint adds an Interest to a specific UserKey. Learn more about Interest Targeting.

You'll want to GET this endpoint AND make sure the UserKey field is correct.

http://engine.adzerk.net/udb/{networkId}/interest/i.gif?userKey={userKey}&interest=xxxxxxxxx

Such as:

http://engine.adzerk.net/udb/812/interest/i.gif?userKey=2315124&interest=Sports

The Interest has to already have been created for this to work. Please visit our Flight Categories endpoint to learn how to create them.

A UserKey can have up to 100 interests tied to them.

Retargeting Endpoint

This pixel endpoint adds a specific UserKey to a Retargeting Segment. Learn more about Retargeting.

You'll want to GET this pixel http://engine.adzerk.net/udb/{networkId}/rt/{advertiserID}/{segment}/i.gif AND make sure to have "azk=<USERKEY>" at the front (see cURL example).

Opt-Out Endpoint

If there is any reason you'd like to opt-out a user from UserDB tracking, you can do that by GETting the below pixel. This clears the user's record and prevents future data from being written. It also excludes the user from frequency capping.

You'll want to GET this pixel http://engine.adzerk.net/udb/(networkID}/optout/i.gif AND make sure to have "azk=<USERKEY>" at the front (see cURL example).

Read User From Javascript

This end-point returns all data about your users in UserDB as a JSON object.

Definition
GET http://engine.adzerk.net/udb/{networkid}/read

Response
Below are arguments in response:

Name
Data Type

key
(string)

The unique UserKey for the user

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 their Flight Categoy interests. See here for more info

custom
(object)

Contains custom JSON uploaded by you

retargetingSegments
(object)

Lists the retargeting segments the user belongs to. The keys are "b" plus the Advertiser ID in Adzerk. The values retargeting segment ID. More info here

blockedItems
(object)

Lists the IDs of objects that 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

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. Ignore this field

cookieMonster
(object)

Internal data for UserDB services. Ignore this field

siteViewtimes
(object) - deprecated

Deprecated

pendingConversions
(object) - deprecated

Deprecated

Cookie Pixel Endpoints

If you're using JavaScript ad code, you can ping the below endpoints for Interest Targeting, Retargeting, and Opt-Out. They will pull the UserKey from an Adzerk cookie.

Interest Targeting

http://engine.adzerk.net/udb/{networkId}/interest/i.gif?interest=xxxxxxxxx

Retargeting

http://engine.adzerk.net/udb/{networkId}/rt/{advertiserID}/{segment}/i.gif

Opt-Out

http://engine.adzerk.net/udb/{networkid}/optout/i.gif

curl -b "azk=234412" -X POST -H "X-Adzerk-ApiKey:<APIKEY>" http://engine.adzerk.net/udb/2601/custom -d '{"Age":"30"}' 
curl -b "azk=235342" http://engine.adzerk.net/udb/2601/rt/113959/42/i.gif
curl -b "azk=235342" http://engine.adzerk.net/udb/2601/optout/i.gif
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

ContentDB

 

ContentDB is a feature in the Business and Enterprise plans.

Overview

Content DB is a server-side database 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 Decision 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": "..."
}
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

 
post
 

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. Nothing is required.

Property
Description

StartDateISO
(string)

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

EndDateISO
(string)

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

Parameters
(list of Crit objects)

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 (string) - deprecated

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

EndDate (string) - deprecated

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 --data-urlencode '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

 
get
 

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:

Property
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

Forecast Specific Parameters

Property
Description

Days

Number of days included in the forecast.

PastImpressions

Coming soon

PastImpressions2x

Coming soon

CurrentGrowthPct

Coming soon

MediaPlanStatus

Key:
1 = Pitched
2 = Reserved
3 = Approved
4 = Trafficked
`5 = ClosedLos

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

Create Login

 
post
 

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.

Email is only required field.

Property
Description

Email
(string)

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. Required.

Name
(string)

Friendly name of user

Password
(string)

Password

Response

The result will include the unique "Log-in ID" that can be used to update or remove the login.

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 --data-urlencode '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

 
put
 

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. Use the "Log-in ID" in the URL.

Definition

PUT https://api.adzerk.net/v1/login/1234

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 --data-urlencode 'login={"Id":19290,"Email":"ddraper@adzerk.com","Name":"Don Draper","Password":"password"}'
{
  "Id":1234,
  "Email":"ddraper@adzerk.com",
  "Password":"",
  "Name":"Don Draper"
}
Suggest Edits

List Logins

 
get
 

Description

This returns a list of all users in your account.

Definition

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

Passwords are not returned in the response, but are represented by empty strings.

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

Get Login

 
get
 

Description

This returns the data for a specific user.

No parameters are needed, besides the "Log-in ID" in the URL.

Definition

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

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.