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 objectabout 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.

bcat

string array

Blocked advertiser categories using the IAB content categories.

ext

object

Placeholder for exchange-specific extensions to OpenRTB.

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.

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.

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.

podid

string

Unique identifier indicating that an impression opportunity belongs to a video ad pod. If multiple impression opportunities within a bid request share the same podid, this indicates that those impression opportunities belong to the same video ad pod.

poddur

integer; recommended

Indicates the total amount of time in seconds that advertisers may fill for a “dynamic” video ad pod

podseq

integer; default 0

The sequence (position) of the video ad pod within a content stream.

slotinpod

integer; default 0

For video ad pods, this value indicates that the seller can guarantee delivery against the indicated slot position in the pod.

maxseq

integer; recommended

Indicates the maximum number of ads that may be served into a “dynamic” video ad pod.

protocols

integer array;
recommended

Array of supported video protocols.

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).

startdelay

integer;
recommended

Indicates the start delay in seconds for pre-roll, mid-roll, or post-roll ad placements.

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.

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., “mysite.foo.com”).

page

string

URL of the page where the impression will be shown.

ref

string

Referrer URL that caused navigation to the current page.

mobile

integer

Indicates if the site has been programmed to optimize layout when viewed on mobile devices, where 0 = no, 1 = yes.

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 (e.g., com.foo.mygame). On iOS, it is typically a numeric ID.

domain

string

Domain of the app (e.g., “mygame.foo.com”).

storeurl

string

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

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.

lmt

integer;
recommended

“Limit Ad Tracking” signal commercially endorsed (e.g., iOS, Android), where 0 = tracking is unrestricted, 1 = tracking must be limited per commercial guidelines.

ip

string;
recommended

IPv4 address closest to device.

ipv6

string

IP address closest to device as IPv6.

make

string

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

model

string

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

os

string

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

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., “VERIZON”) using exchange curated string names which should be published to bidders a priori.

ifa

string

ID sanctioned for advertiser use in the clear (i.e., not hashed).

didsha1

string

Hardware device ID (e.g., IMEI); hashed via SHA1.

didmd5

string

Hardware device ID (e.g., IMEI); hashed via MD5.

dpidsha1

string

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

dpidmd5

string

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

macsha1

string

MAC address of the device; hashed via SHA1.

macmd5

string

MAC address of the device; hashed via MD5.

Attribute

Type

Description

lat

float

Latitude from -90.0 to +90.0, where negative is south.

lon

float

Longitude from -180.0 to +180.0, where negative is west.

country

string

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

Attribute

Type

Description

id

string;
recommended

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

buyeruid

string;
recommended

Buyer-specific ID for the user as mapped by the exchange for the buyer. At least one of buyeruid or id is recommended.

yob

integer

Year of birth as a 4-digit integer.

gender

string

Gender, where “M” = male, “F” = female, “O” = known to be other (i.e., omitted is unknown).

Attribute

Type

Description

id

string; required

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

seatbid

object array

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

bidid

string

Bidder generated response ID to assist with logging/tracking.

cur

string;
default “USD”

Bid currency using ISO-4217 alpha codes.

nbr

integer

Reason for not bidding.

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

Attribute

Type

Description

id

string; required

Bidder generated bid ID to assist with logging/tracking.

impid

string; required

ID of the Imp object in the related bid request.

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).

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.

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.

adid

string

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

adomain

string array

Advertiser domain for block list checking (e.g., “ford.com”). This can be an array of for the case of rotating creatives. Exchanges can mandate that only one domain is allowed.

iurl

string

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

cid

string

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

crid

string

Creative ID to assist with ad quality checking.

cat

string array

IAB content categories of the creative.

w

integer

Width of the creative in device independent pixels (DIPS).

h

integer

Height of the creative in device independent pixels (DIPS).

Field

Scope

Type

Default

Description

assets

required

array of objects

-

An array of Asset Objects. Any bid response must comply with the array of elements expressed in the bid request.

Field

Scope

Type

Default

Description

id

required

int

-

Unique asset ID, assigned by
exchange. Typically a counter for the array.

required

optional

int

0

Set to 1 if asset is required
(exchange will not accept a bid
without it)

title

recommended

object

-

Title object for title assets.

img

recommended

object

-

Image object for image assets.

video

optional

object

-

Video object for video assets. Note that in-stream (ie preroll, etc) video ads are not part of Native. Native ads may contain a video as the ad creative itself.

data

recommended

object

-

Data object for brand name, description, ratings, prices etc.

Field

Scope

Type

Default

Description

Len

required

integer

-

Maximum length of the text in the title element. Recommended to be 25, 90, or 140.

Field

Scope

Type

Default

Description

w

optional

integer

-

Width of the image in pixels.

wmin

recommended

integer

-

The minimum requested width of the image in pixels. This option should be used for any rescaling of images by the client. Either w or wmin should be transmitted. If only w is included, it should be considered an exact requirement.

h

optional

integer

-

Height of the image in pixels.

hmin

recommended

integer

-

