OpenRTB 2.2 Specifications

Home » Marketer Documentation » OpenRTB 2.2 Specifications

This is Smaato’s OpenRTB Bid Request Documentation for OpenRTB 2.2 integrations.

Bid Request Object

Field	Scope	Type	Default	Description
`id`	required	string	–	The unique ID of the bid request, provided by the exchange.
`imp`	required	array of objects	–	The array of impression objects. Multiple impression auctions may be specified in a single bid request. At least one impression is required for a valid bid request.
`site`	recommended for websites	object	–	See Site Object.
`app`	recommended for native apps	object	–	See App Object.
`device`	recommended	object	–	See Device Object.
`user`	recommended	object	–	See User Object.
`at`	optional	integer	2	The auction type. “2” stands for second price auction (“1” = first price auction). Additional auction types can be defined as per the exchange’s business rules. Exchange specific rules should be numbered over 500.
`tmax`	optional	integer	–	The maximum amount of time in milliseconds to submit a bid (e.g., 120 means the bidder has 120 ms to submit a bid before the auction is complete). If this value never changes across an exchange, then the exchange may supply this information offline.
`wseat`	optional	array of strings	–	The array of buyer seats allowed to bid on this auction. Seats are an optional exchange feature. For example, [“4”,”34”,”82”,”A45”] indicates that only advertisers using these exchange seats are allowed to bid on the impressions in this auction.
`allimps`	optional	integer	0	The flag to indicate whether the exchange can verify that all impressions offered to represent all of the impressions available in context (e.g., all impressions available on the web page; all impressions available for a video [pre, mid and postroll spots], etc.) to support roadblocking. A true value should only be passed if the exchange is aware of all impressions in context for the publisher. “0” means the exchange cannot verify, and “1” means that all impressions represent all impressions available.
`cur`	optional	array of strings	–	The array of allowed currencies for bids on this bid request using ISO-4217 alphabetic codes. If only one currency is used by the exchange, this parameter is not required.
`bcat`	optional	array of strings	–	Blocked advertiser categories. Note that there is no existing categorization/taxonomy of advertiser industries. However, as a substitute, exchanges may decide to use IAB categories as an approximation (See Content Categories).
`badv`	optional	array of strings	–	The array of strings of blocked top-level domains of advertisers. For example, {“company1.com”, “company2.com”}.
`regs`	optional	object	–	This object is a container for any legal, governmental or industry regulations in force for the request.
`ext`	optional	object	–	This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification. See also Extensions.

Impression Object

Field	Scope	Type	Default	Description
`id`	required	string	–	A unique identifier for this impression within the context of the bid request (typically, value starts with 1, and increments up to n for n impressions).
`banner`	required for banner impressions	object	–	A reference to a banner object. Either a banner or video object (or both if the impression could be either) must be included in an impression object. See Banner Object.
`video`	required for video impressions	object	–	A reference to a video object. Either a banner or video object (or both if the impression could be either) must be included in an impression object. See Video Object.
`displaymanager`	recommended for video and native apps	string	–	Name of ad mediation partner, SDK technology, or native player responsible for rendering ad (typically video or mobile). Used by some ad servers to customize ad code by a partner.
`displaymanagerver`	recommended for video and native apps	string	–	The version of ad mediation partner, SDK technology, or native player responsible for rendering ad (typically video or mobile). Used by some ad servers to customize ad code by a partner.
`instl`	optional	integer	0	1 if the ad is interstitial or full screen; otherwise 0.
`tagid`	optional	string	–	The identifier for specific ad placement or ad tag that was used to initiate the auction. This can be useful for debugging any issues, or for optimization by the buyer.
`bidfloor`	optional	float	0	Bid floor for this impression (in CPM of bidfloorcur).
`bidfloorcur`	optional	string	USD	If bid floor is specified and multiple currencies supported per bid request, then the currency should be specified here using ISO-4217 alphabetic codes. This may be different from bid currency returned by bidder, if this is allowed on an exchange.
`secure`	optional	int	–	Flag to indicate whether the impression requires secure HTTPS URL creative assets and markup. A value of “1” means that the impression requires secure assets, “0” denotes non-secure assets. If this field is omitted, the bidder should interpret the secure state is unknown and assume HTTP is supported.
`iframebuster`	optional	array of string	None	The array of names for supported iframe busters. Exchange specific.
`pmp`	optional	object	–	A reference to the PMP object containing any Deals eligible for the impression object. See the PMP object definition.
`ext`	optional	object	–	This object is a place holder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

