Versions Compared

Key

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

...





source ObjectA Source object that provides data about the inventory source and which entity makes the final decision.Optional
testInteger

Indicator of test mode, in which auctions are not billable.

0=live mode (Default)

1=test mode

Optional
ext ObjectPlaceholder for exchange-specific extensions to OpenRTB.Optional

Imp

Expand
titleExpand for to view bidrequest.imp attributes...


Info
Each impression object can contain one object from each video/native/banner object, but PubMatic considers only a maximum of 2.    


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.

Info
  • You can also use as PubMatic ad placement id or ad id. You must maintain the mapping of your publisher ad id to the PubMatic ad id.
  • You must send PubMatic ad id here.
  • You can also use as a slotname for wrapper/prebid. PubMatic maintains mapping to derive the PubMatic ad id from the slotname.


Optional
banner ObjectA banner object is required if this impression is offered as a banner ad opportunity. Optional
native ObjectA Native object; required if this impression is offered as a native ad opportunityOptional
video ObjectA 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.Recommended
bidfloorcur StringCurrency specified using ISO-4217 alpha codes.Recommended

iframebuster

String ArrayArray of exchange-specific names of supported iframe busters.Optional
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.Recommended
pmp ObjectA PMP Object containing any private marketplace deals in effect for this impression.Optional
metric Object arrayAn array of the Metric object.Optional
ext ObjectPlaceholder for exchange-specific extensions to OpenRTBOptional

Banner

Expand
titleExpand for to view bidrequest.imp.banner attributes...


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 Array

Array of format objects representing permitted banner sizes. Banner.w and banner.h are considered as primary width and height.

Limitation: 4 objects max.

Recommended
apiInteger Array

List of supported API frameworks for the impression. If an API si not explicitly listed, it is assumed not to be supported.

Info

In OpenRTB 2.1-2.5, the api attribute is now also used in support of the Open Measurement SDK.

Add 7 to the array of supported API frameworks if you use Open Measurement.

See List 5.6 API Frameworks in the IAB OpenRTB Advisory for Open Measurement SDK to learn more.


Recommended
Format
Expand
titleExpand for to view bidrequest.imp.banner.format attributes…attributes


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


Code Block
languagexml
titleBidRequest.imp.banner.format sample JSON
linenumberstrue
collapsetrue
{
	"id": "6503ED1F-B749-4215-9721-0EA5A7054F2F",
	"at": 1,
	"imp": [{
		"id": "1",
		"tagid": "904294",
		"bidfloor": 0.300000,
		"secure": 1,
		"banner": {
			"w": 300,
			"h": 250,
			"format": [{
				"w": 300,
				"h": 250
			}],
			"topframe": 1,
			"battr": [1, 3, 6, 7, 8, 9, 11],
			"btype": [1, 2]
		},
		"ext": {
			"headerbidding": {
				"present": 1
			}
		}
	}],
	"site": {
		"id": "173321",
		"cat": ["IAB10", "IAB10-4", "IAB9-30", "IAB25", "IAB1", "IAB9-20", "IAB25-2", "IAB19", "IAB1-6", "IAB9"],
		"page": "https://sonidossumergidosblog.wordpress.com/tag/post-punk/",
		"domain": "sonidossumergidosblog.wordpress.com",
		"mobile": 1,
		"publisher": {
			"id": "156078"
		}
	},
	"device": {
		"ip": "200.106.117.237",
		"lmt": 0,
		"ua": "Mozilla/5.0 (Linux; Android 9; moto g(7) power) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/77.0.3865.92 Mobile Safari/537.36",
		"carrier": "Telefonica del Peru",
		"make": "Motorola",
		"os": "Android",
		"osv": "2.0",
		"js": 1,
		"geo": {
			"country": "PER",
			"region": "lma",
			"city": "lima",
			"metro": "-1",
			"zip": "15000"
		},
		"geofetch": 0,
		"ext": {
			"xff": "10.100.129.33",
			"res": "-1x-1",
			"freq": 0,
			"pf": 2
		}
	},
	"user": {
		"id": "DB389E6A-8559-46FB-A0AD-999D51B017CB",
		"buyeruid": "1oKWGtqMrMmZx1A9VcdW",
		"geo": {
			"country": "per"
		},
		"eids": [{
			"source": "adserver.org",
			"uids": [{
				"id": "8bb26040-d46c-4a47-ab6e-df1e94215ae4",
				"ext": {
					"rtiPartner": "TDID"
				}
			}]
		}],
		"ext": {
			"eids": [{
				"source": "adserver.org",
				"uids": [{
					"id": "8bb26040-d46c-4a47-ab6e-df1e94215ae4",
					"ext": {
						"rtiPartner": "TDID"
					}
				}]
			}]
		}
	},
	"bcat": ["IAB5-2", "IAB25-3", "IAB25-2", "IAB26", "IAB25-5", "IAB25-4", "IAB9-9"],
	"source": {
		"fd": 1,
		"pchain": "5d62403b186f2ace:156078",
		"ext": {
			"schain": {
				"complete": 0,
				"ver": "1.0",
				"nodes": [{
					"asi": "pubmatic.com",
					"sid": "156078",
					"rid": "6503ED1F-B749-4215-9721-0EA5A7054F2F",
					"hp": 1
				}]
			}
		}
	}
}



