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.

Sample HTTP POST impression
curl -v --location --request POST 'http://172.16.4.192:7878/video/vast' \
--header 'Content-Type: text/plain' \
--data-raw '{
  "id": "1559039248176",
  "imp": [
    {
      "id": "28635736ddc2bb",
      "video": {
        "pos": 7,
        "companionad": [
          {
            "pos": 7,
            "format": [
              {
                "w": 320,
                "h": 480
              }
            ],
            "api": [
              5,
              6,
              7
            ]
          }
        ],
        "maxbitrate": 2000,
        "minduration": 15,
        "protocols": [
          2,
          3,
          5,
          6,
          7,
          8
        ],
        "mimes": [
          "video/3gpp",
          "video/mp4",
          "video/webm"
        ],
        "linearity": 1,
        "boxingallowed": 1,
        "playbackmethod": [
          1
        ],
        "delivery": [
          2
        ],
        "companiontype": [
          1,
          2,
          3
        ],
        "placement": 5,
        "playbackend": 1,
        "startdelay": 0
      },
      "tagid": "/15671365/DMDemo",
      "secure": 0,
      "ext": {
        "bidder": {}
      }
    }
  ],
  "app": {
    "name": "OpenWrapperSample",
    "bundle": "com.pubmatic.openbid.app",
    "storeurl": "https://itunes.apple.com/?videobid=12",
    "ver": "1.0",
    "publisher": {
      "id": "5890"
    }
  },
  "device": {
    "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 13_2_3 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148",
    "dnt": 0,
    "lmt": 1,
    "ip": "172.16.8.74",
    "ipv6": "2001:db8::8a2e:370:7334",
    "devicetype": 1,
    "make": "Apple",
    "model": "iPhone X",
    "os": "ios",
    "osv": "10",
    "hwv": "10x",
    "h": 768,
    "w": 1366,
    "ppi": 4096,
    "pxratio": 1.3,
    "js": 1,
    "geofetch": 0,
    "flashver": "1.1",
    "language": "en-US",
    "carrier": "VERIZON",
    "mccmnc": "310-005",
    "connectiontype": 2,
    "ifa": "EA7583CD-A667-48BC-B806-42ECB2B48606",
    "didsha1": "EA7583CD-A667-48BC-B806-42ECB2B48606",
    "didmd5": "EA7583CD-A667-48BC-B806-42ECB2B48606",
    "dpidsha1": "EA7583CD-A667-48BC-B806-42ECB2B48606",
    "dpidmd5": "EA7583CD-A667-48BC-B806-42ECB2B48606",
    "macsha1": "EA7583CD-A667-48BC-B806-42ECB2B48606",
    "macmd5": "EA7583CD-A667-48BC-B806-42ECB2B48606",
    "geo": {
      "lat": 72.6,
      "lon": 72.6,
      "type": 1,
      "accuracy": 10,
      "lastfix": 0,
      "ipservice": 1,
      "country": "Ind",
      "region": "Maharashtra",
      "regionfips104": "MAHA",
      "metro": "Mumbai",
      "city": "Mumbai",
      "zip": "123456",
      "utcoffset": 120
    }
  },
  "user": {
    "geo": {}
  },
  "source": {
    "tid": "edc7717c-ca43-4ad6-b2a1-354bd8b10f78"
  },
  "at": 1,
  "cur": [
    "USD"
  ],
  "ext": {
    "extra-key": 123,
    "wrapper": {
      "profileid": 3514,
      "versionid": 1,
      "ssauction": 0,
      "sumry_disable": 0,
      "clientconfig": 1
    }
  }
}'
Note: Unnecessary use of -X or --request, POST is already inferred.
*   Trying 172.16.4.192:7878...
* TCP_NODELAY set
* Connected to 172.16.4.192 (172.16.4.192) port 7878 (#0)
> POST /video/vast HTTP/1.1
> Host: 172.16.4.192:7878
> User-Agent: curl/7.65.2
> Accept: */*
> Content-Type: text/plain
> Content-Length: 1997
> Expect: 100-continue
>
* Mark bundle as not supporting multiuse
< HTTP/1.1 100 Continue
* We are completely uploaded and fine
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< Access-Control-Allow-Origin: *
< Content-Type: application/xml
< Date: Fri, 27 Mar 2020 16:37:11 GMT
< Transfer-Encoding: chunked
<
<VAST version="3.0">
    <Ad id="601364">
        <InLine>
            <AdSystem>
                <![CDATA[Acudeo Compatible]]>
            </AdSystem>
            <AdTitle>
                <![CDATA[VAST 2.0 Instream Test 1]]>
            </AdTitle>
            <Description>
                <![CDATA[VAST 2.0 Instream Test 1]]>
            </Description>
            <Impression>
                <![CDATA[//t.pubmatic.com/wt?bidid=28635736ddc2bb&eg=12&en=12&iid=aa5237b4-ba9e-4960-ad9c-2910aa9e1346&kgpv=%2F15671365%2FDMDemo%400x0&pdvid=1&pid=3514&pn=pubmatic&pubid=5890&purl=https%3A%2F%2Fitunes.apple.com%2F%3Fvideobid%3D12&slot=28635736ddc2bb_%2F15671365%2FDMDemo&tst=1585326824]]>
            </Impression>
            <Impression>
                <![CDATA[http://172.16.4.213/AdServer/AdDisplayTrackerServlet?operId=1&pubId=5890&siteId=47163&adId=1405268&adType=13&adServerId=243&kefact=70.000000&kaxefact=70.000000&kadNetFrequecy=0&kadwidth=0&kadheight=0&kadsizeid=97&kltstamp=1529929473&indirectAdId=0&adServerOptimizerId=2&ranreq=0.1&kpbmtpfact=100.000000&dcId=1&tldId=0&passback=0&svr=MADS1107&ekefact=Ad8wW91TCwCmdG0jlfjXn7Tyzh20hnTVx-m5DoNSep-RXGDr&ekaxefact=Ad8wWwRUCwAGir4Zzl1eF0bKiC-qrCV0D0yp_eE7YizB_BQk&ekpbmtpfact=Ad8wWxRUCwD7qgzwwPE2LnS5-Ou19uO5amJl1YT6-XVFvQ41&imprId=48F73E1A-7F23-443D-A53C-30EE6BBF5F7F&oid=48F73E1A-7F23-443D-A53C-30EE6BBF5F7F&crID=creative-1_1_2&ucrid=160175026529250297&campaignId=17050&creativeId=0&pctr=0.000000&wDSPByrId=511&wDspId=6&wbId=0&wrId=0&wAdvID=3170&isRTB=1&rtbId=EBCA079F-8D7C-45B8-B733-92951F670AA1&pmZoneId=zone1&pageURL=www.yahoo.com&lpu=ae.com]]>
            </Impression>
            <Impression>
                <![CDATA[https://dsptracker.com/{PSPM}]]>
            </Impression>
            <Error>
                <![CDATA[http://172.16.4.213/track?operId=7&p=5890&s=47163&a=1405268&wa=243&ts=1529929473&wc=17050&crId=creative-1_1_2&ucrid=160175026529250297&impid=48F73E1A-7F23-443D-A53C-30EE6BBF5F7F&advertiser_id=3170&ecpm=70.000000&er=[ERRORCODE]]]>
            </Error>
            <Error>
                <![CDATA[https://Errortrack.com?p=1234&er=[ERRORCODE]]]>
            </Error>
            <Creatives>
                <Creative AdID="601364">
                    <Linear skipoffset="70%">
                        <TrackingEvents>
                            <Tracking event="close">
                                <![CDATA[https://mytracking.com/linear/close]]>
                            </Tracking>
                            <Tracking event="skip">
                                <![CDATA[https://mytracking.com/linear/skip]]>
                            </Tracking>
                            <Tracking event="creativeView">
                                <![CDATA[http://172.16.4.213/track?operId=7&p=5890&s=47163&a=1405268&wa=243&ts=1529929473&wc=17050&crId=creative-1_1_2&ucrid=160175026529250297&impid=48F73E1A-7F23-443D-A53C-30EE6BBF5F7F&advertiser_id=3170&ecpm=70.000000&e=1]]>
                            </Tracking>
                            <Tracking event="start">
                                <![CDATA[http://172.16.4.213/track?operId=7&p=5890&s=47163&a=1405268&wa=243&ts=1529929473&wc=17050&crId=creative-1_1_2&ucrid=160175026529250297&impid=48F73E1A-7F23-443D-A53C-30EE6BBF5F7F&advertiser_id=3170&ecpm=70.000000&e=2]]>
                            </Tracking>
                            <Tracking event="midpoint">
                                <![CDATA[http://172.16.4.213/track?operId=7&p=5890&s=47163&a=1405268&wa=243&ts=1529929473&wc=17050&crId=creative-1_1_2&ucrid=160175026529250297&impid=48F73E1A-7F23-443D-A53C-30EE6BBF5F7F&advertiser_id=3170&ecpm=70.000000&e=3]]>
                            </Tracking>
                            <Tracking event="firstQuartile">
                                <![CDATA[http://172.16.4.213/track?operId=7&p=5890&s=47163&a=1405268&wa=243&ts=1529929473&wc=17050&crId=creative-1_1_2&ucrid=160175026529250297&impid=48F73E1A-7F23-443D-A53C-30EE6BBF5F7F&advertiser_id=3170&ecpm=70.000000&e=4]]>
                            </Tracking>
                            <Tracking event="thirdQuartile">
                                <![CDATA[http://172.16.4.213/track?operId=7&p=5890&s=47163&a=1405268&wa=243&ts=1529929473&wc=17050&crId=creative-1_1_2&ucrid=160175026529250297&impid=48F73E1A-7F23-443D-A53C-30EE6BBF5F7F&advertiser_id=3170&ecpm=70.000000&e=5]]>
                            </Tracking>
                            <Tracking event="complete">
                                <![CDATA[http://172.16.4.213/track?operId=7&p=5890&s=47163&a=1405268&wa=243&ts=1529929473&wc=17050&crId=creative-1_1_2&ucrid=160175026529250297&impid=48F73E1A-7F23-443D-A53C-30EE6BBF5F7F&advertiser_id=3170&ecpm=70.000000&e=6]]>
                            </Tracking>
                        </TrackingEvents>
                        <Duration>
                            <![CDATA[00:00:04]]>
                        </Duration>
                        <VideoClicks>
                            <ClickTracking>
                                <![CDATA[http://172.16.4.213/track?operId=7&p=5890&s=47163&a=1405268&wa=243&ts=1529929473&wc=17050&crId=creative-1_1_2&ucrid=160175026529250297&impid=48F73E1A-7F23-443D-A53C-30EE6BBF5F7F&advertiser_id=3170&ecpm=70.000000&e=99]]>
                            </ClickTracking>
                            <ClickThrough>
                                <![CDATA[https://www.pubmatic.com]]>
                            </ClickThrough>
                        </VideoClicks>
                        <MediaFiles>
                            <MediaFile delivery="progressive" type="video/mp4" bitrate="500" width="400" height="300" scalable="true" maintainAspectRatio="true">
                                <![CDATA[https://stagingams.pubmatic.com:8443/openwrap/media/pubmatic.mp4]]>
                            </MediaFile>
                        </MediaFiles>
                    </Linear>
                </Creative>
            </Creatives>
            <Pricing model="CPM" currency="USD">
                <![CDATA[12]]>
            </Pricing>
        </InLine>
    </Ad>
</VAST>

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.

ObjectDescription
BidRequest.Imp.Banner

Full banner object unsupported. OpenWrap ignores the impression object if it contains a banner object.

Sample impression with banner object
Input BidRequest with banner object
{
	"imp":[{
		...
		"banner":{},
		...
	}]
}

Resulting BidRequest
{
	"imp":[] /*Removed banner object and impression*/
}