ImpressionExtension Object

Field Scope Type Description

Field	Scope	Type	Description
`strictbannersize`	optional	integer	Custom field with the following values: 1 if the banner size to be treated strictly 0 (default value) if the DSP can return ads smaller than the banner size
`native`	optional	object	Smaato native object

strictbannersize

optional

integer

Custom field with the following values:

1 if the banner size to be treated strictly
0 (default value) if the DSP can return ads smaller than the banner size

native optional object Smaato native object

Banner Object

Field	Scope	Type	Default	Description
`w`	recommended	integer	–	The width of the impression in pixels. Since some ad types are not restricted by size, this field is not required, but it’s highly recommended that this information be included when possible.
`h`	recommended	integer	–	The height of the impression in pixels. Since some ad types are not restricted by size, this field is not required, but it’s highly recommended that this information be included when possible.
`wmax`	optional	integer	–	The maximum width of the impression in pixels. If included, it indicates that a range of sizes is allowed with this maximum width and “w” is taken as recommended. If not included, then “w” should be considered an exact requirement.
`hmax`	optional	integer	–	The maximum height of the impression in pixels. If included, it indicates that a range of sizes is allowed with this maximum height and “h” is taken as recommended. If not included, then “h” should be considered an exact requirement.
`wmin`	optional	integer	–	The minimum width of the impression in pixels. If included, it indicates that a range of sizes is allowed with this minimum width and “w” is taken as recommended. If not included, then “w” should be considered an exact requirement.
`hmin`	optional	integer	–	The minimum height of the impression in pixels. If included, it indicates that a range of sizes is allowed with this minimum height and “h” is taken as recommended. If not included, then “h” should be considered an exact requirement.
`id`	recommended when subordinate to a video object	string	–	The unique identifier for this banner object. Useful for tracking multiple banner objects (e.g., in a companion banner array). It usually starts with 1, increasing with each object. Combination of impression id banner object should be unique.
`pos`	optional	integer	–	Ad position.
`btype`	optional	array of integers	All types are allowed	Blocked creative types. See Banner Ad Types. If blank, assume all types are allowed.
`battr`	optional	array of integers	All types are allowed	Blocked creative attributes. See Creative Attributes. If blank assumes all types are allowed.
`mimes`	optional	array of integers	All types are allowed	The whitelist of content MIME types supported. Popular MIME types include, but are not limited to “image/jpg”, “image/gif” and “application/x-‐shockwave-‐flash”.
`topframe`	optional	integer	0	This specifies f the banner is delivered in the top frame or in an iframe. “0” means it’s not in the top frame, and “1” means that it is.
`expdir`	optional	array of integers	Not expandable	This specifies properties for an expandable ad. See Expandable Direction for possible values.
`api`	optional	array of integers	None	The list of supported API frameworks for this banner. (See API Frameworks). If an API is not explicitly listed, it is assumed to not be supported.
`ext`	optional	object	–	This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Video Object

