Bid Request Objects and Parameters

PubMatic supports Ad Serving integration using OpenRTB 2.5 and proprietary APIs. This document provides Bid Request Objects and Parameters for the OpenRTB Ad Serving integration.

gzip compression support

You can send gzip-compressed bid requests to PubMatic through the OpenRTB API by ensuring that request header content-encoding contains the value gzip.

You can also receive a gzip-compressed bid response if the following requirements are fulfilled:

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

PubMatic sends response header content-encoding with the value gzip, whenever response is gzip compressed.

Bid Request object

The top-level bid request object contains a globally unique bid request or auction ID. This ID attribute is required as is at least one impression object.

AttributeTypeDescription
idstring; requiredUnique ID of the bid request, provided by the exchange.
imp object Array; requiredArray of impression objects representing the impressions offered. At least 1 impression object is required.
site object; optional

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

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.
device
object; required

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

user
object; optional

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

app object; optional

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

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.
atinteger; optional

Auction Type

1 = Publisher first price auction

2 = (Default) Publisher second price auction

bcatstring array; optional

Blocked advertiser categories using the IAB content categories.

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

badvstring array; optional

Block list of advertisers by their domains; for example, "ford.com".

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

bapp

string array; optional

Blocklist of applications by their platform-specific exchange-independent application identifiers. On Android, these should be bundle or package names (e.g., com.foo.mygame). On iOS, these are numeric IDs.

Limitation:

  • Max string size: 10500
  • Max blocked appid 40 each of max size 256

tmax

integer; optional

Maximum time in milliseconds the exchange allows for bids to be received including Internet latency to avoid timeout. This value supersedes any a priori guidance from the exchange.

regs

object; optionalA Regs object that specifies any industry, legal, or governmental regulations in force for this request.
source object; optionalA Source object that provides data about the inventory source and which entity makes the final decision.
testinteger; optional

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

0=live mode (Default)

1=test mode

ext object; optionalPlaceholder for exchange-specific extensions to OpenRTB.

BidRequest.ext

AttributeTypeDescription
wrapper object; optionalExtra information about wrapper.
is_pinginteger; optional

Is it a ping request?

1 = ping request

sspstring; optionalAllows 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.
google_query_idstring; optionalThe google_query_id attribute lets DSPs identify a request and keep a mapping on their side to resolve any billing discrepancies.

placementtype

string; optional

Only supported value is case-sensitive rewarded, which indicates the video is non-skippable-reward-video.

  • When the value is rewarded, the video.skip, video.skipmin, and video.skipafter parameters will be ignored.

  • For requests with multiple impressions, the signal will be applied to all video impressions.

  • For requests with multi-format impressions, banner formats will be ignored.

Note: Since attribute names are not case-sensitive, publisher should send the field name using this format: placementType.

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

Wrapper object

AttributeTypeDescription

version

integer; optionalVersion ID of the Wrapper

profile

integer; optionalProfile ID of the Wrapper
wiidinteger; optionalWrapper impression ID

Source object

This object describes the nature and behavior of the entity that is the source of the bid request upstream from the exchange. The primary purpose of this object is to define post-auction or upstream decisioning when the exchange itself does not control the final decision.

AttributeTypeDescription
pchainstring; best practice

Payment ID chain string containing embedded syntax described in the TAG Payment ID Protocol v. 1.0

tidstring; best practice

Transaction ID that must be common across all participants in this bid request (for example, potentially multiple exchanges).

extobject; optionalPlaceholder for exchange-specific extensions to OpenRTB.

Source.ext

ATTRIBUTE

TYPE

DESCRIPTION

omidpnstring; optionalIdentifier of the OM SDK integration. This is the same as the "name" parameter of the OMID Partner object.
omidpvstring; optionalVersion of the OM SDK integration. This is the same as the versionString parameter of the OMID Partner object.
schainobject; requiredThis object represents both the links in the supply chain as well as an indicator whether or not the supply chain is complete.

SupplyChain object

Attribute

Type

Description

complete

integer; required

Flag indicating whether the chain contains all nodes involved in the transaction leading back to the owner of the site, app or other medium of the inventory.

0 = no

1 = yes

nodes

supplychain node object array; required

