--- title: "Decision API" method: POST path: "/api/v2" --- # Decision API `POST /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 ## Path parameters - `networkId` integer, required ## Request body - object - `placements` object[], 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.** - `divName` string, required — A unique name for the placement defined by you - `networkId` integer, required — The numeric network id - `siteId` integer, required — The numeric site id - `adTypes` integer[], required — One or more integer ad types. More info [here](https://dev.kevel.com/docs/ad-sizes) - `zoneIds` integer[] — Zone IDs to use - `advertiserId` integer — A numeric Advertiser id; if specified, only consider ads belonging to that Advertiser - `campaignId` integer — A numeric campaign id; if specified, only consider ads in that campaign - `flightId` integer — A numeric flight id; if specified, only consider ads in that flight - `adId` integer — A numeric Ad ID; if specified, only serve that ad if possible - `clickUrl` string — Override click-through URL (defaults to what is set on the Ad) - `properties` object — A map of key/value pairs used for [Custom Targeting](https://dev.kevel.com/docs/custom-targeting) - `age` integer - `segment_membership` string - `eventIds` integer[] — An array of numeric event types. Requests tracking URLs for custom events. More details: [Event Tracking IDs](https://dev.kevel.com/docs/custom-event-tracking) - `contentKeys` object — A map of key/value pairs used with [ContentDB](https://dev.kevel.com/docs/contentdb-1). The format is `"contentKeys": {"schema": "contentKey"}.` - `audience` string — *example key/value pair* - `businesses` string — *example key/value pair* - `count` integer — The number of ads to return per placement. Integer between 1 and 20. See [Multi-Winner Placements](https://dev.kevel.com/reference/multi-winner-placements). - `proportionality` boolean — If true, fills ads in a multi-winner placement in proportion to the flight's goals - `ecpmPartitions` string[] — The name of the eCPM Partition that should be used to source eCPM data for auctions - `skipSelection` boolean — If `true`, bypasses weighted lottery/auction selection and returns eligible candidate ads sorted by rank/eCPM. **Behavior:** Without `count`: Returns all eligible ads from the highest priority level only. With `count`: Returns up to `count` ads, evaluating lower priorities if needed to fill the `count`. **Notes:** Targeting filters, no-duplicate rules, and floor pricing still apply. Use `skipFilters: true` with `adId` to bypass all filters. - `skipFilters` object — Specifies which filters to bypass during the selection process. For example, given `"skipFilters":{"keyword":true}`, keyword targeting is ignored. Options: `geodistance`, `geolocation`, `keyword`, `placementLimit`, `facet`, `siteZone`, `searchTerm`. See [skipFilters](https://dev.kevel.com/docs/skipfilters) for more details. - `keyword` boolean - `eventMultiplier` integer — Multiples the count of all events returned in the selection. For example, an impression with an eventMultiplier of 10 will count as 10 impressions in reporting. - `floorPrice` number, float — Sets a floor price to use if the selection results in an auction. Overrides any floor price set on the priority. Should be expressed as an eCPM value. - `floorCpc` number, float — Sets a [floor CPC](https://dev.kevel.com/docs/second-price-auctions#cpc-floor-prices) to use if the selection results in an auction. Overrides any floor CPC set on the priority. - `logEvents` string, json — Similar to eventIds, but instead of returning event pixels in the response, pushes event pixles into [data shipping logs](https://dev.kevel.com/docs/data-shipping) - `relevancy` object — See the [relevancy score](https://dev.kevel.com/docs/relevancy-score) documentation for data type examples - `idAttribute` unknown[] — See the [using relevancy score](https://dev.kevel.com/docs/relevancy-score#using-relevancy-scores) documentation for data type examples - unknown - `adQuery` object — See [AdQuery](https://dev.kevel.com/docs/adquery#setting-up-adquery-decision-api-requests) for details and example usage. - `key` string - `eCtrOverride` object — See [Per-ID eCTR + eCPM Overrides](https://dev.kevel.com/docs/per-id-ectr-ecpm-overrides) - `key` string - `eCpmOverride` object — See [Per-ID eCTR + eCPM Overrides](https://dev.kevel.com/docs/per-id-ectr-ecpm-overrides) - `bidModifiers` object[] — Kevel accepts Per-ID Bid Modifiers in Ad Decision Requests (ADRs). These values are provided in the same format as set during campaign management with the addition of additional allowed match types. Specifically, this feature allows customers to submit bid values for specific entities (advertiser, campaign, flight, ad, or creative template field) at request time. These provided values will augment (or optionally override) the default or auto-calculated bids, giving customers full control over how much they’re bidding for a given opportunity. Learn more at [Per-ID Bid Modifiers in ADRs](https://dev.kevel.com/docs/per-id-bid-overrides). - `match` object — Object containing the entity type and ID to match against. - `adId` integer — `adId` key can be any of: adId, flightId, campaignId, advertiserId, creative template variable - `multipler` number, float — Specify the modification as a multiplier on the Flight's Price - `price` number, float — Specify the modification as a fixed value - `forceOverride` boolean — If true, ignore any other matching bid modifiers and only use the modifier sent in the ADR (defaults to false). Note: if multiple modifiers sent in an ADR contain force override true and more than one matches, the highest resulting bid will be used. - `category` string — Optional page or placement category for reporting. Pass a breadcrumb-style string such as `"Electricals > Computing > Laptops"`. Kevel logs this as *Placement Category* on decision and event logs, where it can be used as a reporting dimension to calculate fill rate by category. Category targeting is coming soon and will leverage this field; today it does not affect which ads are selected or served. - `user` object — Object containing the UserKey used for [UserDB targeting](https://dev.adzerk.com/docs/userdb-1). - `key` string - `segments` integer[] — Array of Segment IDs that will override any set on the UserDB record for this user. For use with [Segment Targeting](https://dev.kevel.com/docs/segment-targeting). - `group` integer — The user’s assigned experimental cohort (1–100) used for [incrementality testing using externally assigned user groups](docs:incrementality). This value determines whether the user is in a campaign’s holdout or test group when evaluating ads. Requests must include this field for incrementality-enabled campaigns. - `keywords` string[] — Keywords for [Keyword Targeting](https://dev.adzerk.com/docs/keyword-targeting). Such as `"keywords": ["foo", "bar", "baz"]` - `url` string — The current page URL - `referrer` string — The referrer URL - `ip` string — The IP address. Required for [Geo-Targeting](https://dev.adzerk.com/docs/geo-location) - `includePricingData` boolean — If true, return pricing data for the decision in the response. Defaults to `false` - `includeRelevancyData` boolean — See the [relevancy score](https://dev.kevel.com/docs/relevancy-score#reporting-on-relevancy-score) documentation for more information - `notrack` boolean — Deprecated: If true, only return ads that are set to honor Do Not Track. Defaults to `false` - `enableBotFiltering` boolean — If making a client-side request, set to `true`. Defaults to `false` to ensure a server isn't seen as a bot. See [here](https://dev.adzerk.com/docs/tracking-overview#section-bot-filtering) 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](https://dev.kevel.com/docs/gdpr-compliance-and-consent-settings). - `gdpr` boolean - `gdprConsentString` string — Passes a user's consent to downstream providers via an IAB consent string. Does *not* pass Kevel consent, which must be passed via the `gdpr` parameter OR when an allowed `gdprVendorId` is passed and the user specifies ad selection consent (purpose number `3`) in the consent string. gdprConsentString will be passed to downstream providers regardless of whether the request's IP address originates from the EU. - `gdprConsentRequired` boolean — Requests with `gdprConsentRequired` set to `true` treat the user as requiring GDPR consent, even if the request or UserDB record doesn't use an EU IP address. Likewise, setting to `false` identifies the user as being outside of the EU and not subject to GDPR. - `gdprVendorId` integer — A vendor ID that is used to compute the boolean `gdpr` consent from a consent string in `gdprConsentString` (if one is provided). The vendor ID is from the [IAB vendor list](https://vendorlist.consensu.org/vendorlist.json). Consent will only be calculated if the vendor ID is allowed and the user specifies ad selection consent (purpose number `3`) in the consent string. - `deviceID` string — RTB requests only - sets an Identifier for Advertisers (IFA or IDFA) - `parallel` boolean — If true, processes the placements in parallel. Has no advantage except for RTB and header bidding requests. Does not work with companion ads. - `intendedLatitude` number, float — (BETA) Latitude to use for [Distance Targeting](https://dev.kevel.co/docs/distance-targeting). Range: [-90, 90]. Contact Kevel support to get started - `intendedLongitude` number, float — (BETA) Longitude to use for [Distance Targeting](https://dev.kevel.co/docs/distance-targeting). Range: [-180, 180]. Contact Kevel support to get started - `radius` number, float — (BETA) Radius of the user if using user-specified radius with [Distance Targeting](https://dev.kevel.co/docs/distance-targeting). Range: [0.01, 100]. Contact Kevel support to get started - `rtb` object — 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. - `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](https://dev.kevel.com/docs/search-term-targeting). - `block` object — Prevents specific advertisers, campaigns, creatives, or flights from being served in the response. - `advertisers` integer[] — Advertiser IDs to exclude - `campaigns` integer[] — Campaign IDs to exclude - `creatives` integer[] — Creative IDs to exclude - `flights` integer[] — Flight IDs to exclude ## Response `200` 200 - object - `user` object - `key` string - `decisions` object - `div0` object - `adId` integer - `creativeId` integer - `flightId` integer - `campaignId` integer - `advertiserId` integer - `priorityId` integer - `clickUrl` string - `contents` object[] - `type` string - `body` string - `template` string - `data` object - `imageUrl` string - `title` string - `width` integer - `height` integer - `customData` object - `headline` string - `cta` string - `impressionUrl` string - `events` object[] - `id` integer - `url` string - `pricing` object - `price` integer - `clearPrice` number - `revenue` number - `rateType` integer - `eCPM` integer - `candidateRetrieval` object - `div0` object - `candidatesFoundCount` integer --- [API](https://skmtc.net/kevel/apis/engine-apis.md) · [All operations](https://skmtc.net/kevel/apis/engine-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/kevel/engine-apis/versions/0ca55f45aa7d/schema)