Field	Scope	Type	Default	Description
`mimes`	required	array of strings	–	The content MIME types supported. Popular MIME types include, but are not limited to “video/x-‐ms-‐wmv” for Windows Media, and “video/x-‐flv” for Flash video.
`minduration`	required	integer	–	The minimum video ad duration in seconds.
`maxduration`	required	integer	–	The maximum video ad duration in seconds.
`protocol`	optional	integer	–	The video bid response protocols. See Video Bid Response Protocols for a list of possible values. NOTE: Use “protocols” when multiple protocols are supported. Its use is also highly recommended even though this attribute is likely to be deprecated in a future version. At least one supported protocol must be specified in either the “protocol” or “protocols” attribute.
`protocols`	recommended	array of integers	–	The video bid response protocols. See Video Bid Response Protocols for a list of possible values. At least one supported protocol must be specified in either the “protocol” or “protocols” attribute.
`w`	recommended	integer	–	The width of the player in pixels. This field is not required, but it’s highly recommended that this information be included.
`h`	recommended	integer	–	The height of the player in pixels. This field is not required, but it’s highly recommended that this information be included.
`startdelay`	recommended	integer	–	Indicates the start delay in seconds for pre-roll, midroll, or post-roll ad placement. See Video Start Delay for generic placement values.
`linearity`	optional	integer	–	Indicates whether the ad impression must be linear, non‐linear, or can be of any type (field not set). See Video Linearity for a list of the possible values and recommended bidder interpretation.
`sequence`	optional	integer	1	If multiple ad impressions are offered in the same bid request, the sequence number will allow for the coordinated delivery of multiple creatives.
`battr`	optional	array of integers	Assume all types are allowed	Blocked creative attributes. See Creative Attributes. If blank, assume all types are allowed.
`maxextended`	optional	integer	Extension not allowed	The maximum extended video ad duration if the extension is allowed. If blank or 0, the extension is not allowed. If -1, an extension is allowed, and there is no time limit imposed. If greater than 0, then the value represents the number of seconds of extended play supported beyond the max duration value.
`minbitrate`	optional	integer	Any bitrate accepted	The minimum bit rate in kbps. Exchanges may set this dynamically, or universally across their set of publishers.
`maxbitrate`	optional	integer	Any bitrate accepted	The maximum bit rate in kbps. Exchanges may set this dynamically, or universally across their set of publishers.
`boxingallowed`	optional	integer	1	If an exchange publisher has rules preventing letterboxing of 4×3 content to play in a 16×9 window, then this should be set to false. The default setting is true, which assumes that boxing of content to fit into a window is allowed. “1” indicates boxing is allowed. “0” indicates it is not allowed.
`playbackmethod`	optional	array of integers	All	The list of allowed playback methods. If blank, assume that all are allowed. See Video Playback Methods for a list of possible values.
`deliver`	optional	array of integers	All	The list of supported delivery methods (streaming, progressive). If blank, assume all are supported. See Content Delivery Methods for a list of possible values.
`pos`	optional	integer	Unknown	Ad position.
`companionad`	optional	array of objects	Not available	If companion ads are available, they can be listed as an array of banner objects. See Banner Object.
`api`	optional	array of integers	Assume None	List of supported API frameworks for this impression. See API Frameworks. If an API is not explicitly listed, it is assumed not to be supported.
`companiontype`	optional	array of integers	–	Recommended if companion objects are included. See VAST Companion Types for a list of possible values.
`ext`	optional	object	–	This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Site Object

Field	Scope	Type	Default	Description
`id`	recommended	string	–	The site ID on the exchange.
`name`	optional	string	–	The site name (may be masked at publisher’s request).
`domain`	optional	string	–	The domain of the site, used for advertiser side blocking. For example, “example.com”.
`cat`	optional	array of strings	–	The array of IAB content categories for the overall site. See Content Categories.
`sectioncat`	optional	array of strings	–	The array of IAB content categories for the current subsection of the site. See Content Categories.
`pagecat`	optional	array of strings	–	The array of IAB content categories for the current page. See Content Categories.
`page`	recommended	string	–	The URL of the page where the impression will be shown.
`privacypolicy`	optional	integer	–	Specifies whether the site has a privacy policy. “1” means there is a policy. “0” means there is not.
`ref`	optional	string	–	The referrer URL that caused navigation to the current page.
`search`	optional	string	–	The search string that caused navigation to the current page.
`publisher`	optional	object	–	See Publisher Object.
`content`	optional	object	–	See Content Object.
`keywords`	optional	string	–	The list of keywords describing this site in a comma separated string. ALTERNATE Representation: Array of strings.
`ext`	optional	object	–	This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined.

