OpenRTB Bid Request Objects and Parameters

Document created by pubmatic-archivist on Mar 27, 2017Last modified by catherine.racette on Sep 13, 2018
Version 49Show Document
  • View in full screen mode

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. 

 

PubMatic supports the following parameters from OpenRTB 2.4 and higher

 

User Object:

  • eids

Extended IDs Object:

  • source
  • uids

Extended ID UIDs Object:

  • id
  • atype

Source Object:

  • fd
  • tid
  • pchain

 

Supporting gzip compression of bid request and response for publishers

Publishers can send gzip-compressed bid requests to PubMatic through the OpenRTB API by ensuring that Content-Encoding contains the value, gzip.

Publishers can also receive a gzip-compressed bid response through the OpenRTB API for publishers when required conditions are met:

  • The request header Content-Encoding has value, gzip, AND
  • The response size is greater than 512 bytes, AND
  • The gzip response has been explicitly enabled for the publisher by the PubMatic Customer Success Team.

 

Additionally, publishers can detect that PubMatic's response is gzip-encoded when our response's Content-Encoding has the value, gzip.

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
siteObject

Details via a site object about the publisher's website.

Note: A request containing both site and app object in BidRequest Object will not be considered. Only site OR app should be present in the request; not both in the same request.

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.

Note: A request containing both site and app object in BidRequest Object will not be considered. Only site OR app should be present in the request; not both in the same request.
YesNo
atInteger

Auction Type

Default = 2  

1 = Publisher first price auction

2 = Publisher second price auction

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

Blocked advertiser categories using the IAB content categories.

 

The limit of IAB categories the system can support is 20 categories.

YesNo
badvString Array

Block list of advertisers by their domains (e.g., "ford.com").

 

The limit of URLs the system can support is 40 URLs.

YesNo
regsObjectA Regs object that specifies any industry, legal, or governmental regulations in force for this request.YesNo
tmaxIntegerThe maximum time in milliseconds to submit a bid to avoid timeout.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
protocolsInteger

Array of supported video bid response protocols. Refer to List 6.7 in https://www.iab.com/wp-content/uploads/2015/06/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 nar. 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 https://www.iab.com/wp-content/uploads/2015/06/OpenRTBAPISpecificationVersion2_2.pdf ) YesNo
apiInteger ArrayAPI frameworks supported (See Table 6.4 in https://www.iab.com/wp-content/uploads/2015/06/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 https://www.iab.com/wp-content/uploads/2015/06/OpenRTBAPISpecificationVersion2_2.pdf )YesNo
deliveryInteger ArrayList of supported delivery methods (e.g., streaming, progressive). (See Table 6.12 in https://www.iab.com/wp-content/uploads/2015/06/OpenRTBAPISpecificationVersion2_2.pdf ) BrightRoll only supports progressive delivery at this time.NoNo
posIntegerAd position on the page. (See Table 6.5 in https://www.iab.com/wp-content/uploads/2015/06/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 https://www.iab.com/wp-content/uploads/2015/06/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.1: https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-Native-Ads-Specification-1-1_2016.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

Object: 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
eidsObject Array

An array of Extended ID objects.

Note: First 3 valid objects will be used and the rest will be discarded

YesNo

Object: User Extension Object

AttributeTypeDescriptionSupportedMandatory
gdpr IntegerPossible values: 0 or 1 to indicate if the impression is GDPR regulated or not.YesNo
consentStringIf the above flag is 1, then this string gives consent information of various vendorsYesNo

consented_providers_settings.consented_providers

Array of Integers

Set of IDs corresponding to providers for whom the publisher has told Google that its EEA (European Economic Area) users have consented to the use of their personal data for ad personalization.

Note: Specific to Google EB Integrations and applicable only when Regs.ext.gdpr=1

YesNo

 

Example:

"user": { "ext": {"gdpr": 1,"consent": "BONihAGONihAGABABAENAQ____AArABAAAA"}}

 

Example of Google EB parameter:

"user": { 
     "ext": {
       "consented_providers_settings":
       { "consented_providers": [123, 456] }
     }
   }

 

 

Object: Extended IDs

AttributeTypeDescriptionSupportedMandatory
source StringSource or technology provider responsible for the set of included IDs. Expressed as a top-level domain.
Note: Maximum size of 64 bytes is supported.
YesYes
uidsObject Array

Array of extended ID UID objects.

Note: First 3 valid objects will be used and the rest will be discarded

YesYes

 

Object: Extended ID UIDs

AttributeTypeDescriptionSupportedMandatory
id String

Cookie or platform native of the identifier

Note: Maximum size of 384 bytes is supported
YesYes
atypeIntegerType of user agent the match is from. See agent types table below.YesNo

 

Agent Types (atype)

Type IdNameDescription
WebAn ID intended which is tied to a specific browser or device (cookie-based, probabilistic, or other).
2IDFAApple IDFA
3AAIDAndroid Ad ID
4Window Advertising IDWindows mobile advertising ID
5Other mobile IDAnother mobile advertising identifier, such as a SHA1 or MD5 version, or other legacy native mobile identifier.
500+Exchange-specific

 

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: Regs Extension

AttributeTypeDescriptionSupportedMandatory
gdprIntegerPossible values: 0 or 1 to indicate whether or not the impression is gdpr regulated.YesNo

Note: This flag can be sent either in Regs.ext or User.ext out of which the Regs.ext takes priority

Example:

"regs": {"ext": {"gdpr": 1}}

 

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