Page tree


Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents
indent20px
stylenone

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:

  • pchain

BidRequest

  • source

Impression

  • metric

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 

AttributeTypeDescriptionScope
idStringUnique ID of the bid request, provided by the exchange.Required
impObject ArrayArray of impression objects representing the impressions offered. At least 1 impression object is required.Required
siteObject

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

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


Optional
deviceObject

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

Required
userObject

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

Optional
appObject

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

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


Optional
atInteger

Auction Type

Default = 2  

1 = Publisher first price auction

2 = Publisher second price auction

Optional
bcatString Array

Blocked advertiser categories using the IAB content categories.


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

Optional
badvString Array

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


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

Optional
regsObjectA Regs object that specifies any industry, legal, or governmental regulations in force for this request.Optional
sourceObjectA Source object that provides data about the inventory source and which entity makes the final decision.Optional
extObjectPlaceholder for exchange-specific extensions to OpenRTB.Optional

Object: BidRequest Extension Object

AttributeTypeDescriptionScope
wrapperObjectExtra information about wrapper.Optional
is_pingInteger

Is it a ping request?

1=ping request

Optional

Object: Wrapper

AttributeTypeDescriptionScope
versionIntegerVersion ID of the WrapperOptional
profileIntegerProfile ID of the WrapperOptional


Object: Imp

Info
Each impression object can contain one object from each video/native/banner object but at max 2 will be considered.    


AttributeTypeDescriptionScope
idStringA unique identifier for this impression within the context of the bid request (typically, starts with 1 and increments).Required
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.
Optional
bannerObjectA banner object is required if this impression is offered as a banner ad opportunity. Optional
nativeObjectA Native object; required if this impression is offered as a native ad opportunityOptional
videoObjectA Video object required if this impression is offered as a video ad opportunity.Optional
instlInteger1 = the ad is interstitial or full screen, 0 = not interstitial.Optional
bidfloorFloatMinimum bid for this impression expressed in CPM.Optional
bidfloorcur StringCurrency specified using ISO-4217 alpha codes.Optional

iframebuster

String ArrayArray of exchange-specific names of supported iframe bustersOptional
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.Optional
pmpObjectA PMP Object containing any private marketplace deals in effect for this impression.Optional
metricObject arrayAn array of the Metric object.Optional
extObjectPlaceholder for exchange-specific extensions to OpenRTGOptional

Object: Imp Extension Object  

AttributeTypeDescriptionScope
pmZoneIdStringThis parameter is used to pass zone ID for reporting.Optional

Object: Metric

AttributeTypeDescriptionScope
typeStringType of metric being presented using exchange-curated string names, which should be published to bidders a priori.Required
valueFloatNumber representing the value of the metric. Probabilities must b in the range of 0.0 - 1.0.Required
vendorStringSource of the value using exchange-curated string names, which should be published to bidders a priori. If the exchange itself is the source versus a third party, "EXCHANGE" is recommended.Recommended

Object: Banner

AttributeTypeDescriptionScope
wIntegerWidth of the impression in pixels.Required
hIntegerHeight of the impression in pixels.Required
battrInteger ArrayBlocked creative attributes.Optional
posIntegerAd position on screen.Optional
topframeIntegerIndicates if the banner is in the top frame as opposed to an iframe, where 0 = no, 1 = yes.Optional
expdirInteger ArrayDirections in which the banner may expand.Optional
formatObject ArrayArray of format objects representing the banner sizes permitted. Banner.w and banner.h is considered as primary width and height.Optional
apiInteger ArrayList of supported API frameworks for the impression. If an API si not explicitly listed, it is assumed not to be supported.Optional

Object: Format

AttributeTypeDescriptionScope
wIntegerWidth in device independent pixels (DIPS).Required
hIntegerHeight in device independent pixels (DIPS).Required

Object: Video

AttributeTypeDescriptionScope
protocolInteger


Info
Note: Deprecated in favor or protocols.

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


protocolsInteger

Array of supported video protocols. At least one supported protocol must be specified in either the protocol or protocols attribute


