Page tree



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.

OpenRTB 2.4 and higher

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

Objects and Parameters Supported

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

Object: BidRequest 

AttributeTypeDescriptionSupportedScope
idStringUnique ID of the bid request, provided by the exchange.YesRequired
impObject ArrayArray of impression objects representing the impressions offered. At least 1 impression object is required.YesRequired
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.
YesOptional
deviceObject

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

YesRequired
userObject

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

YesOptional
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.
YesOptional
atInteger

Auction Type

Default = 2  

1 = Publisher first price auction

2 = Publisher second price auction

YesOptional
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 requestOptional
bcatString Array

Blocked advertiser categories using the IAB content categories.


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

YesOptional
badvString Array

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


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

YesOptional
regsObjectA Regs object that specifies any industry, legal, or governmental regulations in force for this request.YesOptional
tmaxIntegerThe maximum time in milliseconds to submit a bid to avoid timeout.YesOptional
wrapperObjectExtra information about wrapper.YesOptional

Object: Wrapper

AttributeTypeDescriptionSupportedScope
versionIntegerVersion ID of the WrapperYesOptional
profileIntegerProfile ID of the WrapperYesOptional


Object: Imp

Each impression object can contain one object from each video/native/banner object but at max 2 will be considered.    
AttributeTypeDescriptionSupportedScope
idStringA unique identifier for this impression within the context of the bid request (typically, starts with 1 and increments).YesRequired
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.
YesOptional
bannerObjectA banner object is required if this impression is offered as a banner ad opportunity. YesOptional
nativeObjectA Native object; required if this impression is offered as a native ad opportunityYesOptional
videoObjectA Video object required if this impression is offered as a video ad opportunity.YesOptional
instlInteger1 = the ad is interstitial or full screen, 0 = not interstitial.YesOptional
bidfloorFloatMinimum bid for this impression expressed in CPM.YesOptional
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.

Optional

iframebuster

String ArrayArray of exchange-specific names of supported iframe bustersYesOptional
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.YesOptional
pmpObjectA PMP Object containing any private marketplace deals in effect for this impression.YesOptional


Object: Imp Extension Object                 

AttributeTypeDescriptionSupportedScope
pmZoneIdStringThis parameter is used to pass zone ID for reporting.YesOptional

Object: Banner

AttributeTypeDescriptionSupportedScope
wIntegerWidth of the impression in pixels.YesRequired
hIntegerHeight of the impression in pixels.YesRequired
battrInteger ArrayBlocked creative attributes.YesOptional
posIntegerAd position on screen.YesOptional
topframeIntegerIndicates if the banner is in the top frame as opposed to an iframe, where 0 = no, 1 = yes.YesOptional
expdirInteger ArrayDirections in which the banner may expand.YesOptional
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.YesOptional

Object: Format

AttributeTypeDescriptionSupportedScope
wIntegerWidth in device independent pixels (DIPS).YesRequired
hIntegerHeight in device independent pixels (DIPS).YesRequired

Object: Video

AttributeTypeDescriptionSupportedScope
protocol (from video object)Not Supp

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

NoOptional
protocolsInteger

Array of supported video bid response protocols. Refer to List 6.7 in https://www.iab.com/wp-content/uploads/2015/05/OpenRTB_API_Specification_Version_2_3_1.pdf

At least one supported protocol must be specified in either the protocols attribute.

YesRequired
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.YesRequired
linearityIntegerIndicates if the impression is linear or nar. 1=Linear/In-Stream and 2=Non-Linear/Overlay.YesHighly Recommended
mindurationIntegerMinimum video ad duration in secondsYesRequired
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/05/OpenRTB_API_Specification_Version_2_3_1.pdf ) YesRequired
apiInteger ArrayAPI frameworks supported (See Table 6.4 in https://www.iab.com/wp-content/uploads/2015/05/OpenRTB_API_Specification_Version_2_3_1.pdf )YesRequired (if VPAID inventory)
wIntegerWidth of the video player in pixels.YesRequired
hIntegerHeight of the video player in pixels.YesRequired
startdelayIntegerIndicates the start delay in seconds for pre-roll, mid-roll, or
post-roll ad placements. 
YesHighly Recommended (If In-Stream)
placementInteger

Placement type for the impression as specified by oRTB 2.5 (Table 5.9). Should be used to distinguish between in-stream and out-stream inventory. 

Possible integer values:

  • 1 - In-Stream   (Played before, during or after the streaming video content that the consumer has requested: Pre-roll, Mid-roll, Post-roll).
  • 2 - In-Banner   (Exists within a web banner that leverages the banner space to deliver a video experience as opposed to another static or rich media format. The format relies on the existence of display ad inventory on  the page for its delivery.)
  • 3 - In-Article    (Loads and plays dynamically between paragraphs of editorial content; existing as a standalone branded message.)
  • 4 - In-Feed       (Found in content, social, or product feeds.)
  • 5 - Interstitial/Slider/Floating     (Covers the entire or a portion of screen area, but is always on screen while displayed - i.e. cannot be scrolled out of view).
YesHighly Recommended
maxbitrateIntegerMaximum bit rate in Kbps.YesRecommended for mobile
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/05/OpenRTB_API_Specification_Version_2_3_1.pdf )YesHighly Recommended
deliveryInteger ArrayList of supported delivery methods (e.g., streaming, progressive). (See Table 6.12 in https://www.iab.com/wp-content/uploads/2015/05/OpenRTB_API_Specification_Version_2_3_1.pdf ) BrightRoll only supports progressive delivery at this time.NoOptional
posIntegerAd position on the page. (See Table 6.5 in https://www.iab.com/wp-content/uploads/2015/05/OpenRTB_API_Specification_Version_2_3_1.pdf )YesOptional
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/05/OpenRTB_API_Specification_Version_2_3_1.pdf )NoOptional
companionadObject ArrayCompanion ads are described by the banner objectNoOptional
extObjectPlaceholder for exchange-specific extensions to OpenRTBYesOptional

Object: Video.ext

AttributeTypeDescriptionSupportedScope
video_skippableIntegerIndicator for ability to skip video 0/1YesHighly Recommended

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.

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

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. 
AttributeTypeDescriptionSupportedScope
idStringA unique identifier for the direct deal. Maximum length of string is 64YesRequired

Object: Native

AttributeTypeDescriptionSupportedScope
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 

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


Object: App

AttributeTypeDescriptionSupportedScope
idStringMobile applications ID on the exchange.YesOptional
nameStringApp name (may be aliased upon request)YesOptional
publisherObjectDetails about the PublisherYesOptional
bundleStringApplication bundle or package name. Intended to be a unique ID across exchanges.YesOptional
domainStringDomain of the app.YesOptional
storeurlStringApp store URL for an installed app; for QAG 1.5 compliance.YesOptional
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)YesOptional
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)NoOptional
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)NoOptional
verStringApplication versionYesOptional
privacypolicyIntegerIndicates if the app has a privacy policy, where 0=no, 1=yesNoOptional
paidInteger0=app is free, 1=app is a paid versionYesOptional
keywordsStringcomma separated list of keywords about the appNoOptional
contentObjectDetails of the content in the app.YesOptional