App Object

Field	Scope	Type	Default	Description
`id`	recommended	string	–	The application ID on the exchange.
`name`	optional	string	–	The application name (may be masked at publisher’s request).
`domain`	optional	string	–	The domain of the application (e.g., “mygame.example.com”).
`cat`	optional	array of strings	–	The array of IAB content categories for the overall application. See Content Categories.
`sectioncat`	optional	array of strings	–	The array of IAB content categories for the current subsection of the app. See Content Categories.
`pagecat`	optional	array of strings	–	The array of IAB content categories for the current page/view of the app. See Content Categories.
`ver`	optional	string	–	The application version.
`bundle`	recommended	string	–	The application bundle or package name (e.g., com.foo.mygame). This is intended to be a unique ID across multiple exchanges.
`privacypolicy`	optional	integer	–	Specifies whether the app has a privacy policy. “1” means there is a policy and “0” means there is not.
`paid`	optional	integer	–	“1” if the application is a paid version; else “0” (i.e., free).
`publisher`	optional	object	–	See Publisher Object.
`content`	optional	object	–	See Content Object.
`keywords`	optional	string	–	List of keywords describing this app in a comma separated string. ALTERNATE Representation: Array of strings.
`storeurl`	optional	string	–	For QAG 1.5 compliance, an app store URL for an installed app should be passed in the bid request.
`ext`	optional	object	–	This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in the specification.

Content Object

Field	Scope	Type	Default	Description
`id`	optional	string	–	The ID uniquely identifying the content.
`episode`	optional	integer	–	The content episode number (typically applies to video content).
`title`	optional	string	–	Content title. Video examples: “Search Committee” (television) or “A New Hope” (movie) or “Endgame” (made for web) Non‐video example: “Why an Antarctic Glacier Is Melting So Quickly” (Time magazine article)
`series`	optional	string	–	Content series. Video examples: “The Office” (television) or “Star Wars” (movie) or “Arby ‘N’ The Chief” (made for web) Non‐video example: “Ecocentric” (Time magazine blog)
`season`	optional	string	–	Content season. E.g., “Season 3” (typically applies to video content).
`url`	optional	string	–	The original URL of the content, for buy-‐side contextualization or review.
`cat`	optional	array of strings	–	The array of IAB content categories for the content. See Content Categories.
`videoquality`	optional	integer	–	Video quality per the IAB’s classification. See Video Quality.
`keywords`	optional	string	–	Comma-separated list of keywords describing the content. ALTERNATE Representation: Array of strings.
`contentrating`	optional	string	–	Content rating (e.g., MPAA).
`userrating`	optional	string	–	User rating of the content (e.g., number of stars, likes, etc.).
`context`	optional	integer	–	Specifies the type of content (game, video, text, etc.). See Table 6.13 Content Context.
`livestream`	optional	integer	–	Is content live? E.g., live video stream, live blog.“1” means the content is live. “0” means it is not live.
`sourcerelationship`	optional	integer	–	1 for “direct”; 0 for “indirect”.
`producer`	optional	object	–	See the Producer Object.
`len`	optional	integer	–	Length of content (appropriate for video or audio) in seconds.
`qagmediarating`	optional	integer	–	Media rating of the content, per QAG guidelines. See QAG Media Ratings for list of possible values.
`embeddable`	optional	integer	–	From QAG Video Addendum. If content can be embedded (such as an embeddable video player) this value should be set to “1”. If content cannot be embedded, then this should be set to “0”.
`language`	optional	string	–	Language of the content. Use alpha‐2/ISO 639-1 codes.
`ext`	optional	object	–	This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Publisher Object

