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.