OpenRTB Bid Request Objects and Parameters

Document created by pubmatic-archivist on Mar 27, 2017Last modified by catherine.racette on Dec 12, 2017
Version 26Show Document
  • View in full screen mode

OpenRTB 2.3 Documentation Index

OpenRTB 2.3 Introduction 

OpenRTB 2.3 Integration Plan 

OpenRTB Bid Request Objects and Parameters 

OpenRTB Bid Response Objects and Parameters 

OpenRTB Ad Server API Cookie Sync 

OpenRTB 2.3 PubMatic Extensions 

Open RTB 2.3 Examples 

OpenRTB Ad Server API Cookie Sync 

OpenRTB 2.3 Click Tracking 

OpenRTB 2.3 Win/Loss Notification 

OpenRTB 2.3 API Performance 

OpenRTB 2.3 Known Limitations & Reference 

 

PubMatic supports Ad Serving integration using OpenRTB 2.3, as well as a proprietary API. This document provides Bid Request Objects and Parameters for the OpenRTB Ad Serving integration.

Objects and Parameters Supported

Supported objects and parameters are listed in the following table, with mandatory/optional indicators. Requests that do not contain mandatory objects and parameters will be considered invalid. 

Object: BidRequest

                                                                                       

AttributeTypeDescriptionSupportedMandatory
idStringUnique ID of the bid request, provided by the exchange.YesYes
impObject ArrayArray of impression objects representing the impressions offered. At least 1 impression object is required.YesYes
siteObjectDetails via a site object about the publisher's website.YesNo
deviceObject

Details via a device object about the user's device to which the impression will be delivered.

YesYes
userObject

Details via a user object about the human user of the device; the advertising audience.

YesNo
appObject

Details via an App object about the publisher's app (i.e., non-browser applications). Only applicable and recommended for apps.

YesNo
atInteger

Auction Type

Default = 2  

1 = Publisher first price auction

2 = Publisher second price auction

YesYes
curString ArrayArray of allowed currencies for bids on this bid request using ISO-4217 alpha codes.Not supported. Imp[0].bidfloorcur will be considered for all impressions of the requestNo
bcatString ArrayBlocked advertiser categories using the IAB content categories.YesNo
badvString ArrayBlock list of advertisers by their domains (e.g., "ford.com").YesNo
regsObjectA Regs object that specifies any industry, legal, or governmental regulations in force for this request.YesNo
wrapperObjectExtra information about wrapper.YesNo

Object: Wrapper

AttributeTypeDescriptionSupportedMandatory
versionIntegerVersion ID of the WrapperYesNo
profileIntegerProfile ID of the WrapperYesNo

 

Object: Imp

Each impression object can contain any one of video/native/banner object otherwise it will be treated as invalid impression.

                                                                  

AttributeTypeDescriptionSupportedMandatory
idStringA unique identifier for this impression within the context of the bid request (typically, starts with 1 and increments).YesYes
tagidString

Identifier for specific ad placement or ad tag that was used to initiate the auction.
Note:

  • This can be also use as PubMatic ad placement id or ad id. In this case mapping of publisher ad id to PubMatic ad id needs to be maintained by the publisher.
  • Publisher needs to send PubMatic adid here.
  • Can be used as slotname by wrapper/prebid. PubMatic will keep a mapping to derive PubMatic adid from this slotname.
YesNo
bannerObjectA banner object is required if this impression is offered as a banner ad opportunity.YesYes
nativeObjectA Native object; required if this impression is offered as a native ad opportunityYesNo
videoObjectA Video object required if this impression is offered as a video ad opportunity.YesNo
instlInteger1 = the ad is interstitial or full screen, 0 = not interstitial.YesNo
bidfloorFloatMinimum bid for this impression expressed in CPM.YesNo
bidfloorcur StringCurrency specified using ISO-4217 alpha codes.

Imp[0].bidfloorcur will be considered for all impressions of the request.

If not specified - default currency USD will be used.

No

iframebuster

String ArrayArray of exchange-specific names of supported iframe bustersYesNo
secureIntegerFlag to indicate if the impression requires secure HTTPS URL creative assets and markup, where 0 = non-secure, 1 = secure. If omitted, the secure state is unknown, but non-secure HTTP support can be assumed.YesNo
pmpObjectA PMP Object containing any private marketplace deals in effect for this impression.YesNo

 