Field	Scope	Type	Default	Description
`id`	recommended	string	–	Publisher ID on the exchange.
`name`	optional	string	–	Publisher name (may be masked at publisher’s request).
`cat`	optional	array of strings	–	The array of IAB content categories for the publisher. See Table 6.1 Content Categories.
`domain`	optional	string	–	Publisher’s highest level domain name. e.g., “example.com”.
`ext`	optional	object	–	This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Producer Object

Field	Scope	Type	Default	Description
`id`	optional	string	–	Content producer or originator ID. Useful if the content is syndicated, and may be posted on a site using embed tags.
`name`	optional	string	–	Content producer or originator name (e.g., “Warner Bros”).
`cat`	optional	array of strings	–	The array of IAB content categories for the content producer. See Content Categories.
`domain`	optional	string	–	URL of the content producer.
`ext`	optional	object	–	This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Device Object

Field	Scope	Type	Default	Description
`dnt`	recommended	integer	–	If “0”, then do not track Is set to false, if “1”, then do no track is set to true in browser.
`ua`	recommended	string	–	Browser user agent string.
`ip`	recommended if geo object is not supplied	string	–	IPv4 address is closest to the device.
`geo`	recommended if IP is not supplied	object	–	Geography as derived from the device’s location services (e.g., cell tower triangulation, GPS) or IP address. See Geo Object.
`didsha1`	optional	string	–	SHA1 hashed device ID; IMEI when available, else MEID or ESN. OpenRTB’s preferred method for device ID hashing is SHA1.
`didmd5`	optional	string	–	MD5 hashed device ID; IMEI when available, else MEID or ESN. Should be interpreted as case insensitive.
`dpidsha1`	optional	string	–	SHA1 hashed platform-‐specific ID (e.g., Android ID or UDID for iOS). OpenRTB’s preferred method for device ID hash is SHA1.
`dpidmd5`	optional	string	–	MD5 hashed platform-‐specific ID (e.g., Android ID or UDID for iOS). Should be interpreted as case insensitive.
`carrier`	optional	string	–	Carrier or ISP (e.g., “VERIZON”). “WIFI” is often used in mobile to indicate high bandwidth (e.g., video friendly vs. cellular).
`language`	optional	string	–	Browser language; use alpha-2/ISO 639-1 codes.
`make`	optional	string	–	Device make (e.g., “Apple”).
`model`	optional	string	–	Device model (e.g., “iPhone 5s”)
`os`	optional	string	–	Device operating system (e.g., “iOS”).
`osv`	optional	string	–	Device operating system version (e.g., “3.1.2”).
`js`	optional	integer	–	“1” if the device supports JavaScript; else “0”.
`connectiontype`	optional	integer	–	Return the detected data connection type for the device.
`devicetype`	optional	integer	–	Return the device type being used. See Table 6.16 Device Type.
`ifa`	optional	string	–	Native identifier for advertisers; an opaque ID assigned by the device or browser for use as an advertising identifier.
`ext`	optional	object	–	This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Geo Object