Required
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.Required
linearityIntegerIndicates if the impression is linear or nar. 1=Linear/In-Stream and 2=Non-Linear/Overlay.Highly Recommended
mindurationIntegerMinimum video ad duration in secondsRequired
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 ) Required
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 )Required (if VPAID inventory)
wIntegerWidth of the video player in pixels.Required
hIntegerHeight of the video player in pixels.Required
startdelayIntegerIndicates the start delay in seconds for pre-roll, mid-roll, or
post-roll ad placements. 
Highly 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).
Highly Recommended
maxbitrateIntegerMaximum bit rate in Kbps.Recommended 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 )Highly Recommended
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 )Optional
extObjectPlaceholder for exchange-specific extensions to OpenRTBOptional
battrInteger arrayBlocked creative attributesOptional

Object: Video.ext

AttributeTypeDescriptionScope
video_skippableIntegerIndicator for ability to skip video 0/1Highly Recommended

Object: PMP    

Warning

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.


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

Object: Deal          

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


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

Object: Native

AttributeTypeDescriptionScope
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 

Required
verStringVersion of the Native Ad Specification to which request complies; highly recommended for efficient parsingOptional


Info

NOTE: Refer to https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-Native-Ads-Specification-1-1_2016.pdf  for Native request and response details.

Object: App

AttributeTypeDescriptionScope
idStringMobile applications ID on the exchange.Optional
nameStringApp name (may be aliased upon request)Optional
publisherObjectDetails about the PublisherOptional
bundleStringApplication bundle or package name. Intended to be a unique ID across exchanges.Optional
domainStringDomain of the app.Optional
storeurlStringApp store URL for an installed app; for QAG 1.5 compliance.Optional
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)Optional
verStringApplication versionOptional
paidInteger0=app is free, 1=app is a paid versionOptional
contentObjectDetails of the content in the app.Optional
extObjectPlaceholder for exchange-specific extensions to OpenRTBOptional

Object: App.ext 

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

Optional

Object: Content                 


AttributeTypeDescriptionScope
idstring   ID uniquely identifying the content.optionalOptional
episode       integerEpisode number (typically applies to video content).Optional
title         string   Content title.Optional
series        string   Content series.Optional
season        string   Content season; typically for video content (e.g., “Season 3”).Optional
producer      Producer   objectDetails about the content ProducerOptional
url           string   URL of the content, for buy-side contextualization or review.Optional
cat           string  arrayArray of IAB content categories that describe the content producer.Optional
videoqualityinteger      Video quality per IAB’s classification.Optional
contentratingstring   Content rating (e.g., MPAA).Optional
userrating    string   User rating of the content (e.g., number of stars, likes, etc.).Optional
qagmediaratinginteger      Media rating per QAG guidelines.Optional
keywords      string   Comma separated list of keywords describing the content.Optional
livestream    integer      0 = not live, 1 = content is live (e.g., stream, live blog).Optional
sourcerelationshipinteger       0 = indirect, 1 = direct.Optional
len           integer      Length of content in seconds; appropriate for video or audio.Optional
language      string   Content language using ISO-639-1-alpha-2.Optional
embeddable    integer      Indicator of whether or not the content is embeddable where 0 = no, 1 = yes.Optional
ext           objectPlaceholder for exchange-specific extensions to OpenRTB.Optional

Object: Producer

AttributeTypeDescriptionScope
id    
 
string   Content producer or originator ID. Useful if content is syndicated and may be posted on a site using embed tags.Optional
name  string   Content producer or originator name (e.g., “Warner Bros”).Optional
cat   string arrayArray of IAB content categories that describe the content producer.Optional
domainstring   Highest level domain of the content producer (e.g., “producer.com”).Optional
ext   objectPlaceholder for exchange-specific extensions to OpenRTB.OptionaOptional

Object: Device

