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

AttributeRequired?Description
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.

imp

AttributeRequired?Description
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

imp.banner

AttributeRequired?Description
wYesWidth of the banner (integer)
hYesHeight of the banner (integer)
mimesNoList of supported mime types (string array). We support: image/jpeg, image/jpg, image/png, image/png, image/gif, image/webp, video/mp4
extNoPlaceholder for exchange-specific extensions (object)

imp.banner.ext

AttributeRequired?Description
image_outputNoIndicates output format for image banners* (string)
video_outputNoIndicates 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

AttributeRequired?Description
instlYes0 = direct link/email clicks, 1 = popunder

imp.native (for Native and Push Notification Ads)

AttributeRequired?Description
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)

imp.native.request

AttributeRequired?Description
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)

imp.native.request.assets

AttributeRequired?Description
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

imp.native.request.assets.img

AttributeRequired?Description
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

imp.native.request.assets.title

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

imp.native.request.assets.data

AttributeRequired?Description
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)

imp.video

AttributeRequired?Description
mimesNoList of supported mime types (string array)
protocolsNoList of supported video bid response protocols (int array)
skipNoIndicates if the player will allow the video to be skipped, where 0 = no, 1 = yes
skipafterNoNumber of seconds a video must play before skipping is enabled; only applicable if the ad is skippable
skipminNoVideos 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

AttributeRequired?Description
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.  

site

AttributeRequired?Description
idRequiredUnique Site ID (string)
domainRequiredDomain name of the site (string)
nameRequiredName 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.

site.ext

AttributeRequired?Description
exchangecatNoCustom ExoClick category ID (integer)
idzoneNoCustom ExoClick Ad Zone ID (integer)

app

AttributeRequired?Description
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.


app.publisher

AttributeRequired?Description
domainRecommendedHighest level domain of the publisher (e.g., "publisher.com") (string)

device

AttributeRequired?Description
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

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

AttributeRequired?Description
countryNoCountry ISO3

device.ext

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

user

AttributeRequired?Description
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.


ext

AttributeRequired?Description
subNoThe Sub ID. This should be a number between six and ten digits: Do not use zeroes at the beginning of Sub IDs.
exportNoResponse 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