This is Smaato's OpenRTB Bid Request Documentation for OpenRTB 2.2 integrations.

Bid Request Details

Bid Request Object

Field
Scope
Type
Default
Description

id 

required

string

-

Unique ID of the bid request, provided by the exchange.

imp

required

array of objects

-

Array of impression objects. Multiple impression auctions may be specified in a single bid request. At least one impression is required for a valid bid request.

site

recommended for websites

object-

See Site Object.

app

recommended for native appsobject-

See App Object.

device

recommended

object-

See Device Object.

user

recommendedobject-

See User Object.

at    

optionalinteger2

Auction Type. "2" stands for second price auction (“1” = first price auction). Additional auction types can be defined as per the exchange’s business rules. Exchange specific rules should be numbered over 500.

tmax

optionalinteger-

Maximum amount of time in milliseconds to submit a bid (e.g., 120 means the bidder has 120 ms to submit a bid before the auction is complete). If this value never changes across an exchange, then the exchange may supply this information offline.

wseat     

optionalarray of strings-

Array of buyer seats allowed to bid on this auction. Seats are an optional exchange feature. For example, [“4”,”34”,”82”,”A45”] indicates that only advertisers using these exchange seats are allowed to bid on the impressions in this auction.


allimps

optionalinteger0

Flag to indicate whether exchange can verify that all impressions offered represent all of the impressions available in context (e.g., all impressions available on the web page; all impressions available for a video [pre, mid and postroll spots], etc.) to support roadblocking.

A true value should only be passed if the exchange is aware of all impressions in context for the publisher. “0” means the exchange cannot verify, and “1”  means that all impressions represent all impressions available.

cur

optionalarray of strings-

Array of allowed currencies for bids on this bid request using ISO-4217 alphabetic codes. If only one currency is used by the exchange, this parameter is not  required.

bcat

optionalarray of strings-

Blocked Advertiser Categories. Note that there is no existing categorization/taxonomy of advertiser industries. However, as a substitute exchanges may decide to use IAB categories as an approximation (See Content Categories).

badv

optionalarray of strings-

Array of strings of blocked top-level domains of advertisers. For example, {“company1.com”, “company2.com”}.

regs

optionalobject-

This object is a container for any legal, governmental or industry regulations in force for the request.

ext

optionalobject-

This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification. See also Extensions.

Back to table of contents

Impression Object    

Field
Scope
Type
Default
Description

id

required

string

-

A unique identifier for this impression within the context of the bid request (typically, value starts with 1, and increments up to n for n impressions).

banner

required for banner impressions

object

-

A reference to a banner object. Either a banner or video object (or both if the impression could be either) must be included in an impression object. See Banner Object

video

required for video impressions

object

-

A reference to a video object. Either a banner or video object (or both if the impression could be either) must be included in an impression object. See Video Object.  

displaymanager

recommended for video and native apps

string

-

Name of ad mediation partner, SDK technology, or native player responsible for rendering ad (typically video or mobile). Used by some ad servers to customize ad code by partner.

displaymanagerver

recommended for video and native apps

string

-

Version of ad mediation partner, SDK technology, or native player responsible for rendering ad (typically video or mobile). Used by some ad servers to customize ad code by partner.

instl

optionalinteger0

1 if the ad is interstitial or full screen; otherwise 0.

tagid

optional

string

-

Identifier for specific ad placement or ad tag that was used to initiate the auction. This can be useful for debugging of any issues, or for optimization by the buyer.

bidfloor

optionalfloat0

Bid floor for this impression (in CPM of bidfloorcur).

bidfloorcur

optional

string

USD

If bid floor is specified and multiple currencies supported per bid request, then currency should be specified here using ISO-­4217 alphabetic codes. This may be different from bid currency returned by bidder, if this is allowed on an exchange.      

secureoptionalint-

