Open RTB 2.4 Bid Request

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

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).
app	Yes	Details via an App object about the publisher’s app* (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.

Only one of the objects {site, app} should be present in each request.

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 and full page interstitial imps	A Banner object opportunity (object).
instl	Only for pop, direct link, email and full page interstitial 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/full page interstitial

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

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 a CTA example, 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)

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

You only need to include either ip or ipv6 in your request, not both. If you use ipv6, remove the ip attribute, 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)

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

Examples

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