Open RTB Bid Request Specifications
This page describes the different components of the RTB requests you will receive in order to bid.
- OpenRTB Version HTTP Header: x-openrtb-version: 2.4
- Keep-Alive HTTP Header: Connection: Keep-Alive
- Content JSON: Content-Type: application/json
- Data Encoding Header: Accept-Encoding
Bid Request
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.
Attribute | Description |
---|
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
Attribute | Description |
---|
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 ad opportunity(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
Attribute | Description |
---|
w | Width of the banner in pixels (integer). |
h | Height of the banner in pixels (integer). |
imp.instl
Attribute | Description |
---|
instl | Flag specifying if ad is popunder/interstitial (integer): 1=true, 0=false |
imp.native (Native & Push Notifications)
Attribute | Description |
---|
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
Attribute | Description |
---|
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
Attribute | Description |
---|
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
Attribute | Description |
---|
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
Attribute | Description |
---|
len | Maximum length of the text in the title element. (integer) |
imp.native.request.assets.data
Attribute | Description |
---|
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.native.request.assets.video | |
Attribute | Description |
---|
mimes | List of supported mime types (string array) |
minduration | Minimum video ad duration in seconds(int). |
maxduration | Maximum video ad duration in seconds(int). |
protocols | List of supported video bid response protocols (int array) |
linearity | Indicates if the impression must be linear, nonlinear, etc. (int) |
boxingallowed | 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) |
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 |
Note: 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
Attribute | Description |
---|
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
Attribute | Description |
---|
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
Attribute | Description |
---|
ua | Browser user agent (string) |
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 |
device.geo
Attribute | Description |
---|
country | Country ISO3 |
device.ext
Attribute | Description |
---|
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) |
user
Attribute | Description |
---|
id | Unique user ID (string) |
ext
Attribute | Required? | Description |
---|
sub | No | The sub will be an integer number representing the ID of the zone where the request was originated from. |
regs.ext
Attribute | Description |
---|
dsaapply | Flag to indicate if DSA is applied to the request. 1 = Required (int) |
dsa | Extension for DSA transparency information (object) |
regs.ext.dsa
Attribute | Description |
---|
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) |
Note: *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.