Decision API

post

https://e-YOUR-NETWORKID.adzerk.net/api/v2

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

📘
If the request does not contain a user key, one is automatically generated in the response. UserKeys are important for Frequency Capping and UserDB.

👍
Note
API Key authentication is not required when making a Decision API request. For added security, Kevel has the option to require API Key authentication. Please reach out to your CSM or [email protected] to enable.
For more on authenticating requests, see this page.

Error Handling

Message	Reason(s)
`Out of n% placements on the request, none were valid`	The siteId has been deleted The siteId is not active No siteId on the request
`Keywords must be an array or string`	Keywords are not a string or an array of strings
`invalid JSON`	JSON is not valid
`Request received with no placements defined`	The `placements` object or the request body is missing
`No sites found`	Invalid SiteId provided in the request
`Count must be an integer in the interval [1, 20]`	`placements.count` in the request is not between `1` and `20`
`Event multiplier must be an integer in the interval [1, 100000000]`	`placements.eventMultiplier` in the request is not between `1` and `100000000`

Path Params

networkId

int32

required

Your account (network) ID

Body Params

placements

array of objects

required

Every request must contain one or more placements. Each placement represents a "slot" in which an ad may be served. Click the '+' below to view the placement object fields.

placements*

user

object

Object containing the UserKey used for UserDB targeting.

keywords

array of strings

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

keywords

url

string

The current page URL

referrer

string

The referrer URL

string

The IP address. Required for Geo-Targeting

includePricingData

boolean

Defaults to false

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

includeRelevancyData

boolean

Defaults to false

See the relevancy score documentation for more information

notrack

boolean

Defaults to false

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

enableBotFiltering

boolean

Defaults to false

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

enableUserDBIP

boolean

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.

consent

object

Object that sets the data consent preferences. For example, "consent": {"gdpr": true} sets GDPR consent for tracking in the European Union. (This defaults to false.) Other consent settings are available in the GDPR settings documentation.

deviceID

string

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

parallel

boolean

Defaults to false

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

intendedLatitude

float

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

intendedLongitude

float

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

radius

float

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

time

integer

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.

searchTerm

string

See Search Term Targeting.

block

object

Prevents specific advertisers, campaigns, creatives, or flights from being served in the response.

Response

Note

Error Handling

200200