Native

Expand
titleExpand for to view bidrequest.imp.native attrbutes...attributes


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; best practice for efficient parsing.Optional
apiInteger array

List of supported API frameworks for the impression. If an API si not explicitly listed, it is assumed not to be supported.

Info

In OpenRTB 2.1-2.5, the api attribute is now also used in support of the Open Measurement SDK.

Add 7 to the array of supported API frameworks if you use Open Measurement.

See List 5.6 API Frameworks in the IAB OpenRTB Advisory for Open Measurement SDK to learn more.

If you are using Native ads with the eventtrackers object, see Specific Guidance for Native Ads in the IAB OpenRTB Advisory for Open Measurement SDK documentation.


Optional


Info
titleTo learn Learn more about native request and response details see…:

https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-Native-Ads-Specification-1-1_2016.pdf.


Video

Expand
titleExpand for to view bidrequest.imp.video attrbutes......attributes


AttributeTypeDescriptionScope
protocolInteger


Info
Deprecated in favor of protocols.

Supported video protocol. You must specify at least one supported protocol in either the protocol or protocols attribute.


protocolsInteger

Array of supported video protocols. You must specify a t least one supported protocol in either the protocol or protocols attribute.

Required
mimesString Array


Content MIME types supported for media files. Common video MIME types may include "video/mp4," while "application/javascript" applies to VPAID creatives.

Supported mime types:

  • video/mp4
  • application/x-shockwave-flash (used for VPAID - FLASH)
  • video/wmv
  • video/h264
  • video/webm
  • application/javascript (used for VPAID - JS)
  • video/ogg
  • video/flv (used for Flash Video)
  • video/3gpp
  • video/quicktime
  • video/mpeg
  • application/x-mpegURL
Required
linearityIntegerIndicates if the impression is linear or nar. 1=Linear/In-Stream and 2=Non-Linear/Overlay.Best Practice
mindurationIntegerMinimum video ad duration in secondsRequired
maxdurationInteger

Maximum video ad duration in seconds. 

