OpenRTB 2.5
- Objects
- 25
- Fields
- 298
- Enum references
- 35
- Deprecated fields
- 6
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.120 fields2 requiredThe top-level bid request object contains a globally unique bid request or auction ID. This id attribute 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 the Site and App objects, 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 or a non-browser application, respectively.
- Source§3.2.24 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.32 fieldsThis object contains any legal, governmental, or industry regulations that apply to the request. The coppa flag signals whether or not the request falls under the United States Federal Trade Commission's regulations for the United States Children's Online Privacy Protection Act ("COPPA").
Ad slots & media formats
Impression plus Banner / Video / Audio / Native format definitions and deal terms- Imp§3.2.418 fields1 requiredThis object describes an ad placement or impression being auctioned. A single bid request can include multiple Imp objects, a use case for which might be an exchange that supports selling all ad positions on a given page. Each Imp object has a required ID so that bids can reference them individually. The presence of Banner (Section 3.2.6), Video (Section 3.2.7), and/or Native (Section 3.2.9) objects subordinate to the Imp object 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 types.
- 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.617 fields4 enums4 deprecatedThis 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 Video object in Section 3.2.7 for the more generalized and full featured video ad units). An array of Banner objects can also appear within the Video to describe optional companion ads defined in the VAST specification. The presence of a Banner as a subordinate of the Imp object 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 as Imp subordinates objects of those types. However, any given bid for the impression must conform to one of the offered types.
- Video§3.2.727 fields1 required11 enums1 deprecatedThis object represents an in-stream 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 Banner objects (refer to the Banner object in Section 3.2.6) that define these companion ads. The presence of a Video as a subordinate of the Imp object indicates that this impression is offered as a video type impression. At the publisher's discretion, that same impression may also be offered as banner, audio, and/or native by also including as Imp subordinates objects of those types. However, any given bid for the impression must conform to one of the offered types.
- Audio§3.2.819 fields1 required8 enumsThis 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 DAAST standard. As such, the notion of companion ads is supported by optionally including an array of Banner objects (refer to the Banner object in Section 3.2.6) that define these companion ads. The presence of a Audio as a subordinate of the Imp object indicates that this impression is offered as an audio type impression. At the publisher's discretion, that same impression may also be offered as banner, video, and/or native by also including as Imp subordinates 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 Native as a subordinate of the Imp object indicates that this impression is offered as a native type impression. At the publisher's discretion, that same impression may also be offered as banner, video, and/or audio by also including as Imp subordinates 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/h pair or the wratio/hratio/wmin set (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 Deal objects. Refer to Section 7.3 for more details.
- Deal§3.2.127 fields1 requiredThis object constitutes a specific deal that was struck a priori between a buyer and a seller. Its presence with the Pmp collection indicates that this impression is available under the terms of that deal. Refer to Section 7.3 for more details.
Media context
Site / App containers, content and publishers- Site§3.2.1315 fieldsThis object should be included if the ad supported content is a website as opposed to a non-browser application. A bid request must not contain both a Site and an App object. At a minimum, it is useful to provide a site ID or page URL, but this is not strictly required.
- App§3.2.1415 fieldsThis 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 both an App and a Site object. At a minimum, it is useful to provide an App ID or bundle, but this is not strictly required.
- Publisher§3.2.155 fieldsThis object describes the publisher of the media in which the ad will be displayed. The publisher is typically the seller in an OpenRTB transaction.
- Content§3.2.1626 fields3 enums1 deprecatedThis 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, as a result 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.175 fieldsThis 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.1831 fields2 enumsThis 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 Device object, it indicates the location of the device which can also be interpreted as the user's current location. When subordinate to a User object, it indicates the location of the user's home base (i.e., not necessarily their current location). The lat/lon attributes should only be passed if they conform to the accuracy depicted in the type attribute. For example, the centroid of a geographic region such as postal code should not be passed.
- User§3.2.209 fieldsThis object contains information known or derived about the human user of the device (i.e., the audience for advertising). The user id is an exchange artifact and may be subject to rotation or other privacy policies. However, this user ID must be stable long enough to serve reasonably as the basis for frequency capping and retargeting.
- Data§3.2.214 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.
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 id attribute is a reflection of the bid request ID for logging purposes. Similarly, bidid is 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 one seatbid object 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 a BidResponse object is returned with a reason code in the nbr attribute.
- 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.327 fields3 required3 enumsA SeatBid object contains one or more Bid objects, each of which relates to a specific impression in the bid request via the impid attribute and constitutes an offer to buy that impression for a given price.