Bid Response

When our demand pool bids, we answer 200 with a standard OpenRTB BidResponse and Content-Type: application/json; charset=utf-8. When nothing bids we answer 204 with an empty body.

We return the single winning bid: one seatbid, carrying one bid. There is no landscape to rank and no auction to run on your side.

Fields marked 2.6 exist in OpenRTB 2.6 only and are omitted when you declare 2.5. Complete bodies are on Bid Response Samples.

BidResponse

Field	Type	Notes
`id`	string	The `BidRequest.id` you sent. Always echoed.
`seatbid`	object[]	The winning seat bid. Absent on a no-bid body.
`bidid`	string	Our identifier for this response. Quote it in support requests.
`cur`	string	Currency of `price`. `USD` at launch.
`customdata`	string	Opaque data, when a buyer supplies it.
`nbr`	int	No-bid reason, on the rare `200` we send without `seatbid`.
`ext`	object	Exchange extensions.

SeatBid

Field	Type	Notes
`bid`	object[]	The bid. Always exactly one entry.
`seat`	string	Buyer seat the bid is made on behalf of.
`group`	int	Always `0`, since we return a single bid.
`ext`	object	Exchange extensions.

Bid

Field	Type	Notes
`id`	string	Bidder-generated id for this bid.
`impid`	string	The `imp.id` from your request.
`price`	float	Bid price CPM in `cur`. See the note on settlement below.
`adid`	string	Id of the ad to be served, in the buyer's system.
`nurl`	string	Win notice URL. Fire it after substitution.
`burl`	string	Billing notice URL. Fire it when the impression is counted.
`lurl`	string	Loss notice URL. Not returned to you, since we send you the winner.
`adm`	string	The creative markup. Substitute macros before rendering.
`adomain`	string[]	Advertiser domains, for your own blocklists.
`bundle`	string	Bundle or package name for app-promotion creatives.
`iurl`	string	Sample image URL, for ad quality checks.
`cid`	string	Campaign id in the buyer's system.
`crid`	string	Creative id in the buyer's system.
`tactic`	string	Tactic id, where a buyer supplies one.
`cattax`	int	Taxonomy the `cat` values follow. 2.6.
`cat`	string[]	IAB content categories of the creative.
`attr`	int[]	Creative attributes present in the markup.
`apis`	int[]	API frameworks the markup requires. 2.6.
`api`	int	API framework the markup requires.
`protocol`	int	Video response protocol of the markup.
`qagmediarating`	int	Creative media rating per IQG guidelines.
`language`	string	Creative language, ISO-639-1.
`langb`	string	Creative language, IETF BCP 47. 2.6.
`dealid`	string	Deal id, when the bid transacts on a deal from `imp.pmp`.
`w`	int	Creative width in device-independent pixels.
`h`	int	Creative height in device-independent pixels.
`wratio`	int	Relative width when expressing size as a ratio.
`hratio`	int	Relative height when expressing size as a ratio.
`exp`	int	Seconds the bid is valid for, and the creative may be cached.
`dur`	int	Creative duration in seconds, for video and audio. 2.6.
`mtype`	int	Creative type: `1` banner, `2` video, `3` audio, `4` native. 2.6.
`slotinpod`	int	Slot position within a pod. 2.6.
`ext`	object	Exchange extensions.

Rendering the bid

Substitute the macros in adm, nurl and burl. This is not optional, and an unsubstituted ${AUCTION_PRICE} in a notice means the win is recorded at no price. See Substitution Macros.
Check mtype under 2.6, or infer the type from which object you sent under 2.5, and hand the markup to the right renderer.
Render adm in the slot the impression came from, at w by h when they are present, or at the size you offered when they are not.
Respect imp.secure. If you set it to 1, every asset in the returned markup will be HTTPS. If you did not set it, the markup may contain HTTP assets, which an HTTPS page will block.
Honour exp. A creative rendered after the bid expires produces an impression we will not bill.

Native bids carry the native response object JSON-encoded into adm as a string, mirroring the way imp.native.request is sent. Video bids carry a VAST document inline in adm, or a VAST URL when tag-based serving is agreed for your account.

Win and billing notices

Notice	Fire it when	Carries
`nurl`	The bid wins your auction, before render	`${AUCTION_PRICE}`
`burl`	The impression is counted	`${AUCTION_PRICE}` and impression identifiers

Fire both. nurl tells the buyer they won, burl tells them the impression happened, and buyers who see wins without billing notices reduce their bids on your inventory. The gap between the two is normal, since a win precedes a render.

Notices are plain HTTP GETs. Fire them server side where you can, and do not retry a failed one, since a duplicate notice counts as a duplicate impression.

Settlement

bid.price is what the buyer bid. What you are paid is what ${AUCTION_PRICE} resolves to after substitution, which under a second-price auction (at of 2) is normally lower.

Bill against the substituted value. Reconciling against the raw bid.price will overstate your revenue by a stable margin every day, and it is the single most common cause of a discrepancy claim that turns out not to be one.

No bid

204 No Content with an empty body. There is nothing to parse. Fall back to whatever you would otherwise show and move on.

Occasionally you will see 200 with nbr and no seatbid instead. It carries a reason code, and it is otherwise equivalent to a 204. Reason codes are listed on Errors & No-Bids.

Next: Substitution Macros.