The minimum requested height of the image in pixels. This option should be used for any rescaling of images by the client. Either h or hmin should be transmitted. If only h is included, it should be considered an exact requirement.

Field

Scope

Type

Default

Description

mimes

required

array

-

Content MIME types supported. Popular MIME types include,but are not limited to “video/x-mswmv” for Windows Media, and “video/x-flv” for Flash Video, or “video/mp4”. Note that native frequently does not support flash.

minduration

required

integer

-

Minimum video ad duration in seconds.

maxduration

required

integer

-

Maximum video ad duration in seconds.

protocols

required

array of integers

-

An array of video protocols the publisher can accept in the bid response.

Field

Scope

Type

Default

Description

Type

required

integer

-

Type ID of the element supported by the publisher. The publisher can display this information in an appropriate format.

Len

optional

integer

-

Maximum length of the text in the element’s response.

Field

Scope

Type

Default

Description

ver

recommended

string

“1.2”

Version of the Native Markup version in use.

assets

recommended

array of
objects

-

List of native ad’s assets. Required if no assetsurl. Recommended as fallback even if assetsurl is provided.

assetsurl

optional

string

-

URL of an alternate source for the assets object. The expected response is a JSON object mirroring the assets object in the bid response, subject to certain requirements as specified in the individual objects. Where present, overrides the asset object in the response.

link

required

object

-

Destination Link. This is default link object for the ad. Individual assets can also have a link object which applies if the asset is activated(clicked). If the asset doesn’t have a link object, the parent link object applies.

imptrackers

optional

array of strings

-

Array of impression tracking URLs, expected to return a 1x1 image or 204 response - typically only passed when using 3rd party trackers. To be deprecated - replaced with eventtrackers

jstracker

optional

string

-

Optional JavaScript impression
tracker. This is a valid HTML,
Javascript is already wrapped in
<script> tags. It should be executed at impression time where it can be supported. To be deprecated - replaced with eventtrackers.

eventtrackers

optional

Array of

-

Array of tracking objects to run with the ad, in response to the declared supported methods in the request. Replaces imptrackers and jstracker, to be deprecated.

Field

Scope

Type

Default

Description

id

optional

int

-

Optional if assetsurl/dcourl is being used; required if embedded asset is being used.

required

optional

int

0

Set to 1 if asset is required
(exchange will not accept a bid
without it)

title

optional

object

-

Title object for title assets.

img

optional

object

-

Image object for image assets.

video

optional

object

-

Video object for video assets. Note that in-stream (ie preroll, etc) video ads are not part of Native. Native ads may contain a video as the ad creative itself.

data

optional

object

-

Data object for brand name, description, ratings, prices etc.

link

optional

object

-

Link object for call to actions. The link object applies if the asset item is activated (clicked). If there is no link object on the asset, the parent link object on the bid response applies.

Field

Scope

Type

Default

Description

Text

required

String

-

The text associated with the text element.

Len

optional

integer

-

The length of the title being provided. Required if using assetsurl/dcourl representation, optional if using embedded asset representation

Field

Scope

Type

Default

Description

url

required

string

-

URL of the image asset.

w

recommended

integer

-

Width of the image in pixels. Recommended for embedded asset responses. Required for assetsurl/dcourlresponses if multiple assets of same type submitted.

h

recommended

integer

-

Height of the image in pixels. Recommended for embedded asset responses. Required for assetsurl/dcourl responses if multiple assets of same type submitted.

Field

Scope

Type

Default

Description

vasttag

required

string

-

vast xml.

Field

Scope

Type

Default

Description

value

required

string

-

The formatted string of data to be displayed. Can contain a formatted value such as “5 stars” or “$10” or “3.4 stars out of 5”

Field

Scope

Type

Default

Description

url

required

string

-

Landing URL of the clickable link.

clicktrackers

optional

array of
strings

-

List of third-party tracker URLs to be fired on click of the URL.

fallback

optional

string
(URL)

-

Fallback URL for deeplink. To be used if the URL given in url is not supported by the device.

Field

Scope

Type

Default

Description

event

required

integer

-

Type of event to track.

method

required

integer

-

Type of tracking requested.

url

optional

text

-

The URL of the image or js. Required for image or js, optional for custom.

Macro

Description

${AUCTION_ID}

ID of the bid request; from BidRequest.id attribute.

${AUCTION_BID_ID}

ID of the bid; from BidResponse.bidid attribute.

${AUCTION_IMP_ID}

ID of the impression just won; from imp.id attribute.

${AUCTION_SEAT_ID}

ID of the bidder seat for whom the bid was made.

${AUCTION_AD_ID}

ID of the ad markup the bidder wishes to serve; from bid.adid attribute.

${AUCTION_PRICE}

Clearing price using the same currency and units as the bid.

${AUCTION_CURRENCY}

The currency used in the bid (explicit or implied); for confirmation only.

${AUCTION_MBR}

Market Bid Ratio defined as: clearance price / bid price.

${AUCTION_LOSS}

Loss reason codes.