Field	Scope	Type	Default	Description
`lat`	optional	float	–	Latitude from ‐90 to 90. South is negative. This should only be passed if known to be accurate (For example, not the centroid of a postal code).
`lon`	optional	float	–	Longitude from ‐180 to 180. West is negative. This should only be passed if known to be accurate.
`country`	optional	string	–	Country using ISO‐3166-1 Alpha-3.
`region`	optional	string	–	Region using ISO 3166‐2.
`regionfips104`	optional	string	–	Region of a country using FIPS 10-4 notation (alternative to ISO 3166-2).
`metro`	optional	string	–	Pass the metro code. Metro codes are similar to but not exactly the same as Nielsen DMAs.
`city`	optional	string	–	City using United Nations Code for Trade and Transport Locations (http://www.unece.org/cefact/locode/ser vice/location.htm ).
`zip`	optional	string	–	Zip/postal code.
`type`	recommended	integer	–	Indicate the source of the geo data (GPS, IP address, user provided). See Table 6.15 Location Type for a list of potential values. Type should be provided when lat/lon is provided.
`ext`	optional	object	–	This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

User Object

Field	Scope	Type	Default	Description
`id`	recommended (or buyeruid)	string	–	Unique consumer ID of this user on the exchange.
`buyeruid`	recommended (or id)	string	–	Buyer’s user ID for this user as mapped by exchange for the buyer.
`yob`	optional	integer	–	Year of birth as a 4-‐digit integer.
`gender`	optional	string	–	Gender as “M” male, “F” female, “O” Other. (Null indicates unknown).
`keywords`	optional	string	–	A comma-separated list of keywords of consumer interests or intent. ALTERNATE Representation: Array of strings.
`customdata`	optional	string	–	If supported by the exchange, this is custom data that the bidder had stored in the exchange’s cookie. The string may be in base85 cookie safe characters and be in any format. This may useful for storing user features. Note: Proper JSON encoding must be used to include “escaped” quotation marks.
`geo`	optional	object	–	Home geo for the user (e.g., based off of registration data); this is different from the current location of the access device (that is defined by the geo object embedded in the Device Object); see Device Object.
`data`	optional	array of objects	–	See Data Object.
`ext`	optional	object	–	This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Object User.ext

Field	Scope	Type	Default	Description
`consent`	optional	string	–	It contains the data structure developed by the GDPR Consent Working Group under the auspices of IAB Europe.

Data Object

Field	Scope	Type	Default	Description
`id`	optional	string	–	Exchange specific ID for the data provider.
`name`	optional	string	–	Data provider name.
`segment`	optional	array of objects	–	The array of segment objects.
`ext`	optional	object	–	This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Segment Object

Field	Scope	Type	Default	Description
`id`	optional	string	–	The ID of a data provider’s segment applicable to the user.
`name`	optional	string	–	Name of a data provider’s segment applicable to the user.
`value`	optional	string	–	A string representing the value of the segment. The method for transmitting this data should be negotiated offline with the data provider. For example: for gender, “male”, or “female”, for age, “30-‐40”).
`ext`	optional	object	–	This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Regulations Object

Field	Scope	Type	Default	Description
`coppa`	optional	integer	–	Flag indicating whether or not this request falls under the COPPA regulations established by the USA FTC, where 0 = no, 1 = yes.
`ext`	optional	object	–	This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Object: Regs.ext

Field	Scope	Type	Default	Description
`gdpr`	optional	integer	–	Signaled whether or not the request is subject to GDPR via the extension attribute “gdpr” which is an optional integer that indicates: 0 = No, 1 = Yes.

PMP Object

Field	Scope	Type	Default	Description
private_auction	optional	integer	–	An integer flag indicating that this impression is a private auction eligible only to seats named in the Direct Deals object. (e.g., 1 = bids for this impression are restricted to the deals specified and the terms thereof; 0 = all bids are accepted).
deals	optional	array of objects	–	A collection of “deal” objects encapsulating a list of direct deals eligible for this impression.
ext	optional	object	–	This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Direct Deals Object

Field	Scope	Type	Default	Description
id	required	string	–	A unique identifier for the direct deal.
bidfloor	optional	float	0	Bid floor for this impression (in CPM of bidfloorcur).
bidfloorcur	optional	string	USD	If the bid floor is specified and multiple currencies supported per bid request, then the currency should be specified here using ISO--4217 alphabetic codes. Note, this may be different from bid currency returned by the bidder, if this is allowed on an exchange.
wseat	optional	array of strings	–	The array of buyer seats allowed to bid on this Direct Deal. Seats are an optional feature of exchange. For example, [“4”,”34”,”82”,”45”] indicates that only advertisers using these exchange seats are allowed to bid on this direct deal.
wadomain	optional	array of strings	–	The array of advertiser domains allowed to bid on this Direct Deal. For example, [“advertiser1.com”,”advertiser2.com”] indicates that only the listed advertisers are allowed to bid on this direct deal.
at	optional	integer	–	Auction type. If “1”, the first price auction. If “2”, the second price auction. If “3”, the passed bid floor indicates the apriori agreed upon deal price. Additional auction types can be defined as per the exchange’s business rules.
ext	optional	object	–	This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Bid Response Object

