Tech Specs for OpenRTB Demand Partners

Attribute

Type

Description

id

string; required

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

imp

object array;  required 

Array of Imp objects representing the impressions offered. At least 1 Imp object is required. 

site

object;  recommended 

Details via a Site object about the publisher’s website. Only applicable and recommended for websites. 

app

object; recommended 

Details via an App object about the publisher’s app (i.e., non-browser applications). Only applicable and recommended for apps.

device

object;  recommended 

Details via a Device object about the user’s device to which the impression will be delivered. 

user

object;  recommended 

Details via a User object about the human user of the device; the advertising audience. 

at

integer;  default 2 

Auction type, where 1 = First Price, 2 = Second Price Plus. Exchange-specific auction types can be defined using values greater than 500.  

tmax

integer 

Maximum time in milliseconds the exchange allows for bids to be received including Internet latency to avoid timeout. This value supersedes any a priori guidance from the exchange. 

cur

string array

Array of allowed currencies for bids on this bid request using ISO-4217 alpha codes. Recommended only if the exchange accepts multiple currencies. 

Attribute

Type

Description

id

string; required

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

banner

object

A Banner object; required if this impression is offered as a banner ad opportunity. 

video

object 

A Video object; required if this impression is offered as a video ad opportunity.

native

object 

A Native object; required if this impression is offered as a native ad opportunity. 

instl

integer; default 0 

1 = the ad is interstitial or full screen, 0 = not interstitial.

tagid

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

float; default 0 

Minimum bid for this impression expressed in CPM.

secure

integer

Flag to indicate if the impression requires secure HTTPS URL creative assets and markup, where 0 = non-secure, 1 = secure. If omitted, the secure state is unknown, but non-secure HTTP  support can be assumed. 

Attribute

Type

Description

w

integer 

Exact width in device independent pixels (DIPS);  recommended if no format objects are specified. 

h

integer 

Exact height in device independent pixels (DIPS);  recommended if no format objects are specified. 

battr

integer array

Blocked creative attributes. 

Attribute

Type

Description

mimes 

string array; required 

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

minduration

integer; recommended

Minimum video ad duration in seconds.

maxduration

integer; recommended 

Maximum video ad duration in seconds.

protocols 

integer array; recommended 

Array of supported video protocols. At least one supported protocol must be specified in either the protocol or protocols attribute. 

w

integer; recommended

Width of the video player in device independent pixels (DIPS).

h

integer; recommended

Height of the video player in device independent pixels (DIPS).

Attribute

Type

Description

request 

string; required

Request payload complying with the Native Ad Specification.

ver

string; recommended

Version of the Dynamic Native Ads API to which request complies; highly recommended for efficient parsing.

battr 

integer array 

Blocked creative attributes.

Attribute

Type

Description

id

string;  recommended 

Exchange-specific site ID. 

name

string

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

domain

string

Domain of the site (e.g., “example.com”).

cat

string array 

Array of IAB content categories of the site. 

pagecat

string array 

Array of IAB content categories that describe the current page or view of the site.  

page

string

URL of the page where the impression will be shown.

publisher

object 

Details about the Publisher of the site.

Attribute

Type

Description

id

string; recommended 

Exchange-specific app ID. 

name

string

App name (may be aliased at the publisher’s request). 

bundle

string

A platform-specific application identifier intended to be unique to the app and independent of the exchange. On Android, this should be a bundle or package name. On iOS, it is typically a numeric ID. 

storeurl

string   

App store URL for an installed app; for IQG 2.1 compliance.

Attribute

Type

Description

id

string

Exchange-specific publisher ID.

Attribute

Type

Description

ua

string;  recommended 

Browser user agent string.

geo

object;  recommended 

Location of the device assumed to be the user’s current location defined by a Geo object. 

dnt

integer; recommended 

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

ip

string; recommended 

IPv4 address closest to device.

devicetype

integer

The general type of device. 

make

string

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

model

string

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

os

string

Device operating system (e.g., “Android”). 

osv

string

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

js

integer 

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

language

string

Browser language using ISO-639-1-alpha-2.

carrier

string

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

connectiontype

integer

Network connection type. 

Attribute

Type

Description

type

integer 

Source of location data; recommended when passing lat/lon. Refer to List 5.20. 

country

string

Country code using ISO-3166-1-alpha-3. 

region

string

Region code using ISO-3166-2; 2-letter state code if USA. 

metro

string 

Google metro code; similar to but not exactly Nielsen DMAs.

city

string

City using United Nations Code for Trade & Transport  Locations.

zip

string

Zip or postal code.

Attribute

Type

Description

id

string;  recommended 

Exchange-specific ID for the user. At least one of id or buyeruid is recommended. 

Attribute

Type

Description

id

string; required

ID of the bid request to which this is a response. 

bidid

string

Bidder generated response ID to assist with logging/tracking.

seatbid

object array

Array of seatbid objects; 1+ required if a bid is to be made.

cur

string; default “USD” 

Bid currency using ISO-4217 alpha codes. 

Attribute

Type

Description

bid

object array; required 

Array of 1+ Bid objects each related to an impression. Multiple bids can relate to the same impression. 

seat

string

ID of the buyer seat (e.g., advertiser, agency) on whose behalf  this bid is made. 

Attribute

Type

Description

id

string; required

Bidder generated bid ID to assist with logging/tracking.

adid

string

ID of a preloaded ad to be served if the bid wins.

nurl

string

Win notice URL called by the exchange if the bid wins (not  necessarily indicative of a delivered, viewed, or billable ad);  optional means of serving ad markup. Substitution macros  may be included in both the URL and optionally  returned markup. 

price

float; required

Bid price expressed as CPM although the actual transaction is  for a unit impression only. Note that while the type indicates  float, integer math is highly recommended when handling  currencies (e.g., BigDecimal in Java). 

impid

string; required 

ID of the Imp object in the related bid request.

crid

string; required

Creative ID to assist with ad quality checking. 

cid

string

Campaign ID to assist with ad quality checking; the collection  of creatives for which iurl should be representative. 

adomain

string array

Advertiser domain for block list checking. This can be an array of for the case of rotating creatives. Exchanges can mandate that only one domain is allowed. 

adm

string

Optional means of conveying ad markup in case the bid wins; supersedes the win notice if markup is included in both.  Substitution macros may be included. 

iurl

string

URL without cache-busting to an image that is representative of the content of the campaign for ad quality/safety checking. 

cat

string array

IAB content categories of the creative.

ext

object

Placeholder for bidder-specific extensions to OpenRTB.