OpenWrap CTV Video API Specification
OpenWrap supports CTV inventory using GET/POST methods. OpenWrap accepts BidRequest in OpenRTB 2.5 format for POST API, and the same specification for GET API, but using only key/value pairs.
POST API
OpenWrap supports CTV inventory as defined in the Object: Video section of the IAB OpenRTB API Specification Version 2.5, with some minor differences. For example, PubMatic's CTV BidRequest implementation supports multiple video impressions. The following sample shows how a typical impression might appear.
The next section provides example JSON payloads that illustrate unsupported features of OpenRTB 2.5.
POST API limitations
OpenWrap's HTTP POST method ignores banner, native, and audio objects.
Unsupported examples
The table below lists JSON payload snippets that illustrate OpenRTB 2.5 structures that OpenWrap does not support at this time.
| Object | Description |
|---|---|
BidRequest.Imp.Banner | Full banner object unsupported. OpenWrap ignores the impression object if it contains a banner object. OpenWrap removes a banner object from an impression when it is specified with a video object in the same impression. |
BidRequest.Imp.Audio | OpenWrap ignores impression object if it contains an unsupported audio object. OpenWrap removes an audio object from an impression if it is specified with video object in the same impression. |
BidRequest.Imp.Native | Full native object not supported. OpenWrap ignores impressions when they contain a native object. OpenWrap removes the native object from the impression if it is specified with a video object in the same impression. |
GET API parameters
Using HTTP GET, you'll send all BidRequest parameters and values encoded in the URL. The sections below show the Required parameters, followed by the Optional parameters, and a brief example for each.
Required parameters
OpenWrap rejects BidRequests that do not include the parameters in the following table.
| OpenWrap Key | ORTB 2.5 Key | Type | Description | Example |
|---|---|---|---|---|
imp.tagid | bidrequest.imp[0].tagid | String | The identifier for a specific ad placement or ad tag that initiated the auction. Use to troubleshoot issues and to help buyers optimize bids; for example, you can specify | /ID/SampleAdUnit |
imp.vid.mimes | bidrequest.imp[0].video.mimes | String Array | Comma separated String Array. Supported content MIME types include:: | video%2F3gpp,video%2Fmp4,video%2Fwebm |
|
| String | Exchange-specific publisher ID. Requires at least one of either, site.pub.id or app.pub.id. | 12345 |
req.ext.wrapper.profileid | bidrequest.ext.wrapper.profileid | Integer | OpenWrap requires a specific profile id for inventory type. | 12345 |
Optional parameters
Use the objects/parameters below as needed on a case-by-case basis.
BidRequest object
The BidRequest object is the top-level parent for the other objects described in later sections. The next table shows the OpenWrap key to reference Req objects, and for comparison, the equivalent OpenRTB 2.5 key to reference BidRequest objects.
| OpenWrap Key | ORTB 2.5 Key |
|---|---|
req.[param] | bidrequest.[param] |
The following table lists the parameters available to let you configure Req objects.
| Parameter | Type | Description | Example |
|---|---|---|---|
id | String | The unique ID of the | 45067fec-eab7-4ca0-ad3a-87b01f21846a |
test | Integer Default: | Boolean value that indicates test mode, in which auctions are not billable; for example, 0 = live mode, 1 = test mode. | 1 |
at | Integer Default: | Auction type: | 2 |
tmax | Integer | Maximum time in milliseconds the exchange allows bids to be received, including Internet latency to avoid timeout. Supersedes any prior guidance from the exchange. Set this in the OpenWrap configuration file. | 100 |
bseat | String Array | Blocklist of buyer seats (for example, advertisers, agencies), restricted from bidding on the impression. Bidders and the exchange must make the connection between seat IDs and the buyer’s customers which the IDs represent. Use only one | nike,puma |
wseat | String Array | White list | nike,puma |
allimps | Integer Default: 0 | Flags whether the exchange can verify that the offered impressions represent all available impressions in context (that is, all on the web page, or all video spots such as pre, mid, and post-roll), that support road-blocking. 0 = no or unknown, 1 = yes, the impressions offered represent all available. | 1 |
wlang | String Array | White list of creative languages in ISO-639-1-alpha-2 alpha codes. Omission implies no specific restrictions, but buyers should consider language attributes in the | en,ca |
cur | String Array | An array of allowed currencies for bids on a Currently, server-side OpenWrap works with only USD… Server-side OpenWrap replaces any other currency with USD. | USD |
bcat | String Array | Blocked advertiser categories using the IAB content categories. | IAB-1,IAB-2 |
badv | String Array | Blocklist of advertisers by their domains; for example, ford.com. | ford.com,puma.com |
bapp | String Array | Blocklist of apps by their platform-specific, exchange-independent identifiers.
| com.foo.mygame,1234 |
Info
The BidRequest object supports ad pods. See AdPod object for details.
Source object
The Source object is a child of BidRequest described above. The next table shows the OpenWrap key to reference Src objects, and for comparison, the equivalent OpenRTB 2.5 key to reference Source objects.
| OpenWrap Key | ORTB 2.5 Key |
|---|---|
src.[param] | bidrequest.source.[param] |
The following table lists the parameters available to let you configure Src objects.
| Parameter | Type | Description | Example |
|---|---|---|---|
fd | Integer | Entity responsible for the final impression sale decision, where 0 = exchange, 1 = upstream source. | 1 |
tid | String | Transaction ID common across all participants in a bid request, and potentially may represent multiple exchanges. | 45067fec-eab7-4ca0-ad3a-87b01f21846a |
pchain | String | Payment ID chain string containing embedded syntax described in the TAG Payment ID Protocol v1.0. | 5d62403b186f2ace:158309 |
Impression object
The Imp object is a child of BidRequest described above, and Imp objects are typically the parent of Video. The next table shows the OpenWrap key to reference Imp objects, and for comparison, the equivalent OpenRTB 2.5 key to reference Impression objects.
| OpenWrap Key | ORTB 2.5 Key |
|---|---|
imp.[param] | bidrequest.imp[0].[param] |
The following table lists the parameters available to let you configure Imp objects.
| OpenWrap Key | Type | Description | Example |
|---|---|---|---|
id | String | A unique identifier for this impression within the context of the bid request (typically, starts with 1 and increments. | 123 |
displaymanager | String | 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 a partner. Recommended for video and/or apps. | PubMaticSDK |
displaymanagerver | String | A 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 a partner. Recommended for video and/or apps. | PubMaticSDK-1.0 |
instl | Integer Default: 0 | 0 = ad is not interstitial. 1 = ad is interstitial or full screen. | 1 |
bidfloor | Float | The minimum bid for this impression expressed in CPM. | 1.1 |
bidfloorcur | String | Currency specified using ISO-4217 alpha codes. This may be different from bid currency returned by the bidder if this is allowed by the exchange. | USD |
clickbrowser | Integer | Indicates the type of browser opened upon clicking the creative in an app. 0 = embedded 1 = native Note that the Safari View Controller in iOS 9.x devices is considered a native browser for purposes of this attribute. | 0 |
secure | Integer | Flag to indicate if the impression requires secure HTTPS URL creative assets and markup. 0 = non-secure 1 = secure If omitted, the secure state is unknown, but non-secure HTTP support can be assumed. | 1 |
iframebuster | String Array | An array of exchange-specific names of supported iframe busters. | 1 |
exp | Integer | Advisory as to the number of seconds that may elapse between the auction and the actual impression | 1 |
pmp | String | An oRTB 2.5 PMP object containing configuration JSON for any private marketplace deals active for the impression. Server-side OpenWrap… Forwards the PMP object unchanged to the Prebid Server. |
|
Info
The Impression object supports ad pods. See AdPod object for details.
PMP object
The PMP object is a parameter object of the Imp object. PMP objects in turn may encapsulate Deal and Extension objects, as described below.
| Parameter | Type | Description | Example |
|---|---|---|---|
| Integer Default: | Indicator of auction eligibility to seats named in the Direct Deals object 0 = all bids are accepted 1 = bids are restricted to the deals specified and the terms thereof. | 1 |
deals
| Object Array | Array of Deal objects that convey the specific deals applicable to an impression | See Deals section below. |
ext | Object | Placeholder for exchange-specific extensions to OpenRTB. | See Ext section below. |
Deal object
The Deal object contains configuration details for Deals belonging to the current Imp, and are encapsulated by a PMP object.
| Parameter | Type | Description | Example |
|---|---|---|---|
id | String: Required | A unique identifier for the direct deal. | 1234 |
bidfloor | Float Default: | Minimum bid for this impression expressed in CPM. | 1.2 |
bidfloorcur | String Default: | Currency specified using ISO-4217 alpha codes. This may be different from bid currency returned by bidder if this is allowed by the exchange. | USD |
at | Integer | Optional override of the overall auction type of the bid request 1 = First Price 2 = Second Price Plus 3 = the value passed in bidfloor is the agreed upon deal price. Additional auction types can be defined by the exchange. | 1 |
wseat | String Array | Allowlist of buyer seats (for example, advertisers, agencies) allowed to bid on this deal. IDs of seats and the buyer’s customers to which they refer must be coordinated between bidders and the exchange a priori. Omission implies no seat restrictions. | nike,puma |
wadomain | String Array | Array of advertiser domains (for example, Omission implies no advertiser restrictions. | ad.com,page.com |
ext | Object | Placeholder for exchange-specific extensions to OpenRTB. | See Ext section below. |
Video object
The Video object is a child of the Impression object, described above. The next table shows the OpenWrap key to reference Vid objects, and for comparison, the equivalent OpenRTB 2.5 key to reference Video objects.
| OpenWrap Key | ORTB 2.5 Key |
|---|---|
imp.vid.[param] | bidrequest.imp[0].video.[param] |
The following table lists the parameters available to let you configure Vid objects.
| Parameter | Type | Description | Example |
|---|---|---|---|
minduration | Integer | Minimum video duration of ad (or ad pod) in seconds. | 5 |
maxduration | Integer | Maximum video duration of ad (or ad pod) in seconds . | 120 |
protocols | Integer Array | Array of supported video protocols. Specify at least one supported protocol in either the | 2,3,5,6,7,8 |
w | Integer | Width of the video player in device independent pixels (DIPS). | 320 |
h | Integer | Height of the video player in device independent pixels (DIPS). | 480 |
startdelay | Integer | Indicates the start delay in seconds for pre, mid, or post-roll ad placements. | 0 |
placement | Integer | Placement type for the impression. | 5 |
linearity | Integer | Determines whether the impression is linear, nonlinear, and so on. Leaving unspecified implies all are allowed. | 1 |
skip | Integer | Determines whether the user can skip the video ad. If a bidder sends markup/creative that is skippable, the | 1 |
skipmin | Integer | Videos of total duration greater than this number of seconds can be skippable; only applicable if the ad is skippable. | 1 |
skipafter | Integer | Number of seconds a video must play before skipping is enabled; only applicable if the ad is skippable. | 1 |
sequence | Integer | If the BidRequest offers multiple ad impressions, the sequence number facilitates coordinated delivery of multiple creatives. | 1 |
battr | Integer Array | Blocked creative attributes. | 1,2,3 |
maxextended | Integer | Maximum extended ad duration, if allowed.
| 10 |
minbitrate | Integer | Minimum bit rate in Kbps. | 1200 |
maxbitrate | Integer | Maximum bit rate in Kbps. | 2000 |
boxingallowed | Integer | Determines whether 4:3 content is letter-boxed into 16:9 aspect ratio. 0 = No. 1 = Yes. | 1 |
playbackmethod | Integer Array | Playback methods that may be in use. Unspecified implies that any method is possible. Typically only one method ever used. As a result, a future version of the specification may define this parameter as an integer. The best practice is to use only the first element of this array in preparation for this change. | 1 |
delivery | Integer Array | Supported delivery methods; for example, streaming, progressive. Unspecified implies that all are supported. | 2 |
pos | Integer | Ad position on screen. | 7 |
api | Integer Array | List of supported API frameworks for this impression. Unlisted APIs equal unsupported. | 2 |
Site object
The Site object is a child of BidRequest described above. The next table shows the OpenWrap key to reference Site objects, and for comparison, the equivalent OpenRTB 2.5 key to reference Site objects.
| OpenWrap Key | ORTB 2.5 Key |
|---|---|
site.[param] | bidrequest.site.[param] |
The following table lists the parameters available to let you configure Site objects.
| Parameter | Type | Description | Example |
|---|---|---|---|
id | String | Exchange-specific site ID | 123 |
name | String | Site name (may be aliasedat the publisher’s request). | EbayShopping |
domain | String | Domain of the site (for example, “mysite.foo.com”). | ebay.com |
cat | String Array | Array of IAB content categories of the site. | IAB1-5 |
sectioncat | String Array | Array of IAB content categories that describe the current section of the site. | IAB1-5 |
pagecat | String Array | Array of IAB content categories that describe the current page or view of the site. | IAB1-5 |
page | String | URL of the page where the impression will be shown. | http%3A%2F%2Febay.com%2Fhome |
ref | String | Referrer URL that caused navigation to the current page. | http%3A%2F%2Febay.com%2Fhome |
search | String | Search string that caused navigation to the current page. | NewCloths |
mobile | Integer | Indicates if the site has been programmed to optimize layout when viewed on mobile devices, where 0 = no, 1 = yes. | 1 |
privacypolicy | Integer | Indicates if the site has a privacy policy. 0 = No 1 = Yes. | 1 |
keywords | String | Comma separated list of keywords about the site . | Clothes |
The Site object can also contain the following parameter objects:
| Object | OpenWrap Key | ORTB 2.5 Key |
|---|---|---|
| Content | site.cnt.[param] | bidrequest.site.content.[param] |
| Publisher | site.pub.[param] | bidrequest.site.publisher.[param] |
App object
The App object is a child of BidRequest described above. The next table shows the OpenWrap key to reference App objects, and for comparison, the equivalent OpenRTB 2.5 key to reference App objects.
| OpenWrap Key | ORTB 2.5 Key |
|---|---|
app.[param] | bidrequest.app.[param] |
The following table lists the parameters available to let you configure App objects.
| OpenWrap Key | Type | Description | Example |
|---|---|---|---|
id | String | Exchange-specific app ID. | 1234 |
name | String | App name (may be aliasedat the publisher’s request). | MyFooGame |
bundle | String | A platform-specific application identifierintended to be unique to the app and independent of the exchange. On Android, this should be a bundle or package name (for example, com.foo.mygame). On iOS, it is typically a numeric ID | com.foo.mygame |
domain | String | Domainof the app (for example, “mygame.foo.com”) | mygame.foo.com |
storeurl | String | App store URL for an installed app; for IQG2.1 compliance. |
https://play.google.com/store/apps/details?id=com.foo.mygame
|
cat | String Array | Array of IAB content categories of the app. | IAB1-5,IAB1-6 |
sectioncat | String Array | Array of IAB content categories that describe the current section of the app. | IAB1-5 |
pagecat | String Array | Array of IAB content categories that describe the current page or view of the app. | IAB1-5 |
ver | String | Application version. | 1.1 |
privacypolicy | Integer | Indicates ifthe app has a privacy policy. 0 = No 1 = Yes | 1 |
paid | Integer | 0 = app is free 1 = the app is a paid version | 1 |
keywords | String | Comma separated list of keywordsabout the app. | Games |
The App object can also contain the following parameter objects:
| Object | OpenWrap Key | ORTB 2.5 Key |
|---|---|---|
| Content | app.cnt.[param] | bidrequest.app.content.[param] |
| Publisher | app.pub.[param] | bidrequest.app.publisher.[param] |
Publisher object
The Publisher object is a child of the Site and App objects, described above. The next table shows the OpenWrap keys to reference Pub objects, and for comparison, the equivalent OpenRTB 2.5 keys to reference Publisher objects.
| OpenWrap Key | ORTB 2.5 Key |
|---|---|
app.pub.[param] | bidrequest.app.publisher.[param] |
site.pub.[param] | bidrequest.site.publisher.[param] |
The following table lists the parameters available to let you configure Pub objects.
| Parameter | Type | Description | Example |
|---|---|---|---|
id | String | Exchange-specific publisher ID. | 5890 |
name | String | Publisher name (may be aliased at the publisher’s request). | TestPublisher |
cat | String Array | Array of IAB content categories that describe the publisher. | IAB1-5 |
domain | String | Highest level domain of the publisher; for example, “publisher.com”). | publisher.com |
Content object
The Content object is a child of the Site and App objects, described above. The next table shows the OpenWrap keys to reference Cnt objects, and for comparison, the equivalent OpenRTB 2.5 keys to reference Content objects.
| OpenWrap Key | ORTB 2.5 Key |
|---|---|
app.cnt.[param] | bidrequest.app.content.[param] |
site.cnt.[param] | bidrequest.site.content.[param] |
The following table lists the parameters available to let you configure Content objects.
| Parameter | Type | Description | Example |
|---|---|---|---|
id | String | ID uniquely identifying the content. | 381d2e0b-548d-4f27-bfdd-e6e66f43557e |
episode | Integer | Episode number. | 1 |
title | String | Content title. Video Examples: “Search Committee” (television), “A New Hope” (movie), or “Endgame” (made for web). Non-Video Example: “Why an Antarctic Glacier Is Melting So Quickly” (Time magazine article) | StarWars |
series | String | Content series. Video Examples: “The Office” (television), “Star Wars” (movie), or “Arby ‘N’ The Chief” (made for web). Non-Video Example: “Ecocentric” (Time Magazine blog). | StarWars |
season | String | Content season (for example, “Season 3”). | Season3 |
artist | String | Artist credited with the content. | GeorgeLucas |
genre | String | Genre that best describes the content (for example, rock, pop, etc). | Action |
album | String | Album to which the content belongs; typically for audio. | Action |
isrc | String | International Standard Recording Code conforming to ISO-3901. | 2 |
url | String | URL of the content, for buy-side contextualization or review. | http://www.pubmatic.com/test/ |
cat | String Array | Array of IAB content categories that describe the content producer. | IAB1-1,IAB1-2 |
prodq | Integer | Production quality. | 1 |
context | Integer | Type of content (game, video, text, etc.). | 1 |
contentrating | String | Content rating (for example, MPAA). | MPAA |
userrating | String | User rating of the content (for example, number of stars, likes, etc.). | 9-Stars |
qagmediarating | Integer | Media rating per IQG guidelines. | 1 |
keywords | String | Comma separated list of keywords describing the content. | ActionMovies |
livestream | Integer | 0 = Not Live 1 = Content is Live (for example, stream, live blog). | 1 |
sourcerelationship | Integer | 0 = Indirect 1 = Direct. | 1 |
len | Integer | Length of content in seconds; appropriate for video or audio. | 12000 |
language | String | Content language using ISO-639-1-alpha-2. | en-US |
embeddable | Integer | Indicator of whether or not the content is embeddable (for example, an embeddable video player). 0 = No 1 = Yes | 1 |
The Content object can also contain the Producer parameter object.
Producer object
The Producer object is a parameter object for the Content, described above. The next table shows the OpenWrap keys to reference Prod objects from App and Site contexts, and for comparison, the equivalent OpenRTB 2.5 keys.
| OpenWrap Keys | ORTB 2.5 Keys |
|---|---|
app.cnt.prod.[param] | bidrequest.app.content.producer.[param] |
site.cnt.prod.[param] | bidrequest.site.content.producer.[param] |
The following table lists the parameters available to let you configure Prod objects.
| Parameter | Type | Description | Example |
|---|---|---|---|
id | String | Content producer or originator ID. Useful if content is syndicated and may be posted on a site using embed tags | Prod123 |
name | String | Content producer or originator name; for example, “Warner Bros”. | GaryKurtz |
cat | String Array | Array of IAB content categories that describe the content producer. | IAB1-5,IAB1-6 |
domain | String | Highest level domainof the content producer; for example, “producer.com”. | producer.com |
Device object
The Device object is a child of BidRequest described above. The next table shows the OpenWrap key to reference Dev objects, and for comparison, the equivalent OpenRTB 2.5 key to reference Device objects.
| OpenWrap Key | ORTB 2.5 Key |
|---|---|
dev.[param] | bidrequest.device.[param] |
The following table lists the parameters available to let you configure Device objects.
| Parameter | Type | Description | Example |
|---|---|---|---|
ua | String | Browser user agent string. It can be derived from User-Agent header if not specified. |
|
dnt | Integer | Standard “DoNotTrack” flag as set in the header by the browser. 0 = Tracking is unrestricted 1 = Do Not Track. | 1 |
lmt | Integer | “Limit Ad Tracking” signal commercially endorsed (for example, iOS, Android) 0 = tracking is unrestricted 1 = tracking must be limited per commercial guidelines. | 1 |
ip | String | IPv4 address closest to device. It can be derived from request headers in following sequence. * HTTP_RLNCLIENTIPADDR | 127.0.0.1 |
ipv6 | String | IP address closest to device as IPv6. | 2001:db8::8a2e:370:7334 |
devicetype | Integer | The general type of device. | 1 |
make | String | Device make (for example, “Apple”) | Samsung |
model | String | Device model (for example, “iPhone”) | Galaxy-A70S |
os | String | Device operating system (for example, “iOS”). | Android |
osv | String | Device operating system version (for example, “3.1.2”) | MarshMellow |
hwv | String | Hardware version of the device (for example, “5S” for iPhone 5S). | A70s |
h | Integer | Physical height of the screen in pixels | 768 |
w | Integer | Physical width of the screen in pixels | 1366 |
ppi | Integer | Screen size as pixels per linear inch. | 4096 |
pxratio | Float | The ratio of physical pixels to device independent pixels | 1.3 |
js | Integer | Support for JavaScript. 0 = No 1 = Yes | 1 |
geofetch | Integer | Indicates if the geolocation API will be available to JavaScript code running in the banner 0 = No 1 = Yes | 0 |
flashver | String | Version of Flash supported by the browser. | 1.1 |
language | String | Browser language using ISO-639-1-alpha-2. | en-US |
carrier | String | Carrier or ISP (for example, “VERIZON”) using exchange-curated string names, which once deduced, should be published to bidders. | VERIZON |
mccmnc | String | Mobile carrier as the concatenated MCC-MNC code (for example, “310-005” identifies Verizon Wireless CDMA in the USA). See the Wikipedia article on Mobile country codes for further examples. Note that the dash between the MCC and MNC segments is required to ensure accurate parsing. | 310-005 |
connectiontype
| Integer | Network connection type. | 2 |
ifa | String | ID sanctioned for advertiser use in the clear (that is, not hashed). | EA7583CD-A667-48BC-B806-42ECB2B48606 |
didsha1 | String | Hardware device ID (for example, IMEI); hashed via SHA1. |
613b4d2f6a09ee5f820d670a1d5b1cc4ccc08bc2
|
didmd5 | String | Hardware device ID (for example, IMEI); hashed via MD5. | 12d2cd0eacd05dae666c4a5ff3067e42 |
dpidsha1 | String | Platform device ID (for example, Android ID); hashed via SHA1. |
613b4d2f6a09ee5f820d670a1d5b1cc4ccc08bc2 |
dpidmd5 | String | Platform device ID (for example, Android ID); hashed via MD5. | 12d2cd0eacd05dae666c4a5ff3067e42 |
macsha1 | String | MAC address of the device; hashed via SHA1. |
613b4d2f6a09ee5f820d670a1d5b1cc4ccc08bc2 |
macmd5 | String | MAC address of the device; hashed via MD5. | 12d2cd0eacd05dae666c4a5ff3067e42 |
The Device object can also contain the Geo parameter object.
User object
The User object is a child of BidRequest described above. The next table shows the OpenWrap key to reference User objects, and for comparison, the equivalent OpenRTB 2.5 key to reference User objects.
| OpenWrap Key | ORTB 2.5 Key |
|---|---|
user.[param] | bidrequest.user.[param] |
The following table lists the parameters available to let you configure User objects.
| Parameter | Type | Description | Example |
|---|---|---|---|
id | String | Exchange-specific ID for the user. At least one of idor buyeruidis recommended. | 45067fec-eab7-4ca0-ad3a-87b01f21846a |
buyeruid | String | Buyer-specific ID for the user as mapped by the exchange for the buyer. At least one of buyeruidor idis recommended. | 45067fec-eab7-4ca0-ad3a-87b01f21846a |
yob | Integer | Year of birth as a 4-digit integer. | 1990 |
gender | String | Gender, where “M” = male,“F” = female, “O” = known to be other (that is, omitted is unknown). | M |
keywords | String | Comma separated list of keywords, interests, or intent. | Movies |
customdata | String | Optional feature to pass bidder data that was set in the exchange’s cookie. The string must be in base85 cookie safe characters and be in any format. Proper JSON encoding must be used to include “escaped” quotation marks. | StarWars |
ext.consent | String | GDPR consent string should be passed here. | BOEFEAyOEFEAyAHABDENAI4AAAB9vABAASA |
The User object can also contain the Geo parameter object.
Geo object
The Geo object is a child of the Device and User objects, described above. The next table shows the OpenWrap keys to reference the Geo object from Device and User contexts, and for comparison, the equivalent OpenRTB 2.5 keys.
| OpenWrap Keys | ORTB 2.5 Keys |
|---|---|
dev.geo.lat.[param] | bidrequest.device.geo.[param] |
user.geo.lat.[param] | bidrequest.user.geo.[param] |
The following table lists the parameters available to let you configure Geo objects.
| Parameter | Type | Description | Example |
|---|---|---|---|
lat | Float | Latitude from -90.0 to +90.0, where negative is south. | 72.6 |
lon | Float | Longitude from -180.0 to +180.0, where negative is west. | 72.6 |
type | Integer | Source of location data; recommended when passing lat/lon. | 1 |
accuracy | Integer | Estimated location accuracy in meters; Recommended when lat/lonare specified and derived from a device’s location services (that is, type = 1). Note that this is the accuracy as reported from the device. Consult OS specific documentation (for example, Android, iOS) for exact interpretation. | 10 |
lastfix | Integer | 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. | 0 |
ipservice
| Integer | Service or provider used to determine geolocation from IP address if applicable (that is, type = 2). | 1 |
country | String | Country code using ISO-3166-1-alpha-3 | India |
region | String | Region code using ISO-3166-2; 2-letter state code if USA. | Maharashtra |
regionfips104 | String | Region of a country using FIPS 10-4 notation. While OpenRTB supports this attribute, it has been withdrawn by NIST in 2008. | MAHA |
metro | String | Google metro code; similar to but not exactly Nielsen DMAs. | Mumbai |
city | String | City using United Nations Code for Trade and Transport Locations. | Mumbai |
zip | String | Zip or postal code. | 123456 |
utcoffset | Integer | Local time as the number +/- of minutes from UTC. | 120 |
Regulation object
The Regs object is a child of BidRequest described above. The next table shows the OpenWrap key to reference Regs objects, and for comparison, the equivalent OpenRTB 2.5 key to reference Regs objects. Note that the Regs uses the Ext object to accommodate newer regulations like GDPR and US Privacy, which are not covered in the oRTB 2.5 specification.
| OpenWrap Key | ORTB 2.5 Key |
|---|---|
regs.[param] | bidrequest.regs.[param] |
The following table lists the parameters available to let you configure User objects.
| Parameter | Type | Description | Example |
|---|---|---|---|
coppa | Integer | Indicates whether the 0 = No 1 = Yes | 1 |
ext.gdpr | Integer | Indicates whether GDPR applies to the 0 = No 1 = Yes | 1 |
ext.us_privacy | String | CCPA string for the BidRequest, in US Privacy string format. | 1YNN |
OpenWrap-specific Extension object
The Ext object is a child of BidRequest described above. The next table shows the OpenWrap key to reference Ext objects, and for comparison, the equivalent OpenRTB 2.5 key to reference Ext objects.
| OpenWrap Key | ORTB 2.5 Key |
|---|---|
req.ext.wrapper.[param] | bidrequest.ext.[param] |
The following table lists the parameters available to let you configure User objects.
| Parameter | Type | Description | Example |
|---|---|---|---|
versionid | Integer | PubMatic OpenWrap specific profile versionid. | 1 |
sumry_disable | Integer | PubMatic OpenWrap should return detailed summary in response extension: 0 = Summary will be returned in response extension 1 = Summary will not be returned in response extension | 1 |
clientconfig | Integer | PubMatic OpenWrap specific configuration. | 1 |
Dynamic Extension object
We can add any number of extension parameters dynamically by providing nested objects separated by dot, resulting in a String Parameter.
To learn about supporting other data types in the Ext object…
Contact the PubMatic OpenWrap Team.
Passing sample ext parameter such as, req.ext.ow.bidder.name=pubmatic
and
req.ext.ow.pubmatic.consent=present:
Dynamic Extension Parameter Example
{
"ext": {
"ow": {
"bidder": {
"name":"pubmatic"
},
"pubmatic" : {
"consent":"present"
}
}
}
}
Data types currently unsupported for ext object:
- JSON Integer
- JSON Double
- JSON Array Integer
- JSON Array Double
- JSON Array String
- JSON Array Objects
You can use the Ext object to add String parameters to the object keys shown below:
| Extension Prefix Keys | ORTB 2.5 Key |
|---|---|
req.ext | bidrequest.ext |
src.ext | bidrequest.source.ext |
regs.ext | bidrequest.regs.ext |
imp.ext | bidrequest.imp[0].ext |
imp.vid.ext | bidrequest.imp[0].video.ext |
site.ext | bidrequest.site.ext |
app.ext | bidrequest.app.ext |
site.pub.ext | bidrequest.site.publisher.ext |
site.cnt.ext | bidrequest.site.content.ext |
site.cnt.prod.ext | bidrequest.site.content.producer.ext |
app.pub.ext | bidrequest.app.publisher.ext |
app.cnt.ext | bidrequest.app.content.ext |
app.cnt.prod.ext | bidrequest.app.content.producer.ext |
dev.ext | bidrequest.device.ext |
dev.geo.ext | bidrequest.device.geo.ext |
user.ext | bidrequest.user.ext |
user.geo.ext | bidrequest.user.geo.ext |
Example BidRequest
GET API limitations
GETAPIsupports single video impression only. It currently does not support multiple impressions.- Use standard URL encoding for all String parameters to ensure requested URL doesn't break.
- The default format for all String Array parameters is comma separated.
- The dynamic extension parameters currently support only JSON string and JSON object data types. No other JSON data types are supported at this time.
AdPod object
AdPod is an Extension object of the
BidRequest or
Impression.Video objects described above.
Info
For more information, see Ad Pod Support for OpenWrap Video.
You reference AdPod objects using the Extension object hierarchy, and the table below shows the object path to use for the HTTP GET and POST methods.
GET API | POST API | Scope notes |
|---|---|---|
req.ext.adpod.[param] | bidrequest.ext.adpod.[param] | BidRequest parameters are global in scope, including default values. |
imp.vid.ext.adpod.[param] | video.ext.adpod.[param] | Impression.Video object parameters override global scope parameters from BidRequest. |
The following table lists the parameters available to let you configure AdPod objects.
| Parameter | Type | Mandatory (with a defined AdPod object)? | Description | Default value (with a defined AdPod object) |
|---|---|---|---|---|
offset | Integer |
| Defines the position where the AdPod might play in a long video; for example, 30 min from start. This helps define duration based rules to determine when the same ads can/cannot play. | 0 |
minads | Integer |
| Minimum number of ads to include in the AdPod. | 1 |
maxads | Integer |
| Maximum number of ads to include in the AdPod. | 3 |
adminduration | Integer |
| Minimum duration in seconds for each ad in the AdPod. | video.minduration/2 |
admaxduration | Integer |
| Maximum duration in seconds for each ad in the AdPod. | video.maxduration/2 |
excladv | Integer |
| Percentage of ads allowed to have the same advertiser in the AdPod. | 100 |
excliabcat | Integer |
| Percentage of ads allowed to have the same IAB category in the AdPod. | 100 |
| BIDREQUEST-ONLY PARAMETERS | ||||
adpod( POST method only) | Object |
| New object for defining an AdPod object. | |
crosspodexcladv | Integer |
| Percentage of ads allowed to have the same advertiser across all AdPods in the BidRequest. | 100 |
crosspodexcliabcat | Integer |
| Percentage of ads allowed to have the same IAB categories across all AdPod s in the BidRequest . | 100 |
excliabcatwindow | Integer |
| The number of minutes during which the exclusive IAB rule applies. If two | 100 |
excladvwindow | Integer |
| The number of minutes during which the exclusive advertiser rule applies. If two | 100
|
CTV endpoints
| Endpoint | Description |
|---|---|
OpenRTB endpoint returns IAB Standard OpenRTB 2.5 formatted response for a BidRequest. | |
VAST endpoint returns VAST-format XML response for a video BidRequest. | |
| /video/json | This CTV video endpoint will cache individual AdPod creatives and return targeting values in response. |
OpenRTB endpoint response
IAB Standard Open RTB 2.5 BidResponse format.
Response Headers
| Content-Type | application/json |
|---|
Error response
OpenWrap CTV OpenRTB endpoint uses two error formats according to the type of error.
VAST endpoint response
The VAST endpoint returns a standard VAST XML response. In the cases of, Request ERROR, Application ERROR, or No Bid, the endpoint returns an empty VAST tag with error details in the response headers.
Supported VAST versions: VAST 2.0, VAST 3.0.
Response headers
| Content-Type | application/xml | ||||||
|---|---|---|---|---|---|---|---|
| X-Ow-Status | Error details:
|
Endpoint examples
JSON endpoint response
The JSON endpoint will cache all individual creatives of adpod and returns the targeting keys of that creatives.
Response object
| Key | Type | Description |
|---|---|---|
adpod | Array of adpod objects | Contains targeting key/values for each impression and its respective slots. |
ext | Object | Holds debug information. |
AdPod object
| Key | Type | Description |
|---|---|---|
id | String | Contains Impression ID. |
targeting | Array of targeting object | Contains targeting objects for all ad slots of the adpod. |
ext | Object | Holds ad pod-specific extension parameter. |
Targeting object
It is a map of the key-value objects which signifies targeting keys of the bid object. Below are some standard targeting keys.
| Key | Partner Level Key | Description | Example |
|---|---|---|---|
pwtbst | pwtbst_<partnerName> | Winning bid status 1: Winning bid 0: Non-winning bid |
|
pwtcid | pwtcid_<partnerName> | Cache ID |
|
pwtdid | pwtdid_<partnerName> | Deal ID |
|
pwtecp | pwtecp_<partnerName> | eCPM value |
|
pwtpid | pwtpid_<partnerName> | Partner name |
|
pwtsid | pwtsid_<partnerName> | Slot ID |
|
pwtsz | pwtsz_<partnerName> | Ad Size in WIDTHxHEIGHT |
|
pwtprofid | - | Profile ID | "pwtprofid":"2375", |
pwtpubid | - | Publisher ID | "pwtpubid":"159396", |
pwtverid | - | Version ID | "pwtverid":"1" |
pwtplt | - | Platform
| "pwtplt":"video", |
pwtdur | - | Video duration | "pwtdur":"35", |
pwtcurl | - | OpenWrap cache URL | "pwtcurl":"https://ow.pubmatic.com", |
pwtcpath | - | OpenWrap cache path | "pwtcpath":"/cache", |
Response headers
| Content-Type | application/json | ||||||
|---|---|---|---|---|---|---|---|
| X-Ow-Status | Error details
|
Endpoint example
CTV endpoint assumptions
- Currently, OpenWrap server-side works only in USD currency. OpenWrap currently automatically replaces any other currency with USD. Note that ECPM values are also reported in USD.
- Server Side Auction is done for all CTV requests whether or not the
req.ext.wrapper.ssauctionparameter is defined. - Creative Blocked Attributes, Blocked Domains, Blocked Categories, and Allowlisted Categories are not yet implemented by OpenWrap CTV video. OpenWrap will forward the request to partners via prebid and it is the partner's sole responsibility to serve creatives based on these attributes.
- Profile level platform is not checked for CTV endpoints, which means Display/InApp other profiles are served for video request.
- Profile ID is mandatory for CTV requests using both
GETandPOSTmethods.
BidResponse specification
The following sections describe the objects that make up a BidResponse.
Info
- Multiple impressions can be generated for each ad pod request.
- Standard OpenRTB response will be rendered for non-ad pod requests.
BidResponse object
The table below describes the parent
BidResponse
object, which encapsulates the SeatBid object array.
PARAMETER | TYPE | Supports ad pod requests? | DESCRIPTION |
|---|---|---|---|
id | string |
| ID of the bid request to which this is a response. |
seatbid | object array |
| Array of seatbid objects; 1+ required if a bid is to be made. |
bidid | string |
| Bidder generated response ID to assist with logging/tracking. |
cur | string |
| Bid currency using ISO-4217 alpha codes.default USD. |
customdata | string |
| Optional feature to allow a bidder to set data in the exchange’s cookie. The string must be in base85 cookie-safe characters and be in any format. Proper JSON encoding must be used to include “escaped” quotation marks. |
nbr | integer |
| Reason for not bidding. |
ext | object |
| Placeholder for bidder-specific OpenRTB extensions. |
SeatBid object
The table below lists the parameters for the SeatBid object, whose main function is to deliver an array of Bid objects for the Impressions in the BidRequest.
| Parameter | Type | Supports ad pod requests? | Description |
|---|---|---|---|
bid | object array |
| Array of 1 or more Bid objects (Section 4.2.3) each related to an impression. Multiple bids can relate to the same impression. |
seat | string |
| ID of the buyer seat on whose behalf the bid was made. For example, an advertiser, agency, or in the case of a |
| group | integer | NA | 0 = impressions can be won individually 1 = impressions must be won or lost as a group |
| ext | object | NA | Placeholder for bidder-specific extensions to OpenRTB. |
Bid object
The table below lists the parameters for the Bid objects, which represent a winning bid for an Impression. The BidResponse object can encapsulate many Bids within a SeatBid object's bid property.
| Parameter | Type | Supports ad pod requests? | Description |
|---|---|---|---|
id | string |
| Bidder generated bid ID to assist with logging/tracking. |
impid | string |
| ID of the Imp object in the related bid request. |
price | float |
| Bid price expressed as CPM although the actual transaction is for a unit impression only. Note that while the type indicates float, integer math is highly recommended when handling currencies (e.g., BigDecimal in Java). |
nurl | string |
| Win notice URL called by the exchange if the bid wins (not necessarily indicative of a delivered, viewed, or billable ad); optional means of serving ad markup. |
burl | string |
| Billing notice URL called by the exchange when a winning bid becomes billable based on exchange-specific business policy (e.g., typically delivered, viewed, etc.). |
lurl | string |
| Loss notice URL called by the exchange when a bid is known to have been lost. Exchange-specific policy may preclude support for loss notices or the disclosure of winning clearing prices resulting in ${AUCTION_PRICE} macros being removed (i.e., replaced with a zero-length string). |
adm | string |
| Optional means of conveying ad markup in case the bid wins; supersedes the win notice if markup is included in both. |
adid | string |
| ID of a preloaded ad to be served if the bid wins. |
adomain | string array |
| Advertiser domain for block list checking (e.g., “ford.com”). This can be an array of for the case of rotating creatives. Exchanges can mandate that only one domain is allowed. |
bundle | string |
| A platform-specific application identifier intended to be unique to the app and independent of the exchange. On Android, this should be a bundle or package name (e.g., com.foo.mygame). On iOS, it is a numeric ID. |
iurl | string |
| URL without cache-busting to an image that is representative of the content of the campaign for ad quality/safety checking. |
cid | string |
| Campaign ID to assist with ad quality checking; the collection of creatives for which iurl should be representative. |
crid | string |
| Creative ID to assist with ad quality checking. |
tactic | string |
| Tactic ID to enable buyers to label bids for reporting to the exchange the tactic through which their bid was submitted. The specific usage and meaning of the tactic ID should be communicated between buyer and exchanges a priori. |
cat | string array |
| IAB content categories of the creative. |
attribute | integer array |
| Set of attributes describing the creative |
api | integer |
| API required by the markup if applicable |
protocol | integer |
| Video response protocol of the markup if applicable. |
qamediarating | integer |
| Creative media rating per IQG guidelines. |
language | string |
| Language of the creative using ISO-639-1-alpha-2. The non-standard code “xx” may also be used if the creative has no linguistic content (e.g., a banner with just a company logo). |
dealid | string |
| Reference to the deal.id from the bid request if this bid pertains to a private marketplace direct deal. |
w | integer |
| Width of the creative in device independent pixels (DIPS) |
h | integer |
| Height of the creative in device independent pixels (DIPS). |
wratio | integer |
| Relative width of the creative when expressing size as a ratio. Required for Flex Ads. |
hratio | integer |
| Relative height of the creative when expressing size as a ratio. Required for Flex Ads. |
exp | integer |
| Advisory as to the number of seconds the bidder is willing to wait between the auction and the actual impression. |
ext | object |
| Placeholder for bidder-specific extensions to OpenRTB. |
Endpoint error codes
Info
For more information, see OpenWrap server-side debugging.
| Error Code | Error Message | HTTP Status Code | Scenarios |
|---|---|---|---|
| 500 | Empty Response | 500 | Any Panic in Program |
| 600 | Missing Request ID | 400 | req.id is not specified |
| 601 | Missing Impressions | 400 | req.imp is not specified |
| 602 | Missing Site/App Object | 400 | req.site and req.app both not present |
| 603 | Site App Both Present | 400 | req.site and req.app both present in request |
| 604 | Missing Publisher ID | 400 | req.site.publisher.id or req.app.publisher.id not specified |
| 605 | Missing Tag ID | 400 | req.imp.tagid is not specified |
| 606 | Missing Impression ID | 400 | req.imp.id is not specified |
| 607 | Missing Ad Type(Banner/Video) | 400 | banner/native/audio/video any one not specified in request |
| 608 | Missing Ad Sizes | 400 | banner.w, banner.h, or banner.format is not specified |
| 609 | Missing MIMEs | 400 | video.mimes or audio.mimes not specified |
| 610 | Missing Native Request Payload | 400 | native.request payload not specified |
| 611 | Missing Video Object | 400 | video object missing for ctv requests |
| 700 | Missing Profile ID | 400 | mandatory profile id missing in request |
Enumerated value definitions
The expandable tables below define the enumerated values you will to configure the various objects and parameters that make up your BidRequests.
Video Protocols
Playback methods
Ad position
Video placement types
API frameworks
Video linearity
Start delay
Content context
Content delivery methods
Playback cessation modes
Production quality
Inventory Quality Guidelines (IQG) ratings
Device type
Connection type
Location type
IP location services
Reference documents
Table of Contents
Overview
Content Tools
Activity