OpenRTB 2.5 API

This document specifies the Verizon Media Video SSP OpenRTB 2.5 implementation for Supply
Partners interested in buying from our marketplaces.

 

 

Data Center Locations

At the time of writing, VSSP has 4 data centers:

  • North California
  • North Virginia
  • Singapore
  • Frankfurt

Please contact the support team for the latest data center locations and setup instructions at https://support.vzbuilders.com/.

Support

For additional technical help, please contact your Customer Success Manager or open a support ticket at https://support.vzbuilders.com/.

OpenRTB Basics

The following figure illustrates the OpenRTB interactions between Video SSP and the supply partners.

Ad requests originate at publisher sites. For each inbound ad request, bid requests are sent to bidders, responses are evaluated under the prevailing auction rules and the corresponding ad response is sent to the publisher. The OpenRTB 2.5 standard focuses on real-time interactions.

mceclip0.png

  1. The video player on the web page identifies an opportunity to play a video ad. Player requests for an ad from the Supply partner.
  2. The supply partner registers this request as an opportunity to serve an ad and tries to find the video ad for this opportunity by starting an auction for this inventory.
  3. The supply partner sends an OpenRTB bid request to Video SSP
  4. Video SSP parses the bid request and requests an ad from our demand partners.
  5. Video SSP receives all the bids from all demand partners and runs an auction (First or Second price) on the bid price and creative quality of the bid.
  6. OpenRTB response is created for the winning bid with bid price and the adtag or VAST response of the winning creative. This response is sent to the supply partner
  7. Supply partner runs its auction and decides the winning bid and the final winning price (If the supply partner runs a price auction) .Winning bid Vast response is sent to the player and win notification is sent to Video SSP, if 1V wins the auction.
  8. Player sends the Impression pixel to Video SSP.

Data Format

Bid Request and Bid Responses payload will follow the JSON format. The HTTP message should have the respective header: Content-Type: application/json

OpenRTB Version

The OpenRTB Version is passed in the header of a Bid Request with a custom HTTP header parameter: 

x-openrtb-version: 2.5

Bid Request

Bid Request Object

A Bid Request contains the information required by the buyer to make a bid

Attribute

Support

Type

Description

id

Supported

string

Unique ID of this bid request

imp

Supported

object array

Our platform will send only one impression per bid request

site

For site ad opportunities

object

Either a site or app object is required

app

For app ad opportunities

object

Either a site or app object is required

device

Supported

object

Device the ad impression will be delivered to

user

Supported

object

User the ad impression will be delivered to

tmax

Offline

integer

Tmax values are communicated & configured through offline channels

cur

Supported

string array

Bid currency

bcat

Supported

string array

Blocked advertiser categories using the IAB content categories. See Table 5.1 of the OpenRTB 2.5 standard for details

badv

Supported

string array

Blocklist of advertisers by their domains. (e.g., “company1.com”)

regs

Supported

object

Specifies any industry, legal, or governmental regulations in force for this request. See below for details

ext

Supported

object

Placeholder for exchange-specific extensions to OpenRTB

 

Source Extension (source.ext) Object

The Source object describes the nature and behavior of the entity that is the source of the bid request upstream from the exchange. 

Attribute

Supported

Type

Description

schain

Optional

object

Indicates whether the Supply Chain is complete and contains the seller/s  info

 

Regs Object

The Regs object contains the COPPA flag, which signals whether or not the request falls under the United States Federal Trade Commission’s regulations for the United States Children’s Online Privacy Protection Act (“COPPA”).

Attribute

Included

Type

Description

coppa

always

integer

Flag indicating if this request is subject to the COPPA regulations established by the USA FTC, where 0 = no, 1 = yes

ext

Optional

object

Placeholder for exchange-specific extensions to OpenRTB

 

Impression Object

The imp object describes the impression being auctioned:

Attribute

Support

Type

Description

id

Supported

string

Impression id of the bid request

video

Supported

object

This object describes the video opportunity

pmp

Supported

object

Contains any private marketplace deals in effect for the impression

secure

Supported

integer

Video SSP will respond with “Https” responses only when this is set to 1

bidfloor

Supported

 float

Minimum bid for the impression (CPM) 

 bidfloorcur