Array of SupplyChainNode objects in the order of the chain. In a complete supply chain, the first node represents the initial advertising system and seller ID involved in the transaction; in other words, the owner of the site, app, or other medium. In an incomplete supply chain, it represents the first known node. The last node represents the entity sending this bid request.

ver

string; required

Version of the supply chain specification in use, in the format of major.minor. The current version in use = 1.0.

SupplyChainNode object

AttributeTypeDescription

asi

String; required

The canonical domain name of the SSP, Exchange, Header Wrapper, etc system that bidders connect to. This may be the operational domain of the system, if that is different than the parent corporate domain, to facilitate WHOIS and reverse IP lookups to establish clear ownership of the delegate system. This should be the same value as used to identify sellers in an ads.txt file if one exists.

pid

string; must pass either pid or sid

The identifier associated with the seller or reseller account within the advertising system. This must contain the same value used in transactions (i.e. OpenRTB bid requests) in the field specified by the SSP/exchange. Typically, in OpenRTB, this is publisher.id. For OpenDirect it is typically the publisher’s organization ID.Should be limited to 64 characters in length.


sid

string; must pass either sid or pid

The identifier associated with the seller or reseller account within the advertising system. This must contain the same value used in transactions (i.e. OpenRTB bid requests) in the field specified by the SSP/exchange. Typically, in OpenRTB, this is publisher.id. For OpenDirect it is typically the publisher’s organization ID.Should be limited to 64 characters in length.

rid

String; optional

The OpenRTB RequestId of the request as issued by this seller.

name

String; optional

The name of the company (the legal entity) that is paid for inventory transacted under the given seller_id. This value is optional and should NOT be included if it exists in the advertising system’s sellers.json file.

domain

string; optional

The business domain name of the entity represented by this node. This value is optional and should NOT be included if it exists in the advertising system’s sellers.json file.

hp

integer; required

Indicates whether this node will be involved in the flow of payment for the inventory.

When set to 1, the advertising system in the asi field pays the seller in the sid field, who is responsible for paying the previous node in the chain. When set to 0, this node is not involved in the flow of payment for the inventory.

For version 1.0 of SupplyChain, this property should always be 1. It is explicitly required to be included as it is expected that future versions of the specification will introduce non-payment handling nodes. Implementers should ensure that they support this field and propagate it onwards when constructing SupplyChain objects in bid requests sent to a downstream advertising system.



Example: BidRequest.Source.ext With Open Measurement SDK extensions
"source" { 
  "ext": { 
    "omidpn": "MyIntegrationPartner", 
    "omidpv": "7.1" 
   } 
}, 
"imp" [{ 
  "banner": { 
    "api": [7] 
  } 
}]

Regs object

This object contains any legal, governmental, or industry regulations that apply to the request. 

AttributeTypeDescription
coppainteger; optionalFlag indicating if this request is subject to the COPPA regulations established by the USA FTC, where 0 = no, 1 = yes.
extobject; optionalPlaceholder for exchange-specific extensions to OpenRTB.

Regs.ext

AttributeTypeDescription
gdprinteger; optionalPossible values: 0 or 1 to indicate whether or not the impression is GDPR regulated.

us_privacy

string

OpenRTB v2.2 to 2.5 only: he CCPA compliance string for requests coming from California (U.S).

For OpenRTB v2.1 and below, see 58525258.

Send this flag either in Regs.ext or User.ext, but Regs.ext takes priority.
Example: Regs With GDPR Extension.
"regs": {"ext": {"gdpr": 1}}‍‍‍‍‍‍‍

Imp object

Each impression object can contain one object from each video/native/banner object, but PubMatic considers only a maximum of 2.    
AttributeTypeDescription
idstring; requiredA unique identifier for this impression within the context of the bid request (typically, starts with 1 and increments).
tagidstring; optional

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

  • 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.
banner object; optionalA banner object is required if this impression is offered as a banner ad opportunity.
native object; optionalA Native object; required if this impression is offered as a native ad opportunity
video object; optionalA Video object required if this impression is offered as a video ad opportunity.
instlinteger; optional1 = the ad is interstitial or full screen, 0 = not interstitial.
bidfloorfloat; recommendedMinimum bid for this impression expressed in CPM.
bidfloorcur string; recommendedCurrency specified using ISO-4217 alpha codes.

iframebuster

