OpenRTB Version HTTP Header: x-openrtb-version: 2.4
Keep-Alive HTTP Header: Connection: Keep-Alive
Content JSON: Content-Type: application/json
The following objects should be sent encoded as JSON in the request body:
Bid Request
Attribute
Required?
Description
at
Yes
Auction type, first price = 1 (int)
id
Yes
Unique bid request ID (string)
imp
Yes
Array of Imp objects representing the impressions offered(object).
site
Yes
Details via a Site object about the publisher’s website(object).
device
Yes
Details via a Device object about the user’s device to which the impression will be delivered(object).
user
No
Details via a User object about the human user of the device; the advertising audience(object).
ext
No
Placeholder for extensions to OpenRTB.
imp
Attribute
Required?
Description
id
Yes
Unique impression ID within this bid request (string)
bidfloor
No
Minimum bid for this impression (CPM) / click (CPC) and account currency, optional (float)
bidfloorcur
No
Currency for minimum bid value specified using ISO-4217 alpha codes, optional (string)
native
only for native imps
A Native object ; required if this impression is offered as a native ad opportunity (object)
banner
Only for banner imps
A banner object ; required if this impression is offered as a banner ad opportunity (object)
instl
Only for instl imps
An interstitial object ; required if this impression is offered as an interstitial ad opportunity (object)
video
Only for video
A Video object; required if this impression is offered as a video ad opportunity (object)
secure
No; Recommended 1
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, optional (integer)
el
No
Base64 Encoded Email (string)
ext
No
Placeholder for exchange-specific extensions
imp.banner
Attribute
Required?
Description
w
Yes
Width of the banner (integer)
h
Yes
Height of the banner (integer)
imp.instl
Attribute
Required?
Description
instl
Yes
Flag specifying if ad is popunder (integer)
imp.native (for Native and Push Notification Ads)
Attribute
Required?
Description
request
Yes
Request payload complying with the Native Ad Specification – a JSON encoded string of the Native Ads request including its native top level object (JSON object)
ver
No
Version of the Dynamic Native Ads API to which request complies (string)
imp.native.request
Attribute
Required?
Description
ver
Yes
Version of the Native Markup version in use (string)
context
No
The context in which the ad appears. In this case it is 1 (Content-centric context such as newsfeed, article, image gallery, video gallery, or similar), optional (integer)
plcmttype
Yes
The design/format/layout of the ad unit being offered. Currently we support 4 (Recommendation widget) and 500 (Push Notification) (integer)
plcmtcnt
No
The number of identical placements in this Layout (integer)
assets
Yes
An array of Asset Objects. Any bid response must comply with the array of elements expressed in the bid request (array of JSON objects)
seq
No
0 for the first ad, 1 for the second ad, and so on. Note this would generally NOT be used in combination with plcmtcnt – either you are auctioning multiple identical placements (in which case plcmtcnt>1, seq=0) or you are holding separate auctions for distinct items in the feed (in which case plcmtcnt=1, seq=>=1)
imp.native.request.assets
Attribute
Required?
Description
id
Yes
Unique asset ID, assigned by exchange. Typically a counter for the array (integer) 1: Image asset ID, 2: Title asset ID, 3: Description asset ID
required
No
Set to 1 if asset is required or 0 if asset is optional (integer)
plcmtcnt
No
The number of identical placements in this Layout (integer)
img
Yes
Image object for image assets* (JSON object)
title
No
Title object for title assets* (JSON object)
data
No
Data object for brand name, description, ratings, prices etc.* (JSON object)
video
No
Video object for video assets. See the Video request object definition. 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(object).
* Only one of the {img, title, data} objects should be present in each asset object
imp.native.request.assets.img
Attribute
Required?
Description
type
No
Type ID of the image element supported by the publisher. We support: 1 (Icon image) (integer), 3 (Large image preview for the ad) (integer)
w
No
Width of the image in pixels, optional (integer)
h
No
Height of the image in pixels, optional (integer)
wmin
Yes
The minimum requested width of the image in pixels (integer)
hmin
Yes
The minimum requested height of the image in pixels (integer)
*Push Notification icon dimensions: 192px x 192px
imp.native.request.assets.title
Attribute
Required?
Description
len
Yes
Maximum length of the text in the title element. (integer)
imp.native.request.assets.data
Attribute
Required?
Description
type
Yes
Type ID of the element supported by the publisher (integer). We support: 1 (sponsored – Sponsored By message where response should contain the brand name of the sponsor), 2 (desc – Descriptive text associated with the product or service being advertised)
len
No
Maximum length of the text in the element’s response (integer)
imp.native.request.assets.video
Attribute
Required?
Description
mimes
Yes
List of supported mime types (string array)
minduration
Yes
Minimum video ad duration in seconds(int).
maxduration
Yes
Maximum video ad duration in seconds(int).
protocols
Yes
List of supported video bid response protocols (int array)
linearity
Required for in-stream ads only.
Indicates if the impression must be linear, nonlinear, etc. (int)
boxingallowed
Required for in-stream ads only.
Indicates if letter-boxing of 4:3 content into a 16:9 window is allowed (int)
imp.video
Attribute
Description
mimes
List of supported mime types (string array)
imp.ext
Attribute
Required?
Description
video_cta
No
Indicates if CTAs should be provided*
* When enabled, CTA should be provided as part of VAST Tag here.
site
Attribute
Required?
Description
id
Recommended
Unique Site ID (string)
domain
Recommended
Domain name of the site (string)
cat
No
IAB category ID (string array)
page
Recommended
Full URL of the page where the ad will be shown (string)
keywords
No
Keywords can be used to ensure ad zones get the right type of advertising. Keywords should be a string of comma-separated words
ext
No
Placeholder for exchange-specific extensions
site.ext
Attribute
Required?
Description
exchangecat
No
Custom Paradox category ID (integer)
idzone
No
Custom Paradox Ad Zone ID (integer)
device
Attribute
Required?
Description
ua
Yes
Browser user agent (string)
geo
No
Location of the device assumed to be the user’s current location defined by a Geo object.
ip
Yes
IP address of the user (string)*
ipv6
Recommended
IPv6 address of the user (string)*
language
Recommended
Browser language (string)
os
No
Operating System (string)
js
No
Support for JavaScript, where 0 = no, 1 = yes (integer)
ext
No
Placeholder for exchange-specific extensions to OpenRTB
*Either ip or ipv6 will be in the request
device.geo
Attribute
Required?
Description
country
No
Country ISO3
device.ext
Attribute
Required?
Description
remote_addr
No
Main IP address of the user (string)
x_forwarded_for
No
X-FORWARDED-FOR IP address of the user or empty if not set (string)
user
Attribute
Required?
Description
id
Yes*
Unique user ID (string)
Note: If you cannot generate a user ID, you can leave it empty (“”). The request will get a response as long as “user” object is included in the request.
ext
Attribute
Required?
Description
sub
No
The Sub ID. This should be a number between six and ten digits: Do not use zeroes at the beginning of Sub IDs.