Field	Scope	Type	Default	Description
id	required	string	–	The ID of the bid request.
seatbid	optional	array of objects	–	The array of seat bid objects.
bidid	optional	string	–	Bid response ID to assist tracking for bidders. This value is chosen by the bidder for cross-‐reference.
cur	optional	string	–	Bid currency using ISO-‐4217 alphabetic codes; default is “USD”.
customdata	optional	string	–	This is an optional feature, which allows a bidder to set data in the exchange’s cookie. The string may be in base85 cookie safe characters and be in any format. This may be useful for storing user features. Note: Proper JSON encoding must be used to include “escaped” quotation marks.
nbr	optional	integer	–	Reason for not bidding. See NoBid Reason Codes.
ext	optional	object	–	This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Seat Bid Object

Field	Scope	Type	Default	Description
bid	required	array of objects	–	The array of bid objects; each bid object relates to an imp object in the bid request. Note that, if supported by an exchange, one imp object can have many bid objects.
seat	optional	string	–	ID of the bidder seat on whose behalf this bid is made.
group	optional	integer	–	“1” means impressions must be won--lost as a group; default is “0”.
ext	optional	object	–	This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Bid Object

Field	Scope	Type	Default	Description
id	required	string	–	ID for the bid object chosen by the bidder for tracking and debugging purposes. Useful when multiple bids are submitted for a single impression for a given seat.
impid	required	string	–	The ID of the impression object to which this bid applies.
price	required	float	–	Bid price in CPM. WARNING/Best Practice Note: Although this value is a float, OpenRTB strongly suggests using integer math for accounting to avoid rounding errors.
adid	optional	string	–	The ID that references the ad to be served if the bid wins.
nurl	optional	string	–	Win notice URL. Note that ad markup is also typically, but not necessarily, returned via this URL.
adm	optional	string	–	Actual ad markup. XHTML if a response to a banner object, or VAST XML if a response to a video object.
adomain	optional	array of strings	–	Advertiser’s primary or top-‐level domain for advertiser checking. This can be a list of domains if there is a rotating creative. However, exchanges may mandate that only one landing domain is allowed.
Iurl	optional	string	–	Sample image URL (without cache busting) for content checking.
cid	optional	string	–	Campaign ID or similar that appears within the ad markup.
crid	optional	string	–	Creative ID for reporting content issues or defects. This could also be used as a reference to a creative ID that is posted with an exchange.
attr	optional	array of integers	–	Array of creative attributes. See Table 6.3 Creative Attributes.
dealid	optional	string	–	A unique identifier for the direct deal associated with the bid. If the bid is associated and in response to a dealid in the request object it is required in the response object.
h	optional		–	Height of the ad in pixels. If the bid request contained the wmax/hmax and wmin/hmin optional fields it is recommended that the response bid contains this field to signal the size of the ad chosen.
w	optional		–	Width of the ad in pixels. If the bid request contained the wmax/hmax and wmin/hmin optional fields it is recommended that the response bid contains this field to signal the size of ad chosen.
ext	optional	object	–	This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Reference Lists/Enumerations

Content Categories

See IAB Content Taxonomy and IAB, Apple & Android Category Taxonomy

Banner Ad Types

Value	Description
`1`	XHTML text ad. (usually mobile)
`2`	XHTML banner ad. (usually mobile)
`3`	JavaScript ad; must be valid XHTML (i.e., script tags included).
`4`	Iframe

Creative Attributes

