Bid Request

The request you post to us is a standard OpenRTB BidRequest. Object names, field names and types follow the IAB specification for the version you declare in x-openrtb-version, and this page does not rename or reshape any of them.

What adon3 adds is a stricter requirement level on four fields. Everything else is optional to us in exactly the way the specification says it is, though the more context you send, the more of our demand can bid.

Fields marked 2.6 exist in OpenRTB 2.6 only and are ignored when you declare 2.5. Fields marked deprecated are still accepted under 2.6 and are read when present. Complete bodies are on Bid Request Samples.

What adon3 requires

Field	Rule
`id`	Required.
`imp`	Required. Exactly one entry.
`device.ua`	Required, unmodified. `device.sua` may accompany it under 2.6 but does not replace it.
`device.ip` or `device.ipv6`	At least one required.
`site.domain` or `app.bundle`	At least one required, on whichever object you send.

BidRequest

Field	Type	Req.	Notes
`id`	string	yes	Unique id of the bid request, generated by you.
`imp`	object[]	yes	Impressions offered. adon3 accepts exactly one.
`site`	object	cond.	Present for web inventory. Mutually exclusive with `app`.
`app`	object	cond.	Present for in-app inventory. Mutually exclusive with `site`.
`dooh`	object	no	Digital out-of-home inventory. 2.6. Not bid on at launch.
`device`	object	yes	Device the impression will be delivered to.
`user`	object	no	Human user of the device.
`test`	int	no	`1` indicates a test auction, which is not billed. Default `0`.
`at`	int	no	Auction type. `1` first price, `2` second price plus. Default `2`.
`tmax`	int	no	Maximum time in milliseconds you will wait for a response.
`wseat`	string[]	no	Buyer seats allowed to bid.
`bseat`	string[]	no	Buyer seats blocked from bidding.
`allimps`	int	no	`1` if `imp` covers all impressions available. Default `0`.
`cur`	string[]	no	Allowed bid currencies, ISO-4217. Default `["USD"]`.
`wlang`	string[]	no	Allowed creative languages, ISO-639-1.
`wlangb`	string[]	no	Allowed creative languages, IETF BCP 47. 2.6.
`acat`	string[]	no	Allowed advertiser categories. 2.6.
`bcat`	string[]	no	Blocked advertiser categories, under `cattax`.
`cattax`	int	no	Category taxonomy. `1` IAB 1.0, `2` IAB 2.x. Default `2`. 2.6.
`badv`	string[]	no	Blocked advertiser domains.
`bapp`	string[]	no	Blocked app bundles or package names.
`source`	object	no	Inventory source and supply chain.
`regs`	object	no	Regulatory conditions in force.
`ext`	object	no	Exchange extensions.

site and app are mutually exclusive. A request carrying both, or neither, is rejected with BOTH_SITE_AND_APP or MISSING_REQUIRED.

Imp

Field	Type	Req.	Notes
`id`	string	yes	Impression id within the request. `"1"` when you send one impression.
`metric`	object[]	no	Metrics known to you about this impression.
`banner`	object	cond.	Present for a banner impression.
`video`	object	cond.	Present for a video impression.
`audio`	object	cond.	Present for an audio impression.
`native`	object	cond.	Present for a native impression.
`pmp`	object	no	Private marketplace deals applicable to this impression.
`displaymanager`	string	no	Name of the ad mediation partner or SDK.
`displaymanagerver`	string	no	Version of the display manager.
`instl`	int	no	`1` if the ad is interstitial or full screen. Default `0`.
`tagid`	string	no	Your identifier for the placement.
`bidfloor`	float	no	Minimum bid CPM in `bidfloorcur`. Default `0`.
`bidfloorcur`	string	no	Currency of `bidfloor`, ISO-4217. Default `USD`.
`clickbrowser`	int	no	`0` embedded browser, `1` native browser.
`secure`	int	no	`1` requires HTTPS markup and assets.
`iframebuster`	string[]	no	Supported iframe busters.
`rwdd`	int	no	`1` if the user receives a reward for viewing. Default `0`. 2.6.
`ssai`	int	no	Server-side ad insertion status. 2.6.
`exp`	int	no	Seconds between the auction and the expected display.
`qty`	object	no	Multiplier for impression counting. 2.6.
`dt`	float	no	Timestamp the item is estimated to be displayed. 2.6.
`refresh`	object	no	Refresh behaviour of the placement. 2.6.
`ext`	object	no	Exchange extensions.

