Open RTB 2.4 Bid Request
This page describes the different components of the RTB requests you will receive in order to bid.
Bid Request Headers
OpenRTB Version HTTP Header:
x-openrtb-version: 2.4Keep-Alive HTTP Header:
Connection: Keep-AliveContent JSON:
Content-Type: application/jsonData Encoding Header:
Accept-Encoding
Bid Request Object
When requesting bids for a specific context, the platform will perform an HTTP request with a timeout of 300ms and send the following object encoded as JSON in the request body. HTTP is recommended due to extra latency when using HTTPS.
at
Auction type, first price = 1 (int)
id
Unique bid request ID (string)
imp
Object representing the impression offered(object).
site
Details via a Site object about the publisher’s website(object).
device
Details via a Device object about the user’s device to which the impression will be delivered(object).
user
Details via a User object about the human user of the device; the advertising audience(object).
ext
Placeholder for exchange-specific extensions.
imp
id
Unique impression ID within this bid request (string)
bidfloor
Minimum bid for this impression (CPM) / click (CPC) and account currency, optional (float).
bidfloorcur
Currency for minimum bid value specified using ISO-4217 alpha codes, optional (string)
native
A Native object ; required if this impression is offered as a native ad opportunity(object).
banner
A banner object ; required if this impression is offered as a banner ad opportunity(object).
instl
An interstitial object ; required if this impression is offered as an interstitial or popunder ad opportunity(object).(object).
secure
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
Base64 Encoded Email (string)
imp.banner
w
Width of the banner in pixels (integer).
h
Height of the banner in pixels (integer).
mimes
Supported MIME types. Example values: image/jpg, image/png, video/mp4, image/webp.
imp.instl
instl
Flag specifying if ad is popunder/interstitial (integer): 1=true, 0=false
imp.native (Native & Push Notifications)
request
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
Version of the Dynamic Native Ads API to which request complies (string)
imp.native.request
ver
Version of the Native Markup version in use (string)
context
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
The design/format/layout of the ad unit being offered. Currently we support 4 (Recommendation widget) and 500 (Push Notification) (integer)
plcmtcnt
The number of identical placements in this Layout (integer)
assets
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
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
id
Unique asset ID, assigned by exchange. Typically a counter for the array (integer)
required
Set to 1 if asset is required or 0 if asset is optional** (integer)
plcmtcnt
The number of identical placements in this Layout (integer)
img
Image object for image assets* (JSON object)
title
Title object for title assets* (JSON object)
data
Data object for brand name, description, ratings, prices etc.* (JSON object)
video
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
** Assets are flagged as required according to the configuration of the publisher zone where your ad may be displayed
imp.native.request.assets.img
type
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
Width of the image in pixels, optional (integer)
h
Height of the image in pixels, optional (integer)
wmin
The minimum requested width of the image in pixels (integer)
hmin
The minimum requested height of the image in pixels (integer)
imp.native.request.assets.title
len
Maximum length of the text in the title element. (integer)
imp.native.request.assets.video
mimes
List of supported MIME types (string array).
minduration
Minimum video ad duration in seconds (integer).
maxduration
Maximum video ad duration in seconds (integer).
protocols
List of supported video bid response protocols (integer array).
linearity
Indicates if the impression must be linear, nonlinear, etc. (integer).
boxingallowed
Indicates if letter-boxing of 4:3 content into a 16:9 window is allowed (integer).
imp.native.request.assets.data
type
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
Maximum length of the text in the element’s response (integer)
imp.video
mimes
List of supported mime types (string array)
protocols
List of supported video bid response protocols (int array)
skip
Indicates if the player will allow the video to be skipped, where 0 = no, 1 = yes
skipafter
Number of seconds a video must play before skipping is enabled; only applicable if the ad is skippable
skipmin
Videos of total duration greater than this number of seconds can be skippable; only applicable if the ad is skippable
If the publisher provides "skip" in the request but not "skipafter", the video will be skippable after 5 seconds. The response will set "skipoffset" to 5. If the publisher provides "skip" but not "skipmin," the video will be skippable regardless of its duration.
site
id*
Unique Site ID (string)
domain*
Domain name of the site (string)
cat
IAB category ID (string array)
page
Full URL of the page where the ad will be shown (string)
keywords
Keywords can be used to ensure ad zones get the right type of advertising. Keywords should be a string of comma-separated words
ext
Placeholder for exchange-specific extensions to OpenRTB.
*These attributes are compulsory for Direct Link and Email Clicks formats.
site.ext
exchangecat
Custom ExoClick category ID (integer)
idzone
Custom ExoClick Ad Zone ID (integer)
keyword
Matching keyword if any (string)
The idzone attribute is used to identify the source in ExoClick from where traffic is coming from.
device
ua
Browser user agent (string)
sua
Structured user agent information, which can be used when a client supports User-Agent Client Hints (object)
geo
Location of the device assumed to be the user’s current location defined by a Geo object.
ip
IP address of the user (string)*
ipv6
IPv6 address of the user (string)*
language
Browser language using ISO-639-1-alpha-2 (string)
os
Operating System (string)
js
Support for JavaScript, where 0 = no, 1 = yes (integer)
ext
Placeholder for exchange-specific extensions to OpenRTB
*Exactly one of ip or ipv6 will be present in the bid request.
device.geo
country
Country ISO3
device.ext
remote_addr
Main IP address of the user (string)
x_forwarded_for
X-FORWARDED-FOR IP address of the user or empty if not set (string)
device.sua
Structured User Agent information. device.sua is considered the more accurate representation of the device attributes.
browsers
Send brands and versions derived from the Sec-CH-UA-Full-Version-List header. (Array of BrandVersion objects)
platform
Send a brand derived from the Sec-CH-UA-Platform header, and version derived from the Sec-CH-UA-Platform-Version header. (BrandVersion Object)
mobile
Derive this value from the Sec-CH-UA-Mobile header. (integer)
architecture
Retrieve this value from the Sec-CH-UA-Arch header. (string)
bitness
Retrieve this value from the Sec-CH-UA-Bitness header. (string)
model
Retrieve this value from the Sec-CH-UA-Model header. (string)
source
The source of data used to create this object, List: User-Agent Source in AdCOM 1.0 (integer; default 0)
device.sua.browsers | device.sua.platform
brand
The value may be sourced from the User-Agent Client Hints headers, representing either the user agent brand (from the Sec-CH-UA-Full-Version header) or the platform brand (from the Sec-CH-UA-Platform header). (string)
version
A sequence of version components, in descending hierarchical order [major, minor, micro, …] (array of string)
user
id
Unique user ID (string)
ext
sub
No
The sub will be an integer number representing the ID of the zone where the request was originated from.
regs.ext
dsaapply
Flag to indicate if DSA is applied to the request. 1 = Required (int)
dsa
Extension for DSA transparency information (object)
regs.ext.dsa
required
Flag to indicate if DSA information should be made available. 0 = Not required, 1 = Supported, bid responses with or without DSA object will be accepted, 2 = Required, bid responses without DSA object will not be accepted, 3 = Required, bid responses without DSA object will not be accepted, Publisher is an Online Platform (int)
datatopub
The publisher may need the transparency data for audit purposes. 0 = do not send transparency data, 1 = optional to send transparency data, 2 = send transparency data (int)
If you receive dsaapply: 1 and required: 2 or 3, it's mandatory to add dsa attributes with values in the response, otherwise the response will be rejected.
Examples
You can find a complete list of all the types of requests you can receive in our Advertiser Request example page.
Last updated
Was this helpful?