OpenRTB 2.5 Specifications

Home » Marketer Documentation » OpenRTB 2.5 Specifications

3.2 Object Specification

The subsections that follow define each of the objects in the bid request model. Several conventions are used throughout:

• Attributes are “required” if their omission would technically break the protocol.
• Some optional attributes are denoted “recommended” due to their elevated business importance.
• Unless a default value is explicitly specified, an omitted attribute is interpreted as “unknown”.

3.2.1 Object: BidRequest

The 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 – IAB OpenRTB 2.5).

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.

3.2.2 Object: Source

This 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 decisioning.

3.2.3 Object: Regs

This 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”).

3.2.4 Object: Imp

This 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.

3.2.5 Object: Metric

This 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.

3.2.6 Object: Banner

This object represents the most general type of impression. Although the term “banner” may have a 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.

3.2.7 Object: Video

This 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.

3.2.8 Object: Audio

This 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 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.

3.2.9 Object: Native

This object represents a native type impression. Native ad units are intended to blend seamlessly into the surrounding content. 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.

3.2.10 Object: Format

3.2.11 Object: Pmp

This 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.

3.2.12 Object: Deal

This 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.

3.2.13 Object: Site

This 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.

3.2.14 Object: App

This 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.

3.2.15 Object: Publisher

This object describes the publisher of the media in which the ad will be displayed. The publisher is typically the seller in an OpenRTB transaction.

3.2.16 Object: Content

This 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, there might be a video impression embedded in an iframe on an unknown web property or device.

3.2.17 Object: Producer

This 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.

3.2.18 Object: Device

This 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 another digital device.

3.2.19 Object: Geo

This 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.

3.2.20 Object: User

This 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.

3.2.21 Object: Data

The 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 id field. 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.

3.2.22 Object: Segment

Segment objects are essentially key-value pairs that convey specific units of data. The parent Data object 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.

Extension Objects

Object: ImpressionExtension

Object: BannerExtension

Object: NativeExtension

Object: VideoExtension

Object: RegsExtension

Object: UserExtension

The user consent string is optional but highly recommended if the request is subject to GDPR regulations.

4. Bid Response Specifications

RTB responses contain bids that reference specific impressions within a bid request. Bids are in essence an offer to buy. The bid response consists of the top-level bid response object and optional objects that depict the specific bids. An empty HTTP response constitutes a no-bid and is, in fact, the most bandwidth friendly form of this signal although returning a response with a “no-bid reason” is encouraged. A malformed response or a response that contains no actual bids will also be interpreted as no-bid.

4.1 Object Model

Following is the object model for the bid response. The top-level object (i.e., in JSON the unnamed outer object) is denoted as BidResponse in the model. A bid response may contain bids from multiple “seats” (i.e., the buying entity upstream from the actual bidder). In fact, a response may contain multiple bids from the same seat; typically but not necessarily from different campaigns. This can improve the seat’s chances of winning since most exchanges enforce various block lists on behalf of their publishers.

Referring to the figure, the actual response objects are shown on the left, specifically the BidResponse top level object the seat specific SeatBid collections of Bid objects. The other objects shown are those objects from the bid request to which response objects related. Specifically, BidResponse includes the BidRequest ID for positive tracking purposes, and since a request can include multiple impressions Bid includes the ID of the Imp for which the bid is an offer to purchase. If a bid is made under the terms of a private marketplace deal, the Bid also includes the ID of the specific Deal object.

Not shown in the model figure is an extensions object. This is an object of undefined structure that can be added to any other object to convey bidder-specific extensions to the standard. Bidders using these objects are responsible for publishing their extensions to their exchanges.

4.2 Object Specifications

The subsections that follow define each of the objects in the bid response model. Several conventions are used throughout:

• Attributes are “required” if their omission would technically break the protocol.
• Some optional attributes are denoted “recommended” due to their elevated business importance.
• Unless a default value is explicitly specified, an omitted attribute is interpreted as “unknown”.

4.2.1 Object: Bid Response

This 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.

4.2.2 Object: Seat Bid

A bid response can contain multiple SeatBid objects, each on behalf of a different bidder seat and each containing one or more individual bids. If multiple impressions are presented in the request, the group attribute 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.

4.2.3 Object: Bid

A 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.

"ext": {
    "advertiserName": "nameOfAdvertiser",
    "agencyName": "nameOfAgency",
    "agencyId": "idOfAgency"
}

4.3 Ad Serving Options

The fulfillment of an RTB transaction within the scope of this OpenRTB specification lies in the delivery of markup. Depending on the impression and other ad type constraints, this markup can be XHTML, HTML5, XHTML or HTML5 with embedded JavaScript, a VAST document for video, a Native ad unit structure, and potentially other formats in the future.

The OpenRTB specification does not require any processing of the ad markup by the exchange other than macro substitution (refer to Section 4.4) and delivery to the supply-side. There are, however, multiple standard methods for transferring markup from the bidder to the exchange. The method used is at the discretion of the bidder, but an OpenRTB compliant exchange is expected to support all methods as defined in the subsections that follow.

Further details about Section 4.3 & 4.4 can be found in the IAB OpenRTB 2.5 Specifications.

Ad Served on the Win Notice