Send exactly one of banner, video, audio or native. A request carrying none of them, or more than one, is rejected.

Imp.Banner

Field	Type	Req.	Notes
`format`	object[]	no	Permitted sizes. Strongly preferred over `w` and `h`.
`w`	int	no	Exact width in device-independent pixels.
`h`	int	no	Exact height in device-independent pixels.
`btype`	int[]	no	Blocked banner creative types.
`battr`	int[]	no	Blocked creative attributes.
`pos`	int	no	Ad position on screen.
`mimes`	string[]	no	Content MIME types supported.
`topframe`	int	no	`0` in an iframe, `1` in the top frame.
`expdir`	int[]	no	Directions the ad may expand in.
`api`	int[]	no	Supported API frameworks.
`id`	string	no	Unique id, relevant when used in `Video.companionad`.
`vcm`	int	no	Companion rendering mode, relevant in `Video.companionad`.
`ext`	object	no	Exchange extensions.

Format carries w, h, wratio, hratio and wmin. Send format even when only one size is permitted, since it is what most buyers target on.

Imp.Video

Field	Type	Req.	Notes
`mimes`	string[]	yes	Content MIME types supported, for example `video/mp4`.
`startdelay`	int	no	`0` pre-roll, `-1` generic mid-roll, `-2` post-roll.
`maxseq`	int	no	Maximum number of ads in a dynamic pod. 2.6.
`poddur`	int	no	Total pod duration in seconds. 2.6.
`protocols`	int[]	no	Supported video protocols.
`w`	int	no	Width of the player in device-independent pixels.
`h`	int	no	Height of the player in device-independent pixels.
`podid`	string	no	Unique id of the ad pod. 2.6.
`podseq`	int	no	Position of the pod in the content stream. 2.6.
`rqddurs`	int[]	no	Precise acceptable durations. 2.6.
`placement`	int	no	Video placement type. Deprecated in 2.6 in favour of `plcmt`.
`plcmt`	int	no	Video placement type per the 2.6 subtype list. 2.6.
`linearity`	int	no	`1` linear or in-stream, `2` non-linear or overlay.
`skip`	int	no	`1` if the player allows skipping.
`skipmin`	int	no	Videos longer than this may be skippable. Default `0`.
`skipafter`	int	no	Seconds before the skip control appears. Default `0`.
`sequence`	int	no	Position in a set of ads. Deprecated in 2.6.
`slotinpod`	int	no	Slot position within the pod. 2.6.
`mincpmpersec`	float	no	Minimum CPM per second for the pod. 2.6.
`battr`	int[]	no	Blocked creative attributes.
`maxextended`	int	no	Maximum extended video ad duration.
`minbitrate`	int	no	Minimum bit rate in Kbps.
`maxbitrate`	int	no	Maximum bit rate in Kbps.
`boxingallowed`	int	no	`1` if letterboxing of 4:3 in 16:9 is allowed. Default `1`.
`playbackmethod`	int[]	no	Playback methods that may be in use.
`playbackend`	int	no	Event that causes playback to end.
`delivery`	int[]	no	Supported delivery methods.
`pos`	int	no	Ad position on screen.
`companionad`	object[]	no	Companion banners available.
`api`	int[]	no	Supported API frameworks.
`companiontype`	int[]	no	Supported VAST companion types.
`minduration`	int	no	Minimum ad duration in seconds. Default `0`.
`maxduration`	int	no	Maximum ad duration in seconds.
`ext`	object	no	Exchange extensions.

Imp.Audio

