Open RTB Bid Request Specifications
This page explains how to make requests for bids
- 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 (float) |
| bidfloorcur | No | Currency for minimum bid value specified using ISO-4217 alpha codes (string) |
| native | Only for native and push imps | A Native object opportunity (object). |
| banner | Only for banner imps | A Banner object opportunity (object). |
| instl | Only for pop, direct link and email click imps | A Fullscreen object opportunity (object). |
| video | Only for video | A Video object opportunity (object) |
| secure | Recommended | Flag to indicate if the impression requires secure HTTPS URL creative assets and markup, where 0 = non-secure, 1 = secure (recommended option). If omitted, the secure state is unknown, but non-secure HTTP support can be assumed (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) |
| mimes | No | List of supported mime types (string array). We support: image/jpeg, image/jpg, image/png, image/png, image/gif, image/webp, video/mp4 |
| ext | No | Placeholder for exchange-specific extensions (object) |
imp.banner.ext
| Attribute | Required? | Description |
|---|
| image_output | No | Indicates output format for image banners* (string) |
| video_output | No | Indicates output format for video banners* (string) |
*Defines format of adm field for the banner format. Options are xml or html. Default values is xml in case field not provided.
imp.instl
| Attribute | Required? | Description |
|---|
| instl | Yes | 0 = direct link/email clicks, 1 = popunder |
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. Max: 10 (integer) (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) |
*The amount of bids received for your Native request will be based on the value you set in "plcmtcnt". For example, a bid request with "plcmtcnt":3 will receive 3 different bid objects. You can find an example of this in the Response example page.
** 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.video
| Attribute | Required? | Description |
|---|
| mimes | No | List of supported mime types (string array) |
| protocols | No | List of supported video bid response protocols (int array) |
| skip | No | Indicates if the player will allow the video to be skipped, where 0 = no, 1 = yes |
| skipafter | No | Number of seconds a video must play before skipping is enabled; only applicable if the ad is skippable |
| skipmin | No | Videos of total duration greater than this number of seconds can be skippable; only applicable if the ad is skippable |
Note: If you provide only "skip" in the request but not "skipafter", the video will be skippable after 5 seconds. The response will set "skipoffset" to 5. If you provide "skip" but not "skipmin," the video will be skippable regardless of its duration.
imp.ext
| Attribute | Required? | Description |
|---|
| video_cta | No | Indicates if CTAs should be provided, where 0 = no, 1 = yes (default 1) |
To see an example of CTA, please check our Response example page.
site
| Attribute | Required? | Description |
|---|
| id | Required | Unique Site ID (string) |
| domain | Required | Domain name of the site (string) |
| name | Required | 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 to OpenRTB. |
site.ext
| Attribute | Required? | Description |
|---|
| exchangecat | No | Custom ExoClick category ID (integer) |
| idzone | No | Custom ExoClick Ad Zone ID (integer) |
app
| Attribute | Required? | Description |
|---|
| id | Required | Unique App ID (string) |
| cat | No | IAB category ID (string array) |
| 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 (string) |
| publisher | No | Details about the Publisher (object) |
Note: You cannot send "app" object together with "site" or vice versa.
app.publisher
| Attribute | Required? | Description |
|---|
| domain | Recommended | Highest level domain of the publisher (e.g., "publisher.com") (string) |
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 using ISO-639-1-alpha-2 (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 |
Note: You only need to include either ip or ipv6 in your request, not both. If you use ipv6, leave the ip field empty, and vice versa. Including both can cause errors.
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 string, 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. |
| export | No | Response type can be "json" or "xml" (string). Default is "json". |
Note: Sub IDs should be a number between 1 and Int32: Do not use zeroes at the beginning of Sub IDs.
Examples
You can find a detailed list of Request examples in our example page