Value	Description
`1`	Audio Ad (Auto Play)
`2`	Audio Ad (User Initiated)
`3`	Expandable (Automatic)
`4`	Expandable (User Initiated -‐ Click)
`5`	Expandable (User Initiated -‐ Rollover)
`6`	In‐Banner Video Ad (Auto Play)
`7`	In‐Banner Video Ad (User Initiated)
`8`	Pop (e.g., Over, Under, or upon Exit)
`9`	Provocative or Suggestive Imagery
`10`	Shaky, Flashing, Flickering, Extreme Animation, Smileys
`11`	Surveys
`12`	Text Only
`13`	User Interactive (e.g., Embedded Games)
`14`	Windows Dialog or Alert Style
`15`	Has audio on/off button
`16`	Ad can be skipped (e.g., skip button on preroll video)

API Frameworks

Value	Description
`1`	VPAID 1.0
`2`	VPAID 2.0
`3`	MRAID-‐1
`4`	ORMMA
`5`	MRAID-2
`6`	MRAID-3
`7`	OMID-1

Ad Position

Value	Description
`0`	Unknown
`1`	Above the fold
`<del>2</del>`	DEPRECATED / May or may not be immediately visible depending on screen size and resolution.
`3`	Below the fold
`4`	Header
`5`	Footer
`6`	Sidebar
`7`	Fullscreen

Video Linearity

Value	Description
`1`	Linear/In-‐stream
`2`	Non-‐Linear/Overlay

Video Bid Response Protocols

Value	Description
`1`	VAST 1.0
`2`	VAST 2.0
`3`	VAST 3.0
`4`	VAST 1.0 Wrapper
`5`	VAST 2.0 Wrapper
`6`	VAST 3.0 Wrapper

Video Playback Methods

Value	Description
`1`	Auto-‐play sound on
`2`	Auto-‐play sound off
`3`	Click-‐to-‐play
`4`	Mouse-‐over

Video Start Delay

Value	Description
`0`	Pre-‐roll
`-1`	Generic mid-‐roll
`-2`	Generic Post-‐roll

Expandable Direction

Value	Description
`1`	Left
`2`	Right
`3`	Up
`4`	Down
`5`	Fullscreen

Content Delivery Methods

Value	Description
`1`	Streaming
`2`	Progressive

Content Context

Value	Description
`1`	Video (a video file or stream that is being watched by the user, including (Internet) television broadcasts)
`2`	Game (an interactive software game that is being played by the user)
`3`	Music (an audio file or stream that is being listened to by the user, including (Internet) radio broadcasts)
`4`	Application (an interactive software application that is being used by the user)
`5`	Text (a document that is primarily textual in nature that is being read or viewed by the user, including web page, ebook, or news article)
`6`	Other (content type unknown or the user is consuming content which does not fit into one of the categories above)
`7`	Unknown

Video Quality

Value	Description
`0`	Unknown
`1`	Professionally Produced
`2`	Prosumer
`3`	User-Generated (UGC)

Location Type

Value	Description
`1`	GPS/Location Services
`2`	IP Address
`3`	User provided (e.g., registration data)

Device Type

Value	Description
`1`	Mobile/Tablet
`2`	Personal Computer
`3`	Connected TV
`4`	Phone
`5`	Tablet
`6`	Connected Device
`7`	Set Top Box

VAST Companion Types

Value	Description
`1`	Static Resource
`2`	HTML Resource
`3`	iframe Resource

QAG Media Ratings

Value	Description
`1`	All Audiences
`2`	Everyone over 12
`3`	Mature Audience

NoBid Reason Codes

Value	Description
`0`	Unknown Error
`1`	Technical Error
`2`	Invalid Request
`3`	Known Web spider
`4`	Suspected Non-‐Human Traffic
`5`	Cloud, Datacenter, or Proxy IP
`6`	Unsupported Device
`7`	Blocked Publisher or Site
`8`	Unmatched user

Last Modified: August 31, 2023 at 11:54 am