Field	Type	Req.	Notes
`mimes`	string[]	yes	Content MIME types supported, for example `audio/mp4`.
`minduration`	int	no	Minimum ad duration in seconds.
`maxduration`	int	no	Maximum ad duration in seconds.
`poddur`	int	no	Total pod duration in seconds. 2.6.
`protocols`	int[]	no	Supported audio protocols.
`startdelay`	int	no	`0` pre-roll, `-1` generic mid-roll, `-2` post-roll.
`rqddurs`	int[]	no	Precise acceptable durations. 2.6.
`podid`	string	no	Unique id of the ad pod. 2.6.
`podseq`	int	no	Position of the pod in the content stream. 2.6.
`sequence`	int	no	Position in a set of ads. Deprecated in 2.6.
`slotinpod`	int	no	Slot position within the pod. 2.6.
`mincpmpersec`	float	no	Minimum CPM per second for the pod. 2.6.
`battr`	int[]	no	Blocked creative attributes.
`maxextended`	int	no	Maximum extended ad duration.
`minbitrate`	int	no	Minimum bit rate in Kbps.
`maxbitrate`	int	no	Maximum bit rate in Kbps.
`delivery`	int[]	no	Supported delivery methods.
`companionad`	object[]	no	Companion banners available.
`api`	int[]	no	Supported API frameworks.
`companiontype`	int[]	no	Supported DAAST companion types.
`maxseq`	int	no	Maximum number of ads in a dynamic pod. 2.6.
`feed`	int	no	Type of audio feed.
`stitched`	int	no	`1` if the ad is stitched into the audio content.
`nvol`	int	no	Volume normalisation mode.
`ext`	object	no	Exchange extensions.

Imp.Native

Field	Type	Req.	Notes
`request`	string	yes	The native request payload, as a JSON-encoded string.
`ver`	string	no	Version of the Native specification the request follows.
`api`	int[]	no	Supported API frameworks.
`battr`	int[]	no	Blocked creative attributes.
`ext`	object	no	Exchange extensions.

request is a string containing JSON rather than a nested object. That is what the specification says, and it catches people every time.

Imp.Pmp

Field	Type	Req.	Notes
`private_auction`	int	no	`1` restricts the auction to the deals listed. Default `0`.
`deals`	object[]	no	The deals available on this impression.
`ext`	object	no	Exchange extensions.

Deal carries id (required), bidfloor, bidfloorcur, at, wseat, wadomain and ext.

Site

Field	Type	Req.	Notes
`id`	string	no	Your id for the site.
`name`	string	no	Site name.
`domain`	string	cond.	Domain of the site. Required by adon3 when you send `site`.
`cattax`	int	no	Taxonomy in use for the category fields. 2.6.
`cat`	string[]	no	Content categories of the site.
`sectioncat`	string[]	no	Content categories of the current section.
`pagecat`	string[]	no	Content categories of the current page.
`page`	string	no	URL of the page where the impression will be shown.
`ref`	string	no	Referrer URL that led to the page.
`search`	string	no	Search string that led to the page.
`mobile`	int	no	`1` if optimised for mobile.
`privacypolicy`	int	no	`1` if the site has a privacy policy.
`publisher`	object	no	Publisher of the site.
`content`	object	no	Content of the site.
`keywords`	string	no	Comma-separated keywords about the site.
`kwarray`	string[]	no	Keywords as an array. 2.6.
`ext`	object	no	Exchange extensions.

App

Field	Type	Req.	Notes
`id`	string	no	Your id for the app.
`name`	string	no	App name.
`bundle`	string	cond.	Platform-specific application identifier. Required by adon3 when you send `app`.
`domain`	string	no	Domain of the app, from its store listing.
`storeurl`	string	no	App store URL for an installed app.
`cattax`	int	no	Taxonomy in use for the category fields. 2.6.
`cat`	string[]	no	Content categories of the app.
`sectioncat`	string[]	no	Content categories of the current section.
`pagecat`	string[]	no	Content categories of the current page.
`ver`	string	no	Application version.
`privacypolicy`	int	no	`1` if the app has a privacy policy.
`paid`	int	no	`0` free, `1` paid.
`publisher`	object	no	Publisher of the app.
`content`	object	no	Content of the app.
`keywords`	string	no	Comma-separated keywords about the app.
`kwarray`	string[]	no	Keywords as an array. 2.6.
`ext`	object	no	Exchange extensions.

Publisher carries id, name, cattax, cat, domain and ext. Content follows the specification in full, and the fields our demand reads most are id, title, series, season, genre, cat, livestream, len and language.

Device