• • Reduced Bandwidth Costs: Serving ad markup only upon winning can save large amounts of bandwidth usage, the costs for which can be large at high volumes or when sending multiple bids per bid response.
  • Additional Bidder Flexibility: Bidders may typically know the ad they will serve at the time of bid, but this provides an additional optional decision point after the clearing price has been established.

Ad Served in the Bid

• • Reduced Risk of Forfeiture: A forfeit is the scenario in which a bidder wins, but forfeits due to failure to serve the ad markup. The risk of an additional HTTP failure (e.g., calling the win notice) is mitigated by this method.
  • Potential Concurrency: The exchange can choose to return that ad markup and call the win notice concurrently, thereby improving user experience.

5.0 Enumerated Lists Specification

All reference lists are actively maintained by the IAB on the OpenRTB website. As such, implementers should ensure they are working from the latest lists and enumerations.

5.1 Content Categories

Standard IDs have been adopted to easily support the communication of primary and secondary categories for various objects. This OpenRTB table has values derived from the IAB Tech Lab Content Taxonomy. To view the IAB Tech Lab Content Taxonomy, please view the Smaato Taxonomy page.

5.2 Banner Ad Types

The following table indicates the types of ads that can be accepted by the exchange unless restricted by publisher site settings.

5.3 Creative Attributes

The following table specifies a standard list of creative attributes that can describe an ad being served or serve as restrictions of thereof.

5.4 Ad Position

The following table specifies the position of the ad as a relative measure of visibility or prominence. This OpenRTB table has values derived from the Inventory Quality Guidelines (IQG). Practitioners should keep in sync with updates to the IQG values as published on IAB.com. Values “4” – “7” apply to apps per the mobile addendum to IQG version 2.1

5.5 Expandable Direction

The following table lists the directions in which an expandable ad may expand, given the positioning of the ad unit on the page and constraints imposed by the content.

5.6 API Frameworks

The following table is a list of API frameworks supported by the publisher.

5.7 Video Linearity

The following table indicates the options for video linearity. “In-stream” or “linear” video refers to preroll, post-roll, or mid-roll video ads where the user is forced to watch ad in order to see the video content. “Overlay” or “non-linear” refer to ads that are shown on top of the video content.

This OpenRTB table has values derived from the Inventory Quality Guidelines (IQG). Practitioners should keep in sync with updates to the IQG values.

5.8 Protocols: Video Bid Response

The following table lists the options for the various bid response protocols that could be supported by an exchange.

5.9 Video Placement Types

The following table lists the various types of video placements derived largely from the IAB Digital Video Guidelines.

5.10 Video Playback Methods

The following table lists the various playback methods.

5.12 Video Start Delay

The following table lists the various options for the video or audio start delay. If the start delay value is greater than 0, then the position is mid-roll and the value indicates the start delay.

5.13 Production Quality

The following table lists the options for content quality. These values are defined by the IAB; refer to www.iab.com/wp-content/uploads/2015/03/long-form-video-final.pdf for more information.

5.14 VAST Companion Types

The following table lists the options to indicate markup types allowed for companion ads that apply to video and audio ads. This table is derived from VAST 2.0+ and DAAST 1.0 specifications. Refer to www.iab.com/guidelines/digital-video-suite for more information.

5.15 Content Delivery Methods

The following table lists the various options for the delivery of video or audio content.

5.17 IQG Media Ratings

5.18 Content Context

The following table lists the various options for indicating the type of content being used or consumed by the user in which the impression will appear. This OpenRTB table has values derived from the Inventory Quality Guidelines (IQG). Practitioners should keep in sync with updates to the IQG values.

5.20 Location Type

The following table lists the options to indicate how the geographic information was determined.

5.21 Device Type

The following table lists the type of device from which the impression originated.

OpenRTB version 2.2 of the specification added distinct values for Mobile and Tablet. It is recommended that any bidder adding support for 2.2 treat a value of 1 as an acceptable alias of 4 & 5.

This OpenRTB table has values derived from the Inventory Quality Guidelines (IQG). Practitioners should
keep in sync with updates to the IQG values.

5.22 Connection Type

The following table lists the various options for the type of device connectivity

5.23 IP Location Service

5.24 NoBid  Reason Codes

The following table lists the options for a bidder to signal the exchange as to why it did not offer a bid for the impression.

Native API Version 1.1 Documentation

Request

context

plcmttype

plcmtcnt

seq

assets

Assets

*Each asset object may contain only one of title, image, data or video.

Title Object

Image Object

Data Object

Example of Native ad request

{
    "ver": "1.1",
    "context": 1,
    "plcmttype": 1,
    "plcmtcnt": 1,
    "seq": 0,
    "assets": [
        {
            "id": 1,
            "required": 1,
            "title": {
                "len": 140
            }
        },
        {
            "id": 2,
            "required": 1,
            "image": {
                "type": 3,
                "wmin": 200,
                "hmin": 200
            }
        },
        {
            "id": 3,
            "required": 1,
            "image": {
                "type": 1,
                "wmin": 50,
                "hmin": 50
            }
        },
        {
            "id": 4,
            "required": 1,
            "data": {
                "type": 2
            }
        },
        {
            "id": 5,
            "required": 1,
            "data": {
                "type": 12
            }
        }
    ]
}

Reference Lists/Enumerations

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