Skip to main content

Open RTB Bid Request Specifications

This page explains how to make requests for bids

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

The following objects should be sent encoded as JSON in the request body:

Bid Request

atYesAuction type, first price = 1 (int)
idYesUnique bid request ID (string)
impYesArray of Imp objects representing the impressions offered(object).
siteYesDetails via a Site object about the publisher’s website(object).
deviceYesDetails via a Device object about the user’s device to which the impression will be delivered(object).
userNoDetails via a User object about the human user of the device; the advertising audience(object).
extNoPlaceholder for extensions to OpenRTB.


idYesUnique impression ID within this bid request (string)
bidfloorNoMinimum bid for this impression (CPM) / click (CPC) and account currency (float)
bidfloorcurNoCurrency for minimum bid value specified using ISO-4217 alpha codes (string)
nativeOnly for native and push impsA Native object opportunity (object).
bannerOnly for banner impsA Banner object opportunity (object).
instlOnly for pop, direct link and email click impsA Fullscreen object opportunity (object).
videoOnly for videoA Video object opportunity (object)
secureRecommendedFlag 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)
elNoBase64 Encoded Email (string)
extNoPlaceholder for exchange-specific extensions


wYesWidth of the banner (integer)
hYesHeight of the banner (integer)


instlYes0 = direct link/email clicks, 1 = popunder

imp.native (for Native and Push Notification Ads)

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


verYesVersion of the Native Markup version in use (string)
contextNoThe 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)
plcmttypeYesThe design/format/layout of the ad unit being offered. Currently we support 4 (Recommendation widget) and 500 (Push Notification) (integer)
plcmtcntNoThe number of identical placements in this Layout. Max: 10 (integer) (integer)
assetsYesAn array of Asset Objects. Any bid response must comply with the array of elements expressed in the bid request (array of JSON objects)
seqNo0 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)


idYesUnique asset ID, assigned by exchange. Typically a counter for the array (integer) 1: Image asset ID, 2: Title asset ID, 3: Description asset ID
requiredNoSet to 1 if asset is required or 0 if asset is optional (integer)
plcmtcntNoThe number of identical placements in this Layout (integer)
imgYesImage object for image assets** (JSON object)
titleNoTitle object for title assets** (JSON object)
dataNoData 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


typeNoType ID of the image element supported by the publisher. We support: 1 (Icon image) (integer), 3 (Large image preview for the ad) (integer)
wNoWidth of the image in pixels, optional (integer)
hNoHeight of the image in pixels, optional (integer)
wminYesThe minimum requested width of the image in pixels (integer)
hminYesThe minimum requested height of the image in pixels (integer)

*Push Notification icon dimensions: 192px x 192px


lenYesMaximum length of the text in the title element. (integer)

typeYesType 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)
lenNoMaximum length of the text in the element’s response (integer)

mimesNoList of supported mime types (string array)
mindurationYesMinimum video ad duration in seconds(int).
maxdurationYesMaximum video ad duration in seconds(int).
protocolsYesList of supported video bid response protocols (int array)
linearityRequired for in-stream ads only.Indicates if the impression must be linear, nonlinear, etc. (int)
boxingallowedRequired for in-stream ads only.Indicates if letter-boxing of 4:3 content into a 16:9 window is allowed (int)


video_ctaNoIndicates if CTAs should be provided, where 0 = no, 1 = yes (default 1)

To see an example of CTA, please check our Response example page.


idRecommended*Unique Site ID (string)
domainRecommended*Domain name of the site (string)
catNoIAB category ID (string array)
pageRecommendedFull URL of the page where the ad will be shown (string)
keywordsNoKeywords can be used to ensure ad zones get the right type of advertising. Keywords should be a string of comma-separated words.
extNoPlaceholder for exchange-specific extensions to OpenRTB.

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


exchangecatNoCustom ExoClick category ID (integer)
idzoneNoCustom ExoClick Ad Zone ID (integer)


idRequiredUnique App ID (string)
catNoIAB category ID (string array)
keywordsNoKeywords can be used to ensure ad zones get the right type of advertising. Keywords should be a string of comma-separated words (string)
publisherNoDetails about the Publisher (object)

Note: You cannot send "app" object together with "site" or vice versa.


domainRecommendedHighest level domain of the publisher (e.g., "") (string)


uaYesBrowser user agent (string)
geoNoLocation of the device assumed to be the user’s current location defined by a Geo object.
ipYesIP address of the user (string)*
ipv6RecommendedIPv6 address of the user (string)*
languageRecommendedBrowser language using ISO-639-1-alpha-2 (string)
osNoOperating System (string)
jsNoSupport for JavaScript, where 0 = no, 1 = yes (integer)
extNoPlaceholder for exchange-specific extensions to OpenRTB

*Either ip or ipv6 will be in the request


countryNoCountry ISO3


remote_addrNoMain IP address of the user (string)
x_forwarded_forNoX-FORWARDED-FOR IP address of the user or empty if not set (string)


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


subNoThe Sub ID. This should be a number between six and ten digits: Do not use zeroes at the beginning of Sub IDs.


You can find a detailed list of Request examples in our example page