string array; optionalArray of exchange-specific names of supported iframe busters.
secureinteger; recommendedFlag 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.
pmp object; optionalA PMP Object containing any private marketplace deals in effect for this impression.
metric object array; optionalAn array of the Metric object.

displaymanager

string; optional

Name of ad mediation partner, SDK technology, or player responsible for rendering ad (typically video or mobile). Used by some ad servers to customize ad code by partner. Recommended for video and/or apps.

displaymanagerver

string; optional

Version of ad mediation partner, SDK technology, or player responsible for rendering ad (typically video or mobile). Used by some ad servers to customize ad code by partner. Recommended for video and/or apps.

exp

integer; optional

Advisory as to the number of seconds that may elapse between the auction and the actual impression (CTV requirement).

ext object; optionalPlaceholder for exchange-specific extensions to OpenRTB

Imp.ext

AttributeTypeDescription
pmZoneIdstring; optionalUsed to pass zone ID for reporting.
viewabilityvendorsstring array; optionalContains a list of viewability vendors supported by publishers
testcridstring; optional
  • 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.
skadn object; recommended for iOS 14

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.

key_valstring; optional

Key-value pair information to be passed to the SSP platform. Each key value pair will be separated by a vertical bar and each value will be separated by a comma.
For example, "key_val"="key1=V1,V2,V3|key2=v1|key3=v3,v5"

  • If we receive this also along with app.ext.key_val/site.ext.key_val, then imp.ext.key_val will take precedence over app.ext.key_val/site.ext.key_val for the impression.
  • Maximum length supported: 5100 ASCII characters. Strings greater than this length will be truncated and used/passed-further.
rewardinteger; optional

Only supported values is 1, which indicates the video is non-skippable-reward-video.

When the value = rewarded, these parameters are ignored in requests:

    • video.skip
    • video.skipmin
    • video.skipafter

Multi-format requests are supported for video object/request, and will be ignored for banner object/request.

is_rewarded_inventoryboolean; optional

Only supported value is true, which indicates the video is non-skippable-reward-video.

When the value = rewarded, these parameters are ignored in requests:

    • video.skip
    • video.skipmin
    • video.skipafter

Multi-format requests are supported for video object/request, and will be ignored for banner object/request.

rewarded

integer; optional

Only supported value is 1, which indicates the video is non-skippable-reward-video.

These parameters will be ignored when the value = 1:

    • video.skip
    • video.skipmin
    • video.skipafter

Multi-format requests are supported for video object/request, and will be ignored for banner object/request.

 Example: Imp with viewabilityvendors extension

Bid {
"imp": [
        {
         "ext": {
                "viewabilityvendors" : [ "moat.com", "whiteops.com" ]
          }
        }
       ]

}

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

Metric object

AttributeTypeDescription
typestring; required

Type of metric being presented using exchange-curated string names, which should be published to derived bidders.

PubMatic supports three types:

  • click_through_rate
  • viewability
  • session_depth
valuefloat; requiredNumber representing the value of the metric. Probabilities must be in the range of 0.0 - 1.0.
vendorstring; best practiceSource 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.

Banner object

AttributeTypeDescription
winteger; requiredWidth of the impression in pixels.
hinteger; requiredHeight of the impression in pixels.
battrinteger array; optionalBlocked creative attributes.
btype

integer array;

optional

Blocked banner ad types:

1 = XHTML text ad

2 = XHTML banner ad

3 = JS

4 = iframe

posinteger; optionalAd position on screen.
topframeinteger; optionalIndicates if the banner is in the top frame as opposed to an iframe, where 0 = no, 1 = yes.
expdirinteger array; optionalDirections in which the banner may expand.
format object array; recommended

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

Limitation: 4 objects max.

apiinteger array; recommended

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

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.

Format object

AttributeTypeDescription
winteger; requiredBanner width in device independent pixels (DIPS).
hinteger; requiredBanner height in device independent pixels (DIPS).
BidRequest.imp.banner.format sample JSON
{
	"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": {
			"": {
				"complete": 0,
				"ver": "1.0",
				"nodes": [{
					"asi": "pubmatic.com",
					"sid": "156078",
					"rid": "6503ED1F-B749-4215-9721-0EA5A7054F2F",
					"hp": 1
				}]
			}
		}
	}
}schain

Video object

AttributeTypeDescription
protocolInteger; deprecated

Deprecated in favor of protocols.

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

protocolsinteger; required

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