Object: App.ext 

ObjectAttributeTypeDescriptionSupportedScope
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

Optional

Object: Content                 

AttributeTypeDescriptionSupportedScope
idStringExchange-specificYesOptional

Object: Device

AttributeTypeDescriptionSupportedScope
uaStringBrowser user agent string.YesOptional
dntIntegerStandard "Do Not Track" flag as set in the header by the browser, where 0 = tracking is unrestricted, 1 = do not trackYesOptional
lmtInteger"Limit Ad Tracking" signal commercially endorsedNoOptional
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.pdfYesRequired for CTV publishers
makeStringDevice make (e.g., "Apple")YesOptional
modelStringDevice model (e.g., "iPhone")YesOptional
osStringDevice operating system (e.g., "iOS")YesOptional
osvStringDevice operating system version (e.g., "3.1.2")YesOptional
hwvStringHardware version of the device (e.g., "5S" for iPhone 5S).NoOptional
hIntegerPhysical height of the screen in pixels.NoOptional
wIntegerPhysical width of the screen in pixels.NoOptional
ppiIntegerScreen size as pixels per linear inch.NoOptional
pxratiofloatThe ratio of physical pixels to device independent pixels.NoOptional
jsIntegerSupport for JavaScript, where 0=no, 1=yes.YesOptional
flashverstringVersion of Flash supported by the browser.NoOptional
languageStringBrowser language using ISO-639-1-alpha-2.YesOptional
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.YesOptional
IpStringIPv4 address closest to device as IPv6. Either of ip/ipv6 is required.YesRequired
Ipv6StringIP address closest to device as IPv6. Either of ip/ipv6 is required.YesRequired
ifaStringID sanctioned for advertiser use in the clear (i.e., not hashed)YesOptional
didsha1StringHardware device ID *e.g., IMEI; hashed via SHA1.YesOptional
didmd5StringHardware device ID *e.g., IMEI; hashed via MD5.YesOptional
dpidsha1StringPlatform device ID (e.g., Android ID); hashed via SHA1.YesOptional
dpidmd5StringPlatform device ID (e.g., Android ID); hashed via MD5.YesOptional
macsha1StringMAC address of the device; hashed via SHA1.NoOptional
macmd5StringMAC address of the device; hashed via MD5.NoOptional

Object: Site

AttributeTypeDescriptionSupportedScope
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.
YesOptional
catString ArrayArray of IAB content categories of the site.YesOptional
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.YesOptional
refStringReferrer URL that caused navigation to the current page.YesOptional
pagecatString ArrayArray of IAB content categories that describe the current page or view of the site.YesOptional
publisherObjectDetails about the PublisherYesRequired
contentObjectDetails about the content within the site.YesOptional

Object: Site.ext 

ObjectAttributeTypeDescriptionSupportedScope
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

Optional

Object: Geo

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

Object: User

AttributeTypeDescriptionSupportedScope
buyeruid StringBuyer-specific ID for the user as mapped by the exchange for the buyer.YesOptional
yob IntegerYear of birth as a 4-digit integer.YesOptional
genderStringGender, where "M" = male, "F" = female, "O" = known to be other (i.e., omitted is unknown).YesOptional
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 objectYesOptional
idStringExchange-specific ID for the user. At least one of id or buyerid is recommended. Buyerid will be preferred by PubMatic.YesOptional
eidsObject Array

An array of Extended ID objects.

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

Object: User Extension Object

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

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
YesOptional


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

AttributeTypeDescriptionSupportedScope
source String

Source or technology provider responsible for the set of included IDs. Expressed as a top-level domain.

Note: Maximum size of 64 bytes is supported.
YesRequired
uidsObject Array

Array of extended ID UID objects.

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

Object: Extended ID UIDs

AttributeTypeDescriptionSupportedScope
id String

Cookie or platform native of the identifier

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

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

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

Object: Regs Extension

AttributeTypeDescriptionSupportedScope
gdprIntegerPossible values: 0 or 1 to indicate whether or not the impression is gdpr regulated.YesOptional
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

AttributeTypeDescriptionSupportedScope
idStringExchange-specific publisher IDYesOptional

Object: Source

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