Flag to indicate whether the impression requires secure HTTPS URL creative assets and markup. A value of “1” means that the impression requires secure assets, "0" denotes non-secure assets. If this field is omitted, the bidder should interpret the secure state is unknown and assume HTTP is supported.

iframebuster

optional

array of string

None

Array of names for supported iframe busters. Exchange specific.

pmp

optional

object

-

A reference to the PMP object containing any Deals eligible for the impression object. See the PMP object definition.

ext

optional

object

-

This object is a place holder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Back to table of contents

ImpressionExtension Object

Field
Scope
Type
Description
strictbannersizeoptionalintegerCustom field with following values:
  • 1 if the banner size to be treated strictly
  • 0 (default value) if the DSP can return ads smaller than banner size
nativeoptionalobjectSmaato Native object

Native Object 

Field
Scope
Type
Description
ver---
iconsize---
imagesize---
pubnsupport---
ctatextlen---
titlelen---
textlen---

Banner Object

Field
Scope
Type
Default
Description

w

recommended

integer

-

Width of the impression in pixels. Since some ad types are not restricted by size, this field is not required, but it’s highly recommended that this information be included when possible.

hrecommendedinteger-

Height of the impression in pixels. Since some ad types are not restricted by size, this field is not required, but it’s highly recommended that this information be included when possible.

wmax

optionalinteger-

Maximum width of the impression in pixels. If included, it indicates that a range of sizes is allowed with this maximum width and "w" is taken as recommended. If not included, then "w" should be considered an exact requirement.

hmax

optionalinteger-

Maximum height of the impression in pixels. If included, it indicates that a range of sizes is allowed with this maximum height and "h" is taken as recommended. If not included, then "h" should be considered an exact requirement.

wmin

optionalinteger-

Minimum width of the impression in pixels. If included, it indicates that a range of sizes is allowed with this minimum width and "w" is taken as recommended. If not included, then "w" should be considered an exact requirement.

hmin      

optionalinteger-

Minimum height of the impression in pixels. If included, it indicates that a range of sizes is allowed with this minimum height and "h" is taken as recommended. If not included, then "h" should be considered an exact requirement.

id

recommended when subordinate to a video object

string-

Unique identifier for this banner object. Useful for tracking multiple banner objects (e.g., in a companion banner array). Usually starts with 1, increasing with each object. Combination of impression id banner object should be unique.

posoptionalinteger-

Ad Position

btypeoptionalarray of integersAll types are allowed

Blocked creative types. See Banner Ad Types. If blank, assume all types are allowed.

battroptionalarray of integersAll types are allowed

Blocked creative attributes.  See Creative Attributes. If blank assume all types are allowed.

mimesoptionalarray of integersAll types are allowed

Whitelist of content MIME types supported. Popular MIME types include, but are not limited to “image/jpg”, “image/gif” and “application/x-­‐shockwave-­‐flash”.

topframeoptionalinteger0

Specify if the banner is delivered in the top frame or in an iframe. “0” means it's not in the top frame, and “1” means that it is.

expdiroptionalarray of integersNot expandable

Specify properties for an expandable ad. See Expandable Direction for possible values.

apioptionalarray of integersNone

List of supported API frameworks for this banner. (See API Frameworks). If an API is not explicitly listed, it is assumed to not be supported.

extoptionalobject-

This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Back to table of contents

Video Object

Field
Scope
Type
Default
Description
mimesrequired

array of strings

-

Content MIME types supported. Popular MIME types include, but are not limited to “video/x-­‐ms-­‐wmv” for Windows Media, and “video/x-­‐flv” for Flash video.

mindurationrequiredinteger-

Minimum video ad duration in seconds.

maxdurationrequiredinteger-

Maximum video ad duration in seconds.

protocol

optionalinteger-

Video bid response protocols. See Video Bid Response Protocols for a list of possible values. NOTE: Use “protocols” when multiple protocols are supported. Its use is also highly recommended even though this attribute is likely to be deprecated in a future version. At least one supported protocol must be specified in either the “protocol” or “protocols” attribute.

