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? | Descripción |
|---|
| 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? | Descripción |
|---|
| 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? | Descripción |
|---|
| 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? | Descripción |
|---|
| 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? | Descripción |
|---|
| instl | Yes | 0 = direct link/email clicks, 1 = popunder |
imp.native (for Native and Push Notification Ads)
| Attribute | Required? | Descripción |
|---|
| 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? | Descripción |
|---|
| 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? | Descripción |
|---|
| 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? | Descripción |
|---|
| tipo | 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? | Descripción |
|---|
| len | Yes | Maximum length of the text in the title element. (integer) |
imp.native.request.assets.data
| Attribute | Required? | Descripción |
|---|
| tipo | 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? | Descripción |
|---|
| 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? | Descripción |
|---|
| 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? | Descripción |
|---|
| 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? | Descripción |
|---|
| exchangecat | No | Custom ExoClick category ID (integer) |
| idzone | No | Custom ExoClick Ad Zone ID (integer) |
app
| Attribute | Required? | Descripción |
|---|
| 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? | Descripción |
|---|
| domain | Recommended | Highest level domain of the publisher (e.g., "publisher.com") (string) |
device
| Attribute | Required? | Descripción |
|---|
| 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 |
Nota: Sólo necesita incluir ip o ipv6 en su solicitud, no ambos. Si utiliza ipv6, elimine el atributo ip, y viceversa. Incluir ambos puede causar errores.
device.geo
| Attribute | Required? | Descripción |
|---|
| country | No | Country ISO3 |
device.ext
| Attribute | Required? | Descripción |
|---|
| 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? | Descripción |
|---|
| 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? | Descripción |
|---|
| 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". |
Nota: Los Sub IDs deben ser un número entre 1 y Int32: No utilice ceros al principio de los Sub IDs.
Ejemplos
You can find a detailed list of Request examples in our example page