OpenRTB Bid Request Objects and Parameters

Document created by pubmatic-archivist on Mar 27, 2017Last modified by pubmatic-archivist on Sep 16, 2017
Version 20Show 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 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


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

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


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


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


Auction Type

Default = 2  

1 = Publisher first price auction

2 = Publisher second price auction

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., "").YesNo
regsObjectA Regs object that specifies any industry, legal, or governmental regulations in force for this request.YesNo

Object: Imp

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


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

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

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



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


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

Object: Banner


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

Object: Video


protocol (from video object)Not Supp

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

protocolsIntegerArray of supported video bid response protocols. Refer to List 5.8 in 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
apiInteger ArrayAPI frameworks supported (See Table 6.4 in
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. 
maxbitrateIntegerMaximum bit rate in Kbps.YesNo
playbackmethodInteger ArrayDefines whether inventory is user-initiated or autoplay sound on/off. (See Table 6.8 in
deliveryInteger ArrayList of supported delivery methods (e.g., streaming, progressive). (See Table 6.12 in BrightRoll only supports progressive delivery at this time.NoNo
posIntegerAd position on the page. (See Table 6.5 in
companiontypeInteger ArrayDescribes the VAST companion resource types supported by the inventory (e.g., static resource, iframe resource, etc.) (See Table 6.17 in
companionadObject ArrayCompanion ads are described by the banner objectNoNo
extObjectPlaceholder for exchange-specific extensions to OpenRTBYesNo


Object: Video.ext                                                                                    

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.

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. 

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

Object: Native



Request payload complying with the Native Ad Specification 1.0:

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


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
sectioncatString ArrayArray of IAB content categories that describe the current section of the app. (Refer to List 5.1 in
pagecatString ArrayArray of IAB content categories that describe the current page or view of the app. (Refer to List 5.1 in
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: Content



Object: Device


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


idStringExchange-specific site ID.
  • 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.
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: Geo


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


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


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

Object: Publisher


idStringExchange-specific publisher IDYesNo