Required
protocol
Video bid response protocols supported. (See Table 5.8 in https://www.iab.com/wp-content/uploads/2015/05/OpenRTB_API_Specification_Version_2_3_1.pdf )
apiInteger Array

API frameworks supported (See Table 5.6 in https://www.iab.com/wp-content/uploads/2015/05/OpenRTB_API_Specification_Version_2_3_1.pdf ).

Info

In OpenRTB 2.1-2.5, the api attribute is now also used in support of the Open Measurement SDK.

Add 7 to the array of supported API frameworks if you use Open Measurement.

See List 5.6 API Frameworks in the IAB OpenRTB Advisory for Open Measurement SDK to learn more.


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. 
Best Practice (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).
Best Practice
maxbitrateIntegerMaximum bit rate in Kbps.Best Practice for mobile
playbackmethodInteger arrayDefines whether inventory is user-initiated or autoplay sound on/off. (See Table 5.9 in https://www.iab.com/wp-content/uploads/2015/05/OpenRTB_API_Specification_Version_2_3_1.pdf )Best Practice
skipIntegerIndicates if the player will allow the video to be skipped, where 0 = no, 1 = yes.Optional
skipminIntegerVideos of total duration greater than this number of seconds can be skippable; only applicable if the ad is skippable.Optional
skipafterIntegerNumber of seconds a video must play before skipping is enabled; only applicable if the ad is skippable.Optional
posIntegerAd position on the page. (See Table 5.4 in https://www.iab.com/wp-content/uploads/2015/05/OpenRTB_API_Specification_Version_2_3_1.pdf)Optional
battrInteger arrayBlocked creative attributes.Optional
ext ObjectPlaceholder for exchange-specific extensions to OpenRTBOptional
Video.ext
AttributeTypeDescriptionScope
video_skippableIntegerIndicator for ability to skip video 0/1.Best Practice


PMP

Expand
titleExpand for to view bidrequest.imp.pmp attrbutes......attributes


Warning

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


AttributeTypeDescriptionScope
dealsObject ArrayArray of deal objects (50 max), that convey the specific deals applicable to an impression.Optional


Metric

Expand
titleExpand for to view bidrequest.imp.metric attrbutes......attributes


AttributeTypeDescriptionScope
typeStringType of metric being presented using exchange-curated string names, which should be published to derived biddersRequired
valueFloatNumber representing the value of the metric. Probabilities must be 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.Best Practice


Imp.ext

Expand
titleExpand for bidrequest.imp.ext attrbutes......


AttributeTypeDescriptionScope
pmZoneIdStringUsed to pass zone ID for reporting.Optional
viewabilityvendorsString arrayContains a list of viewability vendors supported by publishersOptional
testcridString
  • If bidrequest.test=1 and testcrid is valid, the testcrid creative passed will be served.
  • if bidrequest.test=1 and testcrid is absent, the creative in the DB configuration will be served.
  • if bidrequest.test=1 and testcrid is invalid 204 (no content), nothing will be served.
  • if bidrequest.test=0, the request will be treated as live and testcrid will not have any significance.
Optional
skadnObject

skadn object will be sent to DSPs as it's received.
This object will be passed to DSPs only if there is at least one skadnetid listed in skadn.skadnetids.

Optional, recommended for iOS 14+
Object:


imp.ext.skadn

ATTRIBUTE

TYPE

DESCRIPTION

EXAMPLE

versionstring

The version of skadnetwork that is supported.

  • It is always 2.0 or higher, and it is dependent on both the OS version and the SDK version.
  • Maximum number of characters in string: 16 (ASCII)
  • If string length is exceeded it will be truncated when sent to DSP.
2.0
sourceappstring

ID of publisher app in Apple’s App Store.

  • Recommended to match app.bundle.
  • Maximum number of characters in string: 256 (ASCII).
  • If string length is exceeded it will be truncated when sent to DSP.
123456789
skadnetidsarray A subset of SKAdNetworkItem entries in the publisher app’s info.plist that are relevant.
  • Should contain at least one skadnetid.
  • Maximum number of characters in string: 64 (ASCII)
  • If string length is exceeded it will be truncated when sent to DSP.
example123.skadnetwork, example234.skadnetwork


Site

Expand
titleExpand for to view bidrequest.site attributes......


AttributeTypeDescriptionScope
idString

Exchange-specific site ID. 

Info
  • This is the PubMatic site id, used for multi-site support. You must maintain the mapping of your publisher site id to the PubMatic site id.
  • Send only the tag id in the request have PubMatic derive the PubMatic site id from imp[0].tagid. The best practice is to send both the site id and tag id.
  • If you do not want to modify the app body, then send PubMatic 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
publisher ObjectDetails about the PublisherRequired
content ObjectDetails about the content within the site.Optional
ext ObjectPlaceholder for exchange-specific extensions to OpenRTBOptional

Site.ext

AttributeTypeDescriptionScope
key_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 ","; for example, "key_val"="key1=V1,V2,V3|key2=v1|key3=v3,v5".

Optional


BidRequest.ext

Expand
titleExpand for to view bidrequest.ext attributes...


AttributeTypeDescriptionScope
wrapper ObjectExtra information about wrapper.Optional
is_pingInteger

Is it a ping request?

1=ping request

Optional
sspStringAllows publishers who are not listed on ads.txt to integrate with DSPs who require an ads.txt entry. The publisher supplies their name as the value of ssp; for example, ssp=connatix.Optional
google_query_idstringThe google_query_id attribute lets DSPs identify a request and keep a mapping on their side to resolve any billing discrepancies.Optional


Code Block
languagexml
titleExample: BidRequest With ssp Extension.
linenumberstrue
collapsetrue
{
 "id": "3A901F9E-040A-4C6A-8B8E-8CC10DB3E634",
 "imp": [
 ...
 }
 ],
 "site": {
 ...
 },
 "device": {
 ...
 },
 "user": {
 "id": "412C10A4-C2E4-437B-9141-C1740DA949CD"
 },
 "ext": {
 "bidguidefloor": 0.620000,
 "ssp": "connatix"
 }
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Wrapper

Expand
titleExpand for to view bidrequest.ext.wrapper attributes......


AttributeTypeDescriptionScope
versionIntegerVersion ID of the WrapperOptional
profileIntegerProfile ID of the WrapperOptional


Code Block
languagexml
titleExample: Imp With viewabilityvendors Extension.
linenumberstrue
collapsetrue
Bid { 
"imp": [
       {
        "ext": {
               "viewabilityvendors" : [ "moat.com", "whiteops.com" ]
         } 
       }
      ]
}



...