Supported 

string (default usd) 

 From Table 10 – Supported Currencies (below)

displaymanager

 Supported

string 

Name of ad mediation partner, SDK technology, or player responsible for rendering ad (typically video or mobile)  

 displaymanagerver

Supported 

 string

Version of ad mediation partner 

 banner

Supported 

 object

 Parsed only if the option is enabled for the exchange 

 

Extension (imp.ext) Object

Exchange-specific extensions to OpenRTB

Attribute

Supported

Type

Description

rewarded

Optional

object

Is the inventory a Rewarded Video 0 = No 1 = Yes

inventoryid

Optional

integer

ID of the RTB Inventory source setup in Video SSP platform for this ad unit

pblob

Optional

 object

For internal use 

hb

Optional 

 integer

 Did the request originate in an HB adapter

billing_id  Optional string   For Google Open Bidding

 

Video Object

The Video Object describes the video opportunity:

Attribute

Support

Type

Description

mimes

Supported

string array

Content MIME types supported (e.g., “video/x-ms-wmv”, “video/mp4”).

minduration

Supported

integer

Minimum video ad duration in seconds

maxduration

Supported

integer

Maximum video ad duration in seconds

protocols

Supported

integer array

Video bid response protocols. See Table 1

w

Supported

integer

Width of the video player in pixels

h

Supported

integer

Height of the video player in pixels

linearity

Supported

integer

Indicates if the impression must be linear, nonlinear, etc. If none specified,

assume all are allowed. See Table 2

playbackmethod

When available

integer array

List of allowed playback methods. If blank, VSSP

assumes that all are allowed. See Table 3

api

Supported

integer array

List of supported API frameworks for this impression. Our platform Video supports VPAID 1.0, 2.0 and 3.0 See Table 4

placement

Supported

integer

Placement type for the impression. See Table 5

maxbitrate

Supported

integer 

 Maximum bitrate in Kbps

pos

Supported 

 integer

Ad position on screen. See Table 6 

companionad

Supported 

 object array

 Array of Banner objects  if companion ads are available. See section 3.2.6 standard for details

ext

 Supported

object 

Placeholder for exchange-specific extensions to OpenRTB

 

Table 1 - Supported Video Protocols

Value

Description

Supported

1

VAST 1.0

No

2

VAST 2.0

Yes

3

VAST 3.0

Yes

4

VAST 1.0 Wrapper

No

5

VAST 2.0 Wrapper

Yes

6

VAST 3.0 Wrapper

Yes

7

VAST 4.0

No 

8

VAST 4.0 Wrapper

No 

9

DAAST 1.0

No 

10

DAAST 1.0 Wrapper

No 

 

Table 2 - Video Linearity

Value

Description

Supported

1

Linear/Instream

Yes

2

Non-Linear/Overlay

No

 

Table 3 - Video Playback Methods

Value

Description

Supported

1

Auto-play sound on

Yes

2

Auto-play sound off

Yes

3

Click-to-play

Yes

4

Mouse-over

Yes

5

Initiates on Entering Viewport with Sound On

Yes 

 

Table 4 - Video API

Value

Description

Supported

1

VPAID 1.0

Yes

2

VPAID 2.0

Yes

3

VPAID 3.0

No 

4

MRAID-1

No

5

ORMMA

No

6

MRAID-2

No

 

Table 5 - Placement

Value

Description

1

In-Stream

2

In-Banner

3

In-Article

4

In-Feed

5

Interstitial/Slider/Floating

 

Table 6 - Position

Value

Description

0

Unknown

1

Above fold

2

DEPRECATED

3

Below fold

4

Header

5

Footer

6

Sidebar

7

Full Screen


Site Object

Required if the ad-supported content is part of a website.

Attribute

Support

Type

Description

domain

Supported
Required

string

Parent Url of the webpage hosting ad-supporting content

cat

Supported

string array

Array of IAB content categories for the overall site. See Table 5.1 of the OpenRTB 2.5 standard for details

page

Supported

string

Complete URL of the webpage hosting ad-supported content

ref

Supported

string

Referrer URL that caused navigation to the current page

publisher

Ignored

object

Details about the Publisher of the site

content

Ignored

object

Details about the Content within the site

 

App Object