protocols

recommendedarray of integers-

Video bid response protocols. See Video Bid Response Protocols for a list of possible values. At least one supported protocol must be specified in either the “protocol” or “protocols” attribute.

w

recommendedinteger-

Width of the player in pixels. This field is not required, but it’s highly recommended that this information be included.

hrecommendedinteger-

Height of the player in pixels. This field is not required, but it’s highly recommended that this information be included.

startdelayrecommendedinteger-

Indicates the start delay in seconds for preroll, midroll, or postroll ad placement. See Video Start Delay  for generic placement values.

linearityoptionalinteger-

Indicates whether the ad impression must be linear, non-­‐linear or can be of any type (field not set). See Video Linearity for a list of the possible values and recommended bidder interpretation.

sequenceoptionalinteger1

If multiple ad impressions are offered in the same bid request, the sequence number will allow for the coordinated delivery of multiple creatives.

battr

optionalarray of integers

Assume all types are allowed

Blocked creative attributes. See Creative AttributesIf blank, assume all types are allowed.

maxextendedoptionalintegerExtension not allowed

Maximum extended video ad duration, if extension is allowed. If blank or 0, extension is not allowed.  If -1, extension is allowed, and there is no time limit imposed. If greater than 0, then the value represents the number of seconds of extended play supported beyond the maxduration value.

minbitrateoptionalintegerAny bitrate accepted

Minimum bit rate in kbps. Exchanges may set this dynamically, or universally across their set of publishers.

maxbitrateoptionalintegerAny bitrate accepted

Maximum bit rate in kbps. Exchanges may set this dynamically, or universally across their set of publishers.

boxingallowedoptionalinteger1

If exchange publisher has rules preventing letter boxing of 4x3 content to play in a 16x9 window, then this should be set to false. Default setting is true, which assumes that boxing of content to fit into a window is allowed. “1” indicates boxing is allowed.  “0” indicates it is not allowed.    

playbackmethodoptionalarray of integersAll

List of allowed playback methods. If blank, assume that all are allowed. See Video Playback Methods for a list of possible values.

deliveroptionalarray of integersAll

List of supported delivery methods (streaming, progressive). If blank, assume all are supported. See Content Delivery Methods for a list of possible values.

posoptionalintegerUnknown

Ad Position.

companionadoptionalarray of objectsNot available

If companion ads are available, they can be listed as an array of banner objects. See Banner Object.

api

optionalarray of integersAssume None

List of supported API frameworks for this impression. See API Frameworks. If an API is not explicitly listed, it is assumed not to be supported.

companiontype

optionalarray of integers-

Recommended if companion objects are included. See VAST Companion Types for a list of possible values.

extoptionalobject-

This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Back to table of contents

Site Object

Field
Scope
Type
Default
Description

id      

recommendedstring-

Site ID on the exchange. 

nameoptionalstring-

Site name (may be masked at publisher’s request).

domainoptionalstring-

Domain of the site, used for advertiser side blocking. For example, “foo.com”.

catoptionalarray of strings-

Array of IAB content categories for the overall site. See Content Categories.

sectioncatoptionalarray of strings-

Array of IAB content categories for the current subsection of the site. See Content Categories.

pagecatoptionalarray of strings-

Array of IAB content categories for the current page. See Content Categories.

pagerecommendedstring-

URL of the page where the impression will be shown.

privacypolicy    

optionalinteger-

Specifies whether the site has a privacy policy. “1” means there is a policy. “0” means there is not.

refoptionalstring-

Referrer URL that caused navigation to the current page.

searchoptionalstring-

Search string that caused navigation to the current page.

publisheroptionalobject-

See Publisher Object.

contentoptionalobject-

See Content Object.

keywordsoptionalstring-

List of keywords describing this site in a comma separated string. ALTERNATE Representation: Array of strings.

extoptionalobject-

This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined.

Back to table of contents

App Object