mimesstring array; required


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
linearityinteger; best practiceIndicates if the impression is linear or nar. 1=Linear/In-Stream and 2=Non-Linear/Overlay.
mindurationinteger; requiredMinimum video ad duration in seconds
maxdurationinteger; required

Maximum video ad duration in seconds. 

apiinteger array; required (if VPAID inventory)

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

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.

winteger; requiredWidth of the video player in pixels.
hinteger; requiredHeight of the video player in pixels.
startdelayinteger; best practice (if in-stream)Indicates the start delay in seconds for pre-roll, mid-roll, or
post-roll ad placements. 
placementinteger; best practice

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).
maxbitrateinteger; best practice for mobileMaximum bit rate in Kbps.
playbackmethodinteger array; best practiceDefines 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 )
skipinteger; optionalIndicates if the player will allow the video to be skipped, where 0 = no, 1 = yes.
skipmininteger; optionalVideos of total duration greater than this number of seconds can be skippable; only applicable if the ad is skippable.
skipafterinteger; optionalNumber of seconds a video must play before skipping is enabled; only applicable if the ad is skippable.

boxingallowed

integer; optional

Indicates if letter-boxing of 4:3 content into a 16:9 window is allowed, where 0 = no, 1 = yes.

posinteger; optionalAd 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)
battrinteger array; optionalBlocked creative attributes.
ext object; optionalPlaceholder for exchange-specific extensions to OpenRTB.

Video.ext

AttributeTypeDescription
video_skippableinteger; best practiceIndicator for ability to skip video 0/1.
rewardedinteger; optional

Only supported value is 1, which indicates the video is non-skippable-reward-video.

These parameters will be ignored when the value is 1:

  • video.skip, video.skipmin
  • video.skipafter
videotypestring; optional

Only supported value = rewarded, which indicates the video is non-skippable-reward-video.

These parameters will be ignored when the value = rewarded:

    • video.skip
    • video.skipmin
    • video.skipafter
is_rewardedboolean; optional

Only supported value = true, which indicates the video is non-skippable-reward-video.

These parameters will be ignored when the value = true:

    • video.skip
    • video.skipmin
    • video.skipafter

Native object

To learn more about Native requests, see https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-Native-Ads-Specification-1-1_2016.pdf .

AttributeTypeDescription
requeststring; required

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 

verstring/ optionalVersion of the Native Ad Specification to which request complies; best practice for efficient parsing.
apiinteger array; optional

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

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.

PMP object

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.

AttributeTypeDescription
deal object array; optionalArray of deal objects (50 max), that convey the specific deals applicable to an impression.

Deal object

You must first set up the PMP deal ID in the PubMatic platform before you can pass it. You must also create a deal-level flag in PubMatic to instruct the system to ignore the deal unless it is explicitly sent in an ad request. 
AttributeTypeDescription
idstring; requiredA unique identifier for the direct deal. Maximum string length is 64.

Site object

AttributeTypeDescription
idstring; optional

Exchange-specific site ID.

  • 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.
catstring array; optionalArray of IAB content categories of the site.
pagestring; optionalURL 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.
refstring; optionalReferrer URL that caused navigation to the current page.
pagecatstring array; optionalArray of IAB content categories that describe the current page or view of the site.
keywords string; optional

Comma separated list of keywords about the site. The parameter will be passed as-is to DSP when available in publisher request.

Maximum length supported: 1024 ASCII characters. Strings greater than this length will be truncated and used/passed-further.

publisher object; requiredDetails about the Publisher
content object; optionalDetails about the content within the site.
ext object; optionalPlaceholder for exchange-specific extensions to OpenRTB.

Site.ext

AttributeTypeDescription
key_valstring; optional

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

App object

AttributeTypeDescription
idstring; optional

Exchange-specific ID.

  • When using multi-site support, use the PubMatic site id. You must maintain the mapping of your publisher site id to the PubMatic site id.
  • Send both the tag id and PubMatic site id in the request (highly recommended). If you can send only the tag id in the request, PubMatic will derive the site id from imp[0].tagid.
  • If you do not want to modify the app body, then send PubMatic site id in the PubMatic end point URL.
namestring; optionalApp name (may be aliased upon request)
keywordsstring; optional

Comma separated list of keywords about the app. The parameter will be passed as-is to DSP when available in publisher request.

