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. A whitelist 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 whitelist 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.

Attribute

Usage

Sent?

Notes

request

Supported
(New to VMX)

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

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.
Typical value=192.192.192.0

ipv6

Supported

Sometimes

Last 4 hextets of IP address may be suppressed.
Typical value=2c0f:f8f0:c600:1d19:0:0:0:0

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

 

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)

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.

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. A whitelist 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 whitelist, 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: 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.