API DocsKnowledge BaseSystem StatusContact SupportContact Sales
Knowledge Base

Management API Tutorial

Suggest Edits

Overview

The Management APIs, comprised of the Inventory and Campaign Management APIs, are your tools for programmatically:

  1. Creating advertisers, campaigns, flights, or ads without needing the UI.
  2. Pausing, starting, deleting, or 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, an app server that pushes changes from your database to Kevel's system, or a stand-alone script to automate your workflow.

TL;DR: For Those in a Hurry

Skip to the end of this tutorial to read a couple of JavaScript node.js scripts that utilize our JavaScript Management SDK to set up a sample ad and our JavaScript Decision SDK to read it back. You can cut-and-paste these into your own code editor and start testing!

Getting an Ad Into Kevel 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 objects that the ad lives under.

The Campaign Structure is Advertisers --> Campaigns --> Flights --> Ads.

  1. Use the Create Advertiser endpoint with the following fields:
{
  "Title":"Management Tester",
  "IsDeleted":false,
  "IsActive":true
}

curl -X POST -H "X-Adzerk-ApiKey:$ADZERK_API_KEY" -H "Content-Type:application/json" "https://api.kevel.co/v1/advertiser" --data-binary '{"Title":"Management Tester","IsDeleted":false,"IsActive":true}'
  1. Save the id from the Response. Let's assume the Advertiser ID is 12345 for the rest of the examples. You can also find the ID using the List Advertisers endpoint.

Create a Campaign

  1. Use the Create Campaign endpoint as follows. Note it's often smart to create the campaign inactive so it doesn't start serving before you're ready.
{
  "AdvertiserId": 12345,  //the Advertiser ID from step 1
  "Name": "Management Test Campaign",
  "IsActive": false
}

## Use the Advertiser ID from step 1
curl -X POST -H "X-Adzerk-ApiKey:$ADZERK_API_KEY" -H "Content-Type:application/json" "https://api.kevel.co/v1/campaign" --data-binary '{"Name":"Management Test Campaign","StartDateISO":"2020-04-18","AdvertiserId":12345,"IsActive":false}'
  1. Save the id in the Response. Let's assume the Campaign ID is 34567 for the rest of the examples.
    You can also find the ID using the List Campaigns endpoint.

Get the Priority ID

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

  1. Use the List Priorities endpoint.
curl -X GET -H "X-Adzerk-ApiKey:$ADZERK_API_KEY" https://api.kevel.co/v1/priority
  1. In the items object, identify the section that has "Name": "House"; pull the Id associated with it. Let's assume the Priority ID is 7654 for the rest of the examples.

Create a Flight

  1. Use the Create Flight endpoint with the following fields:
{
  "Name": "Management Flight Test",
  "StartDateISO": "2017-04-01",
  "CampaignId": 34567, //the Campaign ID from step 4
  "PriorityId": 7654,  //the Priority ID from step 6
  "GoalType": 2,  //Percentage Goal
  "Impressions": 100, // 100% goal
  "IsActive": true
}

## Use the Campaign ID from step 4
## Use the Priority ID from step 6
curl -X POST \
     -H "X-Adzerk-ApiKey:$ADZERK_API_KEY" \
     "https://api.kevel.co/v1/flight" \
     --data-urlencode '{"Name":"Management Flight Test","StartDateISO":"2017-04-01","CampaignId":34567,"PriorityId":7654,"GoalType":2,"Impressions":100, "IsActive":true}'
  1. Save the id in the Response. Let's assume the Flight ID is 67890 for the rest of the examples. You can also find the ID using the List Flights endpoint.

Create a Creative

In Kevel 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 has been attached to a Flight, has targeting enabled, and is ready to launch.

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

Note: In this example, 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 the Decision API Quickstart for more examples. Must be JSON object in a string.

{
  "AdvertiserId": 12345,  //the Advertiser ID from step 1
  "Title": "Test Creative",
  "AdTypeId":16,
  "Url":"https://www.example.com",
  "IsActive":true,
  "Body": "",
  "Metadata": "{\"headline\":\"Brought To You by Nike\"}"
}

