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!

Management API Tutorial

Overview

The Management APIs - comprised of the Inventory and Campaign Management APIs - are your tools for automatically:

  1. Creating advertisers/campaigns/flights/ads without needing the UI
  2. Pausing/starting/deleting/updating ads
  3. Creating priorities, channels, sites, and more
  4. Pulling a list of what advertisers/ads/etc currently exist

This makes it easy to build a self-serve ad platform, or build an internal server that pushes changes to Adzerk's system.

Getting an Ad Into Adzerk with the Management APIs

First Things First

For this first tutorial, we'll use the default Inventory settings:

Network: Your Account
Channel: "All Sites"
Site: "Web"
Ad Type: "Square Button" (ID = 16)
Priority: "House"

Create an Advertiser

In order to create an ad, you must first create the "folders" that the ad lives under.

The Campaign Hierarchy is Advertiser --> Campaigns --> Flights --> Ads.

  1. Ping the Create an Advertiser endpoint with the following fields:
advertiser={
  "Title":"Management Tester",
  "IsDeleted":false,
  "IsActive":true
}
curl -X POST -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/advertiser --data-urlencode 'advertiser={"Title":"Management Tester","IsDeleted":false,"IsActive":true}'
  1. Save the id in the Response. You can also GET the ID using the List Advertisers endpoint.

Create a Campaign

  1. Ping the Create a Campaign endpoint with the following fields:
campaign={
  "AdvertiserId":"**ID from Step 2**",
  "Name":"Management Test Campaign",
  "StartDate":"4/18/2017",
  "flights":[],
  "IsActive": true
}
curl -X POST -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/campaign --data-urlencode 'campaign={"Name":"Management Test Campaign","StartDate":"4/18/2017","AdvertiserId":XXXX,"IsActive":true,"flights":[]}'
  1. Save the id in the Response. You can also GET the ID using the List Campaigns endpoint.

Get the PriorityID

This is needed in order to create a Flight, which lives under a Campaign.

  1. Ping the List Priorities endpoint
curl -X GET -H "X-Adzerk-ApiKey:$ADZERK_API_KEY" https://api.adzerk.net/v1/priority
  1. In the items object, identify the section that has "Name": "House"; pull the Id associated with it.

Create a Flight

  1. Ping the Create a Flight endpoint with the following fields:
flight={
  "Name":"Management Flight Test",
  "StartDateISO":"2017-04-01T00:00:00.00.0000000",
  "CampaignId":"**ID from Step 4**",
  "PriorityId":"**ID from Step 6**",
  "GoalType": 1,
  "IsActive": true
}
curl -X POST \
     -H "X-Adzerk-ApiKey:$ADZERK_API_KEY" \
     https://api.adzerk.net/v1/flight \
     --data-urlencode 'flight={"Name":"Management Flight Test","StartDateISO":"2017-04-01T00:00:00.00.0000000","CampaignId":XXXX,"PriorityId":XXXX,"GoalType":1, "IsActive":true}'
  1. Save the id in the Response. You can also GET the ID using the List Flights endpoint.

Create a Creative

In Adzerk terminology, a "creative" refers to information about the ad's look/feel, such as its name, ad size, image URL, metadata, etc. This is compared to our "ad" terminology, which refers to a "creative" that's then attached to a Flight, has targeted enabled, and is ready to launch.

  1. Ping the Create Creative endpoint with the following fields:

Note: You'll want to leave body blank, and Metadata is optional. Use this if you'd like to add metadata that's returned in the Response to be used for parsing and insertion into the ad unit. See Quickstart for example. Must be JSON object in a string.

creative={
  "AdvertiserId":"**ID from Step 2**",
  "Title":"Test Creative",
  "Body":"",
  "AdTypeId":16,
  "Url":"https://www.adzerk.com",
  "IsActive":true,
  "Metadata": "{\"headline\":\"Brought To You by Nike\"}"
}
curl -X POST -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/creative --data-urlencode 'creative={"AdvertiserId":XXXX,"Title":"Test Creative","Url":"https://www.adzerk.com","Body":"","IsActive":true,"AdTypeId":16,"Metadata":"{\"headline\":\"Brought To You by Nike\"}"}'
  1. Save the id in the Response. You can also GET the ID using the List Creatives endpoint.

  2. Now, you need to upload the image itself to the creative. To do this, ping the Upload Creative Image endpoint with the following information. Make sure to add sizeOverride=true.

Replace image=@helloworld.gif with your image.

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

Create a Ad

  1. Almost there! Now you need to map the creative to the Flight. To do this, ping the Create Ads endpoint with the following fields:
creative={
    "CampaignId":"**ID From Step 4**",
    "Creative":{
    "Id":"**ID From Step 10**"
  },
    "FlightId":"**ID From Step 8**",
    "IsActive":true
}
curl -X POST -H 'X-Adzerk-ApiKey:<APIKEY>' https://api.adzerk.net/v1/flight/STEP_8_ID/creative --data-urlencode 'creative={"CampaignId":XXXX,"Creative":{"Id":XXXX},"FlightId":XXXX,"IsActive":true}'

Congrats - you successfully uploaded and enabled an ad!

Seeing the Ad in the Decision API Request

You'll first need to pull your Network and Site IDs.

  1. Get Network ID: E-mail support

14a. Get Site ID: with UI, go to Inventory --> Sites --> find the ID next to 'Web'

OR

14b. Get Site ID: With the API, ping the List Sites endpoint. Find the items object that has the title of "Web" and pull the id associated with it.

  1. Using the Decision API, ping Adzerk with the following fields:
{
  "placements": [
    {
      "divName": "Test Placement",
      "networkId": **ID From Step 13**,
      "siteId": **ID From Step 14**,
      "adTypes": [16],
      "campaignId": **ID From Step 4**
}
curl -H 'Content-Type:application/json' -X POST -d '{"placements":[{"divName":"Test Placement","networkId":XXX,"siteId":XXX,"campaignId":XXX,"adTypes":[16]}]}' http://e-<networkId>.adzerk.net/api/v2

Congrats - the ad you just created should appear in the Decision API Response!

Management API Tutorial


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.