FieldScopeTypeDefaultDescription
idrecommendedstring-Application ID on the exchange.
nameoptional    string-Application name (may be masked at publisher’s request).
domainoptionalstring-Domain of the application (e.g., “mygame.foo.com”).
catoptionalarray of strings-Array of IAB content categories for the overall application. See Content Categories.
sectioncatoptionalarray of strings-

Array of IAB content categories for the current subsection of the app. See Content Categories.     

pagecatoptionalarray of strings-Array of IAB content categories for the current page/view of the app. See Content Categories
veroptionalstring-Application version. 
bundlerecommendedstring-Application bundle or package name (e.g., com.foo.mygame). This is intended to be a unique ID across multiple exchanges.
privacypolicyoptionalinteger-Specifies whether the app has a privacy  policy. “1” means there is a policy and “0” means there is not.
paidoptionalinteger-“1” if the application is a paid version; else “0” (i.e., free).
publisheroptionalobject-See Publisher Object.
contentoptionalobject-See Content Object.
keywordsoptionalstring-List of keywords describing this app in a comma separated string. ALTERNATE Representation: Array of strings.
storeurloptionalstring-For QAG 1.5 compliance, an app store URL for an installed app should be passed in the bid request.
extoptionalobject-

This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in the specification.

Back to table of contents

Content Object     

FieldScopeTypeDefaultDescription
idoptionalstring-ID uniquely identifying the content.
episodeoptionalinteger-Content episode number (typically applies to video content).
titleoptionalstring-Content title.
Video examples: “Search Committee” (television) or “A New Hope” (movie) or “Endgame” (made for web)
Non-­‐video example: “Why an Antarctic Glacier Is Melting So Quickly” (Time magazine article)
seriesoptionalstring-Content series.
Video examples: “The Office” (television) or “Star Wars” (movie) or “Arby ‘N’ The Chief” (made for web)       
Non-­‐video example: “Ecocentric” (Time magazine blog)
seasonoptionalstring-Content season. E.g., “Season 3” (typically applies to video content).
urloptionalstring-Original URL of the content, for buy-­‐side contextualization or review.
catoptionalarray of strings-Array of IAB content categories for the content.  See Content Categories.
videoqualityoptionalinteger-Video quality per the IAB’s classification. See Video Quality.
keywordsoptionalstring-Comma separated list of keywords describing the content. ALTERNATE Representation: Array of strings.
contentratingoptionalstring-Content rating (e.g., MPAA).
userratingoptionalstring-User rating of the content (e.g., number of stars, likes, etc.).
contextoptionalinteger-Specifies the type of content (game, video, text, etc.).  See Table 6.13  Content Context.
livestream      optionalinteger-Is content live? E.g., live video stream, live blog.“1” means content is live. “0” means it is not live.

sourcerelationship

optionalinteger-1 for “direct”; 0 for “indirect”.
produceroptionalobject-See Producer Object.
lenoptionalinteger-Length of content (appropriate for video or audio) in seconds.
qagmediaratingoptionalinteger-Media rating of the content, per QAG guidelines. See QAG Media Ratings for list of possible values.
embeddableoptionalinteger-From QAG Video Addendum. If content can be embedded (such as an embeddable video player) this value should be set to “1”.  If content cannot  be embedded, then this should be set to “0”.
languageoptionalstring-Language of the content. Use alpha­‐2/ISO 639-1 codes.
ext    optionalobject-This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Back to table of contents

Publisher Object

FieldScopeTypeDefaultDescription
idrecommendedstring-Publisher ID on the exchange.
nameoptionalstring-Publisher name (may be masked at publisher’s request).     
catoptionalarray of strings-Array of IAB content categories for the  publisher.  See Table  6.1 Content Categories.
domainoptionalstring-Publisher’s highest level domain name, for example “foopub.com”.
extoptionalobject-This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Back to table of contents

Producer Object