## Use the Advertiser ID from step 1
curl -X POST \
     -H "X-Adzerk-ApiKey:$ADZERK_API_KEY" \
     "https://api.kevel.co/v1/creative" \
     --data-urlencode '{"AdvertiserId":12345,"Title":"Test Creative","Url":"https://www.example.com","Body":"","IsActive":true,"AdTypeId":16,"metadata":"{\"headline\":\"Brought To You by Nike\"}"}'

  1. Save the id in the Response. Let's assume the Creative ID is 89012 for the rest of the examples. You can also find the ID using the List Creatives For Advertiser endpoint.

  2. Now, you need to upload the image itself to the creative. To do this, use the Upload Creative Image endpoint with the following information.

Replace [email protected] with your image. (Be sure to include sizeOverride=true if your test image is not 125x125 pixels.)

## Use the Creative ID from step 10
curl -X POST -H "X-Adzerk-ApiKey:$ADZERK_API_KEY" "https://api.kevel.co/v1/creative/89012/upload?sizeOverride=true" \
 -F "[email protected]"

Create an Ad

  1. Almost there! Now you need to map the creative to the Flight to create an Ad. To do this, use the Create Ads endpoint with the following fields:
{
  "Creative": {"Id": 89012}, // Creative ID from step 10
  "FlightId": 67890, // Flight ID from step 8
  "IsActive": true
}

## Use the Flight ID from step 8
## Use the Creative ID from step 10
curl -X POST -H "X-Adzerk-ApiKey:$ADZERK_API_KEY" "https://api.kevel.co/v1/flight/67890/creative" --data-urlencode '{"Creative":{"Id":89012},"FlightId":67890,"IsActive":true}'

Activate the Campaign

  1. Now you have a working campaign hierarchy, but the campaign was not active when we created it. This was pretty smart, as we might be creating lots of flights and ads underneath the campaign, and the campaign could start serving immediately. Keeping the campaign inactive prevents it from serving until we're ready.

Use the Update Campaigns endpoint with the following fields:

{
  "Id":56789, //the Campaign ID from step 4
  "AdvertiserId": 12345,  //the Advertiser ID from step 1
  "Name": "Management Test Campaign",
  "IsActive": true
}

## Use the Advertiser ID from step 1
## Use the Campaign ID from step 4
curl -X PUT -H "X-Adzerk-ApiKey:$ADZERK_API_KEY" -H "Content-Type:application/json" "https://api.kevel.co/v1/campaign/34567" --data-binary '{"Id":34567,"Name":"Management Test Campaign","StartDateISO":"2020-04-18","AdvertiserId":12345,"IsActive":true}'

👍

Congrats - you successfully uploaded and activated an ad!

Seeing the Ad in a Decision API Request

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

  1. Get Network ID: in the UI, click the info icon ("i" in a circle) in the far upper right.

  2. Get Site ID: In the UI, go to Inventory --> Sites --> find the ID next to 'Web'. Or, with the API, use the List Sites endpoint. Find the items object that has the title of "Web" and note the id associated with it.

  3. Use the Decision API with the following fields:

{
  "placements": [
    {
      "divName": "Test Placement",
      "networkId": 1234, //Your Network ID from step 14
      "siteId": 113355, //Your Site ID from step 15
      "adTypes": [16]
    }
  ]
}

## Use your Network ID from step 14
## Use your Site ID from step 15
curl -H 'Content-Type:application/json' -X POST -d '{"placements":[{"divName":"Test Placement","networkId":1234,"siteId":113355,"adTypes":[16]}]}' https://e-<networkId>.adzerk.net/api/v2

👍

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

Complete JavaScript Examples

Using our SDKs make integrating with our APIs a lot easier. For example, we include good logging and validation messages, handling of rate-limiting, convenient enumerated types for common values, and allow you to update without fetching the object first. These examples are written using our JavaScript Management SDK and JavaScript Decision SDK.

#!/usr/bin/env node

const Adzerk = require('@adzerk/management-sdk');

let logger = (lvl, msg, meta) => {
  // Ignore DEBUG and INFO level log messages.
  if (['debug', 'info'].includes(lvl)) { return; }

  // Print out all other log messages.
  console.log(`${lvl.toUpperCase()}: ${msg}. ${JSON.stringify(meta)}`);
}