Should be included if the ad-supported content is a non-browser application (typically in mobile).

Attribute

Support

Type

Description

name

Supported
Required

string

Application name

cat

Supported

string array

Array of IAB content categories for the app. See Table 5.1 of the OpenRTB 2.5 standard for details

bundle

Supported

string

Application bundle or package name (eg, com.foo.mygame); intended to be unique ID across exchanges

storeurl

Supported

string

App store URL for the installed app

publisher

Ignored

object

Details about the Publisher of the app

content

Ignored

object

Details about the Content within the app

domain

Supported

string

Domain of the app

 

Device Object

The Device Object provides information pertaining to the device, which can be a mobile handset, a desktop computer, a set-top box or another digital device.

Attribute

Support

Type

Description

ua

Supported

string

Browser user agent string

lmt

Supported

integer

“Limit Ad Tracking” signal commercially endorsed (e.g., iOS, Android), where 0 = tracking is unrestricted, 1 = tracking must be limited per commercial guidelines. Note: We require the Publishers to respect the guidelines and pass this identifier in the Ad Request. If not passed, we pass the value as “0”

ip

Supported

string

IPv4 address closest to device

dpidsha1

Supported

string

SHA1 hashed platform-specific ID (e.g., Android ID or UDID for iOS)

dpidmd5

Supported

string

MD5 hashed platform-specific ID (e.g., Android ID or UDID for iOS). Should be interpreted as case insensitive

ipv6

Supported

string

IP address in IPv6

language

Supported

string

Device language in Alpha-2/ISO 639-1 codes (see Table 7)

os

Supported

string

Device OS

devicetype

Ignored

integer

Device type being used (see Table 8)

ifa

Supported

string

Native identifier for advertisers; an opaque ID assigned by Type Description the device or browser for use as an advertising identifier. (e.g. Apple's IFA, Android's Advertising ID, etc)

geo

Supported

object

Geography as derived from the device’s location services (e.g., cell tower triangulation, GPS) or IP address

make

Supported

string 

Device make (e.g., “Apple”)

model

Supported

 string

Device model (e.g., “iPhone”)

dnt 

Supported 

 integer

Standard “Do Not Track” flag as set in the header by the browser, where 0 = tracking is unrestricted, 1 = do not track 

dpidsha1

Supported

string

Platform device ID (e.g., Android ID); hashed via SHA1

dpidmd5

Supported

string

Platform device ID (e.g., Android ID); hashed via MD5

osv

Supported

string

Device operating system version (e.g., “3.1.2”)

js

Supported

integer

Support for JavaScript, where 0 = no, 1 = yes

connectiontype

Supported

integer

Network connection type  (see Table 8)

carrier

Supported

string

Carrier or ISP (e.g., “VERIZON”) using exchange curated string names which should be published to bidders a priori

 

Table 7 - Device Language (Alpha-2/ISO 639-1 codes)

Value

Language

ar

Arabic

da

Danish

de

German

el

Greek

en

English

es

Spanish

fr

French

he

Hebrew

hi

Hindi

hu

Hungarian

id

Indonesian

it

Italian

ja

Japanese

ko

Korean

ms

Malaysian

nl

Dutch, Flemish

no

Norwegian

pa

Punjabi

pl

Polish

pt

Portuguese

ru

Russian

sv

Swedish

th

Thai

tl

Tagalog

tr

Turkish

vi

Vietnamese

zh

Cantonese, Mandarin

Table 8 - Network Connection Type

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

 

Geo Object

The Geo Object provides geographic location information pertaining to the device and is part of the Device Object.

Attribute

Support

Type

Description

lat

Not Parsed

float

Latitude from -90 to 90. South is negative

lon

Not Parsed

float

Longitude from -180 to 180. West is negative

country

Supported

string

Country using ISO-3166-1 Alpha-3

region

Supported

string

Region using ISO 3166-2

type

Not Parsed

string

Source of geodata. See Table 9

 

Table 9 - Location Type

Value

Description

1

GPS/Location Services

2

IP Address

3

User-provided (e.g., registration data)

 

User Object

The User Object contains information known or derived about the human user of the device.

Note that the user buyerid should contain uid of the user-provided by Video SSP.

Attribute

