Open RTB Bid Request Specifications
Suggested 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 |
Note: *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, optional (float) |
bidfloorcur | No | Currency for minimum bid value specified using ISO-4217 alpha codes, optional (string) |
native | Only for native imps | A Native object ; required if this impression is offered as a native ad opportunity (object) |
banner | Only for banner imps | A banner object ; required if this impression is offered as a banner ad opportunity (object) |
instl | Only for instl imps | An interstitial object ; required if this impression is offered as an interstitial ad opportunity (object) |
video | Only for video | A Video object; required if this impression is offered as a video ad opportunity (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) |
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 | Flag specifying if ad is popunder (integer) |
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 (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) |
video | No | Video 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
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.native.request.assets.video
Attribute | Required? | Description |
---|---|---|
mimes | Yes | List of supported mime types (string array) |
minduration | Yes | Minimum video ad duration in seconds(int). |
maxduration | Yes | Maximum video ad duration in seconds(int). |
protocols | Yes | List of supported video bid response protocols (int array) |
linearity | Required for in-stream ads only. | Indicates if the impression must be linear, nonlinear, etc. (int) |
boxingallowed | Required for in-stream ads only. | Indicates if letter-boxing of 4:3 content into a 16:9 window is allowed (int) |
imp.video
Attribute | Description |
---|---|
mimes | List of supported mime types (string array) |
protocols | List of supported video bid response protocols (int array) |
imp.ext
Attribute | Required? | Description |
---|---|---|
video_cta | No | Indicates if CTAs should be provided* |
* When enabled, CTA should be provided as part of VAST Tag here.
site
Attribute | Required? | Description |
---|---|---|
id | Recommended | Unique Site ID (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 |
ext | No | Placeholder for exchange-specific extensions |
Note: Only one of the objects {site, app} should be present in each request.
site.ext
Attribute | Required? | Description |
---|---|---|
exchangecat | No | Custom Adnation category ID (integer) |
idzone | No | Custom Adnation 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) |
Note: Only one of the objects {site, app} should be present in each request.
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 |
*Either ip or ipv6 will be in the request
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) |
Note: If you cannot generate a user ID, 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 six and ten digits: Do not use zeroes at the beginning of Sub IDs. |
Examples
Banner
{
"id": "d4b5c697-41f3-4c1c-a3d5-5fd01b5ef2aa",
"at":1,
"imp": [
{
"id": "974090632",
"banner": {
"w": 300,
"h": 250,
"mimes": [
"image/jpg",
"image/png",
"video/mp4",
"image/webp"
],
"ext": {
"image_output": "xml",
"video_output": "xml"
}
}
}
],
"site": {
"id": "12345",
"domain": "sitedomain.com",
"cat": ["IAB25-3"],
"page": "https://sitedomain.com/page",
"keywords": "lifestyle, humour"
},
"device": {
"ua": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.63 Safari/537.36",
"ip": "131.34.123.159",
"geo": {
"country": "IRL"
},
"language": "en",
"os": "Linux & UNIX",
"js": 0,
"ext": {
"remote_addr": "131.34.123.159",
"x_forwarded_for": "",
"accept_language": "en-GB;q=0.8,pt-PT;q=0.6,en;q=0.4,en-US;q=0.2,de;q=0.2,es;q=0.2,fr;q=0.2"
}
},
"user": {
"id": "57592f333f8983.043587162282415065"
},
"ext": {
"sub": 1221
}
}
Banner Bid Request Structure
Direct Links
JSON
{
"id": "d4b5c697-41f3-4c1c-a3d5-5fd01b5ef2aa",
"imp": [
{
"id": "974090632",
"instl": 0,
"el": "dGVzdGVAZW1haWwuY29t",
"bidfloor": 0.035,
"bidfloorcur": "EUR"
}
],
"site": {
"id": "12345",
"domain": "sitedomain.com",
"cat": ["IAB25-3"],
"page": "https://sitedomain.com/page",
"keywords": "lifestyle, humour",
"ext": {
"exchangecat": 508,
"idzone": 445566
}
},
"device": {
"ua": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.63 Safari/537.36",
"ip": "192.168.1.70",
"geo": {
"country": "PRT"
},
"language": "en",
"os": "Linux & UNIX",
"js": 0,
"ext": {
"remote_addr": "192.168.1.70",
"x_forwarded_for": "192.168.1.70"
}
},
"user": {
"id": "57592f333f8983.043587162282415065"
},
"ext": {
"sub": 1221
}
}
Direct Links Bid Request Structure
Email Clicks
JSON
{
"id": "d4b5c697-41f3-4c1c-a3d5-5fd01b5ef2aa",
"imp": [
{
"id": "974090632",
"instl": 0,
"el": "dGVzdGVAZW1haWwuY29t",
"bidfloor": 0.035,
"bidfloorcur": "EUR"
}
],
"site": {
"id": "12345",
"domain": "sitedomain.com",
"cat": ["IAB25-3"],
"page": "https://sitedomain.com/page",
"keywords": "lifestyle, humour",
"ext": {
"exchangecat": 508,
"idzone": 445566
}
},
"device": {
"ua": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.63 Safari/537.36",
"ip": "192.168.1.70",
"geo": {
"country": "PRT"
},
"language": "en",
"os": "Linux & UNIX",
"js": 0,
"ext": {
"remote_addr": "192.168.1.70",
"x_forwarded_for": "192.168.1.70"
}
},
"user": {
"id": "57592f333f8983.043587162282415065"
},
"ext": {
"sub": 1221
}
}
Email Clicks Bid Request Structure
In-Stream Video, Outstream Video, Video Slider
{
"id": "d4b5c697-41f3-4c1c-a3d5-5fd01b5ef2aa",
"imp": [
{
"id": "974090632",
"video": {
"mimes": ["video/mp4"],
"protocols": [
3,
6
]
},
"ext": {
"video_cta": 0
}
}
],
"site": {
"id": "12345",
"domain": "sitedomain.com",
"cat": ["IAB25-3"],
"page": "https://sitedomain.com/page",
"keywords": "lifestyle, humour",
"ext": {
"exchangecat": 508,
"idzone": 445566
}
},
"device": {
"ua": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.63 Safari/537.36",
"ip": "192.168.1.70",
"geo": {
"country": "PRT"
},
"language": "en",
"os": "Linux & UNIX",
"js": 0,
"ext": {
"remote_addr": "192.168.1.70",
"x_forwarded_for": "192.168.1.70"
}
},
"user": {
"id": "57592f333f8983.043587162282415065"
},
"ext": {
"sub": 1221
}
}
In-Stream Video, Outstream Video, Video Slider Bid Request Structure
Native
{
"id": "7a452540-c8c9-43ca-9d30-ab9d8bfd17a4",
"at":1,
"imp": [
{
"id": "2d099176-9feb-44e9-85f9-f385b34123a1",
"native": {
"request": "{\"native\":{\"ver\":\"1.2\"\n,\"context\":1\n,\"contextsubtype\":10\n,\"plcmttype\":4\n,\"plcmtcnt\":4\n,\"assets\":[{\"id\":1,\"required\":1,\"title\":{\"len\":124}},{\"id\":2,\"data\":{\"type\":1,\"len\":50}},{\"id\":3,\"required\":1,\"img\":{\"type\":3,\"wmin\":150,\"hmin\":150}}]\n}}",
"ver": "1.2"
},
"tagid": "2812",
"bidfloor": 0.035,
"secure": 1
}
],
"site": {
"id": "2812",
"domain": "example.com",
"keywords": "lifestyle, humour",
"page": "https://example.com/",
"mobile": 1
},
"device": {
"ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 11_4_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15G77 Version/11.4.1 Safari/604.1 AlohaBrowser/2.10.0b17",
"ip": "88.208.2.198",
"js": 1,
"language": "en"
},
"user": {
"id": "37d1951a-7184-4b7f-b227-5571a1ea7467"
}
}
Native Bid Request Structure
Popunder
{
"id": "d4b5c697-41f3-4c1c-a3d5-5fd01b5ef2aa",
"at":1,
"imp": [
{
"id": "974090632",
"instl": 1
}
],
"site": {
"id": "12345",
"domain": "sitedomain.com",
"cat": ["IAB25-3"],
"page": "https://sitedomain.com/page",
"keywords": "lifestyle, humour"
},
"device": {
"ua": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.63 Safari/537.36",
"ip": "120.52.73.97",
"geo": {
"country": "IRL"
},
"language": "en",
"os": "Linux & UNIX",
"js": 0,
"ext": {
"remote_addr": "131.34.123.159",
"x_forwarded_for": "120.52.73.97"
}
},
"user": {
"id": "57592f333f8983.043587162282415065"
},
"ext": {
"sub": 1221
}
}
Popunder Bid Request Structure
Push Notifications - 720 x 480
{
"id": "d4b5c697-41f3-4c1c-a3d5-5fd01b5ef2aa",
"imp": [
{
"id": "90180978",
"native": {
"request":"{\"native\":{\"ver\":\"1.2\",\"plcmttype\":500,\"plcmtcnt\":1,\"assets\":[{\"id\":1,\"required\":1,\"img\":{\"type\":1,\"w\":720,\"h\":480,\"wmin\":720,\"hmin\":480}},{\"id\":2,\"required\":1,\"title\":{\"len\":60}},{\"id\":3,\"required\":1,\"data\":{\"type\":2,\"len\":110}}]}}",
"ver": "1.2"
}
}
],
"site": {
"id": "12345",
"domain": "sitedomain.com",
"cat": ["IAB25-3"],
"page": "https://sitedomain.com/page",
"keywords": "lifestyle, humour"
},
"device": {
"ua": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.63 Safari/537.36",
"ip": "131.34.123.159",
"geo": {
"country": "IRL"
},
"language": "en",
"os": "Linux & UNIX",
"js": 0,
"ext": {
"remote_addr": "131.34.123.159",
"x_forwarded_for": "",
"accept_language": "en-GB;q=0.8,pt-PT;q=0.6,en;q=0.4,en-US;q=0.2,de;q=0.2,es;q=0.2,fr;q=0.2"
}
},
"user": {
"id": "57592f333f8983.043587162282415065"
},
"ext": {
"sub": 1221
}
}
Push Notifications - 720 x 480 Bid Request Structure
Push Notifications - 192 x 192
{
"id": "d4b5c697-41f3-4c1c-a3d5-5fd01b5ef2aa",
"at":1,
"imp": [
{
"id": "90180978",
"native": {
"request":"{\"native\":{\"ver\":\"1.2\",\"plcmttype\":500,\"plcmtcnt\":1,\"assets\":[{\"id\":1,\"required\":1,\"img\":{\"type\":1,\"w\":192,\"h\":192,\"wmin\":192,\"hmin\":192}},{\"id\":2,\"required\":1,\"title\":{\"len\":60}},{\"id\":3,\"required\":1,\"data\":{\"type\":2,\"len\":110}}]}}",
"ver": "1.2"
}
}
],
"site": {
"id": "12345",
"domain": "sitedomain.com",
"cat": ["IAB25-3"],
"page": "https://sitedomain.com/page",
"keywords": "lifestyle, humour"
},
"device": {
"ua": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.63 Safari/537.36",
"ip": "131.34.123.159",
"geo": {
"country": "IRL"
},
"language": "en",
"os": "Linux & UNIX",
"js": 0,
"ext": {
"remote_addr": "131.34.123.159",
"x_forwarded_for": "",
"accept_language": "en-GB;q=0.8,pt-PT;q=0.6,en;q=0.4,en-US;q=0.2,de;q=0.2,es;q=0.2,fr;q=0.2"
}
},
"user": {
"id": "57592f333f8983.043587162282415065"
},
"ext": {
"sub": 1221
}
}
Push Notifications 192 x 192 Bid Request Structure
In-Page Push Notifications
{
"id": "d4b5c697-41f3-4c1c-a3d5-5fd01b5ef2aa",
"imp": [
{
"id": "90180978",
"native": {
"request":"{\"native\":{\"ver\":\"1.2\",\"plcmttype\":501,\"plcmtcnt\":1,\"assets\":[{\"id\":1,\"required\":1,\"img\":{\"type\":1}},{\"id\":2,\"required\":1,\"title\":{\"len\":60}},{\"id\":3,\"required\":1,\"data\":{\"type\":2,\"len\":110}}]}}",
"ver": "1.2"
}
}
],
"site": {
"id": "12345",
"domain": "sitedomain.com",
"cat": ["IAB25-3"],
"page": "https://sitedomain.com/page",
"keywords": "lifestyle, humour"
},
"device": {
"ua": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.63 Safari/537.36",
"ip": "131.34.123.159",
"geo": {
"country": "IRL"
},
"language": "en",
"os": "Linux & UNIX",
"js": 0,
"ext": {
"remote_addr": "131.34.123.159",
"x_forwarded_for": "",
"accept_language": "en-GB;q=0.8,pt-PT;q=0.6,en;q=0.4,en-US;q=0.2,de;q=0.2,es;q=0.2,fr;q=0.2"
}
},
"user": {
"id": "57592f333f8983.043587162282415065"
},
"ext": {
"sub": 1221
}
}