Maximum length supported: 1024 ASCII characters. Strings greater than this length will be truncated and used/passed-further.

publisher ObjectDetails about the Publisher
bundlestring; optionalApplication bundle or package name. Intended to be a unique ID across exchanges.
domainstring; optionalDomain of the app.
storeurlstring; optionalApp store URL for an installed app; for QAG 1.5 compliance.
catstring array; optionalArray of IAB content categories of the app. See List 5.1 in https://www.iab.com/wp-content/uploads/2015/06/OpenRTB-API-Specification-Version-2-3.pdf.
verstring; optionalApplication version
paidinteger; optional0=app is free, 1=app is a paid version

pagecat

string array

Array of IAB content categories that describe the current page or view of the app.

sectioncat

string array

Array of IAB content categories that describe the current section of the app.

privacypolicy

integer

Indicates if the app has a privacy policy, where 0 = no, 1 = yes.

content object; optionalDetails of the content in the app.
extobject; optionalPlaceholder for exchange-specific extensions to OpenRTB

App.ext

AttributeTypeDescription
key_valstring; optional

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

Publisher object

AttributeTypeDescription
idstring; optionalExchange-specific publisher ID

Content object

Attribute

Type

Description

id

string; optional

ID uniquely identifying the content.

episode       

integer; optional

Episode number (typically applies to video content).

title         

string; optional

Content title.

series        

string; optional

Content series.

season        

string; optional

Content season; typically for video content; for example, “Season 3”.

producer      

producer object; optional

Details about the content Producer

url           

string; optional

URL of the content, for buy-side contextualization or review.

cat           

string array; optional

Array of IAB content categories that describe the content producer.

artist

string; optional

Artist credited with the content.

genre

string; optional

Genre that best describes the content (for example, rock, pop, jazz).

album

string; optional

Album to which the content belongs; typically for audio.

isrc

string; optional

International Standard Recording Code conforming to ISO-3901.

prodq

integer; optional

Production quality.

context

integer; optional

Type of content (for example, game, video, text).

data

object array; optional

Additional content data. Each data object represents a different data source.

videoquality

integer; optional

Video quality per IAB’s classification.

contentrating

string; optional

Content rating; for example, MPAA.

userrating    

string; optional

User rating of the content; for example, number of stars, likes, and so on.

qagmediarating

integer; optional

Media rating per QAG guidelines.

keywords      

string; optional

Comma separated list of keywords describing the content.

livestream    

integer; optional

0 = not live, 1 = content is live; for example, stream, live blog.

sourcerelationship

integer; optional

0 = indirect, 1 = direct.

len           

integer; optional

Length of content in seconds; appropriate for video or audio.

language      

string; optional  

Content language using ISO-639-1-alpha-2.

embeddable    

integer; optional

Indicator of whether or not the content is embeddable where 0 = no, 1 = yes.

ext           

object; optional

Placeholder for exchange-specific extensions to OpenRTB.

Producer object

AttributeTypeDescription
idstring; optionalContent producer or originator ID. Useful if content is syndicated and may be posted on a site using embed tags.
name  string; optionalContent producer or originator name; for example, “Warner Bros”.
cat   string array; optionalArray of IAB content categories that describe the content producer.
domainstring; optionalHighest level domain of the content producer; for example, “producer.com”.
ext   object; optionalPlaceholder for exchange-specific extensions to OpenRTB.

Device object

AttributeTypeDescription
uastring; optionalBrowser user agent string.
dntIntegerStandard "Do Not Track" flag as set in the header by the browser, where 0 = tracking is unrestricted, 1 = do not track
devicetypeinteger; required for CTV publishersThe general type of device. See List 5.17 in https://www.iab.com/wp-content/uploads/2015/06/OpenRTB-API-Specification-Version-2-3.pdf.
makestring; optionalDevice make; for example, "Apple".
modelstring; optionalDevice model; for example, "iPhone".
osstring; optionalDevice operating system; for example, "iOS".
osvstring; optionalDevice operating system version; for example, "3.1.2".
jsIntegerSupport for JavaScript, where 0=no, 1=yes.
languagestring; optionalBrowser language using ISO-639-1-alpha-2.
geo
object; optionalLocation 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.
Ipstring; requiredIPv4 address closest to device as IPv6. Either of ip/ipv6 is required.
Ipv6string; requiredIP address closest to device as IPv6. Either of ip/ipv6 is required.
ifastring; recommendedID sanctioned for advertiser use in the clear; that is, not hashed.
didsha1string; optionalHardware device ID ; for example, IMEI; hashed via SHA1.
didmd5string; optionalHardware device ID; for example, IMEI; hashed via MD5.
dpidsha1string; optionalPlatform device ID (for example, Android ID), hashed via SHA1.
dpidmd5string; optionalPlatform device ID (for example, Android ID), hashed via MD5.

