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)
bcat	No	Blocked advertiser categories using the IAB content categories (string array)
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)
skip	Indicates if the player will allow the video to be skipped, where 0 = no, 1 = yes
skipafter	Number of seconds a video must play before skipping is enabled; only applicable if the ad is skippable
skipmin	Videos of total duration greater than this number of seconds can be skippable; only applicable if the ad is skippable

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)
pagecat	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
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 EXADS category ID (integer)
idzone	No	Custom EXADS Ad Zone ID (integer)

app

Attribute	Required?	Description
id	Required	Unique App ID (string)
cat	No	IAB category ID (string array)
pagecat	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",
        "pagecat": ["IAB25-3"]
    },
    "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
    }
}

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",
        "pagecat": ["IAB25-3"],
        "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

imp
- imp.instl
site
- site.ext
device
- device.geo
- device.ext
user

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",
        "pagecat": ["IAB25-3"],
        "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

imp
- imp.instl
site
- site.ext
device
- device.geo
- device.ext
user

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",
        "pagecat": ["IAB25-3"],
        "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

imp
- imp.instl
site
- site.ext
device
- device.geo
- device.ext
user

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

imp
- imp.native
  - imp.native.request
    - imp.native.request.assets
site
site.ext
device
- device.geo
- device.ext
user

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",
        "pagecat": ["IAB25-3"]
    },
    "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

imp
- imp.instl
site
- site.ext
device
- device.geo
- device.ext
user

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",
        "pagecat": ["IAB25-3"]
    },
    "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

imp
- imp.native
  - imp.native.request
    - imp.native.request.assets
site
- site.ext
device
- device.geo
- device.ext
user

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",
        "pagecat": ["IAB25-3"]
    },
    "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

imp
- imp.native
  - imp.native.request
    - imp.native.request.assets
site
- site.ext
device
- device.geo
- device.ext
user

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",
        "pagecat": ["IAB25-3"]
    },
    "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
    }
}