Support

Type

Description

id

Supported

string

Unique user ID on our platform

buyerid

Supported

string

Buyer’s user ID for this user as mapped by our platform for the buyer. See "User Syncing" below

yob

Supported

string

4 digit integer year of birth of the user

gender

Supported

string

Gender of the user

keywords

Not Parsed

string array

Comma-separated list of keywords, interests, or intent

data

Supported

object array 

Additional user data. Each Data object represents a different data source. See table 3.2.21 of the OpenRTB 2.5 standard for details

ext

Supported 

 object

Contains consent & bcookie info 

geo

Supported 

 object

Location of the user’s home base defined by a Geo object. See table 3.2.19 of the OpenRTB 2.5 standard for details


User Syncing

There are two methods of user syncing, and the buyer may choose to do either or both.

Push Method

The Supply partner sends an HTTPS request from the user’s browser to a User Sync URL of the following form: http://pixel.advertising.com/ups/{seller_pixel_id}/sync?uid={Seller_user_id}

Supply partner should substitute for SELLER_PIXEL_ID with their pixel ID as identified by the account manager and should substitute for SELLER_USER_ID with their unique ID for the user that the request originates from. The maximum length for the SELLER_USER_ID is 36 characters: large enough to fit a standard UUID, although the field can be used to store any type of information.

Pull Method

Video SSP will send an HTTP request from the user’s browser to a URL specified by the buyer. The buyer should then return a 302 redirect, where the redirect URL is just the User Sync URL provided above, with the SELLER_PIXEL_ID and SELLER_USER_ID replaced as specified above. In either case, the buyer must specify the Time To Live (TTL) of the user ID, after which time our platform will no longer use the ID when sending bid requests.

Sample Bid Request

Desktop Ad Opportunity

{
"imp": [{
"video": {
"protocols": [2, 3, 5, 6],
"api": [1, 2],
"w": 640,
"h": 480,
"maxbitrate": 10000,
"playbackmethod": [2],
"startdelay": 0,
"pos": 0,
"mimes": ["application/javascript", "video/mp4"],
"linearity": 1,
"minduration": 5,
"maxduration": 30,
"placement": 4
},
"id": "1",
"tagid": "123456",
"bidfloor": 4.0,
"secure": 1,
"ext": {
"rewarded": 1
}
}],
"regs": {
"ext": {
"gdpr": 1
}
},
"site": {
"publisher": {
"id": "10001"
},
"cat": ["IAB12", "IAB18"],
"page": "https://www.test.com",
"domain": "test.com",
"ref": "https://www.test.com"
},
"device": {
"dnt": 0,
"geo": {
"city": "athens",
"region": "GA",
"type": 2,
"country": "usa"
},
"ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.0.5 Safari/605.1.15",
"osv": "10",
"connectiontype": 2,
"devicetype": 2,
"os": "macOS",
"js": 1,
"make": "generic web browser",
"model": "",
"ip": "138.68.240.218"
},
"id": "987654321",
"at": 1,
"badv": ["abc.org", "xyz.us"],
"user": {
"id": "a35c1d89-42e4-4327-a812-795e3f563098-tuct4abc30f"
}
}


Bid Response
 

Bid Response Object

The top-level Bid Response Object is defined below. The OpenRTB 2.5 standard supports

multiple seatbids (buyer seats) per Bid Response and multiple bids per seatbid.

Attribute

Included

Type

Description

id

Always

string

ID of the Bid Request that originated this Bid Response

seatbid

Always

object array

Array of seatbid objects

cur

Always

string

Bid currency using ISO-4217 alphabetic codes. Our platform expects currencies outlined in Table 10 below

 

Table 10 – Supported Currencies

AED

BSD

DKK

HUF

LKR

NAD

SCR

UAH

XFU

CYP

AFN

BTN

DOP

IDR

LRD

NGN

SDG

UGX

XOF

DEM

ALL

BWP

DZD

ILS

LSL

NIO

SEK

USD

XPD

ECS

AMD

BYR

EGP

INR

LTL

NOK

SGD

USN

XPF

EEK

ANG

BZD

ERN

IQD

LVL

NPR

SHP

USS

XPT

ESP

AOA

CAD

ETB

IRR

LYD

