OpenRTB 2.3 Bid Request Objects and Parameters

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

PubMatic supports the following parameters from OpenRTB 2.3:

User Object:

    • eids

Extended IDs Object:

    • source
    • uids

Extended ID UIDs Object:

    • id
    • atype

Source Object:

    • pchain

BidRequest

    • source

Impression

    • metric

Bid Request and Response gzip Compression

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

You can also receive a gzip-compressed bid responses through the OpenRTB API for publishers with the following requirements:

  • Request header Accept-Encoding has value, gzipAND
  • Response size is greater than 512 bytes, AND
  • 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 Content-Encoding of PubMatic's response contains the value,  gzip.

Objects and Parameters Supported

The following tables list supported objects and attributes with required/optional indicators. Object names ending with .ext are PubMatic supported extensions to the oRTB spec. The PubMatic system considers requests that are missing required objects and parameters as invalid. 

BidRequest

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

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

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

Required
user Object

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

Optional
app Object

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

Auction Type

1 = Publisher first price auction

2 = (Default) 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; for example, "ford.com".

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

Optional
regs ObjectA Regs object that specifies any industry, legal, or governmental regulations in force for this request.Optional
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
ext.rewardInteger

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.

Optional
ext.is_rewarded_inventoryBoolean

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.

Optional

Imp

 Expand for bidrequest.imp attributes...
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.

  • 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.Optional
bidfloorcur StringCurrency specified using ISO-4217 alpha codes.Optional

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.Optional
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 OpenRTGOptional

Banner

 Expand for 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.

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.

Optional
Format
 Expand for bidrequest.imp.banner.format attributes…
AttributeTypeDescriptionScope
wIntegerWidth in device independent pixels (DIPS).Required
hIntegerHeight in device independent pixels (DIPS).Required
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": {
			"schain": {
				"complete": 0,
				"ver": "1.0",
				"nodes": [{
					"asi": "pubmatic.com",
					"sid": "156078",
					"rid": "6503ED1F-B749-4215-9721-0EA5A7054F2F",
					"hp": 1
				}]
			}
		}
	}
}

Native

 Expand for bidrequest.imp.native attrbutes...
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
apiInterger array

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.

Optional

To learn more about native request and response details see…

Video

 Expand for bidrequest.imp.video attrbutes......
AttributeTypeDescriptionScope
protocolInteger
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 ).

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
ext.rewardedInteger

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

When the value is 1, video.skip, video.skipmin and video.skipafter parameters will be ignored in request.

Optional
ext.videotypeString

Only supported value = rewarded, 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
Optional

PMP

 Expand for bidrequest.imp.pmp attrbutes......

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 for bidrequest.imp.metric attrbutes......
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 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

Site

 Expand for bidrequest.site attributes......
AttributeTypeDescriptionScope
idString

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.
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 for custom targeting.

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"



BidRequest.ext

 Expand for 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
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

 Expand for bidrequest.ext.wrapper attributes......
AttributeTypeDescriptionScope
versionIntegerVersion ID of the WrapperOptional
profileIntegerProfile ID of the WrapperOptional
Example: Imp With viewabilityvendors Extension.
Bid { 
"imp": [
       {
        "ext": {
               "viewabilityvendors" : [ "moat.com", "whiteops.com" ]
         } 
       }
      ]
}

Object: Deal

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

Object: App

AttributeTypeDescriptionScope
idString

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

AttributeTypeDescriptionScope
key_valString

Key-value pair information to be passed to the SSP platform for custom targeting.

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"


Object: Content

AttributeTypeDescriptionScope
idString   ID uniquely identifying the content.Optional
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; for example, “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; for example, MPAA.Optional
userrating    String   User rating of the content; for example, number of stars, likes, and so on.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; for example, 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
idStringContent 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; for example, “Warner Bros”.Optional
cat   String arrayArray of IAB content categories that describe the content producer.Optional
domainString   Highest level domain of the content producer; for example, “producer.com”.Optional
ext   ObjectPlaceholder for exchange-specific extensions to OpenRTB.Optional

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. See List 5.17 in https://www.iab.com/wp-content/uploads/2015/06/OpenRTB-API-Specification-Version-2-3.pdf.Required for CTV publishers
makeStringDevice make; for example, "Apple".Optional
modelStringDevice model; for example, "iPhone".Optional
osStringDevice operating system; for example, "iOS".Optional
osvStringDevice operating system version; for example, "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; that is, not hashed.Optional
didsha1StringHardware device ID ; for example, IMEI; hashed via SHA1.Optional
didmd5StringHardware device ID; for example, IMEI; hashed via MD5.Optional
dpidsha1StringPlatform device ID (for example, Android ID), hashed via SHA1.Optional
dpidmd5StringPlatform device ID (for example, Android ID), hashed via MD5.Optional

Object: Geo

AttributeTypeDescriptionScope
latFloatLatitude from -90.0 to +90.0, where negative is southHighly Recommended
lonFloatLongitude from -180.0 to +180.0, where negative is west.Highly Recommended
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.

First 3 valid objects are used and the rest discarded
Optional
extObjectPlaceholder for exchange-specific extensions to OpenRTBOptional

Object: User.ext

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.

Specific to Google Exchange Bidding 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.

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


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]
    } 
  } 
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Object: consented_providers_setting

AttributeTypeDescriptionScope
consented_providersString arrayList of provider_ids that has user consentOptional

Object: eids (Extended IDs)

AttributeTypeDescriptionScope
source String

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

Maximum size of 64 bytes is supported.
Required
uidsObject Array

Array of extended ID UID objects.

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

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

AttributeTypeDescriptionScope
gdprIntegerPossible values: 0 or 1 to indicate whether or not the impression is gdpr regulated.Optional
Send this flag either in Regs.ext or User.ext, but Regs.ext takes priority.
Example: Regs With GDPR Extension.
"regs": {"ext": {"gdpr": 1}}‍‍‍‍‍‍‍

Object: Publisher

AttributeTypeDescriptionScope
idStringExchange-specific publisher IDOptional

Object: Source

AttributeTypeDescriptionScope
pchainStringPayment ID chain string containing embedded syntax described in the TAG Payment ID Protocol v. 1.0Best Practice

Object: Source.ext

AttributeTypeDescriptionScope
omidpnString Identifier of the OM SDK integration. This is the same as the "name" parameter of the OMID Partner object.Optional
omidpvStringVersion of the OM SDK integration. This is the same as the "versionString" parameter of the OMID Partner object.Optional
Example: BidRequest.Source.ext With Open Measurement SDK Extensions.
"source" {  
  "ext": {  
    "omidpn": "MyIntegrationPartner",  
    "omidpv": "7.1"  
   }  
},  
"imp" [{  
  "banner": {  
    "api": [7]  
  }  
}]


⇧ Top

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

Table of Contents