OpenRTB API for Bidding
Object: BidRequest
VMX RTB bid requests always carry a single impression request. VMX also supports the concept of multiple seats per bidder.
Attribute |
Usage |
Sent? |
Notes |
---|---|---|---|
id |
Supported |
Always |
|
at |
Supported |
Always |
Although optional, always included on SSP RTB bid requests. 1= First Price auctions, 2= Second Price Plus. |
tmax |
Supported |
Sometimes |
Value of “200” often sent, dynamic values for some header bidding/S2S auctions may differ |
wseat |
Supported |
Sometimes |
To avoid long request messages, we limit the number of entities that may be included in wseat lists. BidRequest object limit =50. Deals object limit= 20. If the limit is exceeded, the wseat field will be absent. An allowlist still exists in our system and it is enforced. It won’t be sent in the bid request. Bids returned from buyers not on the allowlist are rejected ( appropriate loss reason noted in reporting). For requests without wseat present, any buyer may and should be sent. We filter the bids as needed on our side. If wseat is not present for a deal, assume all seats are eligible and bid with them. |
cur |
Supported (New to VMX) |
Always |
USA - US Dollar (USD) Canada - Canadian Dollar (CAD) Brazil - Brazilian Real (BRL) United Kingdom - British Pound (GBP) France, Spain, Italy, Germany - Euro (EUR) Japan - Japanese Yen (JPY) |
bcat |
Supported (New to VMX) |
Sometimes |
Values "IAB26", "IAB25", "IAB24" usually passed when included. |
badv |
Supported (New to VMX) |
Sometimes |
|
ext.omidpn |
Supported (New to VMX) |
Sometimes (app only) |
Identifier of the OM SDK integration. Same as the "name" parameter of the OMID Partner object. |
ext.omidpv |
Supported (New to VMX) |
Sometimes (app only) |
Version of the OM SDK integration. Same as the "versionString" parameter of the OMID Partner object. |
Object: BidRequest.Imp
Attribute |
Usage |
Sent? |
Notes |
---|---|---|---|
id |
Supported |
Always |
|
displaymanager |
Supported (New to VMX) |
Sometimes |
SDK passed here for app traffic when available |
displaymanagerver |
Supported (New to VMX) |
Sometimes |
SDK Version passed here for app traffic when available |
instl |
Supported (New to VMX) |
Sometimes |
|
bidfloor |
Supported |
Sometimes |
|
bidfloorcur |
Supported |
Sometimes |
USA - US Dollar (USD) Canada - Canadian Dollar (CAD) Brazil - Brazilian Real (BRL) United Kingdom - British Pound (GBP) France, Spain, Italy, Germany - Euro (EUR) Japan - Japanese Yen (JPY) |
secure |
Supported |
Always |
Value “1” always passed. Secure creatives are always required. Non-secure creatives are not accepted on VMX |
Object: BidRequest.Imp.Banner
Attribute |
Usage |
Sent? |
Notes |
---|---|---|---|
w |
Supported |
Always |
For app, the common fixed interstitial size (e.g., 320x480) is sent to indicate orientation (vs 480x320). |
h |
Supported |
Always |
|
pos |
Supported |
Always |
|
mimes |
Supported |
Always |
Typical banner value=*.* |
api |
Supported |
Always |
Typical App Traffic values=3 or 5. Value “7” also supported to communicate if OMID (Open Measurement Viewability) is available for a given app impression in a bid request |
Object: BidRequest.Imp.Banner.Format
This object represents an allowed size (i.e., height and width combination) for a banner impression. These are typically used in an array for an impression where multiple sizes are permitted. The Format object follows the OpenRTB 2.4 standard. The main size is always communicated in the Banner Object (described above).
Attribute |
Usage |
Sent? |
Notes |
---|---|---|---|
w |
Supported (New to VMX) |
Sometimes |
|
h |
Supported (New to VMX) |
Sometimes |
Object: BidRequest.Imp.Video
Attribute |
Usage |
Sent? |
Notes |
---|---|---|---|
w |
Supported (New to VMX) |
Always |
|
h |
Supported (New to VMX) |
Always |
|
pos |
Supported (New to VMX) |
Always |
|
mimes |
Supported (New to VMX) |
Always |
Typical values =video/mp4 or video/3gpp |
minduration |
Supported (New to VMX) |
Sometimes |
|
maxduration |
Supported (New to VMX) |
Sometimes |
|
protocols |
Supported (New to VMX) |
Sometimes |
Typical values=2,3,5 or 6 |
startdelay |
Supported (New to VMX) |
Sometimes |
Typical value=0 |
linearity |
Supported (New to VMX) |
Sometimes |
Typical value=1 |
maxbitrate |
Supported (New to VMX) |
Sometimes |
|
playbackmethod |
Supported (New to VMX) |
Sometimes |
Typical values=1,2 or 3 |
ext.skippable |
Supported (New to VMX) |
Sometimes |
Used to communicate mandatory skippability. Typical value=0 or 1. |
ext.skipoffset |
Supported (New to VMX) |
Sometimes |
Used to communicate time elapsed after the skip button appears. Typical value=7. |
Object: BidRequest.Imp.Native
VMX gives bidders the flexibility to utilize the OpenRTB Native 1.0, 1.1, or 1.2 Protocol definitions. We recommend new bidders integrate with the OpenRTB Native 1.1 Protocol definition or higher. For more information on what is supported by the SSP, please see the Verizon Media SSP Native Ads OpenRTB Integration Specs.
Attribute |
Usage |
Sent? |
Notes |
---|---|---|---|
request |
Supported |
Always |
Sample Request "request":"{\"plcmtcnt\":1,\"assets\":[{\"id\":1,\"required\":1,\"img\":{\"type\":3,\"w\":200,\"wmin\":150,\"h\":300,\"hmin\":280,\"mimes\":[\"image/jpg\",\"image/gif\"]}},{\"id\":2,\"required\":1,\"data\":{\"type\":2,\"len\":200}},{\"id\":3,\"required\":1,\"title\":{\"len\":75}},{\"id\":4,\"required\":1,\"data\":{\"type\":12,\"len\":100}}],\"context\":2,\"contextsubtype\":15,\"plcmttype\":1,\"ver\":\"1.1\",\"seq\":0}", |
ver |
Supported (New to VMX) |
Always |
Typical value=1.1 |
context | Supported (New to VMX) | Always | The context in which the ad appears, 1=content, 2=social, 3=product |
contextsubtype | Supported (New to VMX) | Always | A more detailed context in which the ad appears, typically 10=General or Mixed Content |
plcmttype |
Supported (New to VMX) |
Always | |
assets | Supported (New to VMX) |
Always | |
api |
Supported (New to VMX) |
Sometimes |
|
battr |
Supported (New to VMX) |
Sometimes |
Note: Native Types ease integration for our publisher partners. Native Types are defined once on the server and the specific details are propagated as needed to the ad requests. The biggest advantage of using Native Types is the equilibrium it brings to supply and demand, especially across the exchange. Standardizing ad requests increases the likelihood of finding creatives that match.
Native Inline Type
Asset |
Type |
Attribute Definition |
Advertiser Required |
Publisher Required |
---|---|---|---|---|
Title Text |
Text |
25 Character Max |
Yes |
Yes |
Body Text |
Text |
100 Character Max |
Yes |
No |
Icon Image |
Image |
240x240 px |
Yes |
Yes |
Main Image |
Image |
1200x627 px |
Yes |
No |
CTA Button |
Button |
15 Character Max |
Yes |
Yes |
Rating Text |
Text |
25 Character Max |
No |
No |
Disclaimer |
Text |
15 Character Max |
Yes |
Yes |
Object: BidRequest.Site
Attribute |
Usage |
Sent? |
Notes |
---|---|---|---|
id |
Supported |
Sometimes |
|
cat |
Supported |
Sometimes |
|
page |
Supported |
Always |
|
name |
Supported |
Sometimes |
|
domain |
Supported |
Sometimes |
|
cat |
Supported |
Sometimes |
|
sectioncat |
Supported |
Sometimes |
|
mobile |
Supported |
Sometimes |
Mobile-optimized signal, where 0=no, 1=yes. |
Object: BidRequest.App
Attribute |
Usage |
Sent? |
Notes |
---|---|---|---|
id |
Supported (New to VMX) |
Always |
|
name |
Supported (New to VMX) |
Sometimes |
|
bundle |
Supported (New to VMX) |
Always |
Unique ID of the app's package ID (Android) or bundle/AppStore ID (iOS). Typical values=com.test.verizon or123456789 |
Object: BidRequest.Site.Publisher or BidRequest.App.Publisher
Attribute |
Usage |
Sent? |
Notes |
---|---|---|---|
id |
Supported |
Always |
|
name |
Supported |
Sometimes |
Object: BidRequest.Device
Attribute |
Usage |
Sent? |
Notes |
---|---|---|---|
ua |
Supported |
Always |
|
dnt |
Supported |
Sometimes (Desktop only) |
|
lmt |
Supported |
Sometimes (App only) |
|
ip |
Supported |
Sometimes |
Last octet of IP address may be suppressed. |
ipv6 |
Supported |
Sometimes |
Last 4 hextets of IP address may be suppressed. |
devicetype |
Supported |
Always |
|
language |
Supported |
Always |
|
ifa |
Supported |
Sometimes |
|
carrier |
Supported |
Sometimes |
|
make |
Supported |
Sometimes |
|
os |
Supported |
Sometimes |
|
connectiontype |
Supported |
Sometimes |
Object: BidRequest.Device.Geo
Attribute |
Usage |
Sent? |
Notes |
---|---|---|---|
lat |
Supported |
Sometimes |
|
lon |
Supported |
Sometimes |
|
country |
Supported |
Sometimes |
|
city |
Supported |
Sometimes |
|
region | Supported | Sometimes | |
zip | Supported | Sometimes | |
type | Supported | Sometimes | Source of location data; recommended when passing lat/lon. |
Object: BidRequest.User
Attribute |
Usage |
Sent? |
Notes |
---|---|---|---|
id |
Supported |
Sometimes |
|
buyeruid |
Supported |
Sometimes |
Supported when VMX hosts the match table |
ext.consent |
Supported |
Sometimes |
IAB Consent string provided when the request is subject to GDPR |
Object: BidRequest.Regs
Attribute |
Usage |
Sent? |
Notes |
---|---|---|---|
coppa |
Supported |
Always |
Flag indicating whether this request is subject to COPPA regulations established by the USA FTC. 0=no 1=yes |
ext.gdpr |
Supported |
Always |
Flag indicates if this request is subject to GDPR.0=not subject to GDPR1=yes subject to GDPR |
ext.us_privacy | Supported | Sometimes (as of 1/1/2020) |
Flag indicates if this request is subject to CCPA. IAB US Privacy String format 'Specification_Version|Explicit_Notice|Opt-Out|-' Bid Request Example When CCPA Jurisdiction is In Effect and User Has Not Opted Out "regs": { "ext": { "us_privacy": "1YN-" } Bid Request Example When CCPA Jurisdiction is In Effect and User Has Opted Out "regs": { "ext": { "us_privacy": "1YY-" } |
Object: BidRequest.Pmp
Attribute |
Usage |
Sent? |
Notes |
---|---|---|---|
private_auction |
Supported |
Sometimes |
Indicator of auction eligibility to seats named in the Direct Deals object.0=all bids are accepted1=bids are restricted to the deals specified and the terms thereof. |
Object: BidRequest.Pmp.Deals
Attribute |
Usage |
Sent? |
Notes |
---|---|---|---|
id |
Supported |
Always |
|
at |
Supported |
Sometimes |
Optional override of the overall auction type of the bid Request. 1=First Price, 2=Second Price Plus, 3= the value passed in bidfloor is the agreed upon deal price. |
bidfloor |
Supported |
Sometimes |
|
bidfloorcur |
Supported (New to VMX) |
Sometimes |
USA - US Dollar (USD) Canada - Canadian Dollar (CAD) Brazil - Brazilian Real (BRL) United Kingdom - British Pound (GBP) France, Spain, Italy, Germany - Euro (EUR) Japan - Japanese Yen (JPY) |
wseat |
Supported |
Sometimes |
To avoid long request messages, we limit the number of entities that may be included in wseat lists. BidRequest object limit =50. Deals object limit= 20. If the limit is exceeded, the wseat field will be absent. An allowlist still exists in our system and it will be enforced but is not be sent in the bid request. If bids return for buyers not on the allowlist, they will be rejected (and noted with an appropriate loss reason in reporting). What this means for the bidder is that for a request without wseat present, any buyer may and should be sent. We will filter the bids as needed on our side. If wseat is not present for a deal, assume all seats are eligible and bid with them. |
Object: BidRequest.Pmp.Deals.Ext
The following extension is added when the deal has format object extension.
Attribute |
Usage |
Sent? |
Notes |
---|---|---|---|
format |
When deal has ad size targeting |
Sometimes |
Object array of ad sizes targeted by the deal. |
Object: BidRequest.Pmp.Deals.Format
The following extension is added when the deal has format object extension.
Attribute |
Usage |
Sent? |
Notes |
---|---|---|---|
Attribute |
Usage |
Sent? |
Notes |
w |
When deal has ad size targeting |
Sometimes |
Width of the ad unit as an integer |
h |
When deal has ad size targeting |
Sometimes |
Height of the ad unit as an integer |
Sample Bid Request with ad sizes in deal
"pmp": {
"private_auction": 0,
"deals": [{
"id": "509",
"bidfloor": 3,
"bidfloorcur": "USD",
"at": 3,
"wseat": ["Agency123","Agency456"]
}, {
"id": "131",
"bidfloor": 11.2,
"bidfloorcur": "USD",
"at": 3,
"wseat": ["Agency567","Agency789"]
"ext": {
"format": [{
“w”: “300”,
“h”: “250”
}]
}
Object: BidResponse
Attribute |
Required/Optional? |
Notes |
---|---|---|
id |
Required |
ID of the Bid Request |
bidid |
Optional |
A response ID generated by the bidder for tracking purposes. |
cur |
Required |
|
nbr |
Optional |
Object: BidResponse.SeatBid
Attribute |
Required/Optional? |
Notes |
---|---|---|
bid |
Required, array |
Each bid object corresponds to imp object in the bid request |
seat |
Required |
ID of the seat on whose behalf the bid was made. VMX recommends the use of multiple bids using the "seatbid" object to increase the likelihood of winning the auction. In cases where SSP targeting, blocklists, or Ad Screening may cause a winning bid to not be served, additional bids are considered independently and could ultimately win the auction. |
Object: BidResponse.Seatbid.Bid
id |
Required |
Unique Id for the bid object chosen by the bidder for tracking and debugging. |
---|---|---|
impid |
Required |
ID of the imp object to which the bid applies |
price |
Required |
Maximum precision of 8 digits to the right of the decimal point (e.g., 12.12345678). The maximum "price" is $1,000 CPM. Bids with higher pricing will be considered $1,000 CPM |
adid |
Optional |
ID of the ad for buyer |
adm |
Required |
Admarkup. Note: if an auction winner fails to return ad markup via the “adm” or win notice response, then the win will be forfeited and the Marketplace will select a new winner. |
cid |
Optional |
Campaign ID |
crid |
Required |
Creative ID |
adomain |
Required |
Advertiser Top Level Domain |
iurl |
Optional |
URL to an image that represents the content of the campaign. Used for ad quality and safety checking |
cat |
Optional |
|
attr |
Optional |
|
dealid |
Optional |
|
ext.burl |
Optional |
Billing Notification URL, fired upon confirmation that a creative has been delivered to a device ((SSP considers delivery as a billable event). All existing win notice url macros are available. DSP must notify VMX on intentions to use burl. |
w | Required for Multi-size | If the bid request is a multi-size eligible bid request and contains the Format object, a bidder is required to pass the width and height of a creative on their bid response, otherwise the bid will be rejected. |
h | Required for Multi-size | If the bid request is a multi-size eligible bid request and contains the Format object, a bidder is required to pass the width and height of a creative on their bid response, otherwise the bid will be rejected. |