FieldScopeTypeDefaultDescription
id      optional     string   -Content producer or originator ID. Useful if content is syndicated, and may be posted on a site using embed tags.
name    optionalstring-Content producer or originator name (e.g., “Warner Bros”).
catoptionalarray of strings-Array of IAB content categories for the content producer. See Content Categories.
domainoptionalstring-URL of the content producer.
extoptionalobject-This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Back to table of contents

Device Object

FieldScopeTypeDefaultDescription
dntrecommendedinteger-If “0”, then do not track Is set to false, if “1”, then do no track is set to true in browser.
uarecommendedstring-Browser user agent string.     
iprecommended if geo object is not suppliedstring-IPv4 address closest to device.
georecommended if IP is not suppliedobject-Geography as derived from the device’s location services (e.g., cell tower triangulation, GPS) or IP address.  See Geo O Geo Objectbject.
didsha1optionalstring-SHA1 hashed device ID; IMEI when available, else MEID or ESN. OpenRTB’s preferred method for device ID hashing is SHA1.
didmd5optionalstring-MD5 hashed device ID; IMEI when available, else MEID or ESN. Should be interpreted as case insensitive.
dpidsha1optionalstring-SHA1 hashed platform-­‐specific ID (e.g., Android ID or UDID for iOS). OpenRTB’s preferred method for device ID hash is SHA1.
dpidmd5optionalstring-MD5 hashed platform-­‐specific ID (e.g., Android ID or UDID for iOS). Should be interpreted as case insensitive.
macsha1optionalstring-SHA1 hashed MAC address of the device (ODIN)
macmd5optionalstring-MD5 hashed MAC address of the device.
ipv6optionalstring-IP address in IPv6.
carrieroptionalstring-Carrier or ISP derived from the IP address. Should be specified using Mobile Network Code (MNC) http://en.wikipedia.org/wiki/Mobile_Network_Code
languageoptionalstring-Browser language; use alpha-­2/ISO 639-­1 codes.
makeoptionalstring-Device make (e.g., “Apple”).
modeloptionalstring-Device model (e.g., “iPhone”).
os    optionalstring-Device operating system (e.g., “iOS”).
osvoptionalstring-Device operating system version (e.g., “3.1.2”).
jsoptionalinteger-“1” if the device supports JavaScript; else “0”.
connectiontypeoptionalinteger-Return the detected data connection type for the device.
devicetypeoptionalinteger-Return the device type being used. See Table  6.16 Device Type.
flashveroptionalstring-Return the Flash version detected.
ifaoptionalstring-Native identifier for advertisers; an opaque ID assigned by the device or browser for use as an advertising identifier.
extoptionalobject-This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Back to table of contents

Geo Object   