macsha1

string; optional

MAC address of the device; hashed via SHA1.

macmd5

string; optional

MAC address of the device; hashed via MD5.

hwv

string; optional

Device hardware version. For example, iPhone 5s.

h

integer; optional

Physical height of the screen in pixels.

w

integer; optional

Physical width of the screen in pixels.

ppi

integer; optional

Device screen pixels per inch.

pxratio

float; optional

The ratio of physical pixels to device independent pixels.

connectiontype

integer; optional

Network connection type.

lmt

integer; recommended

Limit ad tracking signal commercially endorsed (e.g., iOS, Android), where 0 = tracking is unrestricted, 1 = tracking must be limited per commercial guidelines.

geofetch

integer; optional

Indicates if the geolocation API will be available to JavaScript code running in the banner, where 0 = no, 1 = yes.

mccmnc

string; optional

Mobile carrier as the concatenated MCC-MNC code; for example, 310-005 identifies Verizon Wireless CDMA in the US.

See https://en.wikipedia.org/wiki/Mobile_country_code  for more examples. Note that the dash between the MCC and MNC parts is required to remove parsing ambiguity.

devicetype

integer; optional

The general type of device.

flashver

string; optional

Version of Flash supported by the browser.

ifa

string; optional

ID sanctioned for advertiser use in the clear; in other words, not hashed.

extobject; optionalPlaceholder for exchange-specific extensions to OpenRTB.

Device.ext

AttributeTypeDescriptionExample
ifvstring;

optional, recommended for iOS 14+

All integration and ad types supported.

IFV of the device in that publisher.

  • Recommended to pass especially when IDFA (BidRequest.device.ifa) is unavailable or all zeros.
  • Maximum number of characters in string: 256 (ASCII)
  • If string length is exceeded it will be truncated when sent to DSP.
  • Listed as ifv to match ifa field format.

ifv: "336F2BC0-245B-4242-8029-83762AB47B15"

ifa_type

string


Indicates origin or type of the device-id passed in device.ifa
Expected values:
 
"aaid", // - Android id
"idfa", // - Apple id
"rida", // - Roku id
"afai", // - Amazon Fire id
"msai", // - Microsoft id
"dpid", // - the generic “device provided id”, but based on historical usage
"ppid", // - publisher provided id
"sspid", // - SSP provided id
"sessionid",// - session id / synthetic id
"ifa_type": "aaid"
attsinteger; optional, recommended for iOS 14+

(iOS Only) An integer passed to represent the app's app tracking authorization status.

Values:

0 = not determined
1 = restricted
2 = denied
3 = authorized

atts: 3
ip_lessinteger; optional


Supported for all platforms and ad types

Indicate whether device.ip field contains the actual client ip address.

Values:

1 = device.ip contains the actual client ip address
0 = device.ip does not contain the actual client ip address

  • When parameter is absent, DSPs may assume value as 0 which indicates that the client ip address is present.
  • For ip_less = 1 traffic, the forwarding server ip address should be included in the device.ip field.
  • Any value other than 0 or 1 will cause this param to be discarded.
  • If device.ip is not present in request, this parameter will be ignored.

ip_less: 1

Geo object

AttributeTypeDescription
latfloat; highly recommendLatitude from -90.0 to +90.0, where negative is south
lonfloat; highly recommendLongitude from -180.0 to +180.0, where negative is west.
typeinteger; recommendSource of location data; recommended when passing lat/lon.
countrystring; optionalCountry code using ISO-3166-1-alpha-3.
regionstring; optionalRegion code using ISO-3166-2; 2-letter state code if USA
metrostring; optionalGoogle metro code; similar to but not exactly Nielsen DMAs.
citystring; optionalCity using United Nations Code for Trade & Transport Locations. It must not be encoded.
zipstring; optionalZip or postal code