NZD

SLL

UYI

XTS

FIM

ARS

CDF

EUR

ISK

MAD

OMR

SOS

UYU

XXX

FRF

AUD

CHE

FJD

JMD

MDL

PAB

SRD

UZS

YER

GHC

AWG

CHF

FKP

JOD

MGA

PEN

SSP

VEF

ZAR

GRD

AZN

CHW

GBP

JPY

MKD

PGK

STD

VND

ZMK

IEP

BAM

CLF

GEL

KES

MMK

PHP

SYP

VUV

ZWL

ITL

BBD

CLP

GHS

KGS

MNT

PKR

SZL

WST

ADF

LUF

BDT

CNY

GIP

KHR

MOP

PLN

THB

XAF

ADP

MGF

BGN

COP

GMD

KMF

MRO

PYG

TJS

XAG

AFA

MTL

BHD

COU

GNF

KPW

MUR

QAR

TMT

XAU

AON

MZM

BIF

CRC

GTQ

KRW

MVR

RON

TND

XBA

ATS

NLG

BMD

CUC

GYD

KWD

MWK

RSD

TOP

XBB

AZM

PTE

BND

CUP

HKD

KYD

MXN

RUB

TRY

XBC

BEF

ROL

BOB

CVE

HNL

KZT

MXV

RWF

TTD

XBD

BGL

SDD

BOV

CZK

HRK

LAK

MYR

SAR

TW

XCD

CFP

SDP

BRL

DJF

HTG

LBP

MZN

SBD

TZS

XDR

CSK

SIT

 

Seatbid Object

Attribute

Included

Type

Description

bid

Always

object array

Array of bid objects

seat

Optional

string

ID of the bidder seat on whose behalf this bid is made. Video SSP recommends that seat is always passed

 

Bid Object

The Bid Object contains the bid details:

Attribute

Included

Type

Description

id

Always

string

ID for this Bid Object chosen by VSSP for tracking and debugging purposes. Useful when multiple bids are submitted for a single impression for a given seat

impid

Required

string

ID of the impression object to which this bid applies

price

Required

float

Bid price in CPM

adid

Always

string

ID that references the ad to be served if the bid wins

nurl

Optional

string

Win notice URL called if the bid wins. Please note that all standard substitution macros are supported in addition to a platform-specific failover macro (see Table 11 below). These same substitution macros can also be placed in the ad markup. ONE Video will perform the same data substitutions as in the aforementioned notice URLs

adomain

Always

string array

Advertiser domain of the creative

adm

Always

string

VAST XML ad markup for the Video Object. Please note that our platform requires this to follow standard JSON encoding (see json.org). Our platform supports Unicode characters and all the standard JSON escape character sequences

crid

Always

string

Video SSP will always pass the Creative ID in the Bid response

 

The following substitution macros should be supported for Win Notice URL (nurl) and adm.

These include the OpenRTB 2.5 Substitution Macros (see section 4.4 of the OpenRTB 2.5 standard)

 

Table 11 - Supported nurl Substitution Macros

Macro

Description

${AUCTION_PRICE}

Settlement price using the same currency and units as the bid

${AUCTION_CURRENCY}

The currency used in the bid. This will always be USD

${AUCTION_ID}

Bid request ID; bidrequest.id

${AUCTION_BID_ID}

Bid ID; bidresponse.bidid

${AUCTION_IMP_ID}

Winning impression ID; imp.id

${AUCTION_SEAT_ID}

ID of the winning bidder seat

${AUCTION_AD_ID}

ID of the bidder’s ad; bid.adid

${AUCTION_PRICE:B64}

Encrypted settlement price encoded using Base64 algorithm. Please contact Video SSP for more details

 

Sample Bid Response:

