v1

latestOpenAPI 3.1.02026-07-2616636641.7 KB

Decision API

The Decision API enables you to make ad requests without using ad code. By posting to a RESTful endpoint, Kevel's ad engine will return decision data and creative contents that can be used to serve ads in your application.You'll want to 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

post/api/v2

Path parameters

networkIdinteger required

Your account (network) ID

Request body

keywordsstring[]

Keywords for Keyword Targeting. Such as "keywords": ["foo", "bar", "baz"]

urlstring

The current page URL

referrerstring

The referrer URL

ipstring

The IP address. Required for Geo-Targeting

includePricingDataboolean

If true, return pricing data for the decision in the response. Defaults to false

includeRelevancyDataboolean

See the relevancy score documentation for more information

notrackboolean

Deprecated: If true, only return ads that are set to honor Do Not Track. Defaults to false

enableBotFilteringboolean

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

enableUserDBIPboolean

If true, override the IP address of the request with the IP address supplied on the UserKey. If no IP address is found on the UserKey, this will fall back to the IP address on the request. Requires UserDB.

deviceIDstring

RTB requests only - sets an Identifier for Advertisers (IFA or IDFA)

parallelboolean

If true, processes the placements in parallel. Has no advantage except for RTB and header bidding requests. Does not work with companion ads.

intendedLatitudenumber float

(BETA) Latitude to use for Distance Targeting. Range: [-90, 90]. Contact Kevel support to get started

intendedLongitudenumber float

(BETA) Longitude to use for Distance Targeting. Range: [-180, 180]. Contact Kevel support to get started

radiusnumber float

(BETA) Radius of the user if using user-specified radius with Distance Targeting. Range: [0.01, 100]. Contact Kevel support to get started

rtbobject

RTB specific parameters. Can be used to pass in Supply Chain information and overrides, e.g. "rtb":{"schain":{"ext":{"sid":"000111"}}} will override the sid on outbound RTB requests.

timeinteger

Expects a Unix epoch timestamp (seconds or milliseconds) in the future.

time overrides the time of the decision request, instead of now. Decisions will then consider ads active in that future time based on their start/end dates as well as its use in day parting, daily capping, etc. This is useful in situations such as in-store, where ad decisions have to be made up to a few hours in advance.

Event URLs called, such as Impressions or Clicks, will be attributed to the date of the overridden time, so they will affect daily goal pacing for that date, and they will be included in the lifetime totals immediately, so if there is a lifetime cap or goal the future impressions could cause the ad to stop serving immediately.

In data shipping logs, the impression, clicks, conversions or other custom event ImpressionCreatedOn and CreatedOn (deprecated) timestamps are overridden, but the EventCreatedOn is not, as it denotes the time at which the event was received by kevel.

Macros in creatives related to dates which will not respect the override, e.g., {{datetime.dayofweek}}

Kevel-run attribution may not cleanly support the time override, if you're running user-level attributable flows get in touch with Kevel for advice.

searchTermstring

See Search Term Targeting.

Response

200

Example response

{
  "user": {
    "key": "abc"
  },
  "decisions": {
    "div0": {
      "adId": 1111,
      "creativeId": 2222,
      "flightId": 3333,
      "campaignId": 4444,
      "advertiserId": 5555,
      "priorityId": 6666,
      "clickUrl": "https://e-23.adzerk.net/r?...",
      "contents": [
        {
          "type": "html",
          "body": "<a href='...'><img src='https://static.adzerk.net/Advertisers/cat.jpg' title='ZOMG A CAT' width='350' height='350'></a>",
          "template": "image",
          "data": {
            "imageUrl": "https://static.adzerk.net/cat.jpg",
            "title": "ZOMG A CAT",
            "width": 350,
            "height": 350,
            "customData": {
              "headline": "Test Headline",
              "cta": "Download Here"
            }
          }
        }
      ],
      "impressionUrl": "https://e-23.adzerk.net/i.gif?...",
      "events": [
        {
          "id": 12,
          "url": "https://e-23.adzerk.net/e.gif?..."
        }
      ],
      "pricing": {
        "price": 5,
        "clearPrice": 2.01,
        "revenue": 0.002,
        "rateType": 2,
        "eCPM": 5
      }
    }
  },
  "candidateRetrieval": {
    "div0": {
      "candidatesFoundCount": 1
    }
  }
}