FieldScopeTypeDefaultDescription
latoptionalfloat      -Latitude from -­‐90 to 90. South is negative. This should only be passed if known to be accurate (For example, not the centroid of a postal code).
lonoptionalfloat      -Longitude from -­‐180 to 180. West is negative. This should only be passed if known to be accurate.     
countryoptionalstring-Country using ISO-­‐3166-­1 Alpha-­3. 
regionoptionalstring-Region using ISO 3166­‐2.
regionfips104optionalstring-Region of a country using FIPS 10-­4 notation (alternative to ISO 3166-­2).
metrooptionalstring-Pass the metro code (see http://code.google.com/apis/adwords/docs/appendix/metrocodes.html). Metro codes are similar to but not exactly the same as Nielsen DMAs.
cityoptionalstring-City using United Nations Code for Trade and Transport Locations (http://www.unece.org/cefact/locode/service/location.htm).
zipoptionalstring-Zip/postal code.
typerecommendedinteger-Indicate the source of the geo data (GPS, IP address, user provided).  See Table 6.15 Location Type for a list of potential values. Type should be provided when lat/lon is provided.
extoptionalobject-This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Back to table of contents

User Object

FieldScopeTypeDefaultDescription
idrecommended (or buyeruid)string-Unique consumer ID of this user on the exchange.
buyeruid     recommended (or id)string-Buyer’s user ID for this user as mapped by exchange for the buyer.
yoboptional      integer-Year of birth as a 4-­‐digit integer.
genderoptionalstring-Gender as “M” male, “F” female, “O” Other. (Null indicates unknown).
keywordsoptionalstring-Comma separated list of keywords of consumer interests or intent. ALTERNATE Representation: Array of strings.
customdataoptionalstring-If supported by the exchange, this is custom data that the bidder had stored in the exchange’s cookie. The string may be in base85 cookie safe characters, and be in any format. This may useful for storing user features. Note: Proper JSON encoding must be used to include “escaped” quotation marks.
geooptionalobject-Home geo for the user (e.g., based off of registration data); this is different from the current location of the access device (that is defined by the geo object embedded in the Device Object); see Device Object.
dataoptionalarray of objects-See Data Object
extoptionalobject-This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification. 

Object User.ext

Field

Scope

Type

Default

Description


consentoptionalstring-Contains the data structure developed by the GDPR Consent Working Group under the auspices of IAB Europe.N/A

Back to table of contents

Data Object

FieldScopeTypeDefaultDescription
idoptionalstring-Exchange specific ID for the data provider.
nameoptionalstring-Data provider name. 
segmentoptionalarray of objects-Array of segment objects.
extoptionalobject-This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Back to table of contents

Segment Object    

Field
Scope
Type
Default
Description
idoptionalstring-

ID of a data provider’s segment applicable to the user.

nameoptionalstring-

Name of a data provider’s segment applicable to the user.

valueoptionalstring-

String representing the value of the segment. The method for transmitting this data should be negotiated offline with the data provider.  For example for gender, “male”, or “female”, for age, “30-­‐40”).

extoptionalobject-

This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Back to table of contents

Regulations Object

Field
Scope
Type
Default
Description

coppaoptionalinteger-

Flag indicating whether or not this request falls under the COPPA regulations established by the USA FTC, where 0 = no, 1 = yes.


extoptionalobject-This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Object: Regs.ext

Field

Scope

Type

Default

Description


gdproptionalinteger-Signaled whether or not the request is subject to GDPR via the extension attribute “gdpr” which is an optional integer that indicates: 0 = No, 1 = Yes.0 or 1

Back to table of contents

PMP Object

FieldScopeTypeDefaultDescription
private_auctionoptionalinteger-An integer flag indicating that this impression is a  private auction eligible only to seats named in the Direct Deals object. (e.g., 1 = bids for this impression are restricted to the deals specified and the terms thereof; 0 = all bids are accepted). 
deals    optionalarray of objects-A collection of “deal” objects encapsulating a list of direct deals eligible for this impression.
extoptionalobject-This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Back to table of contents

Direct Deals Object    

FieldScopeTypeDefaultDescription
idrequiredstring-A unique identifier for the direct deal.
bidflooroptionalfloat0Bid floor for this impression (in CPM of bidfloorcur).
bidfloorcuroptionalstringUSDIf bid floor is specified and multiple currencies supported per bid request, then currency should be specified here using ISO-­-4217 alphabetic codes. Note, this may be different from bid currency returned by bidder, if this is allowed on an exchange.
wseatoptionalarray of strings-Array of buyer seats allowed to bid on this  Direct Deal. Seats are an optional feature of an exchange. For example,  [“4”,”34”,”82”,”45”] indicates that only advertisers using these exchange seats are allowed to bid on this direct deal.
wadomainoptionalarray of strings-Array of advertiser domains allowed to bid on this Direct Deal. For example, [“advertiser1.com”,”advertiser2.com”] indicates that only the listed advertisers are allowed to bid on this direct deal.
atoptionalinteger-Auction type. If “1”, then first price auction. If “2”, then second price auction. If “3”, the passed bidfloor indicates the apriori agreed upon deal price. Additional auction types can be defined as per the exchange’s business rules.
extoptionalobject-This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Back to table of contents

BidRequestExtension Object

Field

Scope

Type

Description

udi

optional

UniqueDeviceIdContainer

Unique device id container

x_uidh

optional

String

The value of the transmitted x-uidh header (from Verizon), null if no header has been transmitted.

operaminibrowser

optional

Integer

Whether the request device's browser is Opera mini

carriername

optional

String

Custom field with the SOMA internal carriername (that is the the name we obtain from the soma db or the GeoIPCache Not the Carriername we log)

Bid Response Details

Bid Response Object  

FieldScopeTypeDefaultDescription
idrequiredstring-ID of the bid request.
seatbidoptionalarray of objects-Array of seatbid objects.
bididoptionalstring-Bid response ID to assist tracking for bidders. This value is chosen by the bidder for cross-­‐reference.
curoptionalstring-Bid currency using ISO-­‐4217 alphabetic codes; default is “USD”.
customdataoptionalstring-This is an optional feature, which allows a bidder to set data in the exchange’s cookie. The string may be in base85 cookie safe characters, and be in any format. This may be useful for storing user features. Note: Proper JSON encoding must be used to include “escaped” quotation marks.
nbroptionalinteger-Reason for not bidding. See NoBid Reason Codes
extoptionalobject-This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Back to table of contents

Seat Bid Object   

FieldScopeTypeDefaultDescription
bidrequiredarray of objects-Array of bid objects; each bid object relates to an imp object in the bid request. Note that, if supported by an exchange, one imp object can have many bid objects.
seatoptionalstring-ID of the bidder seat on whose behalf this bid is made.
groupoptionalinteger-“1” means impressions must be won-­-lost as a group; default is “0”.
extoptionalobject-This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Back to table of contents

Bid Object

FieldScopeTypeDefaultDescription
id      requiredstring-ID for the bid object chosen by the bidder for tracking and debugging purposes. Useful when multiple bids are submitted for a single impression for a given seat.
impid      requiredstring-ID of the impression object to which this bid applies.
pricerequiredfloat-Bid price in CPM.  WARNING/Best Practice Note: Although this value is a  float, OpenRTB strongly suggests using integer math for accounting to avoid rounding errors.
adid     optionalstring-ID that references the ad to be served if the bid wins.
nurl    optionalstring-Win notice URL. Note that ad markup is also typically, but not necessarily, returned via this URL.
admoptionalstring-Actual ad markup. XHTML if a response  to a banner object, or VAST XML if a response to a video object.
adomain      optionalarray of strings-Advertiser’s primary or top-­‐level domain for advertiser checking. This can be a list of domains if there is a  rotating creative. However, exchanges  may mandate that only one landing domain is allowed.
Iurl     optionalstring-Sample image URL (without cache busting) for content checking.
cidoptionalstring-Campaign ID or similar that appears within the ad markup.
cridoptionalstring-Creative ID for reporting content issues or defects. This could also be used as a reference to a creative ID that is posted with an exchange.
attroptionalarray of integers-Array of creative attributes. See Table 6.3 Creative Attributes.
dealidoptionalstring-A unique identifier for the direct deal associated with the bid. If the bid is associated and in response to a dealid in the request object it is required in the response object.
hoptional
-Height of the ad in pixels. If the bid request contained the wmax/hmax and wmin/hmin optional fields it is recommended that the response bid contains this field to signal the size of ad chosen.
woptional
-Width of the ad in pixels. If the bid request contained the wmax/hmax and wmin/hmin optional fields it is recommended that the response bid contains this field to signal the size of ad chosen.
extoptionalobject-This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Back to table of contents

Reference Lists/Enumerations

Content Categories 

see IAB Content Taxonomy and IAB, Apple & Android Category Taxonomy

Banner Ad Types  Back to table of contents

ValueDescription
1

XHTML text ad. (usually mobile)      

2

XHTML banner ad.  (usually mobile)

3

JavaScript ad; must  be valid  XHTML  (i.e., script  tags included).

4Iframe

Back to table of contents

Creative Attributes 

ValueDescription
1Audio Ad (Auto Play)       
2Audio Ad (User Initiated)      
3Expandable (Automatic)      
4Expandable (User Initiated -­‐ Click)      
5Expandable (User Initiated -­‐ Rollover)      
6In-­‐Banner Video Ad (Auto Play)      
7In-­‐Banner Video Ad (User Initiated)      
8Pop (e.g., Over, Under, or upon Exit)      
9Provocative or Suggestive Imagery
10Shaky, Flashing, Flickering, Extreme Animation, Smileys     
11Surveys     
12Text Only
13User Interactive (e.g., Embedded Games)  
14Windows Dialog or Alert Style  
15Has audio on/off button     
16Ad can be skipped (e.g., skip button on preroll video)     

Back to table of contents

API Frameworks

ValueDescription
1VPAID  1.0
2

VPAID  2.0   

3

MRAID-­‐1   

4ORMMA
5MRAID-2

Back to table of contents

Ad Position       

ValueDescription
0Unknown
1Above the fold
2

DEPRECATED  -­‐   May or may not be immediately visible depending  on screen  size and resolution. 

3

Below  the fold 

4Header
5Footer
6Sidebar
7Fullscreen

Back to table of contents

Video Linearity   

ValueDescription
1

Linear/In-­‐stream   

2

Non-­‐Linear/Overlay      

Back to table of contents

Video Bid Response Protocols  

ValueDescription
1VAST 1.0
2VAST 2.0
3VAST 3.0
4

VAST 1.0  Wrapper      

5

VAST 2.0  Wrapper

6

VAST 3.0  Wrapper

Back to table of contents

Video Playback Methods       

ValueDescription
1Auto-­‐play sound on
2

Auto-­‐play sound  off      

3

Click-­‐to-­‐play      

4

Mouse-­‐over      

Back to table of contents

Video Start Delay    

ValueDescription
0

Pre-­‐roll     

-1Generic mid-­‐roll
-2

Generic Post-­‐roll 

Back to table of contents

Expandable Direction       

ValueDescription
1Left
2

Right   

3Up
4Down
5Fullscreen

Back to table of contents

Content Delivery Methods 

ValueDescription
1Streaming
2Progressive

Back to table of contents

Content Context     

ValueDescription
1Video (a video file or stream that is being watched by the user, including (Internet) television broadcasts)
2Game (an interactive software game that is being played by the user)
3Music (an audio file or stream that is being listened to by the user, including (Internet) radio broadcasts)
4Application (an interactive software application that is being used by the user)
5Text (a document that is primarily textual in nature that is being read or viewed by the user, including web page, ebook, or news article)
6Other (content type unknown or the user is consuming content which does not fit into one of the categories above)
7Unknown

Back to table of contents

Video Quality 

ValueDescription
0Unknown
1

Professionally Produced   

2Prosumer
3

User  Generated (UGC) 

Back to table of contents

Location Type        

ValueDescription
1GPS/Location Services
2IP Address
3

User provided  (e.g.,  registration  data)      

Back to table of contents

Device Type 

ValueDescription
1

Mobile/Tablet    

2

Personal Computer      

3Connected TV
4Phone
5Tablet
6

Connected Device   

7Set Top Box

Back to table of contents

VAST Companion Types       

ValueDescription
1Static Resource
2HTML Resource
3iframe Resource

Back to table of contents

QAG Media Ratings  

ValueDescription
1

All  Audiences

2

Everyone over 12

3Mature  Audience

Back to table of contents

NoBid  Reason Codes     

ValueDescription
0Unknown Error
1Technical Error
2Invalid Request
3Known Web spider
4Suspected  Non-­‐Human Traffic
5Cloud, Data center, or Proxy IP
6

Unsupported  Device

7

Blocked Publisher or Site

8

Unmatched user

Back to table of contents