OpenRTB 2.6
- Objects
- 38
- Fields
- 417
- Enum references
- 55
- Deprecated fields
- 12
Bid Request object model
Bid Response object model
seatbid 1..*
cur · nbr (No-Bid reason) · bidid
Request-side objects associated by ID reference (not composed)
BidRequest · Response to this Request (id)
Imp · Bid for this Impression (bid.impid)
Deal · Bid under the terms of this Deal (bid.dealid)
Auction core
Request-level information and deal rules- BidRequest§3.2.124 fields2 required1 enumsThe top-level bid request object contains an exchange unique bid request or auction ID. This
idattribute is required as is at least one impression object (Section 3.2.4). Other attributes in this top-level object establish rules and restrictions that apply to all impressions being offered. There are also several subordinate objects that provide detailed data to potential buyers. Among these are theSite,AppandDOOHobjects, which describe the type of published media in which the impression(s) appear. These objects are highly recommended, but only one applies to a given bid request depending on whether the media is browser-based web content, a non-browser application, or Digital Out of Home inventory respectively. - Source§3.2.25 fieldsThis object describes the nature and behavior of the entity that is the source of the bid request upstream from the exchange. The primary purpose of this object is to define post-auction or upstream decisioning when the exchange itself does not control the final decision. A common example of this is header bidding, but it can also apply to upstream server entities such as another RTB exchange, a mediation platform, or an ad server combines direct campaigns with 3rd party demand in decisioning.
- Regs§3.2.36 fieldsThis object contains any legal, governmental, or industry regulations that the sender deems applicable to the request. See Section 7.5 for more details on the flags supporting Coppa, GDPR and others.
Ad slots & media formats
Impression plus Banner / Video / Audio / Native format definitions and deal terms- Imp§3.2.423 fields1 requiredThis object describes an ad placement or impression being auctioned. A single bid request can include multiple
Impobjects, a use case for which might be an exchange that supports selling all ad positions on a given page. EachImpobject has a required ID so that bids can reference them individually. The presence ofBanner(Section 3.2.6),Video(Section 3.2.7), and/orNative(Section 3.2.9) objects subordinate to theImpobject indicates the type of impression being offered. The publisher can choose one such type which is the typical case or mix them at their discretion. However, any given bid for the impression must conform to one of the offered type. - Metric§3.2.54 fields2 requiredThis object is associated with an impression as an array of metrics. These metrics can offer insight into the impression to assist with decisioning such as average recent viewability, click-through rate, etc. Each metric is identified by its type, reports the value of the metric, and optionally identifies the source or vendor measuring the value.
- Banner§3.2.613 fields4 enumsThis object represents the most general type of impression. Although the term “banner” may have very specific meaning in other contexts, here it can be many things including a simple static image, an expandable ad unit, or even in-banner video (refer to the
Videoobject in Section 3.2.7 for the more generalized and full featured video ad units). An array ofBannerobjects can also appear within theVideoto describe optional companion ads defined in the VAST specification. The presence of aBanneras a subordinate of theImpobject indicates that this impression is offered as a banner type impression. At the publisher’s discretion, that same impression may also be offered as video, audio, and/or native by also including asImpsubordinates objects of those types. However, any given bid for the impression must conform to one of the offered types. - Video§3.2.736 fields1 required14 enums2 deprecatedThis object represents a video impression. Many of the fields are non-essential for minimally viable transactions, but are included to offer fine control when needed. Video in OpenRTB generally assumes compliance with the VAST standard. As such, the notion of companion ads is supported by optionally including an array of
Bannerobjects (refer to theBannerobject in Section 3.2.6) that define these companion ads. The presence of aVideoas a subordinate of theImpobject indicates that this impression is offered as a video type impression. At the publisher’s discretion, that same impression may also be offered asBanner,Audio, and/orNativeby also including asImpsubordinates objects of those types. However, any given bid for the impression must conform to one of the offered types. - Audio§3.2.826 fields1 required10 enums1 deprecatedThis object represents an audio type impression. Many of the fields are non-essential for minimally viable transactions, but are included to offer fine control when needed. Audio in OpenRTB generally assumes compliance with the VAST standard. As such, the notion of companion ads is supported by optionally including an array of
Bannerobjects (refer to theBannerobject in Section 3.2.6) that define these companion ads. The presence of aAudioas a subordinate of theImpobject indicates that this impression is offered as an audio type impression. At the publisher’s discretion, that same impression may also be offered asBanner,Video, and/orNativeby also including asImpsubordinates objects of those types. However, any given bid for the impression must conform to one of the offered types. - Native§3.2.95 fields1 required2 enumsThis object represents a native type impression. Native ad units are intended to blend seamlessly into the surrounding content (e.g., a sponsored Twitter or Facebook post). As such, the response must be well-structured to afford the publisher fine-grained control over rendering. The Native Subcommittee has developed a companion specification to OpenRTB called the Dynamic Native Ads API. It defines the request parameters and response markup structure of native ad units. This object provides the means of transporting request parameters as an opaque string so that the specific parameters can evolve separately under the auspices of the Dynamic Native Ads API. Similarly, the ad markup served will be structured according to that specification. The presence of a
Nativeas a subordinate of theImpobject indicates that this impression is offered as a native type impression. At the publisher’s discretion, that same impression may also be offered asBanner,Video, and/orAudioby also including asImpsubordinates objects of those types. However, any given bid for the impression must conform to one of the offered types. - Format§3.2.106 fieldsThis object represents an allowed size (i.e., height and width combination) or Flex Ad parameters for a banner impression. These are typically used in an array where multiple sizes are permitted. It is recommended that either the
w/hpair or thewratio/hratio/wminset (i.e., for Flex Ads) be specified. - Pmp§3.2.113 fieldsThis object is the private marketplace container for direct deals between buyers and sellers that may pertain to this impression. The actual deals are represented as a collection of
Dealobjects. Refer to Section 7.3 for more details. - Deal§3.2.1210 fields1 requiredThis object constitutes a specific deal that was struck between a buyer and a seller. Its presence with the
Pmpcollection indicates that this impression is available under the terms of that deal. Refer to Section 7.3 for more details. - Qty§3.2.314 fields2 required1 enumsA programmatic impression is often referred to as a ‘spot’ in digital out-of-home and CTV, with an impression being a unique member of the audience viewing it. Therefore, a standard means of passing a multiplier in the bid request, representing the total quantity of impressions, is required. This object includes the impression multiplier, and describes the source of the multiplier value.
- DOOH§3.2.329 fields1 enumsThis object should be included if the ad supported content is a Digital Out-Of-Home screen. A bid request with a DOOH object must not contain a site or app object. At a minimum, it is useful to provide id and/or venuetypeid, but this is not strictly required.
- Refresh§3.2.333 fields
- RefSettings§3.2.343 fields1 enumsInformation on how often and what triggers an ad slot being refreshed.
- DurFloors§3.2.354 fieldsThis object allows sellers to specify price floors for video and audio creatives, whose price varies based on time. For example: 1-15 seconds at a floor of $5; 16-30 seconds at a floor of $10, > 31 seconds at a floor of $20. There are no explicit constraints on the defined ranges, nor guarantees that they don't overlap. In cases where multiple ranges may apply, it is up to the buyer and seller to coordinate on which floor is applicable. See [Section 7.11 of Implementation Guidance](implementation.md#floors) for additional notes regarding the use of these fields.
Media context
Site / App containers, content and publishers- Site§3.2.1318 fields1 enumsThis object should be included if the ad supported content is a website as opposed to a non-browser application or Digital Out of Home (DOOH) inventory. A bid request must not contain more than one of a
Site,ApporDOOHobject. At a minimum, it is useful to provide a site ID or page URL, but this is not strictly required. - App§3.2.1418 fields1 enumsThis object should be included if the ad supported content is a non-browser application (typically in mobile) as opposed to a website. A bid request must not contain more than one of a
Site,ApporDOOHobject. At a minimum, it is useful to provide an App ID or bundle, but this is not strictly required. - Publisher§3.2.156 fields1 enumsThis object describes the entity who directly supplies inventory to and is paid by the exchange. This may be a publisher, intermediary exchange, ad network, etc.
- Content§3.2.1634 fields5 enumsThis object describes the content in which the impression will appear, which may be syndicated or non-syndicated content. This object may be useful when syndicated content contains impressions and does not necessarily match the publisher’s general content. The exchange might or might not have knowledge of the page where the content is running, because of the syndication method. For example, might be a video impression embedded in an iframe on an unknown web property or device.
- Producer§3.2.176 fields1 enumsThis object defines the producer of the content in which the ad will be shown. This is particularly useful when the content is syndicated and may be distributed through different publishers and thus when the producer and publisher are not necessarily the same entity.
Device & user
Device, geo, user and audience segments- Device§3.2.1833 fields2 enums6 deprecatedThis object provides information pertaining to the device through which the user is interacting. Device information includes its hardware, platform, location, and carrier data. The device can refer to a mobile handset, a desktop computer, set top box, or other digital device.
- Geo§3.2.1914 fields2 enumsThis object encapsulates various methods for specifying a geographic location. When subordinate to a
Deviceobject, it indicates the location of the device which can also be interpreted as the user’s current location. When subordinate to aUserobject, it indicates the location of the user’s home base (i.e., not necessarily their current location). Thelat/lonattributes should only be passed if they conform to the accuracy depicted in thetypeattribute. For example, the centroid of a geographic region such as postal code should not be passed. - User§3.2.2012 fields2 deprecatedThis object contains information known or derived about the human user of the device (i.e., the audience for advertising). The user
idis an exchange artifact and may be subject to rotation or other privacy policies. However, when present, this user ID should be stable long enough to serve reasonably as the basis for frequency capping and retargeting. - Data§3.2.215 fieldsThe data and segment objects together allow additional data about the related object (e.g., user, content) to be specified. This data may be from multiple sources whether from the exchange itself or third parties as specified by the
idfield. A bid request can mix data objects from multiple providers. The specific data providers in use should be published by the exchange a priori to its bidders. - Segment§3.2.224 fieldsSegment objects are essentially key-value pairs that convey specific units of data. The parent
Dataobject is a collection of such values from a given data provider. The specific segment names and value options must be published by the exchange a priori to its bidders. - UserAgent§3.2.298 fields1 enumsStructured user agent information, which can be used when a client supports User-Agent Client Hints. If both
device.uaanddevice.suaare present in the bid request,device.suashould be considered the more accurate representation of the device attributes. This is because thedevice.uamay contain a frozen or reduced user agent string due to deprecation of user agent strings by browsers. - BrandVersion§3.2.303 fields1 requiredFurther identification based on User-Agent Client Hints, the
BrandVersionobject is used to identify a device’s browser or similar software component, and the user agent’s execution platform or operating system.
Distribution channels
Network and channel identifiers for ad distribution- Network§3.2.234 fieldsThis object describes the network an ad will be displayed on. A Network is defined as the parent entity of the
Channelobject’s entity for the purposes of organizing Channels. Examples are companies that own and/or license a collection of content channels (Viacom, Discovery, CBS, WarnerMedia, Turner and others), or studio that creates such content and self-distributes content. Name is a human-readable field while domain and id can be used for reporting and targeting purposes. See 7.6 for further examples. - Channel§3.2.244 fieldsThis object describes the channel an ad will be displayed on. A Channel is defined as the entity that curates a content library, or stream within a brand name for viewers. Examples are specific view selectable ‘channels’ within linear and streaming television (MTV, HGTV, CNN, BBC One, etc) or a specific stream of audio content commonly called ‘stations.’ Name is a human-readable field while domain and id can be used for reporting and targeting purposes. See 7.6 for further examples.
Identity & supply chain
Extended IDs and the payment path (schain)- EID§3.2.276 fields1 enumsExtended identifiers support in the OpenRTB specification allows buyers to use audience data in real-time bidding. This object can contain one or more UIDs from a single source or a technology provider. The exchange should ensure that business agreements allow for the sending of this data. See [Section 7.12 of Implementation Guidance](implementation.md#idmm) for additional notes regarding the use of these fields.
- UID§3.2.283 fields1 enumsThis object contains a single user identifier provided as part of extended identifiers. The exchange should ensure that business agreements allow for the sending of this data.
- SupplyChain§3.2.254 fields3 requiredThis object is composed of a set of nodes where each node represents a specific entity that participates in the transacting of inventory. The entire chain of nodes from beginning to end represents all entities who are involved in the direct flow of payment for inventory. Detailed implementation examples can be found here: https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/supplychainobject.md
- SupplyChainNode§3.2.267 fields2 requiredThis object is associated with a
SupplyChainobject as an array of nodes. These nodes define the identity of an entity participating in the supply chain of a bid request. Detailed implementation examples can be found here: https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/supplychainobject.md. TheSupplyChainNodeobject contains the following attributes:
Bid response
Bid Response side objects- BidResponse§4.2.17 fields1 requiredThis object is the top-level bid response object (i.e., the unnamed outer JSON object). The
idattribute reflects the bid request ID for logging purposes. Similarly,bididis an optional response tracking ID for bidders. If specified, it can be included in the subsequent win notice call if the bidder wins. At least oneseatbidobject is required, which contains at least one bid for an impression. Other attributes are optional. To express a “no-bid”, the options are to return an empty response with HTTP 204. Alternately if the bidder wishes to convey to the exchange a reason for not bidding, just aBidResponseobject is returned with a reason code in thenbrattribute. - SeatBid§4.2.24 fields1 requiredA bid response can contain multiple
SeatBidobjects, each on behalf of a different bidder seat and each containing one or more individual bids. If multiple impressions are presented in the request, thegroupattribute can be used to specify if a seat is willing to accept any impressions that it can win (default) or if it is only interested in winning any if it can win them all as a group. - Bid§4.2.333 fields3 required5 enums1 deprecatedA
SeatBidobject contains one or moreBidobjects, each of which relates to a specific impression in the bid request via theimpidattribute and constitutes an offer to buy that impression for a givenprice.