Open RTB 2.5 Bid Request
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
- Data Encoding Header: Accept-Encoding
Bid Request 2.5
When requesting bids for a specific context, the platform will perform an HTTP request with a timeout of 300ms and send the following object encoded as JSON in the request body. HTTP is recommended due to extra latency when using HTTPS.
| Attribute | Description |
|---|---|
| id | Unique bid request ID (string) |
| site | Details via a Site object about the publisher’s website (object) |
| device | Details via a Device object about the user’s device to which the impression will be delivered (object) |
| user | Details via a User object about the human user of the device; the advertising audience (object) |
| imp | Details via an Imp object about the ad placement or impression being auctioned (object) |
| ext | Placeholder for extensions to OpenRTB (object) |
site
| Attribute | Description |
|---|---|
| id | Unique Site ID (string) |
| domain | Domain name of the site (string) |
| cat | IAB category ID (string array) |
| page | Full URL of the page where the ad will be shown (string) |
| keywords | Keywords can be used to ensure ad zones get the right type of advertising. Keywords should be a string of comma-separated words |
| ext | Placeholder for exchange-specific extensions (object) |
site.ext
| Attribute | Description |
|---|---|
| exchangecat | Custom EXADS category ID (integer) |
| idzone | Custom EXADS Ad Zone ID (integer) |
| keyword | Matching keyword if any (string) |
device
| Attribute | Description |
|---|---|
| ua | Browser user agent (string) |
| sua | Structured user agent information, which can be used when a client supports User-Agent Client Hints (object) |
| geo | Location of the device assumed to be the user’s current location defined by a Geo object |
| ip | IPv4 address of the user (string)* |
| ipv6 | IPv6 address of the user (string)* |
| language | Browser language (string) |
| os | Operating System (string) |
| js | Support for JavaScript, where 0 = no, 1 = yes (integer) |
| ext | Placeholder for exchange-specific extensions to OpenRTB (object) |
*Condition: Exactly one of ip or ipv6 will be present in the bid request.
device.geo
| Attribute | Description |
|---|---|
| country | Country ISO3 |
| ipservice | Service or provider used to determine geolocation from IP address if applicable (integer) |
device.ext
| Attribute | Description |
|---|---|
| remote_addr | Main IP address of the user (string) |
| x_forwarded_for | X-FORWARDED-FOR IP address of the user or empty if not set (string) |
device.sua
Structured User Agent information. Once provided device.sua is considered the more accurate representation of
the device attributes.
| Attribute | Description |
|---|---|
| browsers | Send brands and versions derived from the Sec-CH-UA-Full-Version-List header. (Array of BrandVersion objects) |
| platform | 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 | Derive this value from the Sec-CH-UA-Mobile header. (integer) |
| architecture | Retrieve this value from the Sec-CH-UA-Arch header. (string) |
| bitness | Retrieve this value from the Sec-CH-UA-Bitness header. (string) |
| model | Retrieve this value from the Sec-CH-UA-Model header. (string) |
| source | The source of data used to create this object, List: User-Agent Source in AdCOM 1.0 (integer; default 0) |
device.sua.browsers.BrandVersion | device.sua.platform.BrandVersion
| Attribute | Description |
|---|---|
| brand | 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 | A sequence of version components, in descending hierarchical order [major, minor, micro, …] (array of string) |
user
| Attribute | Description |
|---|---|
| id | Unique user ID (string) |
user.ext
| Attribute | Description |
|---|---|
| consent | user.ext.consent: This is the consent string required by the IAB standards. Negative consent only for now (string) |
regs.ext
| Attribute | Description |
|---|---|
| gdpr | regs.ext.gdpr: 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. |
imp
| Attribute | Description |
|---|---|
| id | A unique identifier for this impression within the context of the bid request (string) |
| native | A Native object ; required if this impression is offered as a native ad opportunity (object) |
| instl | 1 = the ad is interstitial or full screen, 0 = not interstitial (integer) |
| video | Details via Video object that represents an in-stream video impression |
| secure | Flag to indicate if the impression requires secure HTTPS URL (integer) |
| ext | Placeholder for exchange-specific extensions to OpenRTB (object) |
imp.video
| Attribute | Description |
|---|---|
| mimes | Content MIME types supported (e.g., "video/mp4") (string array ) |
| minduration | Minimum video ad duration in seconds (integer) |
| maxduration | Maximum video ad duration in seconds (integer) |
| protocols | Array of supported video protocols (integer) |
| linearity | Indicates if the impression must be linear, nonlinear, etc. If none specified, assume all are allowed (integer) |
| boxingallowed | Indicates if letter-boxing of 4:3 content into a 16:9 window is allowed, where 0 = no, 1 = yes (integer) |
| pos | Ad position on screen (integer) |
| h | Width of the video player in device independent pixels (DIPS) (integer) |
| w | Height of the video player in device independent pixels (DIPS) (integer) |
| ext | Placeholder for exchange-specific extensions to OpenRTB (object) |
imp.video.ext
| Attribute | Description |
|---|---|
| zone_type | Zone type (e.g exchange_video_slider) |
imp.full-page-interstitial
| 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.instl
| Attribute | Description |
|---|---|
| instl | Flag specifying if ad is popunder/interstitial (integer): 1=true, 0=false |
imp.native (Native & Push Notifications)
| Attribute | Description |
|---|---|
| request | 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 | Version of the Dynamic Native Ads API to which request complies (string) |
imp.native.request
| Attribute | Description |
|---|---|
| ver | Version of the Native Markup version in use (string) |
| context | 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 | The design/format/layout of the ad unit being offered. Currently we support 4 (Recommendation widget) and 500 (Push Notification) (integer) |
| plcmtcnt | The number of identical placements in this Layout (integer) |
| assets | 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 | 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 | Description |
|---|---|
| id | Unique asset ID, assigned by exchange. Typically a counter for the array (integer) |
| required | Set to 1 if asset is required or 0 if asset is optional** (integer) |
| plcmtcnt | The number of identical placements in this Layout (integer) |
| img | Image object for image assets* (JSON object) |
| title | Title object for title assets* (JSON object) |
| data | Data object for brand name, description, ratings, prices etc.* (JSON object) |
| video | 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
** Assets are flagged as required according to the configuration of the publisher zone where your ad may be displayed
imp.native.request.assets.img
| Attribute | Description |
|---|---|
| type | 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 | Width of the image in pixels, optional (integer) |
| h | Height of the image in pixels, optional (integer) |
| wmin | The minimum requested width of the image in pixels (integer) |
| hmin | The minimum requested height of the image in pixels (integer) |
imp.native.request.assets.title
| Attribute | Description |
|---|---|
| len | Maximum length of the text in the title element. (integer) |
imp.native.request.assets.data
| Attribute | Description |
|---|---|
| type | 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 | Maximum length of the text in the element’s response (integer) |
imp.native.request.assets.video
| Attribute | Description |
|---|---|
| mimes | List of supported mime types (string array) |
| minduration | Minimum video ad duration in seconds(int). |
| maxduration | Maximum video ad duration in seconds(int). |
| protocols | List of supported video bid response protocols (int array) |
| linearity | Indicates if the impression must be linear, nonlinear, etc. (int) |
| boxingallowed | Indicates if letter-boxing of 4:3 content into a 16:9 window is allowed (int) |
Examples
Video (Stored Request)
{
"id": "b7da78ea-cce3-4524-a806-26ca48dd1857",
"site": {
"domain": "privesexopname.nl",
"page": "https://sitedomain.com/page",
"id": "718990",
"keywords": "lifestyle,humour",
"cat": [
"IAB25-3"
],
"ext": {
"exchangecat": 508,
"idzone": 4998567,
"keyword": "%"
},
"publisher": {
"id": "195600"
}
},
"device": {
"ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/95.0.4638.54 Safari/537.36",
"sua": {
"architecture": "x86",
"bitness": "64",
"model": "Windows",
"mobile": 0,
"source": 2,
"platform": {
"brand": "Windows",
"version": [
"10",
"0",
"0"
]
},
"browsers": [
{
"brand": "Chromium",
"version": [
"136",
"0",
"7103",
"93"
]
},
{
"brand": "Microsoft Edge",
"version": [
"136",
"0",
"3240",
"64"
]
},
{
"brand": "Not.A\/Brand",
"version": [
"99",
"0",
"0",
"0"
]
}
]
},
"ip": "131.34.123.159",
"geo": {
"country": "IRL",
"ipservice": "3"
},
"language": "en",
"os": "MacOS",
"js": 1,
"ext": {
"remote_addr": "131.34.123.159",
"x_forwarded_for": ""
}
},
"imp": [
{
"id": "568094473",
"video": {
"mimes": [
"video/mp4"
],
"minduration": "1",
"maxduration": "7200",
"ext": {
"zone_type": "exchange_video_slider"
},
"protocols": "3,6",
"linearity": "1",
"boxingallowed": "1",
"pos": "0"
},
"instl": "0",
"ext": {
"video_cta": "1",
"type": "video"
},
"secure": "0"
}
],
"user": {
"id": "57592f333f8983.043587162282415065"
},
"tmax": 300
}
You can find more examples here.
Video Bid Request Structure
Email Clicks
{
"id": "d4b5c697-41f3-4c1c-a3d5-5fd01b5ef2aa",
"imp": [
{
"id": "974090632",
"instl": 0,
"el": "dGVzdGVAZW1haWwuY29t"
}
],
"site": {
"id": "12345",
"domain": "sitedomain.com",
"cat": ["IAB25-3"],
"page": "https://sitedomain.com/page",
"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": 445566
}
}
Email Clicks Bid Request Structure
Direct Links
{
"id": "d4b5c697-41f3-4c1c-a3d5-5fd01b5ef2aa",
"imp": [
{
"id": "974090632",
"instl": 0,
"el": "dGVzdGVAZW1haWwuY29t"
}
],
"site": {
"id": "12345",
"domain": "sitedomain.com",
"cat": ["IAB25-3"],
"page": "https://sitedomain.com/page",
"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": 445566
}
}
Direct Links Bid Request Structure
Fullpage Interstitial Desktop
{
"id": "d4b5c697-41f3-4c1c-a3d5-5fd01b5ef2aa",
"at":1,
"imp": [
{
"id": "974090632",
"instl": 1,
"banner": {
"w": 1600,
"h": 900,
"mimes": [
"image/jpg",
"image/png",
"video/mp4",
"image/webp"
]
}
}
],
"site": {
"id": "12345",
"domain": "sitedomain.com",
"name": "site domain",
"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": "PRT"
},
"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
}
}
Fullpage Interstitial Mobile
{
"id": "d4b5c697-41f3-4c1c-a3d5-5fd01b5ef2aa",
"at":1,
"imp": [
{
"id": "974090632",
"instl": 1,
"banner": {
"w": 900,
"h": 1600,
"mimes": [
"image/jpg",
"image/png",
"video/mp4",
"image/webp"
]
}
}
],
"site": {
"id": "12345",
"domain": "sitedomain.com",
"name": "site domain",
"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": "PRT"
},
"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
}
}
Fullpage Interstitial (Mobile and Desktop) Bid Request Structure
Push Notifications - 720 x 480
{
"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\":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"
},
"secure": 1
}
],
"site": {
"id": "12345",
"domain": "sitedomain.com",
"cat": ["IAB25-3"],
"page": "https://sitedomain.com/page",
"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": "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": 445566
}
}
Push Notifications 720x480 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
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"
},
"secure": 1
}
],
"site": {
"id": "12345",
"domain": "sitedomain.com",
"cat": ["IAB25-3"],
"page": "https://sitedomain.com/page",
"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": "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": 445566
}
}
Push Notifications - 192 x 192 Bid Request Structure