Field	Type	Req.	Notes
`geo`	object	no	Location of the device.
`dnt`	int	no	`1` if Do Not Track is enabled.
`lmt`	int	no	`1` if Limit Ad Tracking is enabled.
`ua`	string	yes	Browser user agent string. Required by adon3.
`sua`	object	no	Structured user agent, from client hints. 2.6.
`ip`	string	cond.	IPv4 address closest to the device. One of `ip` or `ipv6` required.
`ipv6`	string	cond.	IPv6 address closest to the device. One of `ip` or `ipv6` required.
`devicetype`	int	no	General type of device.
`make`	string	no	Device make.
`model`	string	no	Device model.
`os`	string	no	Device operating system.
`osv`	string	no	Device operating system version.
`hwv`	string	no	Hardware version of the device.
`h`	int	no	Physical height of the screen in pixels.
`w`	int	no	Physical width of the screen in pixels.
`ppi`	int	no	Screen size as pixels per linear inch.
`pxratio`	float	no	Ratio of physical pixels to device-independent pixels.
`js`	int	no	`1` if the device supports JavaScript.
`geofetch`	int	no	`1` if the geolocation API will be available.
`flashver`	string	no	Flash version supported.
`language`	string	no	Browser language, ISO-639-1.
`langb`	string	no	Browser language, IETF BCP 47. 2.6.
`carrier`	string	no	Carrier or ISP.
`mccmnc`	string	no	Mobile country and network codes.
`connectiontype`	int	no	Network connection type.
`ifa`	string	no	ID sanctioned for advertiser use.
`didsha1`	string	no	Hardware device id, SHA1 hashed.
`didmd5`	string	no	Hardware device id, MD5 hashed.
`dpidsha1`	string	no	Platform device id, SHA1 hashed.
`dpidmd5`	string	no	Platform device id, MD5 hashed.
`macsha1`	string	no	MAC address, SHA1 hashed.
`macmd5`	string	no	MAC address, MD5 hashed.
`ext`	object	no	Exchange extensions.

When lmt is 1, we withhold ifa from demand regardless of what you sent.

Geo carries lat, lon, type, accuracy, lastfix, ipservice, country, region, regionfips104, metro, city, zip, utcoffset and ext. country is ISO-3166-1 alpha-3.

User

Field	Type	Req.	Notes
`id`	string	no	Your id for the user.
`buyeruid`	string	no	Buyer-specific id for the user, from cookie sync.
`yob`	int	no	Year of birth as a four-digit integer. Deprecated in 2.6.
`gender`	string	no	`M`, `F` or `O`. Deprecated in 2.6.
`keywords`	string	no	Comma-separated keywords about the user.
`kwarray`	string[]	no	Keywords as an array. 2.6.
`customdata`	string	no	Opaque data useful to bidders.
`geo`	object	no	Location of the user's home base.
`data`	object[]	no	Additional user data, each with `id`, `name` and `segment`.
`consent`	string	no	TCF consent string when `regs.gdpr` is `1`.
`eids`	object[]	no	Extended identifiers, each with `source` and `uids`.
`ext`	object	no	Exchange extensions.

Source

Field	Type	Req.	Notes
`fd`	int	no	`1` if the final decision is made downstream, `0` if upstream.
`tid`	string	no	Transaction id common to all requests for this impression.
`pchain`	string	no	Payment id chain.
`schain`	object	no	Supply chain object. Send it on every request.
`ext`	object	no	Exchange extensions.

SupplyChain carries complete, nodes and ver. Each SupplyChainNode carries asi, sid, rid, name, domain and hp. asi and sid are required on every node and must resolve against sellers.json.

Regs

Field	Type	Req.	Notes
`coppa`	int	no	`1` if the request is subject to COPPA.
`gdpr`	int	no	`1` if GDPR applies. Read alongside `user.consent`.
`us_privacy`	string	no	US Privacy string.
`gpp`	string	no	Global Privacy Platform string. 2.6.
`gpp_sid`	int[]	no	GPP section ids that apply. 2.6.
`ext`	object	no	Exchange extensions.

Validation

We reject a request before it reaches a bidder when the body is not valid JSON, when id or imp is missing, when device.ua is missing, when neither device.ip nor device.ipv6 is present, when neither site.domain nor app.bundle is present, when both site and app are present, or when the supply chain does not resolve.

Every rejection carries a code and a message. See Errors & No-Bids.

Next: Bid Response.