accuracy

integer; optional

Estimated location accuracy in meters; recommended when lat/lon are specified and derived from a device’s location services (for example, type = 1).

Note that this is the accuracy as reported from the device. Consult OS specific documentation (for example, Android, iOS) for exact interpretation.

lastfix

integer; optional

Number of seconds since this geolocation fix was established.

Note that devices may cache location data across multiple fetches. Ideally, this value should be from the time the actual fix was taken.

ipservice

integer; optional

Service or provider used to determine geolocation from IP address if applicable (for example, type = 2).

utcoffsetinteger; optionalLocal time as the number +/- of minutes from UTC

User object

AttributeTypeDescription
buyeruid string; recommendedBuyer-specific ID for the user as mapped by the exchange for the buyer; recommended when PubMatic user ID exists.
yob integer; optionalYear of birth as a 4-digit integer.
genderstring; optionalGender, where "M" = male, "F" = female, "O" = known to be other (i.e., omitted is unknown).
geo object; optionalLocation 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 object.
idstring; optionalExchange-specific ID for the user. At least one of id or buyerid is recommended. Buyerid will be preferred by PubMatic.
ei ds object array; optional

An array of Extended ID objects.

The ad server supports 25 eids.
keywordsstring; optional

Comma separated list of keywords, interests, or intent. The parameter will be passed as-is to DSP when available in publisher request. It will be discarded for GDPR requests.

Maximum length supported: 1024 ASCII Characters. Strings greater than this length will be truncated and used/passed-further.

extobject; optionalPlaceholder for exchange-specific extensions to OpenRTB

User.ext

AttributeTypeDescription
gdpr integer; optionalPossible values: 0 or 1 to indicate if the impression is GDPR regulated or not.
consentstring; optionalIf the above flag is 1, then this string gives consent information of various vendors
consented_providers_setting object; optional

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.

Specific to Google Exchange Bidding Integrations and applicable only when Regs.ext.gdpr=1.

us_privacy

string; optional

OpenRTB 2.1 and below: the CCPA compliance string for requests coming from California (U.S).

For OpenRTB 2.2 and above, see 58525258 .

eids

eid object array

Consumer identifiers support in the OpenRTB.


Example: User With GDPR Extension.
"user": {
  "ext": {
    "gdpr": 1,"consent": "BONihAGONihAGABABAENAQ____AArABAAAA"
  }
}


Example: User With Google Exchange Bidding Extensions.
"user": { 
  "ext": { 
    "consented_providers_settings": {
      "consented_providers": [123, 456]
    } 
  } 
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

User.ext.consentedProvidersSetting

AttributeTypeDescription
consented_providersstring array; optionalList of provider_ids that has user consent

Eids object

AttributeTypeDescription
source string; required

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

Maximum size of 64 bytes is supported.
uids object array; required

Extended ID user ID objects.

Each eid object supports 3 uids.

The ad server supports a total of 25 eids.

UIDs object

AttributeTypeDescription
id string; required

Cookie or platform native of the identifier

Maximum size of 384 bytes is supported.
atypeinteger; optionalType of user agent the match is from. See agent types table below.

User agent types

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
Example: Passing UIDs via OpenRTB spec
{
   "user": {
      "eids": [
         {
            "source": "criteo.com",
            "uids": [
               {
                  "id": "Y59Jp181QXZzNUElMkIlMkJnQVc3VWtEMlpXRE5MUSUzRCUzRA",
                  "atype": 1
               }
            ]
         },
         {
            "source": "pubcid.org",
            "uids": [
               {
                  "id": "8e66e858-58de-4c6d-8155-fac76663d5e1",
                  "atype": 1
               }
            ]
         },
         {
            "source": "adserver.org",
            "uids": [
               {
                  "id": "0958f39a-b7e3-458e-ba16-ab9067842bd6",
                  "atype": 1,
                  "ext": {
                     "rtiPartner": "TDID"
                  }
               }
            ]
         },
         {
            "source": "id5-sync.com",
            "uids": [
               {
                  "id": "ID5-ZHMOwyxevpXoi3pdrk0hypASGQwi2WzL8y-U15BdSQ",
                  "atype": 1
               }
            ]
         }
      ]
   }
}

⇧ Top

Do you have feedback on this document? Let us know: email us.