Open RTB 2.5 Bid Request

This page explains how to make requests for bids.

Suggested Bid Request Headers

• OpenRTB Version HTTP Header: x-openrtb-version: 2.5
• 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 Object

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 about the publisher’s website(object).
app	Yes	Details about the publisher’s app(object).
device	Yes	Details about the user’s device to which the impression will be delivered(object).
user	No	Details 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).
banner	Only for fullpage imps	A banner object (object).
secure	No; Recommended 1	Flag 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)

imp.banner

Attribute	Required?	Description
w	Yes	Width of the banner (integer)
h	Yes	Height of the banner (integer)
mimes	Yes	Mimes types - image/jpg, image/png, video/mp4 or image/webp

imp.video

Attribute	Required?	Description
mimes	Yes	Content MIME types supported (e.g., "video/mp4") (string array)
minduration	No	Minimum video ad duration in seconds (integer)
maxduration	No	Maximum video ad duration in seconds (integer)
protocols	No	Array of supported video protocols (integer)
linearity	No	Indicates if the impression must be linear, nonlinear, etc. If none specified, assume all are allowed (integer)
boxingallowed	No	Indicates if letter-boxing of 4:3 content into a 16:9 window is allowed, where 0 = no, 1 = yes (integer)
pos	No	Ad position on screen (integer)
h	No	Width of the video player in device independent pixels (DIPS) (integer)
w	No	Height of the video player in device independent pixels (DIPS) (integer)
ext	No	Placeholder for exchange-specific extensions to OpenRTB (object)

imp.video.ext

Attribute	Required?	Description
zone_type	No	Zone type within ExoClick's ad formats (e.g: video_slider)
cta	No	Specifies whether the ad zone shows a CTA component (integer)

site

Attribute	Required?	Description
id	Recommended	Unique Site ID (string)
name	No	Site name (string)
domain	Recommended	Domain 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

site.ext

Attribute	Required?	Description
exchangecat	No	Custom ExoClick category ID (integer)
idzone	No	Custom ExoClick Zone ID (integer)

app

Attribute	Required?	Description
id	Recommended	Unique App ID (string)
name	No	App name (string)
domain	Recommended	Domain name of the app (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)

device

Attribute	Required?	Description
ua	Yes	Browser user agent (string)
sua	No	Structured user agent information, which can be used when a client supports User-Agent Client Hints (object)
geo	No	Location of the device assumed to be the user’s current location defined by a Geo object.
ip	Yes	IPv4 address of the user (string)*
ipv6	Yes	IPv6 address of the user (string)*
language	Recommended	Browser language (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)

device.sua

Structured User Agent information. device.sua is considered the more accurate representation of the device attributes.

Attribute	Required?	Description
browsers	Recommended	Implementers should send brands and versions derived from the Sec-CH-UA-Full-Version-List header. (Array of BrandVersion objects)
platform	Recommended	Implementers should send a brand derived from the Sec-CH-UA-Platform header, and version derived from the Sec-CH-UA-Platform-Version header. (BrandVersion Object)
mobile	Recommended	Implementers should derive this value from the Sec-CH-UA-Mobile header. (integer)
architecture	Recommended	Implementers should retrieve this value from the Sec-CH-UA-Arch header. (string)
bitness	Recommended	Implementers should retrieve this value from the Sec-CH-UA-Bitness header. (string)
model	Recommended	Implementers should retrieve this value from the Sec-CH-UA-Model header. (string)
source	Recommended	The source of data used to create this object, List: User-Agent Source in AdCOM 1.0 (integer; default 0)

device.sua.browsers | device.sua.platform

Attribute	Required?	Description
brand	Required	The value may be sourced from the User-Agent Client Hints headers, representing either the user agent brand (from the Sec-CH-UA-Full-Version header) or the platform brand (from the Sec-CH-UA-Platform header). (string)
version	Recommended	A sequence of version components, in descending hierarchical order [major, minor, micro, …] (array of string)

user

Attribute	Required?	Description
id	No	Unique user ID (string)
ext	No	Placeholder for exchange-specific extensions to OpenRTB (object)

user.ext

Attribute	Required?	Description
consent	No	This is the consent string required by the IAB standards. Negative consent only for now (string)

regs

Attribute	Required?	Description
ext	No	Placeholder for exchange-specific extensions to OpenRTB (object)

regs.ext

Attribute	Required?	Description
gdpr	No	This is 0 if the caller believes that the user is not under GDPR, and 1 if the user is under GDPR. If neither, this parameter will be undefined.

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.