Skip to main content

Open RTB Bid Request Specifications

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.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.  

AttributeDescription
atAuction type, first price = 1 (int)
idUnique bid request ID (string)
impObject representing the impression offered(object).
siteDetails via a Site object about the publisher’s website(object).
deviceDetails via a Device object about the user’s device to which the impression will be delivered(object).
userDetails via a User object about the human user of the device; the advertising audience(object).
extPlaceholder for exchange-specific extensions.

imp

AttributeDescription
idUnique impression ID within this bid request (string)
bidfloorMinimum bid for this impression (CPM) / click (CPC) and account currency, optional (float).
bidfloorcurCurrency for minimum bid value specified using ISO-4217 alpha codes, optional (string)
nativeA Native object ; required if this impression is offered as a native ad opportunity(object).
bannerA banner object ; required if this impression is offered as a banner ad opportunity(object).
instlAn interstitial object ; required if this impression is offered as an interstitial ad opportunity(object).
secureFlag 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)
elBase64 Encoded Email (string)

imp.banner

AttributeDescription
wWidth of the banner in pixels (integer).
hHeight of the banner in pixels (integer).

imp.instl

AttributeDescription
instlFlag specifying if ad is popunder/interstitial (integer): 1=true, 0=false

imp.native (Native & Push Notifications)

AttributeDescription
requestRequest payload complying with the Native Ad Specification - a JSON encoded string of the Native Ads request including its native top level object (JSON object)
verVersion of the Dynamic Native Ads API to which request complies (string)

imp.native.request

AttributeDescription
verVersion of the Native Markup version in use (string)
contextThe 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)
plcmttypeThe design/format/layout of the ad unit being offered. Currently we support 4 (Recommendation widget) and 500 (Push Notification) (integer)
plcmtcntThe number of identical placements in this Layout (integer)
assetsAn array of Asset Objects. Any bid response must comply with the array of elements expressed in the bid request (array of JSON objects)
seq0 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

AttributeDescription
idUnique asset ID, assigned by exchange. Typically a counter for the array (integer)
requiredSet to 1 if asset is required or 0 if asset is optional** (integer)
plcmtcntThe number of identical placements in this Layout (integer)
imgImage object for image assets* (JSON object)
titleTitle object for title assets* (JSON object)
dataData object for brand name, description, ratings, prices etc.* (JSON object)
videoVideo 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

AttributeDescription
typeType ID of the image element supported by the publisher. We support: 1 (Icon image) (integer), 3 (Large image preview for the ad) (integer)
wWidth of the image in pixels, optional (integer)
hHeight of the image in pixels, optional (integer)
wminThe minimum requested width of the image in pixels (integer)
hminThe minimum requested height of the image in pixels (integer)

imp.native.request.assets.title

AttributeDescription
lenMaximum length of the text in the title element. (integer)

imp.native.request.assets.data

AttributeDescription
typeType 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)
lenMaximum length of the text in the element’s response (integer)
<!--
imp.native.request.assets.video
AttributeDescription
mimesList of supported mime types (string array)
mindurationMinimum video ad duration in seconds(int).
maxdurationMaximum video ad duration in seconds(int).
protocolsList of supported video bid response protocols (int array)
linearityIndicates if the impression must be linear, nonlinear, etc. (int)
boxingallowedIndicates if letter-boxing of 4:3 content into a 16:9 window is allowed (int)
-->

imp.video

AttributeDescription
mimesList of supported mime types (string array)
protocolsList of supported video bid response protocols (int array)
skipIndicates if the player will allow the video to be skipped, where 0 = no, 1 = yes
skipafterNumber of seconds a video must play before skipping is enabled; only applicable if the ad is skippable
skipminVideos 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

AttributeDescription
id*Unique Site ID (string)
domain*Domain name of the site (string)
catIAB category ID (string array)
pageFull URL of the page where the ad will be shown (string)
keywordsKeywords can be used to ensure ad zones get the right type of advertising. Keywords should be a string of comma-separated words
extPlaceholder for exchange-specific extensions to OpenRTB.

*These attributes are compulsory for Direct Link and Email Clicks formats.

site.ext

AttributeDescription
exchangecatCustom ExoClick category ID (integer)
idzoneCustom ExoClick Ad Zone ID (integer)
keywordMatching keyword if any (string)

The idzone attribute is used to identify the source in ExoClick from where traffic is coming from.

device

AttributeDescription
uaBrowser user agent (string)
geoLocation of the device assumed to be the user’s current location defined by a Geo object.
ipIP address of the user (string)*
ipv6IPv6 address of the user (string)*
languageBrowser language using ISO-639-1-alpha-2 (string)
osOperating System (string)
jsSupport for JavaScript, where 0 = no, 1 = yes (integer)
extPlaceholder for exchange-specific extensions to OpenRTB

device.geo

AttributeDescription
countryCountry ISO3

device.ext

AttributeDescription
remote_addrMain IP address of the user (string)
x_forwarded_forX-FORWARDED-FOR IP address of the user or empty if not set (string)

user

AttributeDescription
idUnique user ID (string)

ext

AttributeRequired?Description
subNoThe sub will be an integer number representing the ID of the zone where the request was originated from.

regs.ext

AttributeDescription
dsaapplyFlag to indicate if DSA is applied to the request. 1 = Required (int)
dsaExtension for DSA transparency information (object)

regs.ext.dsa

AttributeDescription
requiredFlag 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)
datatopubThe 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.