Object: Imp Extension Object

                 

AttributeTypeDescriptionSupportedMandatory
pmZoneIdStringThis parameter is used to pass zone ID for reporting.YesNo

Object: Banner

                                                    

AttributeTypeDescriptionSupportedMandatory
wIntegerWidth of the impression in pixels.YesYes
hIntegerHeight of the impression in pixels.YesYes
battrInteger ArrayBlocked creative attributes.YesNo
posIntegerAd position on screen.YesNo
topframeIntegerIndicates if the banner is in the top frame as opposed to an iframe, where 0 = no, 1 = yes.YesNo
expdirInteger ArrayDirections in which the banner may expand.YesNo
formatObject ArrayArray of format objects representing the banner sizes permitted. If non are specified, then use of the h and w attributes is highly recommended.YesNo

Object: Format

AttributeTypeDescriptionSupportedMandatory
wIntegerWidth in device independent pixels (DIPS).YesYes
hIntegerHeight in device independent pixels (DIPS).YesYes

 

Object: Video

                                                                                                                                               

AttributeTypeDescriptionSupportedMandatory
protocol (from video object)Not Supp

Video Bid Response protocol. VAST 1.0, VAST 2.0, VAST 3.0, etc. 

NoNo
protocolsIntegerArray of supported video bid response protocols. Refer to List 5.8 in http://www.iab.net/media/file/OpenRTBAPISpecificationVersion2_2.pdf. At least one supported protocol must be specified in either the protocols attribute.YesNo
mimesString ArrayContent MIME types supported for media files. Common video MIME types may include ‰ŰĎvideo/x-flv" and "video/mp4," while "application/x-shockwave-flash" typically applies to VPAID creatives.YesNo
linearityIntegerIndicates if the impression is linear or nonlinear. 1=Linear/In-Stream and 2=Non-Linear/Overlay.YesNo
mindurationIntegerMinimum video ad duration in secondsYesNo
maxdurationIntegerMaximum video ad duration in seconds. Protocol Video bid response protocols supported. (See Table 6.7 in http://www.iab.net/media/file/OpenRTBAPISpecificationVersion2_2.pdfYesNo
apiInteger ArrayAPI frameworks supported (See Table 6.4 in http://www.iab.net/media/file/OpenRTBAPISpecificationVersion2_2.pdf)YesNo
wIntegerWidth of the video player in pixels.YesNo
hIntegerHeight of the video player in pixels.YesNo
startdelayIntegerIndicates the start delay in seconds for pre-roll, mid-roll, or
post-roll ad placements. 
YesNo
maxbitrateIntegerMaximum bit rate in Kbps.YesNo
playbackmethodInteger ArrayDefines whether inventory is user-initiated or autoplay sound on/off. (See Table 6.8 in http://www.iab.net/media/file/OpenRTBAPISpecificationVersion2_2.pdf)YesNo
deliveryInteger ArrayList of supported delivery methods (e.g., streaming, progressive). (See Table 6.12 in http://www.iab.net/media/file/OpenRTBAPISpecificationVersion2_2.pdf) BrightRoll only supports progressive delivery at this time.NoNo
posIntegerAd position on the page. (See Table 6.5 in http://www.iab.net/media/file/OpenRTBAPISpecificationVersion2_2.pdf)YesNo
companiontypeInteger ArrayDescribes the VAST companion resource types supported by the inventory (e.g., static resource, iframe resource, etc.) (See Table 6.17 in http://www.iab.net/media/file/OpenRTBAPISpecificationVersion2_2.pdf)NoNo
companionadObject ArrayCompanion ads are described by the banner objectNoNo
extObjectPlaceholder for exchange-specific extensions to OpenRTBYesNo

   

Object: Video.ext                                                                                    

AttributeTypeDescriptionSupportedMandatory
video_skippableIntegerIndicator for ability to skip video 0/1YesNo

 

Object: PMP    

PubMatic must first enable a publisher-level flag before you can start passing a deal object in the ad request. Pleas contact your account manager to enable this.

AttributeTypeDescriptionSupportedMandatory
dealsObject ArrayArray of Deal objects (Max 50 Deal objects) that convey the specific deals applicable to this impression.YesNo

 

Object: Deal          

The PMP deal ID passed in the ad request must first be set up in the PubMatic platform in advance. A deal-level flag also must be set up in the PubMatic UI to instruct the PubMatic system to ignore the deal unless it is sent in the ad request explicitly. 

AttributeTypeDescriptionSupportedMandatory
idStringA unique identifier for the direct deal. Maximum length of string is 64YesYes

Object: Native

                                             

AttributeTypeDescriptionSupportedMandatory
requestString

Request payload complying with the Native Ad Specification 1.0: http://www.iab.net/media/file/OpenRTB-Native-Ads-Specification-1_0-Final.pdf

YesYes
verStringVersion of the Native Ad Specification to which request complies; highly recommended for efficient parsingYesNo
apiInteger ArrayList of supported API frameworks for this impression. If an API is not explicitly listed, it is assumed not to be supported.NoNo
battrInteger ArrayBlocked creative attributesNoNo
extObjectPlaceholder for exchange-specific extensions to OpenRTBNoNo

NOTE: Refer to OpenRTB-Native-Ads-Specification-1_0-Final.pdf for Native request and response details.

Object: Mobile App

                                                                                                     

AttributeTypeDescriptionSupportedMandatory
idStringMobile applications ID on the exchange.YesNo
nameStringApp name (may be aliased upon request)YesNo
publisherObjectDetails about the PublisherYesNo
bundleStringApplication bundle or package name. Intended to be a unique ID across exchanges.YesNo
domainStringDomain of the app.YesNo
storeurlStringApp store URL for an installed app; for QAG 1.5 compliance.YesNo
catString ArrayArray of IAB content categories of the app. (Refer to List 5.1 in https://www.iab.com/wp-content/uploads/2015/06/OpenRTB-API-Specification-Version-2-3.pdf)YesNo
sectioncatString ArrayArray of IAB content categories that describe the current section of the app. (Refer to List 5.1 in https://www.iab.com/wp-content/uploads/2015/06/OpenRTB-API-Specification-Version-2-3.pdf)NoNo
pagecatString ArrayArray of IAB content categories that describe the current page or view of the app. (Refer to List 5.1 in https://www.iab.com/wp-content/uploads/2015/06/OpenRTB-API-Specification-Version-2-3.pdf)NoNo
verStringApplication versionYesNo
privacypolicyIntegerIndicates if the app has a privacy policy, where 0=no, 1=yesNoNo
paidInteger0=app is free, 1=app is a paid versionYesNo
keywordsStringcomma separated list of keywords about the appNoNo
contentObjectDetails of the content in the app.YesNo

Object: App.ext 

ObjectAttributeTypeDescriptionSupportedMandatory
app.extkey_valString

key-value pair information to be passed to the SSP platform. Each key value pair will be separated by "|" and each value will be separated by ","

eg:- "key_val"="key1=V1,V2,V3|key2=v1|key3=v3,v5"

Yes

No

Object: Content

                 

AttributeTypeDescriptionSupportedMandatory
idStringExchange-specificYesNo

Object: Device

                                                                                                                                                                                                       

AttributeTypeDescriptionSupportedMandatory
uaStringBrowser user agent string.YesNo
dntIntegerStandard "Do Not Track" flag as set in the header by the browser, where 0 = tracking is unrestricted, 1 = do not trackYesNo
lmtInteger"Limit Ad Tracking" signal commercially endorsedNoNo
devicetypeIntegerThe general type of device. Refer to List 5.17 in https://www.iab.com/wp-content/uploads/2015/06/OpenRTB-API-Specification-Version-2-3.pdfYesNo
makeStringDevice make (e.g., "Apple")YesNo
modelStringDevice model (e.g., "iPhone")YesNo
osStringDevice operating system (e.g., "iOS")YesNo
osvStringDevice operating system version (e.g., "3.1.2")YesNo
hwvStringHardware version of the device (e.g., "5S" for iPhone 5S).NoNo
hIntegerPhysical height of the screen in pixels.NoNo
wIntegerPhysical width of the screen in pixels.NoNo
ppiIntegerScreen size as pixels per linear inch.NoNo
pxratiofloatThe ratio of physical pixels to device independent pixels.NoNo
jsIntegerSupport for JavaScript, where 0=no, 1=yes.YesNo
flashverstringVersion of Flash supported by the browser.NoNo
languageStringBrowser language using ISO-639-1-alpha-2.YesNo
geoObjectLocation of the device assumed to be the user's current location defined by a Geo object. This will be given lower priority in respect to user.geo object.YesNo
IpStringIPv4 address closest to device as IPv6. Either of ip/ipv6 is required.YesYes
Ipv6StringIP address closest to device as IPv6. Either of ip/ipv6 is required.YesYes
ifaStringID sanctioned for advertiser use in the clear (i.e., not hashed)YesNo
didsha1StringHardware device ID *e.g., IMEI; hashed via SHA1.YesNo
didmd5StringHardware device ID *e.g., IMEI; hashed via MD5.YesNo
dpidsha1StringPlatform device ID (e.g., Android ID); hashed via SHA1.YesNo
dpidmd5StringPlatform device ID (e.g., Android ID); hashed via MD5.YesNo
macsha1StringMAC address of the device; hashed via SHA1.NoNo
macmd5StringMAC address of the device; hashed via MD5.NoNo

Object: Site

                                                    

AttributeTypeDescriptionSupportedMandatory
idStringExchange-specific site ID.
Note:
  • If this is to be used for multi-site support, this should be the PubMatic site id. In this case, mapping of the publisher site id to PubMatic site id needs to be maintained by publisher.
  • If the publisher is willing to send only the tag id in the request, then the PubMatic site id will be derived from imp[0].tagid. It will be advantageous if the publisher sends both the site id and tag id.
  • If the publisher is not willing to modify the site body, they can send site id in the PubMatic end point URL.
YesNo
catString ArrayArray of IAB content categories of the site.YesNo
pageStringURL of the page where the impression will be shown. ref string Referrer URL that caused navigation to the current page. It must not be encoded.YesNo
refStringReferrer URL that caused navigation to the current page.YesNo
pagecatString ArrayArray of IAB content categories that describe the current page or view of the site.YesNo
publisherObjectDetails about the PublisherYesYes
contentObjectDetails about the content within the site.YesNo

Object: Site.ext 

ObjectAttributeTypeDescriptionSupportedMandatory
site.extkey_valString

key-value pair information to be passed to the SSP platform. Each key value pair will be separated by "|" and each value will be separated by ","

eg:- "key_val"="key1=V1,V2,V3|key2=v1|key3=v3,v5"

Yes

No

Object: Geo

                                                                  

AttributeTypeDescriptionSupportedMandatory
latFloatLatitude from -90.0 to +90.0, where negative is southYesNo
lonFloatLongitude from -180.0 to +180.0, where negative is west.YesNo
typeIntegerSource of location data; recommended when passing lat/lon.YesNo
countryStringCountry code using ISO-3166-1-alpha-3.YesNo
regionStringRegion code using ISO-3166-2; 2-letter state code if USAYesNo
metroStringGoogle metro code; similar to but not exactly Nielsen DMAs.YesNo
cityStringCity using United Nations Code for Trade & Transport Locations. It must not be encoded.YesNo
zipStringZip or postal codeYesNo

Object: User

                                             

AttributeTypeDescriptionSupportedMandatory
buyeruid StringBuyer-specific ID for the user as mapped by the exchange for the buyer.YesNo
yob IntegerYear of birth as a 4-digit integer.YesNo
genderStringGender, where "M" = male, "F" = female, "O" = known to be other (i.e., omitted is unknown).YesNo
geoObjectLocation of the user‰ŰŞs home base defined by a Geo object. This is not necessarily their current location. This will be given higher preference over device.geo objectYesNo
idStringExchange-specific ID for the user. At least one of id or buyerid is recommended. Buyerid will be preferred by PubMatic.YesNo

Object: Regs

                 

AttributeTypeDescriptionSupportedMandatory
coppaIntegerFlag indicating if this request is subject to the COPPA regulations established by the USA FTC, where 0 = no, 1 = yes.YesNo

Object: Publisher

                 

AttributeTypeDescriptionSupportedMandatory
idStringExchange-specific publisher IDYesNo

 

Object: Source

AttributeTypeDescriptionSupportedMandatory
fdInteger; recommendedEntity responsible for the final impression sale decision, where 0=exchange, 1=upstream source.YesNo
tidString; recommendedTransaction ID that must be common across all participants in the bid request (e.g., potentially multiple exchanges)NoNo
pchainString; recommendedPayment ID chain string containing embedded syntax described in the TAG Payment ID Protocol v. 1.0YesNo
extObjectPlaceholder for exchange-specific extensions to OpenRTBNoNo

Attachments

    Outcomes