Decision API Quickstart


Below is an introduction to using the Decision API and its SDKs . The goal is to quickly create and display a server-side example ad.


For this tutorial, we'll use the Kevel UI to upload an ad. However, many of our users prefer the Management API and Management SDKs for programmatic campaign/ad creation.


Inventory Prep

Inventory refers to details about the ad placement (i.e., where the ad is appearing). Below are details of what you'll be using for this test:

NetworkYour companyIn the UI, click the info icon ("i" in a circle) in the far upper right.
ChannelUse the "All Sites" default ChannelN/A (don't need)
SitesUse the "Web" default SiteIn the UI, go to Inventory --> Sites --> the ID is to the right of the site called 'Web'
Ad TypeWe will use "Square Button" defaultid=16
CreativeCreate a 125x125 imageN/A

Ad Placement Prep


As this is an API quickstart, we will not be dealing with JavaScript tags. You'll need to connect to our APIs via JSON requests or Decision SDK calls .

  1. Determine where you'll display the ad. While the creative image itself is 125x125, with metadata you can include a headline, ad copy, call-to-action, etc, all of which you can use to populate the ad.

  2. Determine how you'll connect Kevel's Decision API Response with your CMS, app, or whatever system you use to insert content into your app/website. The API Response will be in JSON format. More info here

Create an Advertiser

  1. Click on Advertisers in top left --> All Advertisers
  2. Click New Advertiser
  3. Name it 'Test Account'
  4. Save

Create The Ad

This process involves completing a few steps in our Campaign hierarchy, including creating a Campaign, Flight, and Ad.

Step 1: Create Campaign

  1. Campaigns tab --> Campaigns
  2. Click New Campaign button
  1. Select the 'Test Account' as the advertiser
  2. Put in 'Test Campaign' as Campaign Name
  3. You can leave Salesperson blank
  4. Save

Step 2: Create Flight

  1. Click on the Campaign's name in the Campaigns tab
  2. Click the Add a Flight to this Campaign button in top left
  1. Add in Flight Details. For now, we'll stick to only the required fields. Refer here for an overview of all Flight options.
FieldWhat you should put
NameTest Flight
Priority House (All Sites). This is a default priority; refer here for more info on Priorities
Start Date Use current time
Rate CPC
Price 1.00
Goal Type Percentage
Goal Amount 100
  1. Go to the Creatives section and click New Creative. See here for more details on the Creative/Ad options.
  1. Fill in the required fields with the below info
FieldWhat you should put
Format Image/Flash
Upload Upload the 125x125 image
Friendly Name Test Ad
Ad Size 125x125 - Square Button
Click URL (or whatever you'd like)
MetadataOptional. Use if you have additional text/info you'd like to parse and place into the ad. Basically, anything you put here will be returned in the API Response, which you can then insert dynamically into your native ad. Format as JSON object, like:

"headline": "Test Headline",
"cta": "Download Here"
  1. Click Save

  2. Once the Creative has been added to the Flight page, scroll down and click Save


You've successfully created an Ad in the Kevel UI! The next step is to ping the Decision API with information about the ad slot, parse the Response, and insert the information into your CMS.

Requesting an Ad for a Placement

You can use any of our Decision SDKs to make ad requests from your favorite programming language, or you make a POST request directly to the Decision API at https://e-<networkId> and using the JSON payload below.

Note that networkId will be your own Network ID. You can log into Kevel UI & use the "circle-i" help menu in upper right corner to find your Network ID. All API and SDK actions require it.

  "placements": [
      "divName": "div1",
      "networkId": "**Your Network ID**",
      "siteId": "**Your Site ID**",
      "adTypes": [16]
# NOTE: Use your own network and site IDs!
export NETWORK_ID=23
export SITE_ID=667480
export AD_TYPE_ID=16

curl -H "Content-Type:application/json" \
  -X POST \
  -d "{
      ]}" \
import { Client } from '@adzerk/decision-sdk';

// NOTE: Use your own network and site IDs!
let client = new Client({networkId: 23, siteId: 667480});

let request = {
  placements: [{adTypes: [16]}],

client.decisions.get(request).then(response => {
  console.dir(response, {depth: null})
import java.util.*;
import com.adzerk.sdk.*;
import com.adzerk.sdk.generated.ApiException;
import com.adzerk.sdk.generated.model.*;
import com.adzerk.sdk.model.DecisionResponse;

public class FetchAds {
  public static void main(String[] args) throws ApiException {
    // NOTE: Use your own network and site IDs!
    Client client = new Client(new ClientOptions(23).siteId(667480));
    Placement placement = new Placement().adTypes(Arrays.asList(16));

    DecisionRequest request = new DecisionRequest()
    DecisionResponse response = client.decisions().get(request);
import adzerk_decision_sdk

# NOTE: Use your own network and site IDs!
client = adzerk_decision_sdk.Client(23, site_id=667480)

request = {
  "placements": [{"adTypes": [16]}]

response = client.decisions.get(request)
require "adzerk_decision_sdk"

# NOTE: Use your own network and site IDs!
client = 23, site_id: 667480)

request = {
  placements: [{ adTypes: [16] }],

pp client.decisions.get(request)
(ns ad-request-sample
  (:import (com.adzerk.sdk Client ClientOptions)
           (com.adzerk.sdk.generated.model DecisionRequest Placement)))

(defn -main []
  ;; NOTE: Use your own network and site IDs!
  (let [client (Client. (doto (ClientOptions. (int 23)) (.siteId (int 667480))))
        request (doto (DecisionRequest.)
                      (.placements [(doto (Placement.) (.adTypes [16]))]))]
    (print (-> client (.decisions) (.get request)))))
import AdzerkSDK

// NOTE: Use your own network and site IDs!
DecisionSDK.defaultNetworkId = 23
DecisionSDK.defaultSiteId = 667480

let client = DecisionSDK()
let p = Placements.custom(divName: "div0", adTypes: [16])

client.request(placements: [p]) {response in

Parsing the Response

  1. Refer here for the Decision API Response details. It'll look something like:
  "decisions": {
    "div1": {
      "adId": 111,
      "creativeId": 222,
      "flightId": 333,
      "campaignId": 444,
      "clickUrl": "",
      "contents": [
          "type": "html",
          "template": "image",
          "data": {
            "imageUrl": "",
            "title": "Test Ad",
            "width": 125,
            "height": 125,
            "customData": {
                 "headline": "Test Headline",
                 "cta": "Download Here"
          "body": "<a href='...'><img src='' title='Test Ad' width="125" height="125"></a>"
      "impressionUrl": ""
  "user": {
    "key": "ad39231daeb043f2a9610414f08394b5"


This may look like a lot! But for the test, the only fields that will matter are clickURL, imageURL, impressionURL, and any custom JS in the customdata section (the metadata section).

  1. Insert the relevant, parsed information into your CMS or app. Make sure that
    a. The impression URL is fired at time of impression
    b. The click event hits the Click URL
    c. The image pulls from the Image URL

  2. Display and then click on the ad for tracking purposes


  1. Go to Reports in the UI
  2. Run a report and see your impression and click!