AttributeTypeDescriptionScope
uaStringBrowser user agent string.Optional
dntIntegerStandard "Do Not Track" flag as set in the header by the browser, where 0 = tracking is unrestricted, 1 = do not trackOptional
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.pdfRequired for CTV publishers
makeStringDevice make (e.g., "Apple")Optional
modelStringDevice model (e.g., "iPhone")Optional
osStringDevice operating system (e.g., "iOS")Optional
osvStringDevice operating system version (e.g., "3.1.2")Optional
jsIntegerSupport for JavaScript, where 0=no, 1=yes.Optional
languageStringBrowser language using ISO-639-1-alpha-2.Optional
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.Optional
IpStringIPv4 address closest to device as IPv6. Either of ip/ipv6 is required.Required
Ipv6StringIP address closest to device as IPv6. Either of ip/ipv6 is required.Required
ifaStringID sanctioned for advertiser use in the clear (i.e., not hashed)Optional
didsha1StringHardware device ID *e.g., IMEI; hashed via SHA1.Optional
didmd5StringHardware device ID *e.g., IMEI; hashed via MD5.Optional
dpidsha1StringPlatform device ID (e.g., Android ID); hashed via SHA1.Optional
dpidmd5StringPlatform device ID (e.g., Android ID); hashed via MD5.Optional

Object: Site

AttributeTypeDescriptionScope
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.
Optional
catString ArrayArray of IAB content categories of the site.Optional
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.Optional
refStringReferrer URL that caused navigation to the current page.Optional
pagecatString ArrayArray of IAB content categories that describe the current page or view of the site.Optional
publisherObjectDetails about the PublisherRequired
contentObjectDetails about the content within the site.Optional
extObjectPlaceholder for exchange-specific extensions to OpenRTBOptional

Object: Site.ext 

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

Optional

Object: Geo

AttributeTypeDescriptionScope
latFloatLatitude from -90.0 to +90.0, where negative is southOptional
lonFloatLongitude from -180.0 to +180.0, where negative is west.Optional
typeIntegerSource of location data; recommended when passing lat/lon.Optional
countryStringCountry code using ISO-3166-1-alpha-3.Optional
regionStringRegion code using ISO-3166-2; 2-letter state code if USAOptional
metroStringGoogle metro code; similar to but not exactly Nielsen DMAs.Optional
cityStringCity using United Nations Code for Trade & Transport Locations. It must not be encoded.Optional
zipStringZip or postal codeOptional
utcoffsetIntegerLocal time as the number +/- of minutes from UTCOptional

Object: User

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

An array of Extended ID objects.

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


Optional
extObjectPlaceholder for exchange-specific extensions to OpenRTBOptional

Object: User Extension Object

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

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.

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


Optional
consented_providers_settingObject

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


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


Optional


Example:

Code Block
languagejs
"user": { "ext": {"gdpr": 1,"consent": "BONihAGONihAGABABAENAQ____AArABAAAA"}}


‍‍‍‍‍‍‍‍‍‍‍‍‍

Example of Google EB parameter:

Code Block
languagejs
"user": { 
"ext": { 
"consented_providers_settings": 
{ "consented_providers": [123, 456] } 
} 
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Object: consented_providers_setting

AttributeTypeDescriptionScope
consented_providersString arrayList of provider_ids that has user consentoptionalOptional

Object: eids (Extended IDs)

AttributeTypeDescriptionScope
source String

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

Info
Note: Maximum size of 64 bytes is supported.


Required
uidsObject Array

Array of extended ID UID objects.

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


Required

Object: uids (Extended ID UIDs)

AttributeTypeDescriptionScope
id String

Cookie or platform native of the identifier

Info
Note: Maximum size of 384 bytes is supported


Required
atypeIntegerType of user agent the match is from. See agent types table below.Optional

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

AttributeTypeDescriptionScope
coppaIntegerFlag indicating if this request is subject to the COPPA regulations established by the USA FTC, where 0 = no, 1 = yes.Optional
extObjectPlaceholder for exchange-specific extensions to OpenRTB.Optional

Object: Regs Extension

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


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

Example:

Code Block
languagejs
"regs": {"ext": {"gdpr": 1}}‍‍‍‍‍‍‍

Object: Publisher

AttributeTypeDescriptionScope
idStringExchange-specific publisher IDOptional

Object: Source

AttributeTypeDescriptionScope
pchainString; recommendedPayment ID chain string containing embedded syntax described in the TAG Payment ID Protocol v. 1.0Optional