Response Parameters

A Response will contain zero or more Decision Objects, 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.

Decision Object

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

Contents Object

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 Kevel Management UI) 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.

{
  "type": "html",
  "template": "image",
  "data": {
    "fileName": "cat-eating-spaghetti.jpg",
    "title": "Example title"
  },
  "body": "<a href='...'><img src='https://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"
}

Data Object

Content Types

Predefined Content Templates

Event Multipliers

You can optionally set an event multiplier on impressions, clicks, conversions, and custom events via the eventMultiplier parameter. This will set the count of that event in reporting to the value of the multiplier. For instance, if you set a multiplier of 10 on an impression URL:

curl -g "https://e-1234.adzerk.net/i.gif?e=eyJ2Ijoi...xneGk&eventMultiplier=10"

That impression will be counted ten times in reporting, and any revenue associated with the impression will also be registered ten times.

An event multiplier must be in the range [-100000000, -1] or [1, 100000000].

Event multipliers on events will override any event multiplier set on the placement.

Event multipliers do not multiply the revenue set via the override parameter.

Triggering Click Events Without Redirects

By default, calling the clickUrl will perform a 302 redirect to the click URL specified in the creative and trigger a click event in reporting. To trigger a click event without the redirect, you can add the query string noredirect to the ClickUrl:

curl -g "https://e-1234.adzerk.net/r?e=eyJ2Ijo...ewxlb6Do_o&noredirect"

The response will contain a 200 status code with an empty response body. This enables the clickUrl to be used in the same way as custom event URLs.

Pricing Data

Provenance

Provenance identifies the demand source that each returned ad came from. This is useful when you want to distinguish ads booked directly in your own network from ads sourced from outside it — for example, to apply different rendering, labeling, or downstream logic to programmatic ads.

Provenance is opt-in. To request it, set includeProvenanceData to true in the Decision API request body:

curl -H 'Content-Type:application/json' -X POST -d '{"includeProvenanceData":true,"placements":[{"divName":"div0","networkId":1234,"siteId":123456,"adTypes":[5]}]}' https://e-1234.adzerk.net/api/v2

Each returned ad then carries a provenance string with exactly one of the following values:

If includeProvenanceData is omitted or set to false, no provenance key appears anywhere in the response, so existing integrations are unaffected.

📘

Whether the programmatic and cross_network values ever appear in your responses depends on which demand sources are enabled for your network. To find out which demand sources are active on your network — or to discuss adding programmatic or cross-network demand — please contact your account manager.

Which ads carry a provenance value

Provenance is derived independently for every ad in the response, so a single response can mix values. It is returned on:

• the winning ad of a single-winner placement
• every ad in a multi-winner placement's array
• every entry nested under adChain
• companion ads, on their own placements

Selections that render no ad object — such as an incrementality holdout — carry no provenance value.

{
  "user": {
    "key": "abc"
  },
  "decisions": {
    "div0": {
      "adId": 1111,
      "creativeId": 2222,
      "flightId": 3333,
      "campaignId": 4444,
      "impressionUrl": "https://e-23.adzerk.net/i.gif?...",
      "clickUrl": "https://e-23.adzerk.net/r?...",
      "contents": [],
      "events": [],
      "provenance": "in_network"
    },
    "div1": [
      {
        "adId": 5555,
        "creativeId": 6666,
        "impressionUrl": "https://e-23.adzerk.net/i.gif?...",
        "clickUrl": "https://e-23.adzerk.net/r?...",
        "contents": [],
        "events": [],
        "provenance": "programmatic"
      },
      {
        "adId": 7777,
        "creativeId": 8888,
        "impressionUrl": "https://e-23.adzerk.net/i.gif?...",
        "clickUrl": "https://e-23.adzerk.net/r?...",
        "contents": [],
        "events": [],
        "provenance": "cross_network"
      }
    ]
  }
}

Availability

Provenance is returned on API v2 JSON decision responses only (POST /api/v2 and its aliases). The VAST, AMP, and ados.js serializers do not support includeProvenanceData, and setting the flag on those requests has no effect.

Provenance is not included in event-tracking URLs, and it is not available as a reporting dimension or in data shipping. If you need to analyze your demand mix across the network, please contact your Kevel account team.