What fields are required in an OpenRTB bid response?

The response needs an id echoing the request. Each bid needs an id, an impid matching an impression, a price, and markup as either adm or nurl. Everything else is optional in the specification, though not in practice.

What does the nbr field mean?

No-bid reason. It is an integer code explaining why no bid was returned — 2 for an invalid request, 8 for an unmatched user, and so on — and it lets an exchange report on why a bidder passes.

Why does nurl need the AUCTION_PRICE macro?

Because the exchange substitutes the clearing price into it when the bid wins. Without the macro the win notice fires with no price, so your logs record the bid rather than what you actually paid.

What is the difference between adm and nurl?

adm carries the creative markup inline in the response; nurl is a URL the exchange calls to fetch it on a win. Inline markup is the norm today because it removes a round trip from the render path.

Does mtype replace anything from 2.5?

It makes explicit what used to be inferred. In 2.5 the media type came from which object the impression carried, which broke down for multi-format impressions; 2.6 has the bid state it outright.

OpenRTB Bid Response Validator

Check a bid response for missing fields, mistyped prices and the macros exchanges expect.

The OpenRTB Bid Response Validator runs entirely in your browser, so responses carrying real deal ids and pricing are checked on your device.

Validate a bid request

About OpenRTB Bid Response Validator

A bid response is the short half of the OpenRTB conversation, and almost everything that goes wrong with one is structural rather than clever: a bid with no impid to tie it to an impression, a price sent as a string, a creative that never declares its advertiser domain, or a win notice that forgets the auction price macro and so reports the wrong clearing price. This validator walks the response the way an exchange would, separating the fields the specification requires from the ones buyers and publishers reject in practice. Every finding carries a JSON path, so it points at the offending bid rather than at the document as a whole.

Features

Checks required fields at the response, seatbid and bid level
Errors, warnings and notes kept apart, each with a JSON path
Type checking on price, dimensions, adomain and the id fields
Version-aware handling of mtype, which arrived in OpenRTB 2.6
Flags a win notice with no auction price macro, and insecure notice URLs
Validates no-bid responses and their nbr reason codes
Spots duplicate bid ids and several bids chasing the same impression
Bundled reference tables for no-bid reasons and media types

How to use the OpenRTB Bid Response Validator

Paste the JSON your bidder returned
Pick the protocol version the exchange is running
Work through the errors first, then the warnings
Use the JSON path on each finding to locate the bid it refers to

Example

Input

{ "id": "1", "seatbid": [{ "bid": [{ "id": "b1", "impid": "1", "price": "2.15" }] }] }

Output

error seatbid[0].bid[0].price — price has to be a number, not a string

A quoted price is the single most common reason a bid is silently discarded.

Common errors & troubleshooting

The bid is valid here but the exchange still discards it. — Exchanges layer their own requirements on top of the specification — a seat id they recognise, categories from a particular taxonomy, or a creative already approved. Check their integration guide alongside this.
A warning about adomain on a house ad. — Fill it in anyway. Publishers block by advertiser domain, and a bid without one is often dropped before anything else about it is considered.
mtype is flagged on a 2.5 integration. — It arrived in OpenRTB 2.6 and a 2.5 exchange ignores it. Switch the version selector to match what the exchange actually runs; sending it does no harm either way.
An empty seatbid array is only a warning. — Because it is legal but unhelpful. The cleaner way to decline is HTTP 204, or a response carrying an nbr code so the exchange can log why you passed.

Frequently asked questions

What fields are required in an OpenRTB bid response?: The response needs an id echoing the request. Each bid needs an id, an impid matching an impression, a price, and markup as either adm or nurl. Everything else is optional in the specification, though not in practice.
What does the nbr field mean?: No-bid reason. It is an integer code explaining why no bid was returned — 2 for an invalid request, 8 for an unmatched user, and so on — and it lets an exchange report on why a bidder passes.
Why does nurl need the AUCTION_PRICE macro?: Because the exchange substitutes the clearing price into it when the bid wins. Without the macro the win notice fires with no price, so your logs record the bid rather than what you actually paid.
What is the difference between adm and nurl?: adm carries the creative markup inline in the response; nurl is a URL the exchange calls to fetch it on a win. Inline markup is the norm today because it removes a round trip from the render path.
Does mtype replace anything from 2.5?: It makes explicit what used to be inferred. In 2.5 the media type came from which object the impression carried, which broke down for multi-format impressions; 2.6 has the bid state it outright.

Related tools

OpenRTB Bid Request Validator — Validate an OpenRTB 2.5 or 2.6 bid request for missing fields, wrong types and bad enums.
OpenRTB Bid Request Generator — Build a valid OpenRTB 2.5 or 2.6 bid request JSON from a form, with CTV presets.
OpenRTB Enum Reference — Search OpenRTB objects and enums like devicetype, api, protocols and plcmt.
VAST Validator — Validate VAST 2.0-4.3 ad XML against IAB rules and see errors and warnings, in your browser.
Prebid Ad Unit Generator — Generate a Prebid.js ad unit config with media types, sizes and bidder params.
SupplyChain (schain) Builder — Build and validate an OpenRTB SupplyChain object and its serialized schain string.