// Requires an $ADZERK_API_KEY environment variable
const apiKey = process.env.ADZERK_API_KEY;
if(apiKey == undefined) {
  console.log("You must specify an $ADZERK_API_KEY value!");
  process.exit(1);
}

// Set up the constants for your network account
const ChannelName  = "All Sites";
const AdTypeId     = 16;  // "Square Button"
const PriorityName = "House";

// Note the step numbers here correspond to the documentation in:
// https://dev.kevel.co/docs/management-api-tutorial
async function setup() {
  let specifications = await Adzerk.fetchSpecifications();
  let client = await Adzerk.buildClient({apiKey, specifications, logger});

  // Step 1: Create an Advertiser
  let advertiser = await client.run("advertiser", "create", {
    title: "Management Tester",
    isActive: true,
  });

  // Step 2: Make note of the newly-created advertiser's ID
  console.log("Advertiser ID", advertiser.id);

  // Step 3: Create a Campaign
  let campaign = await client.run("campaign", "create", {
    name: "Management Test Campaign",
    advertiserId: advertiser.id,
    isActive: false, // TIP: create inactive so nothing serves until ready!
  });

  // Step 4: Make note of the newly-created campaign's ID
  console.log("Campaign ID", campaign.id);

  // Step 5: Get the list of Priorities
  let priorities = await client.run("priority", "list");

  // Extra Sub-Step: Find the ID of our Channel
  let channels = await client.run("channel", "list");
  let channel = channels.items.find(ch => (ch.title == ChannelName));
  console.log("Channel ID", channel.id);

  // Step 6: Find the ID of the "House" priority in our channel
  let priority = priorities.items.find(p => (p.channelId == channel.id && p.name == PriorityName));
  console.log("Priority ID", priority.id);

  // Step 7: Create a Flight
  let flight = await client.run("flight", "create", {
    name: "Management Flight Test",
    isActive: true,
    startDateIso: "2020-01-01",
    priorityId: priority.id,
    campaignId: campaign.id,
    goalType: Adzerk.GoalType.Percentage,
    impressions: 100, // 100% goal
    rateType: Adzerk.RateType.Cpm,
    price: 0.25, // $0.25 for thousand impressions
  });

  // Step 8: Make note of the newly-created flight's ID
  console.log("Flight ID", flight.id);

  // Step 9: Create a Creative
  let creative = await client.run("creative", "create", {
    title: "Test Creative",
    isActive: true,
    advertiserId: advertiser.id,
    adTypeId: AdTypeId,
    url: "https://www.example.com",
    metadata: "{\"headline\":\"Brought To You by Nike\"}",
  });

  // Step 10: Make note of the newly-created creative's ID
  console.log("Creative ID", creative.id);

  // Step 11: Upload an image to the creative
  let image = await client.run('creative', "uploadImage", {
    id: creative.id,
    image: "./hellowworld.gif",  // Replace with a path to your image!
    sizeOverride: true,   // Makes testing easier, but should avoid in general
  });

  // Step 12: Create an Ad (i.e. map the creative to the flight)
  let ad = await client.run('ad', 'create', {
    creative: { id: creative.id },
    flightId: flight.id,
    isActive: true,
  });

  console.log("Ad ID", ad.id);

  // Step 13: Activate the Campaign
  // makes the ad eligible for ad serving depending on start date
  await client.run("campaign", "update", {id: campaign.id, isActive: true});

  // NEXT STEPS: Read the Fetch-Ads.js script at:
  // https://dev.kevel.co/docs/management-api-tutorial
}

setup();

#!/usr/bin/env node

const Adzerk = require('@adzerk/decision-sdk');

const NetworkId = 1234; // Your network ID!
const SiteId = 113355;  // Your site ID! 
const AdTypeId = 16;    // "Square Button"

let client = new Adzerk.Client({networkId: NetworkId, siteId: SiteId});

let request = {
  placements: [
    { adTypes: [AdTypeId] }
  ]
};

client.decisions.get(request).then(response => {
  console.dir(response, {depth: null});
});

Note you can also use our Ruby Management SDK or code directly to our Management API in your language of choice to set up your ad campaigns.

We also have several other Decision SDKs that you could use to fetch decisions, or you could code directly to our Decision API in the language of your choice.

Updated 7 months ago