{
  "id": "cd0aa0c2-41ac-4d71-bbc7-0a0d17c50b7b",
  "seatbid": [{
      "bid": [{
          "id": "1",
          "impid": "1",
          "price": 9.43,
          "crid": "12345",
          "adid": "1971675345",
          "nurl": "http://winnotify.dsp.com/winnotice?bidid=${
          AUCTION_BID_ID
        } & auctionid = $ {
          AUCTION_ID
        } & price = $ {
          AUCTIO
          N_PRICE
        } & failover = $ {
          FAILOVER_WIN
        }
        ",
        "adm": "<?xml version=\"1.0\" encoding=\"UTF-8\" ? >
        < VAST version = \"2.0\"
        xmlns: xsi = \"http://www.w3.org/2001/XMLSchemainstance\"xsi:noNamespaceSchemaLocation=\"VAST.xsd\"><
        Ad > < InLine > < AdSystem version = \"2.0\">Ad
        Server < /AdSystem><AdTitle>In-Stream
        Video < /AdTitle><Description>A test creative with a
        description. < /Description><Impression><![CDATA[http://
        adserver.com / imp
      ]] > < /Impression><Creatives><Creative
    sequence = \"1\"
    AdID = \"\"><Linear><Duration>00:00:58</Duration><VideoC
    licks > < ClickThrough > < ![CDATA[http: //adserver.com/click
    ]] > < /ClickThrough></VideoClicks > < MediaFiles > < MediaFile
    id = \"1\" delivery=\"progressive\" type=\"video/x-flv\"
    bitrate = \"457\" width=\"300\"
    height = \"225\"><![CDATA[http://adserver.com/video.flv]
  ] > < /MediaFile></MediaFiles > < /Linear></Creative > < /Creat
  ives > < /InLine></Ad > < /VAST>",
  "dealid": "532"
}],
"seat": "AgencyAA"
}],
"bidid": "abcd1234",
"cur": "USD"
}

 

Sample Bid Response with JSON Unicode characters: 

{
  "id": "cd0aa0c2-41ac-4d71-bbc7-0a0d17c50b7b",
  "seatbid": [{
      "bid": [{
          "id": "1",
          "impid": "1",
          "price": 9.43,
          "crid": "12345",
          "adid": "1971675345",
          "nurl": "http://winnotify.dsp.com/winnotice?bidid=${
          AUCTION_BID_ID
        } & auctionid = $ {
          AUCTION_ID
        } & price = $ {
          AUCTIO
          N_PRICE
        } & failover = $ {
          FAILOVER_WIN
        }
        ",
        "adm": "\u003c?xml version=\"1.0\" encoding=\"UTF-8\" ?\
        u003e\ u003cVAST version = \"2.0\"
        xmlns: xsi = \"http://www.w3.org/2001/XMLSchemainstance\"
        xsi: noNamespaceSchemaLocation = \"VAST.xsd\"\u003e\u003c
        Ad\ u003e\ u003cInLine\ u003e\ u003cAdSystem
        version = \"2.0\"\u003eAd
        Server\ u003c / AdSystem\ u003e\ u003cAdTitle\ u003eInStream
        Video\ u003c / AdTitle\ u003e\ u003cDescription\ u003eA test
        creative with a
        description.\u003c / Description\ u003e\ u003cImpression\ u
        003 e\ u003c![CDATA[http: //adserver.com/imp]]\u003e\u003
          23 c / Impression\ u003e\ u003cCreatives\ u003e\ u003cCreative sequence = \"1\"
          AdID = \"\"\u003e\u003cLinear\u003e\u003cDuration\u003e0
          0: 00: 58\ u003c / Duration\ u003e\ u003cVideoClicks\ u003e\ u0 03 cClickThrough\ u003e\ u003c![CDATA[http: //adserver.com
            /click]]\u003e\u003c/ClickThrough\
            u003e\ u003c / VideoCli cks\ u003e\ u003cMediaFiles\ u003e\ u003cMediaFile id = \"1\" delivery=\"progressive\" type=\"video/x-flv\"
            bitrate = \"457\" width=\"300\"
            height = \"225\"\u003e\u003c![CDATA[http://adserver.com/
            video.flv]]\ u003e\ u003c / MediaFile\ u003e\ u003c / MediaFil es\ u003e\ u003c / Linear\ u003e\ u003c / Creative\ u003e\ u003c /
          Creatives\ u003e\ u003c / InLine\ u003e\ u003c / Ad\ u003e\ u00 3 c / VAST\ u003e ",
          "dealid": "532"
        }],
        "seat": "AgencyAA"
      }],
    "bidid": "abcd1234",
    "cur": "USD"
  }

 

 

 

Have more questions? Submit a request