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 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 |
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 |
The BidRequest object supports AdPods…
Using the Extension object hierarchy. 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 |
| 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.
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.
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. |
|
The Impression object supports AdPods…
Using the Extension object hierarchy. 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
| 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
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.
| 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.
| 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.
| 1 |
paid | Integer |
| 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 keywordsdescribing the content | ActionMovies |
livestream | Integer |
| 1 |
sourcerelationship | Integer |
| 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 ornot the content is embeddable (for example, an embeddable video player).
| 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”flagas set in the header by the browser.
| 1 |
lmt | Integer | “Limit Ad Tracking” signal commercially endorsed (for example, iOS, Android)
| 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.
| 1 |
geofetch | Integer | Indicates if the geolocation API will be available to JavaScript code running in the banner
| 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
| 1 |
ext.gdpr | Integer | Indicates whether GDPR applies to the
| 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:
| 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
andreq.ext.ow.pubmatic.consent=present
:
{ "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
GET
API
supports 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.
For more information about using Ad Pods…
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 | N | 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 | N | Minimum number of ads to include in the AdPod. | 2 |
maxads | Integer | N | Maximum number of ads to inlcude in the AdPod. | 3 |
adminduration | Integer | N | Minimum duration in seconds for each ad in the AdPod. | video.minduration/2 |
admaxduration | Integer | N | Maximum duration in seconds for each ad in the AdPod. | video.maxduration/2 |
excladv | Integer | N | Percentage of ads allowed to have the same advertiser in the AdPod. | 100 |
excliabcat | Integer | N | Percentage of ads allowed to have the same IAB category in the AdPod. | 100 |
BidRequest-only parameters | ||||
adpod ( POST method only) | Object | Y | New object for defining an AdPod object. | |
crosspodexcladv | Integer | N | Percentage of ads allowed to have the same advertiser across all AdPod s in the BidRequest . | 100 |
crosspodexcliabcat | Integer | N | Percentage of ads allowed to have the same IAB categories across all AdPod s in the BidRequest . | 100 |
excliabcatwindow | Integer | N | The number of minutes during which the exclusive IAB rule applies. If two | 100 |
excladvwindow | Integer | N | 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 adpod 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
|
|
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 |
|
pwtpubid | - | Publisher ID |
|
pwtverid | - | Version ID |
|
pwtplt | - | Platform
|
|
pwtdur | - | Video duration |
|
pwtcurl | - | OpenWrap cache URL |
|
pwtcpath | - | OpenWrap cache path |
|
Response headers
Content-Type | application/json | ||||||
---|---|---|---|---|---|---|---|
X-Ow-Status | Error details
|
Endpoint example
Endpoint error codes
See also…
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 |
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.ssauction
parameter 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
GET
andPOST
methods.
BidResponse specification
The following sections describe the objects that make up a BidResponse
.
BidResponse object
The table below describes the parent
BidResponse
object, which encapsulates the SeatBid
object array.
Parameter | Type | Description |
---|---|---|
id | string | ID of the bid request that generated this response. |
seatbid | object array | Array of seatbid objects; 1+ required if a bid is to be made. |
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 encoded in base85 cookie safe characters and be in any format. Proper JSON encoding must be used to include “escaped” quotation marks. |
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 Impression
s in the BidRequest
.
Parameter | Type | 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 BidRequest with AdPod s, the seat value is, pubmatic_ow . |
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 Bid
s within a SeatBid
object's bid
property.
Parameter | Type | Description |
---|---|---|
id | string | Bidder auto-generated bid ID (at the PreBid side), to assist with logging/tracking. |
impid | string | ID of the original Imp object in the parent BidRequest . |
price | float | Sum of all Bid prices expressed as CPM, even though the actual transaction is for a unit impression only. Note that while the type indicates float, integer math is the best practice for handling currencies; for example, BigDecimal in Java. |
adm | string | Optional means of sending ad markup for winning bids; supersedes the win notice when both include markup. May include substitution macros (Section 4.4). May also include merged VAST XML. |
adomain | string array | Advertiser domain for block list checking; for example, |
cat | string array | IAB content categories of the creative. |
attribute | integer array | Set of attributes describing the creative. |
ext | object | Placeholder for bidder-specific OpenRTB extensions. |
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