OpenWrap removes a banner object from an impression when it is specified with a video object in the same impression.

Sample impression with banner and video
Input BidRequest with banner and video objects
{
	"imp":[{
		...
		"banner":{},
		"video": {},
		...
	}]
}

Resulting BidRequest used throughout
{
	"imp":[{
		...
		/*Removed banner object*/
		"video": {},
		...
	}]
}
BidRequest.Imp.Audio

OpenWrap ignores impression object if it contains an unsupported audio object.

Sample impression with audio
Input BidRequest with audio object
{
	"imp":[{
		...
		"audio":{},
		...
	}]
}

Resulting BidRequest
{
	"imp":[] /*Removed audio object and impression*/
}

OpenWrap removes an audio object from an impression if it is specified with video object in the same impression.

Sample impression with audio and video
Input BidRequest with audio and video objects
{
	"imp":[{
		...
		"audio":{},
		"video": {},
		...
	}]
}

Resulting BidRequest used throughout
{
	"imp":[{
		...
		/*Removed audio object*/
		"video": {},
		...
	}]
}
BidRequest.Imp.Native

Full native object not supported. OpenWrap ignores impressions when they contain a native object.

Sample impression with native object; native object is removed.
Input BidRequest with native object
{
	"imp":[{
		...
		"native":{},
		...
	}]
}

Resulting BidRequest
{
	"imp":[] /*Removed native object and impression*/
}

OpenWrap removes the native object from the impression if it is specified with a video object in the same impression.

Sample impression with native + video objects; native object is removed
Input BidRequest with native and video objects
{
	"imp":[{
		...
		"native":{},
		"video": {},
		...
	}]
}

Resultant BidRequest used throughout
{
	"imp":[{
		...
		/*Removed native object*/
		"video": {},
		...
	}]
}

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 KeyORTB 2.5 KeyTypeDescriptionExample
imp.tagidbidrequest.imp[0].tagidString

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 adUnitId here.

/ID/SampleAdUnit
imp.vid.mimesbidrequest.imp[0].video.mimesString Array

Comma separated String Array. Supported content MIME types include:: video/x-ms-wmv and video/mp4.

video%2F3gpp,video%2Fmp4,video%2Fwebm

site.pub.id / app.pub.id

bidrequest.site.publisher.id / bidrequest.app.publisher.id

StringExchange-specific publisher ID. Requires at least one of either, site.pub.id or app.pub.id.12345
req.ext.wrapper.profileidbidrequest.ext.wrapper.profileidIntegerOpenWrap 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 KeyORTB 2.5 Key
req.[param]bidrequest.[param]

The following table lists the parameters available to let you configure Req objects.

ParameterTypeDescriptionExample
idString

The unique ID of the BidRequest, provided by the exchange. OpenWrap auto-generates this if you do not provide it.

45067fec-eab7-4ca0-ad3a-87b01f21846a
test

Integer

Default: 0

Boolean value that indicates test mode, in which auctions are not billable; for example, 0 = live mode, 1 = test mode.1
at

Integer

Default: 2

Auction type: 1 = First Price, 2 = Second Price Plus. Define exchange-specific auction types using values greater than 500.

2
tmaxInteger

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
bseatString 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 wseat and/or bseat in the same request. Omitting both implies there are no seat restrictions.

nike,puma
wseatString 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 wseat and/or bseat in the same request. Omitting both implies there are no seat restrictions.

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
wlangString 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 Device and/or Content objects if available.

en,ca
curString Array

An array of allowed currencies for bids on a BidRequest using ISO-4217 alpha codes. Use only if the exchange accepts multiple currencies.

Currently, server-side OpenWrap works with only USD…

Server-side OpenWrap replaces any other currency with USD.

USD
bcatString ArrayBlocked advertiser categories using the IAB content categories.IAB-1,IAB-2
badvString ArrayBlocklist of advertisers by their domains; for example, ford.com.ford.com,puma.com
bappString Array

Blocklist of apps by their platform-specific, exchange-independent identifiers.

  • For Android, application IDs are bundle or package names; for example, com.foo.mygame.
  • For iOS, these are numeric IDs that you can obtain through your Apple Developer account.
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 KeyORTB 2.5 Key
src.[param]bidrequest.source.[param]

The following table lists the parameters available to let you configure Src objects.

ParameterTypeDescriptionExample
fdIntegerEntity responsible for the final impression sale decision, where 0 = exchange, 1 = upstream source.1
tidStringTransaction ID common across all participants in a bid request, and potentially may represent multiple exchanges.45067fec-eab7-4ca0-ad3a-87b01f21846a
pchainStringPayment 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 KeyORTB 2.5 Key
imp.[param]bidrequest.imp[0].[param]

The following table lists the parameters available to let you configure Imp objects.

OpenWrap KeyTypeDescriptionExample
idStringA unique identifier for this impression within the context of the bid request (typically, starts with 1 and increments.123
displaymanagerString

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
displaymanagerverString

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: Not interstitial.
  • 1: The ad is interstitial or full screen.
1
bidfloorFloatThe minimum bid for this impression expressed in CPM.1.1
bidfloorcurString

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
clickbrowserInteger

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
secureInteger

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
iframebusterString ArrayAn array of exchange-specific names of supported iframe busters.1
expIntegerAdvisory as to the number of seconds that may elapse between the auction and the actual impression1
pmpString

An oRTB 2.5 PMP object containing configuration JSON for any private marketplace deals active for the impression.

Sample PMP Object JSON
{
	"private_auction": 1,
	"deals": [{
		"id": "123",
		"bidfloor": 1.2,
		"bidfloorcur": "USD",
		"at": 1,
		"wseat": ["IAB-1", "IAB-2"],
		"wadomain": ["WD1", "WD2"]
	}]
}

Server-side OpenWrap…

 Forwards the PMP object unchanged to the Prebid Server.

%7B%22private_auction%22%3A1%2C%22deals%22%3A%5B
%7B%22id%22%3A%22123%22%2C%22bidfloor%22%3A1.2%2C
%22bidfloorcur%22%3A%22USD%22%2C%22at%22%3A1%2C
%22wseat%22%3A%5B%22IAB-1%22%2C%22IAB-2%22%5D%2C
%22wadomain%22%3A%5B%22WD1%22%2C%22WD2%22%5D
%7D%5D%7D

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.

ParameterTypeDescriptionExample

private_auction

Integer

Default: 0

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 ArrayArray of Deal objects that convey the specific deals applicable to an impressionSee  Deals section below.
extObjectPlaceholder 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.

ParameterTypeDescriptionExample
id

String:

Required

A unique identifier for the direct deal.1234
bidfloor

Float

Default: 0

Minimum bid for this impression expressed in CPM.1.2
bidfloorcur

String

Default: USD

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
atInteger

Optional override of the overall auction type of the bid request

  • 1 = First Price
  • 2 = Second Price Plus
  • 3 = the value passed in bidflooris the agreed upon deal price.

Additional auction types can be defined by the exchange.

1
wseatString 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
wadomainString Array

Array of advertiser domains (for example, advertiser.com) allowed to bid on this deal.

Omission implies no advertiser restrictions.

ad.com,page.com
extObjectPlaceholder 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 KeyORTB 2.5 Key
imp.vid.[param]bidrequest.imp[0].video.[param]

The following table lists the parameters available to let you configure Vid objects.

ParameterTypeDescriptionExample
mindurationIntegerMinimum video ad duration in seconds.5
maxdurationIntegerMaximum video ad duration in seconds.120
protocolsInteger Array

Array of supported video protocols.

Specify at least one supported protocol in either the protocol or protocols attribute.

2,3,5,6,7,8
wIntegerWidth of the video player in device independent pixels (DIPS).320
hIntegerHeight of the video player in device independent pixels (DIPS).480
startdelayInteger

Indicates the start delay in seconds for pre, mid, or post-roll ad placements.

0
placementInteger Placement type for the impression.5
linearityInteger

Determines whether the impression is linear, nonlinear, and so on. Leaving unspecified implies all are allowed.

1
skipInteger

Determines whether the user can skip the video ad.

  • 0 = No
  • 1 = Yes

If a bidder sends markup/creative that is skippable, the Bid object must include the attr array with an element of 16 to flag that the video is skippable.

1
skipminIntegerVideos of total duration greater than this number of seconds can be skippable; only applicable if the ad is skippable.1
skipafterIntegerNumber of seconds a video must play before skipping is enabled; only applicable if the ad is skippable.1
sequenceIntegerIf the BidRequest offers multiple ad impressions, the sequence number facilitates coordinated delivery of multiple creatives.1
battrInteger ArrayBlocked creative attributes.1,2,3
maxextendedInteger

Maximum extended ad duration, if allowed.

  • blank/0 = extension is not allowed.
  • -1 = extension allowed, without time limit.
  • 1 or greater = represents the number of seconds playback extends beyond maxduration.
10
minbitrateIntegerMinimum bit rate in Kbps.1200
maxbitrateIntegerMaximum bit rate in Kbps.2000
boxingallowedInteger

Determines whether 4:3 content is letter-boxed into 16:9 aspect ratio.

  • 0 = No.
  • 1 = Yes.
1
playbackmethodInteger 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
deliveryInteger Array Supported delivery methods; for example, streaming, progressive. Unspecified implies that all are supported.2
posInteger Ad position on screen.7
apiInteger ArrayList 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 KeyORTB 2.5 Key
site.[param]bidrequest.site.[param]

The following table lists the parameters available to let you configure Site objects.

ParameterTypeDescriptionExample
idStringExchange-specific site ID123
nameStringSite name (may be aliasedat the publisher’s request).EbayShopping
domainStringDomain of the site (for example, “mysite.foo.com”).ebay.com
catString ArrayArray of IAB content categories of the site.IAB1-5
sectioncatString ArrayArray of IAB content categories that describe the current section of the site.IAB1-5
pagecatString ArrayArray of IAB content categories that describe the current page or view of the site.IAB1-5
pageStringURL of the page where the impression will be shown.http%3A%2F%2Febay.com%2Fhome
refStringReferrer URL that caused navigation to the current page.http%3A%2F%2Febay.com%2Fhome
searchStringSearch string that caused navigation to the current page.NewCloths
mobileIntegerIndicates if the site has been programmed to optimize layout when viewed on mobile devices, where 0 = no, 1 = yes.1
privacypolicyInteger

Indicates if the site has a privacy policy.

  • 0 = No
  • 1 = Yes.
1
keywordsStringComma separated list of keywords about the site .Clothes

The Site object can also contain the following parameter objects:

ObjectOpenWrap KeyORTB 2.5 Key
Contentsite.cnt.[param]bidrequest.site.content.[param]
Publishersite.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 KeyORTB 2.5 Key
app.[param]bidrequest.app.[param]

The following table lists the parameters available to let you configure App objects.

OpenWrap KeyTypeDescriptionExample
idStringExchange-specific app ID.1234
nameStringApp name (may be aliasedat the publisher’s request).MyFooGame
bundleString

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
domainStringDomainof the app (for example, “mygame.foo.com”)mygame.foo.com
storeurlStringApp store URL for an installed app; for IQG2.1 compliance. https://play.google.com/store/apps/details?id=com.foo.mygame
catString ArrayArray of IAB content categories of the app.IAB1-5,IAB1-6
sectioncatString ArrayArray of IAB content categories that describe the current section of the app.IAB1-5
pagecatString ArrayArray of IAB content categories that describe the current page or view of the app.IAB1-5
verStringApplication version.1.1
privacypolicyInteger

Indicates ifthe app has a privacy policy.

  • 0 = No
  • 1 = Yes
1
paidInteger
  • 0 = app is free
  • 1 = the app is a paid version
1
keywordsStringComma separated list of keywordsabout the app.Games

The App object can also contain the following parameter objects:

ObjectOpenWrap KeyORTB 2.5 Key
Contentapp.cnt.[param]bidrequest.app.content.[param]
Publisherapp.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 KeyORTB 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.

ParameterTypeDescriptionExample
idStringExchange-specific publisher ID.5890
nameStringPublisher name (may be aliased at the publisher’s request).TestPublisher
catString ArrayArray of IAB content categories that describe the publisher.IAB1-5
domainStringHighest 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 KeyORTB 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.

ParameterTypeDescriptionExample
idStringID uniquely identifying the content.381d2e0b-548d-4f27-bfdd-e6e66f43557e
episodeIntegerEpisode number.1
titleString

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
seriesString

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
seasonStringContent season (for example, “Season 3”).Season3
artistStringArtist credited with the content.GeorgeLucas
genreStringGenre that best describes the content (for example, rock, pop, etc).Action
albumStringAlbum to which the content belongs; typically for audio.Action
isrcStringInternational Standard Recording Code conforming to ISO-3901.2
urlStringURL of the content, for buy-side contextualization or review.http://www.pubmatic.com/test/
catString ArrayArray of IAB content categories that describe the content producer.IAB1-1,IAB1-2
prodqIntegerProduction quality.1
contextIntegerType of content (game, video, text, etc.).1
contentratingStringContent rating (for example, MPAA).MPAA
userratingStringUser rating of the content (for example, number of stars, likes, etc.).9-Stars
qagmediaratingIntegerMedia rating per IQG guidelines.1
keywordsStringComma separated list of keywordsdescribing the contentActionMovies
livestreamInteger
  • 0 = Not Live
  • 1 = Content is Live (for example, stream, live blog).
1
sourcerelationshipInteger
  • 0 = Indirect
  • 1 = Direct.
1
lenIntegerLength of content in seconds; appropriate for video or audio.12000
languageStringContent language using ISO-639-1-alpha-2.en-US
embeddableInteger

Indicator of whether ornot 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 KeysORTB 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.

ParameterTypeDescriptionExample
idStringContent producer or originator ID. Useful if content is syndicated and may be posted on a site using embed tagsProd123
nameStringContent producer or originator name; for example, “Warner Bros”.GaryKurtz
catString ArrayArray of IAB content categories that describe the content producer.IAB1-5,IAB1-6
domainStringHighest 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 KeyORTB 2.5 Key
dev.[param]bidrequest.device.[param]

The following table lists the parameters available to let you configure Device objects.

ParameterTypeDescriptionExample
uaString

Browser user agent string.

It can be derived from User-Agent header if not specified.

Mozilla%2F5. 0%20
(Windows%20NT%206.
1%3B%20Win64%3B%20x64%3B%20rv%3A47.0)
%20Gecko%2F20100101%20Firefox%2F47.0

dntInteger

Standard “DoNotTrack”flagas set in the header by the browser.

  • 0 = Tracking is unrestricted
  • 1 = Do Not Track.
1
lmtInteger

“Limit Ad Tracking” signal commercially endorsed (for example, iOS, Android)

  • 0 = tracking is unrestricted
  • 1 = tracking must be limited per commercial guidelines.
1
ipString

IPv4 address closest to device.

It can be derived from request headers in following sequence.

* HTTP_RLNCLIENTIPADDR
* HTTP_SOURCE_IP
* HTTP_X_CLUSTER_CLIENT_IP
* HTTP_X_FORWARDED_IP
* REMOTE_ADDR
127.0.0.1
ipv6StringIP address closest to device as IPv6.2001:db8::8a2e:370:7334
devicetype IntegerThe general type of device.1
makeStringDevice make (for example, “Apple”)Samsung
modelStringDevice model (for example, “iPhone”)Galaxy-A70S
osStringDevice operating system (for example, “iOS”).Android
osvStringDevice operating system version (for example, “3.1.2”)MarshMellow
hwvStringHardware version of the device (for example, “5S” for iPhone 5S).A70s
hIntegerPhysical height of the screen in pixels768
wIntegerPhysical width of the screen in pixels1366
ppiIntegerScreen size as pixels per linear inch.4096
pxratioFloatThe ratio of physical pixels to device independent pixels1.3
jsInteger

Support for JavaScript.

  • 0 = No.
  • 1 = Yes.
1
geofetchInteger

Indicates if the geolocation API will be available to JavaScript code running in the banner

  • 0 = No.
  • 1 = Yes.
0
flashverStringVersion of Flash supported by the browser.1.1
languageStringBrowser language using ISO-639-1-alpha-2.en-US
carrierStringCarrier or ISP (for example, “VERIZON”) using exchange-curated string names, which once deduced, should be published to bidders.VERIZON
mccmncString

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 IntegerNetwork connection type. 2
ifaStringID sanctioned for advertiser use in the clear (that is, not hashed).EA7583CD-A667-48BC-B806-42ECB2B48606
didsha1StringHardware device ID (for example, IMEI); hashed via SHA1. 613b4d2f6a09ee5f820d670a1d5b1cc4ccc08bc2
didmd5StringHardware device ID (for example, IMEI); hashed via MD5.12d2cd0eacd05dae666c4a5ff3067e42
dpidsha1StringPlatform device ID (for example, Android ID); hashed via SHA1. 613b4d2f6a09ee5f820d670a1d5b1cc4ccc08bc2
dpidmd5StringPlatform device ID (for example, Android ID); hashed via MD5.12d2cd0eacd05dae666c4a5ff3067e42
macsha1StringMAC address of the device; hashed via SHA1. 613b4d2f6a09ee5f820d670a1d5b1cc4ccc08bc2
macmd5StringMAC 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 KeyORTB 2.5 Key
user.[param]bidrequest.user.[param]

The following table lists the parameters available to let you configure User objects.

ParameterTypeDescriptionExample
idString

Exchange-specific ID for the user.

At least one of idor buyeruidis recommended.

45067fec-eab7-4ca0-ad3a-87b01f21846a
buyeruidString

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
yobIntegerYear of birth as a 4-digit integer.1990
genderStringGender, where “M” = male,“F” = female, “O” = known to be other (that is, omitted is unknown).M
keywordsStringComma separated list of keywords, interests, or intent.Movies
customdataString

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.consentStringGDPR 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 KeysORTB 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.

ParameterTypeDescriptionExample
latFloatLatitude from -90.0 to +90.0, where negative is south.72.6
lonFloatLongitude from -180.0 to +180.0, where negative is west.72.6
type Integer Source of location data; recommended when passing lat/lon.1
accuracyInteger

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
lastfixInteger

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 IntegerService or provider used to determine geolocation from IP address if applicable (that is, type = 2).1
countryStringCountry code using ISO-3166-1-alpha-3India
regionStringRegion code using ISO-3166-2; 2-letter state code if USA.Maharashtra
regionfips104String

Region of a country using FIPS 10-4 notation.

While OpenRTB supports this attribute, it has been withdrawn by NIST in 2008.

MAHA
metroStringGoogle metro code; similar to but not exactly Nielsen DMAs.Mumbai
cityStringCity using United Nations Code for Trade and Transport Locations.Mumbai
zipStringZip or postal code.123456
utcoffsetIntegerLocal 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 KeyORTB 2.5 Key
regs.[param]bidrequest.regs.[param]

The following table lists the parameters available to let you configure User objects.

ParameterTypeDescriptionExample
coppaInteger

Indicates whether the BidRequest is subject to the COPPA regulations established by the US FTC.

  • 0 = No
  • 1 = Yes
1
ext.gdprInteger

Indicates whether GDPR applies to the BidRequest.

  • 0 = No
  • 1 = Yes
1
ext.us_privacyStringCCPA 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 KeyORTB 2.5 Key
req.ext.wrapper.[param]bidrequest.ext.[param]

The following table lists the parameters available to let you configure User objects.

ParameterTypeDescriptionExample
versionidIntegerPubMatic OpenWrap specific profile versionid.1
sumry_disableInteger

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
clientconfigIntegerPubMatic 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…

  • 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 KeysORTB 2.5 Key
req.extbidrequest.ext
src.extbidrequest.source.ext
regs.extbidrequest.regs.ext
imp.extbidrequest.imp[0].ext
imp.vid.extbidrequest.imp[0].video.ext
site.extbidrequest.site.ext
app.extbidrequest.app.ext
site.pub.extbidrequest.site.publisher.ext
site.cnt.extbidrequest.site.content.ext
site.cnt.prod.extbidrequest.site.content.producer.ext
app.pub.extbidrequest.app.publisher.ext
app.cnt.extbidrequest.app.content.ext
app.cnt.prod.extbidrequest.app.content.producer.ext
dev.extbidrequest.device.ext
dev.geo.extbidrequest.device.geo.ext
user.extbidrequest.user.ext
user.geo.extbidrequest.user.geo.ext

Example BidRequest

Sample Video BidRequest Using CURL
curl -v "http://172.16.4.192:7878/video/vast?imp.tagid=%2F15671365%2FDMDemo&app.pub.id=5890&req.ext.wrapper.profileid=3514&req.ext.wrapper.versionid=1&imp.vid.mimes=video/3gpp,video/mp4,video/webm"
*   Trying 172.16.4.192:7878...
* TCP_NODELAY set
* Connected to 172.16.4.192 (172.16.4.192) port 7878 (#0)
> GET /video/vast?imp.tagid=%2F15671365%2FDMDemo&app.pub.id=5890&req.ext.wrapper.profileid=3514&req.ext.wrapper.versionid=1&imp.vid.mimes=video/3gpp,video/mp4,video/webm HTTP/1.1
> Host: 172.16.4.192:7878
> User-Agent: curl/7.65.2
> Accept: */*
> 
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< Access-Control-Allow-Origin: *
< Content-Type: application/xml
< Date: Mon, 16 Mar 2020 12:54:18 GMT
< Transfer-Encoding: chunked
< 
<VAST version="3.0"><Ad id="601364"><InLine><AdSystem><![CDATA[Acudeo Compatible]]></AdSystem><AdTitle><![CDATA[VAST 2.0 Instream Test 1]]></AdTitle><Description><![CDATA[VAST 2.0 Instream Test 1]]></Description><Impression><![CDATA[//t.pubmatic.com/wt?bidid=a9824138-92ac-4185-aa28-7439a06da345&eg=15&en=15&iid=50f9699d-3ab7-4ba9-84b9-0a920741bb02&kgpv=%2F15671365%2FDMDemo%400x0&pdvid=1&pid=3514&pn=pubmatic&pubid=5890&purl=&slot=a9824138-92ac-4185-aa28-7439a06da345_%2F15671365%2FDMDemo&tst=1584363258]]></Impression><Impression><![CDATA[http://172.16.4.213/AdServer/AdDisplayTrackerServlet?operId=1&pubId=5890&siteId=47163&adId=1405268&adType=13&adServerId=243&kefact=70.000000&kaxefact=70.000000&kadNetFrequecy=0&kadwidth=0&kadheight=0&kadsizeid=97&kltstamp=1529929473&indirectAdId=0&adServerOptimizerId=2&ranreq=0.1&kpbmtpfact=100.000000&dcId=1&tldId=0&passback=0&svr=MADS1107&ekefact=Ad8wW91TCwCmdG0jlfjXn7Tyzh20hnTVx-m5DoNSep-RXGDr&ekaxefact=Ad8wWwRUCwAGir4Zzl1eF0bKiC-qrCV0D0yp_eE7YizB_BQk&ekpbmtpfact=Ad8wWxRUCwD7qgzwwPE2LnS5-Ou19uO5amJl1YT6-XVFvQ41&imprId=48F73E1A-7F23-443D-A53C-30EE6BBF5F7F&oid=48F73E1A-7F23-443D-A53C-30EE6BBF5F7F&crID=creative-1_1_2&ucrid=160175026529250297&campaignId=17050&creativeId=0&pctr=0.000000&wDSPByrId=511&wDspId=6&wbId=0&wrId=0&wAdvID=3170&isRTB=1&rtbId=EBCA079F-8D7C-45B8-B733-92951F670AA1&pmZoneId=zone1&pageURL=www.yahoo.com&lpu=ae.com]]></Impression><Impression><![CDATA[https://dsptracker.com/{PSPM}]]></Impression><Error><![CDATA[http://172.16.4.213/track?operId=7&p=5890&s=47163&a=1405268&wa=243&ts=1529929473&wc=17050&crId=creative-1_1_2&ucrid=160175026529250297&impid=48F73E1A-7F23-443D-A53C-30EE6BBF5F7F&advertiser_id=3170&ecpm=70.000000&er=[ERRORCODE]]]></Error><Error><![CDATA[https://Errortrack.com?p=1234&er=[ERRORCODE]]]></Error><Creatives><Creative AdID="601364"><Linear skipoffset="70%"><TrackingEvents><Tracking event="close"><![CDATA[https://mytracking.com/linear/close]]></Tracking><Tracking event="skip"><![CDATA[https://mytracking.com/linear/skip]]></Tracking><Tracking event="creativeView"><![CDATA[http://172.16.4.213/track?operId=7&p=5890&s=47163&a=1405268&wa=243&ts=1529929473&wc=17050&crId=creative-1_1_2&ucrid=160175026529250297&impid=48F73E1A-7F23-443D-A53C-30EE6BBF5F7F&advertiser_id=3170&ecpm=70.000000&e=1]]></Tracking><Tracking event="start"><![CDATA[http://172.16.4.213/track?operId=7&p=5890&s=47163&a=1405268&wa=243&ts=1529929473&wc=17050&crId=creative-1_1_2&ucrid=160175026529250297&impid=48F73E1A-7F23-443D-A53C-30EE6BBF5F7F&advertiser_id=3170&ecpm=70.000000&e=2]]></Tracking><Tracking event="midpoint"><![CDATA[http://172.16.4.213/track?operId=7&p=5890&s=47163&a=1405268&wa=243&ts=1529929473&wc=17050&crId=creative-1_1_2&ucrid=160175026529250297&impid=48F73E1A-7F23-443D-A53C-30EE6BBF5F7F&advertiser_id=3170&ecpm=70.000000&e=3]]></Tracking><Tracking event="firstQuartile"><![CDATA[http://172.16.4.213/track?operId=7&p=5890&s=47163&a=1405268&wa=243&ts=1529929473&wc=17050&crId=creative-1_1_2&ucrid=160175026529250297&impid=48F73E1A-7F23-443D-A53C-30EE6BBF5F7F&advertiser_id=3170&ecpm=70.000000&e=4]]></Tracking><Tracking event="thirdQuartile"><![CDATA[http://172.16.4.213/track?operId=7&p=5890&s=47163&a=1405268&wa=243&ts=1529929473&wc=17050&crId=creative-1_1_2&ucrid=160175026529250297&impid=48F73E1A-7F23-443D-A53C-30EE6BBF5F7F&advertiser_id=3170&ecpm=70.000000&e=5]]></Tracking><Tracking event="complete"><![CDATA[http://172.16.4.213/track?operId=7&p=5890&s=47163&a=1405268&wa=243&ts=1529929473&wc=17050&crId=creative-1_1_2&ucrid=160175026529250297&impid=48F73E1A-7F23-443D-A53C-30EE6BBF5F7F&advertiser_id=3170&ecpm=70.000000&e=6]]></Tracking></TrackingEvents><Duration><![CDATA[00:00:04]]></Duration><VideoClicks><ClickTracking><![CDATA[http://172.16.4.213/track?operId=7&p=5890&s=47163&a=1405268&wa=243&ts=1529929473&wc=17050&crId=creative-1_1_2&ucrid=160175026529250297&impid=48F73E1A-7F23-443D-A53C-30EE6BBF5F7F&advertiser_id=3170&ecpm=70.000000&e=99]]></ClickTracking><ClickThrough><![CDATA[https://www.pubmatic.com]]></ClickThrough></VideoClicks><MediaFiles><MediaFile delivery="progressive" type="video/mp4* Connection #0 to host 172.16.4.192 left intact
" bitrate="500" width="400" height="300" scalable="true" maintainAspectRatio="true"><![CDATA[https://stagingams.pubmatic.com:8443/openwrap/media/pubmatic.mp4]]></MediaFile></MediaFiles></Linear></Creative></Creatives><Pricing model="CPM" currency="USD"><![CDATA[15]]></Pricing></InLine></Ad></VAST>

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.

ParameterTypeMandatory
(with a defined AdPod object)
DescriptionDefault value
(with a defined AdPod object)
offsetIntegerN

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
minadsIntegerNMinimum number of ads to include in the AdPod.2
maxadsIntegerNMaximum number of ads to inlcude in the AdPod.3
admindurationIntegerNMinimum duration in seconds for each ad in the AdPod.video.minduration/2
admaxdurationIntegerNMaximum duration in seconds for each ad in the AdPod.video.maxduration/2
excladvIntegerNPercentage of ads allowed to have the same advertiser in the AdPod.100
excliabcatIntegerNPercentage of ads allowed to have the same IAB category in the AdPod.100
BidRequest-only parameters
adpod
(POST method only)
ObjectYNew object for defining an AdPod object.
crosspodexcladvIntegerNPercentage of ads allowed to have the same advertiser across all AdPods in the BidRequest.100
crosspodexcliabcatIntegerNPercentage of ads allowed to have the same IAB categories across all AdPod s in the BidRequest .100
excliabcatwindowIntegerN

The number of minutes during which the exclusive IAB rule applies. If two AdPods render within a window, then the rule applies, otherwise the rule resets.

100
excladvwindowIntegerN

The number of minutes during which the exclusive advertiser rule applies. If two AdPod s render within a window, then the rule applies, otherwise the rule resets.

100


CTV endpoints

EndpointDescription
OpenRTB endpoint returns IAB Standard OpenRTB 2.5 formatted response for a BidRequest.
VAST endpoint returns VAST-format XML response for a video BidRequest.

OpenRTB endpoint response

IAB Standard Open RTB 2.5 BidResponse format.

Response Headers

Content-Typeapplication/json
Valid OpenRTB BidResponse
* Response Headers
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< Access-Control-Allow-Origin: *
< Content-Type: application/json
< Date: Mon, 16 Mar 2020 12:41:32 GMT
< Content-Length: 47
< 
{
	"id": "1559039248176",
	"seatbid": [{
		"bid": [{
			"id": "28635736ddc2bb1",
			"impid": "28635736ddc2bb1",
			"price": 1.1,
			"adm": "<VAST version=\"3.0\"><![CDATA[\n]]><Ad id=\"1\"><![CDATA[\n]]><Wrapper><![CDATA[\n]]><AdSystem><![CDATA[PubMatic]]></AdSystem><![CDATA[\n]]><VASTAdTagURI><![CDATA[https://stagingva.pubmatic.com:8443/video/Shashank/dspResponse/vastInline.php?adt=13&m=1+2+6+7+8&x=3&y=3&t=0&va=3&c=23216&tpbt=shashank&nuad=1x1&sc=1]]></VASTAdTagURI><![CDATA[\n]]><Error><![CDATA[http://aktrack.pubmatic.com/track?operId=7&p=159586&s=659893&a=2621943&wa=243&ts=1584005486&wc=23216&crId=adt:13_m:1+2+6+7+8_x:3_y:3_t:0_va:3_c:23216_tpbt:shashank_nuad:1x1_sc:1_off&ucrid=11591101254269920398&impid=E43A994E-0139-453F-A0A6-111E3D0BFBAD&advertiser_id=116206&ecpm=1.100000&er=[ERRORCODE]]]></Error><![CDATA[\n]]><Error><![CDATA[https://image8.pubmatic.com/AdServer/ImgSync?&fp=1&mpc=10&p=159586&gdpr=1&gdpr_consent=BOEFEAyOEFEAyAHABDENAI4AAAB9vABAASA&pmc=1&pu=https%3A%2F%2Fimage4.pubmatic.com%2FAdServer%2FSPug%3Fpmc%3D1%26partnerID%3D159586%26partnerUID%3D%28null%29]]></Error><![CDATA[\n]]><Impression><![CDATA[//127.0.0.1:8080/wt?bidid=28635736ddc2bb1&eg=1.1&en=1.1&iid=5eeea7bb-c3a3-4788-8ade-7cf019dda1d3&kgpv=%2F15671365%2FDMDemo%400x0&pdvid=2&pid=1887&pn=pubmatic&pubid=159586&purl=http%3A%2F%2Febay.com%2Finte%2Fautomation%2Fs2s%2Fpwt_parameter_validation_muti_slot_multi_size.html%3Fvideobid%3D5&slot=28635736ddc2bb1_%2F15671365%2FDMDemo&tst=1584005483]]></Impression><Impression><![CDATA[http://aktrack.pubmatic.com/AdServer/AdDisplayTrackerServlet?operId=1&pubId=159586&siteId=659893&adId=2621943&adType=13&adServerId=243&kefact=1.100000&kaxefact=1.100000&kadNetFrequecy=0&kadwidth=0&kadheight=0&kadsizeid=97&kltstamp=1584005486&indirectAdId=0&adServerOptimizerId=2&ranreq=0.1&kpbmtpfact=821.000000&dcId=1&tldId=0&passback=0&svr=ShashankAdServer&ekefact=bgFqXjk7BABqeeq1vNmIqfzWp43CzCesuFsFruVq5Ajvkuh-&ekaxefact=bgFqXlA7BAA_y0cAZgRlplvbsz1ViYMZk-ZoOtN6t7tIV4yN&ekpbmtpfact=bgFqXmI7BAAOigLz24ttvLAd0ktmDVm7f9Pi73FoFB6wxU7X&enpp=bgFqXnU7BABugqBx5MZqgLua_IKRd28xZtHOasI114bVcfhP&crID=adt:13_m:1+2+6+7+8_x:3_y:3_t:0_va:3_c:23216_tpbt:shashank_nuad:1x1_sc:1_off&lpu=ae.com&ucrid=11591101254269920398&campaignId=23216&creativeId=0&pctr=0.000000&wDSPByrId=1&wDspId=22&wbId=0&wrId=0&wAdvID=116206&isRTB=1&rtbId=C9CEB2A5-A0E7-4009-9D16-82DB0CE6ADF1&imprId=E43A994E-0139-453F-A0A6-111E3D0BFBAD&oid=E43A994E-0139-453F-A0A6-111E3D0BFBAD&country=Ind&pageURL=http%3A%2F%2Febay.com%2Finte%2Fautomation%2Fs2s%2Fpwt_parameter_validation_muti_slot_multi_size.html%3Fvideobid%3D5&pmc=1&tpb=0]]></Impression><![CDATA[\n]]><Impression><![CDATA[https://image8.pubmatic.com/AdServer/ImgSync?&fp=1&mpc=10&p=159586&gdpr=1&gdpr_consent=BOEFEAyOEFEAyAHABDENAI4AAAB9vABAASA&pmc=1&pu=https%3A%2F%2Fimage4.pubmatic.com%2FAdServer%2FSPug%3Fpmc%3D1%26partnerID%3D159586%26partnerUID%3D%28null%29]]></Impression><![CDATA[\n]]><Creatives><![CDATA[\n]]><Creative><![CDATA[\n]]><Linear><![CDATA[\n]]><TrackingEvents><![CDATA[\n]]><Tracking event=\"creativeView\"><![CDATA[http://aktrack.pubmatic.com/track?operId=7&p=159586&s=659893&a=2621943&wa=243&ts=1584005486&wc=23216&crId=adt:13_m:1+2+6+7+8_x:3_y:3_t:0_va:3_c:23216_tpbt:shashank_nuad:1x1_sc:1_off&ucrid=11591101254269920398&impid=E43A994E-0139-453F-A0A6-111E3D0BFBAD&advertiser_id=116206&ecpm=1.100000&e=1]]></Tracking><![CDATA[\n]]><Tracking event=\"start\"><![CDATA[http://aktrack.pubmatic.com/track?operId=7&p=159586&s=659893&a=2621943&wa=243&ts=1584005486&wc=23216&crId=adt:13_m:1+2+6+7+8_x:3_y:3_t:0_va:3_c:23216_tpbt:shashank_nuad:1x1_sc:1_off&ucrid=11591101254269920398&impid=E43A994E-0139-453F-A0A6-111E3D0BFBAD&advertiser_id=116206&ecpm=1.100000&e=2]]></Tracking><![CDATA[\n]]><Tracking event=\"midpoint\"><![CDATA[http://aktrack.pubmatic.com/track?operId=7&p=159586&s=659893&a=2621943&wa=243&ts=1584005486&wc=23216&crId=adt:13_m:1+2+6+7+8_x:3_y:3_t:0_va:3_c:23216_tpbt:shashank_nuad:1x1_sc:1_off&ucrid=11591101254269920398&impid=E43A994E-0139-453F-A0A6-111E3D0BFBAD&advertiser_id=116206&ecpm=1.100000&e=3]]></Tracking><![CDATA[\n]]><Tracking event=\"firstQuartile\"><![CDATA[http://aktrack.pubmatic.com/track?operId=7&p=159586&s=659893&a=2621943&wa=243&ts=1584005486&wc=23216&crId=adt:13_m:1+2+6+7+8_x:3_y:3_t:0_va:3_c:23216_tpbt:shashank_nuad:1x1_sc:1_off&ucrid=11591101254269920398&impid=E43A994E-0139-453F-A0A6-111E3D0BFBAD&advertiser_id=116206&ecpm=1.100000&e=4]]></Tracking><![CDATA[\n]]><Tracking event=\"thirdQuartile\"><![CDATA[http://aktrack.pubmatic.com/track?operId=7&p=159586&s=659893&a=2621943&wa=243&ts=1584005486&wc=23216&crId=adt:13_m:1+2+6+7+8_x:3_y:3_t:0_va:3_c:23216_tpbt:shashank_nuad:1x1_sc:1_off&ucrid=11591101254269920398&impid=E43A994E-0139-453F-A0A6-111E3D0BFBAD&advertiser_id=116206&ecpm=1.100000&e=5]]></Tracking><![CDATA[\n]]><Tracking event=\"complete\"><![CDATA[http://aktrack.pubmatic.com/track?operId=7&p=159586&s=659893&a=2621943&wa=243&ts=1584005486&wc=23216&crId=adt:13_m:1+2+6+7+8_x:3_y:3_t:0_va:3_c:23216_tpbt:shashank_nuad:1x1_sc:1_off&ucrid=11591101254269920398&impid=E43A994E-0139-453F-A0A6-111E3D0BFBAD&advertiser_id=116206&ecpm=1.100000&e=6]]></Tracking><![CDATA[\n]]><Tracking event=\"skip\"><![CDATA[http://aktrack.pubmatic.com/track?operId=7&p=159586&s=659893&a=2621943&wa=243&ts=1584005486&wc=23216&crId=adt:13_m:1+2+6+7+8_x:3_y:3_t:0_va:3_c:23216_tpbt:shashank_nuad:1x1_sc:1_off&ucrid=11591101254269920398&impid=E43A994E-0139-453F-A0A6-111E3D0BFBAD&advertiser_id=116206&ecpm=1.100000&e=7]]></Tracking><![CDATA[\n]]></TrackingEvents><![CDATA[\n]]><VideoClicks><![CDATA[\n]]><ClickTracking><![CDATA[http://aktrack.pubmatic.com/track?operId=7&p=159586&s=659893&a=2621943&wa=243&ts=1584005486&wc=23216&crId=adt:13_m:1+2+6+7+8_x:3_y:3_t:0_va:3_c:23216_tpbt:shashank_nuad:1x1_sc:1_off&ucrid=11591101254269920398&impid=E43A994E-0139-453F-A0A6-111E3D0BFBAD&advertiser_id=116206&ecpm=1.100000&e=99]]></ClickTracking><![CDATA[\n]]></VideoClicks><![CDATA[\n]]></Linear><![CDATA[\n]]></Creative><![CDATA[\n]]></Creatives><![CDATA[\n]]><Extensions><![CDATA[\n]]><Extension><![CDATA[\n]]><Meta><![CDATA[name=pm-forcepixel;ver=1.0]]></Meta><![CDATA[\n]]><Pixel loc=\"0\"><![CDATA[\n]]><Code type=\"1\"><![CDATA[https://ads.pubmatic.com/AdServer/js/showad.js#PIX&ptask=DSP&SPug=1&fp=1&mpc=10&u=45067fec-eab7-4ca0-ad3a-87b01f21846a&p=159586&s=659893&d=1&cp=0&sc=0&rs=0&os=0&gdpr=1&gdpr_consent=BOEFEAyOEFEAyAHABDENAI4AAAB9vABAASA]]></Code><![CDATA[\n]]></Pixel><![CDATA[\n]]></Extension><![CDATA[\n]]></Extensions><![CDATA[\n]]></Wrapper><![CDATA[\n]]></Ad><![CDATA[\n]]></VAST>",
			"adomain": [
				"ae.com"
			],
			"cid": "23216",
			"crid": "adt:13_m:1+2+6+7+8_x:3_y:3_t:0_va:3_c:23216_tpbt:shashank_nuad:1x1_sc:1_off",
			"h": 0,
			"w": 0
		}],
		"seat": "pubmatic"
	}],
	"cur": "USD"
}

Error response

OpenWrap CTV OpenRTB endpoint uses two error formats according to the type of error.

1. Input parameter error…
{
    "ErrorCode": 6,
    "Error": "Invalid Configuration"
}


2. SSP Response error…
{
    "id": "0a0e40c8-f66d-4c11-9e9a-f7993b6065bb",
    "seatbid": [
        {
            "bid": [
                {
                    "id": "90b5a5fc-7b46-47db-8380-820c216ff426",
                    "impid": "90b5a5fc-7b46-47db-8380-820c216ff426",
                    "price": 0,
                    "h": 0,
                    "w": 0,
                    "ext": {}
                }
            ],
            "seat": "pubmatic"
        }
    ],
    "ext": {
        "matchedimpression": {
            "pubmatic": 0
        },
        "responsetimemillis": {
            "pubmatic": 55
        },
        "tmaxrequest": 489
    }
}

VAST endpoint response

The VAST endpoint returns a standard VAST XML response. In the cases of, Request ERRORApplication 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-Typeapplication/xml
X-Ow-Status

Error details:

KeyDescription
ErrorCodeInteger Error Code
ErrorGranular Error Message
Sample Error Details
{"ErrorCode":700,"Error":"Missing Profile ID"}

Endpoint examples

Valid VAST response with headers…
* Response Headers
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< Access-Control-Allow-Origin: *
< Content-Type: application/xml
< Date: Mon, 16 Mar 2020 12:19:43 GMT
< Transfer-Encoding: chunked
< 
<VAST version="3.0">
    <Ad id="601364">
        <InLine>
            <AdSystem>
                <![CDATA[Acudeo Compatible]]>
            </AdSystem>
            <AdTitle>
                <![CDATA[VAST 2.0 Instream Test 1]]>
            </AdTitle>
            <Description>
                <![CDATA[VAST 2.0 Instream Test 1]]>
            </Description>
            <Impression>
                <![CDATA[//t.pubmatic.com/wt?bidid=ed49d230-b9fa-4d62-9d4f-2f2ec9e9142a&eg=15&en=15&iid=35226ad9-acd2-4e16-984b-7d4559fc1f87&kgpv=%2F15671365%2FDMDemo%400x0&pdvid=1&pid=3514&pn=pubmatic&pubid=5890&purl=https%3A%2F%2Fplay.google.com%2Fstore%2Fapps%2Fdetails%3Fid%3Dcom.foo.mygame&slot=ed49d230-b9fa-4d62-9d4f-2f2ec9e9142a_%2F15671365%2FDMDemo&tst=1584361062]]>
            </Impression>
            <Impression>
                <![CDATA[http://172.16.4.213/AdServer/AdDisplayTrackerServlet?operId=1&pubId=5890&siteId=47163&adId=1405268&adType=13&adServerId=243&kefact=70.000000&kaxefact=70.000000&kadNetFrequecy=0&kadwidth=0&kadheight=0&kadsizeid=97&kltstamp=1529929473&indirectAdId=0&adServerOptimizerId=2&ranreq=0.1&kpbmtpfact=100.000000&dcId=1&tldId=0&passback=0&svr=MADS1107&ekefact=Ad8wW91TCwCmdG0jlfjXn7Tyzh20hnTVx-m5DoNSep-RXGDr&ekaxefact=Ad8wWwRUCwAGir4Zzl1eF0bKiC-qrCV0D0yp_eE7YizB_BQk&ekpbmtpfact=Ad8wWxRUCwD7qgzwwPE2LnS5-Ou19uO5amJl1YT6-XVFvQ41&imprId=48F73E1A-7F23-443D-A53C-30EE6BBF5F7F&oid=48F73E1A-7F23-443D-A53C-30EE6BBF5F7F&crID=creative-1_1_2&ucrid=160175026529250297&campaignId=17050&creativeId=0&pctr=0.000000&wDSPByrId=511&wDspId=6&wbId=0&wrId=0&wAdvID=3170&isRTB=1&rtbId=EBCA079F-8D7C-45B8-B733-92951F670AA1&pmZoneId=zone1&pageURL=www.yahoo.com&lpu=ae.com]]>
            </Impression>
            <Impression>
                <![CDATA[https://dsptracker.com/{PSPM}]]>
            </Impression>
            <Error>
                <![CDATA[http://172.16.4.213/track?operId=7&p=5890&s=47163&a=1405268&wa=243&ts=1529929473&wc=17050&crId=creative-1_1_2&ucrid=160175026529250297&impid=48F73E1A-7F23-443D-A53C-30EE6BBF5F7F&advertiser_id=3170&ecpm=70.000000&er=[ERRORCODE]]]>
            </Error>
            <Error>
                <![CDATA[https://Errortrack.com?p=1234&er=[ERRORCODE]]]>
            </Error>
            <Creatives>
                <Creative AdID="601364">
                    <Linear skipoffset="70%">
                        <TrackingEvents>
                            <Tracking event="close">
                                <![CDATA[https://mytracking.com/linear/close]]>
                            </Tracking>
                            <Tracking event="skip">
                                <![CDATA[https://mytracking.com/linear/skip]]>
                            </Tracking>
                            <Tracking event="creativeView">
                                <![CDATA[http://172.16.4.213/track?operId=7&p=5890&s=47163&a=1405268&wa=243&ts=1529929473&wc=17050&crId=creative-1_1_2&ucrid=160175026529250297&impid=48F73E1A-7F23-443D-A53C-30EE6BBF5F7F&advertiser_id=3170&ecpm=70.000000&e=1]]>
                            </Tracking>
                            <Tracking event="start">
                                <![CDATA[http://172.16.4.213/track?operId=7&p=5890&s=47163&a=1405268&wa=243&ts=1529929473&wc=17050&crId=creative-1_1_2&ucrid=160175026529250297&impid=48F73E1A-7F23-443D-A53C-30EE6BBF5F7F&advertiser_id=3170&ecpm=70.000000&e=2]]>
                            </Tracking>
                            <Tracking event="midpoint">
                                <![CDATA[http://172.16.4.213/track?operId=7&p=5890&s=47163&a=1405268&wa=243&ts=1529929473&wc=17050&crId=creative-1_1_2&ucrid=160175026529250297&impid=48F73E1A-7F23-443D-A53C-30EE6BBF5F7F&advertiser_id=3170&ecpm=70.000000&e=3]]>
                            </Tracking>
                            <Tracking event="firstQuartile">
                                <![CDATA[http://172.16.4.213/track?operId=7&p=5890&s=47163&a=1405268&wa=243&ts=1529929473&wc=17050&crId=creative-1_1_2&ucrid=160175026529250297&impid=48F73E1A-7F23-443D-A53C-30EE6BBF5F7F&advertiser_id=3170&ecpm=70.000000&e=4]]>
                            </Tracking>
                            <Tracking event="thirdQuartile">
                                <![CDATA[http://172.16.4.213/track?operId=7&p=5890&s=47163&a=1405268&wa=243&ts=1529929473&wc=17050&crId=creative-1_1_2&ucrid=160175026529250297&impid=48F73E1A-7F23-443D-A53C-30EE6BBF5F7F&advertiser_id=3170&ecpm=70.000000&e=5]]>
                            </Tracking>
                            <Tracking event="complete">
                                <![CDATA[http://172.16.4.213/track?operId=7&p=5890&s=47163&a=1405268&wa=243&ts=1529929473&wc=17050&crId=creative-1_1_2&ucrid=160175026529250297&impid=48F73E1A-7F23-443D-A53C-30EE6BBF5F7F&advertiser_id=3170&ecpm=70.000000&e=6]]>
                            </Tracking>
                        </TrackingEvents>
                        <Duration>
                            <![CDATA[00:00:04]]>
                        </Duration>
                        <VideoClicks>
                            <ClickTracking>
                                <![CDATA[http://172.16.4.213/track?operId=7&p=5890&s=47163&a=1405268&wa=243&ts=1529929473&wc=17050&crId=creative-1_1_2&ucrid=160175026529250297&impid=48F73E1A-7F23-443D-A53C-30EE6BBF5F7F&advertiser_id=3170&ecpm=70.000000&e=99]]>
                            </ClickTracking>
                            <ClickThrough>
                                <![CDATA[https://www.pubmatic.com]]>
                            </ClickThrough>
                        </VideoClicks>
                        <MediaFiles>
                            <MediaFile delivery="progressive" type="video/mp4" bitrate="500" width="400" height="300" scalable="true" maintainAspectRatio="true">
                                <![CDATA[https://stagingams.pubmatic.com:8443/openwrap/media/pubmatic.mp4]]>
                            </MediaFile>
                        </MediaFiles>
                    </Linear>
                </Creative>
            </Creatives>
            <Pricing model="CPM" currency="USD">
                <![CDATA[15]]>
            </Pricing>
        </InLine>
    </Ad>
</VAST>


VAST error response…
* Response Headers
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< Access-Control-Allow-Origin: *
< Content-Type: application/xml
< X-Ow-Status: {"ErrorCode":700,"Error":"Missing Profile ID"}
< Date: Mon, 16 Mar 2020 12:20:41 GMT
< Content-Length: 21
< 
* Connection #0 to host 172.16.4.192 left intact
<VAST version="2.0"/>

Endpoint error codes


Error CodeError MessageHTTP Status CodeScenarios
500Empty Response500Any Panic in Program
600Missing Request ID400req.id is not specified
601Missing Impressions400req.imp is not specified
602Missing Site/App Object400req.site and req.app both not present
603Site App Both Present400req.site and req.app both present in request
604Missing Publisher ID400req.site.publisher.id or req.app.publisher.id not specified
605Missing Tag ID400req.imp.tagid is not specified
606Missing Impression ID400req.imp.id is not specified
607Missing Ad Type(Banner/Video)400banner/native/audio/video any one not specified in request
608Missing Ad Sizes400banner.w, banner.h, or banner.format is not specified
609Missing MIMEs400video.mimes or audio.mimes not specified
610Missing Native Request Payload400native.request payload not specified
611Missing Video Object400video object missing for ctv requests
700Missing Profile ID400mandatory 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 and POST 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.

ParameterTypeDescription
idstringID of the bid request that generated this response.
seatbidobject arrayArray of seatbid objects; 1+ required if a bid is to be made.
curstringBid currency using ISO-4217 alpha codes.default USD
customdatastringOptional 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.
extobjectPlaceholder 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.

ParameterTypeDescription
bidobject arrayArray of 1 or more Bid objects (Section 4.2.3) each related to an impression. Multiple bids can relate to the same impression.
seatstringID of the buyer seat on whose behalf the bid was made; for example, an advertiser, agency, or in the case of a BidRequest with AdPods, 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 Bids within a SeatBid object's bid property.

ParameterTypeDescription
idstringBidder auto-generated bid ID (at the PreBid side), to assist with logging/tracking.
impidstringID of the original Imp object in the parent BidRequest.
pricefloatSum 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.
admstringOptional 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.
adomainstring array

Advertiser domain for block list checking; for example, ford.com. Can be an array in the case of rotating creatives. Exchanges can restrict to only a single domain.

catstring arrayIAB content categories of the creative.
attributeinteger arraySet of attributes describing the creative.
extobjectPlaceholder 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

 Select to expand definitions...


Value

Description

1

VAST 1.0

2

VAST 2.0

3

VAST 3.0

4

VAST 1.0 Wrapper

5

VAST 2.0 Wrapper

6

VAST 3.0 Wrapper

7

VAST 4.0

8

VAST 4.0 Wrapper

9

DAAST 1.0

10

DAAST 1.0 Wrapper

Playback methods

 Select to expand definitions...


Value

Description

1

Initiates on Page Load with Sound On

2

Initiates on Page Load with Sound Off by Default

3

Initiates on Clickwith Sound On

4

Initiates on Mouse-Over with Sound On

5

Initiates on Entering Viewportwith Sound On

6

Initiates on Entering Viewportwith Sound Off by Default

Ad position

 Select to expand definitions...

Value

Description

0

Unknown

1

Above the Fold

2

DEPRECATED - May or may not be initially visible depending on screen size/resolution.

3

Below the Fold

4

Header

5

Footer

6

Sidebar

7

FullScreen

Video placement types

 Select to expand definitions...

Value

Description

1

In-Stream

Played before, during, or after the streaming video content that the consumer has requested; for example, 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; exists 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; that is, can't be scrolled out of view).  Note that a full-screen interstitial (for example, inmobile), can be distinguished from a floating/slider unit by the imp.instlfield parameter.

API frameworks

 Select to expand definitions...

Value

Description

1

VPAID 1.0

2

VPAID 2.0

3

MRAID-1

4

ORMMA

5

MRAID-2

6

MRAID-3

Video linearity

 Select to expand definitions...

Value

Description

1

Linear/In-Stream

2

Non-Linear/Overlay

Start delay

 Select to expand definitions...

Value

Description

>0

Mid-Roll (value indicates start delay in seconds)

0

Pre-Roll

-1

Generic Mid-Roll

-2

Generic Post-Roll

Content context

 Select to expand definitions...

Value

Description

1

Video: a video file or stream such as Internet TV broadcasts.

2

Game: an interactive software game.

3

Music: an audio file or stream such as Internet radio broadcasts.

4

Application: an interactive software application.

5

Text: a primarily textual document such as a web page, eBook, or news article.

6

Other: none of the other categories applies.

7

Unknown.

Content delivery methods

 Select to expand definitions...

Value

Description

1

Streaming

2

Progressive

3

Download

Playback cessation modes

 Select to expand definitions...

Value

Description

1

On video completion or when terminated by user

2

On leaving viewPort or when terminated by user

3

On leaving viewPort continues as a floating/slider unit until video completion or when terminated by user

Production quality

 Select to expand definitions...

Value

Description

0

Unknown

1

Professionally Produced

2

Prosumer

3

User Generated (UGC)

Inventory Quality Guidelines (IQG) ratings

 Select to expand definitions...

Value

Description

1

All Audiences

2

Everyone Over 12

3

Mature Audiences

Device type

 Select to expand definitions...

Value

Description

1

Mobile/Table

2

Personal Computer

3

Connected TV

4

Phone

5

Tablet

6

Connected Device

7

Set Top Box

Connection type

 Select to expand definitions...

Value

Description

0

Unknown

1

Ethernet

2

WIFI

3

Cellular Network –Unknown Generation

4

Cellular Network –2G

5

Cellular Network –3G

6

Cellular Network –4G

Location type

 Select to expand definitions...

Value

Description

1

GPS/Location Services

2

IP Address

3

User provided (e.g., registration data)

IP location services

 Select to expand definitions...

Value

Description

1

ip2location

2

Neustar (Quova)

3

MaxMind

4

NetAcuity(Digital Element)

Reference documents

⇧ Top

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

Table of Contents