OpenRTB Bid Requests
Last updated on January 31, 2020
The following sections provide OpenRTB bid request field reference and samples for web inventory and app inventory.
NOTE
With the enactment of the General Data Protection Regulation (GDPR), OpenX includes GDPR-specific elements in its support of OpenRTB. For more information, visit the OpenX Community.
on this page
OpenRTB Bid Request Fields for Web Inventory
The table below describes the fields that OpenX requires and strongly recommends in OpenRTB S2S integration bid requests for web inventory. The list of fields is followed by a sample publisher OpenRTB bid request.
The fields you send depend on your OpenRTB integration. If your integration does not include required or strongly recommended fields, discuss this with OpenX before beginning the integration process.
- Required fields are needed to get a response from the OpenX exchange.
- Strongly recommended fields have been proven to increase yield.
NOTE
For video, follow the requirements of the associated inventory type. For example, for desktop web video, the web inventory requirements apply.
Fields
Bid request fields for web inventory
Object | Field location | Field name | Web inventory |
---|---|---|---|
BidRequest | BidRequest.id | id | Required |
BidRequest.imp | imp | Required, but multiple Imp objects per request are not recommended. Please speak with OpenX before sending multiple Imp objects per request. See Imp object below. | |
BidRequest.site | site | Required. See Site object below. | |
BidRequest.device | device | Required. See Device object below. | |
BidRequest.user | user | Required. See User object below. | |
BidRequest.at | at | Required | |
BidRequest.tmax | tmax | Required for partners with variable timeouts and strongly recommended otherwise. | |
BidRequest.cur | cur | Strongly Recommended | |
BidRequest.source | source | Strongly Recommended | |
Regs | BidRequest.regs.coppa | coppa | Strongly Recommended |
BidRequest.regs.ext.gdpr | ext.gdpr | Required for GDPR enforcement | |
BidRequest.regs.ext.us_privacy | ext.us_privacy | Required for CCPA compliance | |
Imp | BidRequest.imp.id | id | Required |
BidRequest.imp.banner | banner | Required for banner impression opportunities | |
BidRequest.imp.video | video | Required for video impression opportunities | |
BidRequest.imp.bidfloor | bidfloor | Strongly Recommended | |
BidRequest.imp.bidfloorcur | bidfloorcur | Strongly Recommended | |
BidRequest.imp.secure | secure | Required for the support of secure traffic. | |
Banner | BidRequest.imp.banner.format | format | Strongly Recommended |
BidRequest.imp.banner.w | w | Required | |
BidRequest.imp.banner.h | h | Required | |
BidRequest.imp.banner.pos | pos | Strongly Recommended | |
Format | BidRequest.imp.banner.format.w | w | Strongly Recommended |
BidRequest.imp.banner.format.h | h | Strongly Recommended | |
Video | BidRequest.imp.video.mimes | mimes | Required |
BidRequest.imp.video.minduration | minduration | Strongly Recommended | |
BidRequest.imp.video.maxduration | maxduration | Strongly Recommended | |
BidRequest.imp.video.protocols | protocols | Strongly Recommended | |
BidRequest.imp.video.w | w | Strongly Recommended | |
BidRequest.imp.video.h | h | Strongly Recommended | |
BidRequest.imp.video.startdelay | startdelay | Strongly Recommended | |
BidRequest.imp.video.api | api | Strongly Recommended | |
BidRequest.imp.video.pos | pos | Strongly Recommended | |
Site | BidRequest.site.id | id | Required |
BidRequest.site.name | name | Strongly Recommended | |
BidRequest.site.domain | domain | Strongly Recommended | |
BidRequest.site.cat | cat | Strongly Recommended | |
BidRequest.site.page | page | Required | |
BidRequest.site.ref | ref | Strongly Recommended | |
BidRequest.site.publisher | publisher | Required. see Publisher object below. | |
Publisher | BidRequest.site.publisher.id | id | Required |
BidRequest.site.publisher.name | name | Strongly Recommended | |
BidRequest.site.publisher.cat | cat | Strongly Recommended | |
BidRequest.site.publisher.domain | domain | Strongly Recommended | |
Device | BidRequest.device.ui | ua | Required |
BidRequest.device.dnt | dnt | Strongly Recommended | |
BidRequest.device.ip | ip | Required. Note that ipv6 is also supported. | |
User | BidRequest.user.id | id | Strongly Recommended |
BidRequest.user.buyeruid | buyeruid | Strongly Recommended | |
BidRequest.user.ext.consent | ext.consent | Required for GDPR enforcement | |
Source | BidRequest.source.pchain | pchain | Strongly Recommended |
BidRequest.source.ext.schain | ext.schain | Strongly recommended for intermediaries. For more information, see SupplyChain object spec. Note: Intermediaries should also host a sellers.json file on their company’s root domain (for example, openx.com/sellers.json). For more information, see sellers.json spec. |
Sample
As a publisher, you can request an ad from the OpenX Ad Exchange via an OpenRTB bid request. See the following sample.
Bid request for web display inventory sample
{
"id": "80ce30",
"at": 1,
"tmax": 250,
"cur": ["USD"],
"source": {
"pchain": "PCHAIN"
},
"regs": {
"ext": {
"gdpr": 1
}
},
"imp": [{
"id": "1",
"secure": 1,
"bidfloor": 0.75,
"bidfloorcur": "USD",
"banner": {
"h": 250,
"w": 300,
"pos": 0,
"format": [{
"w": 300,
"h": 250
}, {
"w": 300,
"h": 600
}]
}
}],
"site": {
"id": "102855",
"name": "foobar.com",
"cat": [
"IAB3-1"
],
"domain": "www.foobar.com",
"page": "http://www.foobar.com/1234.html",
"publisher": {
"id": "8953",
"name": "foobar.com",
"cat": [
"IAB3-1"
],
"domain": "foobar.com"
}
},
"device": {
"ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/537.13 (KHTML, like Gecko) Version/5.1.7 Safari/534.57.2",
"ip": "123.145.167.10",
"dnt": 0
},
"user": {
"id": "PARTNER_ID",
"buyeruid": "OPENX_ID",
"ext": {
"consent": "[consent_string]"
}
}
}
OpenRTB Bid Request Fields for App Inventory
The table below describe the fields that OpenX requires and strongly recommends in OpenRTB S2S integration bid requests for app inventory. The list of fields is followed by a sample publisher OpenRTB bid request.
The fields you send depend on your OpenRTB integration. If your integration doesn’t include required or strongly recommended fields, please discuss this with OpenX before beginning the integration process.
- Required fields are needed to get a response from the OpenX exchange.
- Strongly recommended fields have been proven to increase yield.
NOTE
For video, follow the requirements of the associated inventory type. For example, for mobile app video, the mobile app inventory requirements apply.
Fields
Bid request fields for app inventory
Object | Field location | Field name | Mobile app inventory |
---|---|---|---|
BidRequest | BidRequest.id | id | Required |
BidRequest.imp | imp | Required. See Imp object below. | |
BidRequest.app | app | Required. See App object below. | |
BidRequest.device | device | Required. See Device object below. | |
BidRequest.user | user | Required. See User object below. | |
BidRequest.at | at | Required | |
BidRequest.tmax | tmax | Required for partners with variable timeouts and strongly recommended otherwise. | |
BidRequest.cur | cur | Strongly Recommended | |
BidRequest.source | source | Strongly Recommended | |
Regs | BidRequest.regs.coppa | coppa | Strongly Recommended |
BidRequest.regs.ext.gdpr | ext.gdpr | Required for GDPR enforcement | |
BidRequest.regs.ext.us_privacy | ext.us_privacy | Required for CCPA compliance | |
Imp | BidRequest.imp.id | id | Required |
BidRequest.imp.banner | banner | Required for banner impression opportunities | |
BidRequest.imp.video | video | Required for video impression opportunities | |
BidRequest.imp.bidfloor | bidfloor | Strongly Recommended | |
BidRequest.imp.bidfloorcur | bidfloorcur | Strongly Recommended | |
BidRequest.imp.secure | secure | Required for the support of secure traffic. | |
Banner | BidRequest.imp.banner.format | format | Strongly Recommended |
BidRequest.imp.banner.w | w | Required | |
BidRequest.imp.banner.h | h | Required | |
BidRequest.imp.banner.pos | pos | Strongly Recommended | |
Format | BidRequest.imp.banner.format.w | w | Strongly Recommended |
BidRequest.imp.banner.format.h | h | Strongly Recommended | |
Video | BidRequest.imp.video.mimes | mimes | Required |
BidRequest.imp.video.minduration | minduration | Strongly Recommended | |
BidRequest.imp.video.maxduration | maxduration | Strongly Recommended | |
BidRequest.imp.video.protocols | protocols | Strongly Recommended | |
BidRequest.imp.video.w | w | Strongly Recommended | |
BidRequest.imp.video.h | h | Strongly Recommended | |
BidRequest.imp.video.startdelay | startdelay | Strongly Recommended | |
BidRequest.imp.video.api | api | Strongly Recommended | |
BidRequest.imp.video.pos | pos | Strongly Recommended | |
App | BidRequest.app.id | id | Required |
BidRequest.app.name | name | Strongly Recommended | |
BidRequest.app.bundle | bundle | Required | |
BidRequest.app.domain | domain | Strongly Recommended | |
BidRequest.app.storeurl | storeurl | Required | |
BidRequest.app.cat | cat | Strongly Recommended | |
BidRequest.app.publisher | publisher | Strongly Recommended. See Publisher object below. | |
Publisher | BidRequest.app.publisher.id | id | Strongly Recommended |
BidRequest.app.publisher.name | name | Strongly Recommended | |
BidRequest.app.publisher.cat | cat | Strongly Recommended | |
Device | BidRequest.device.ua | ua | Required |
BidRequest.device.geo | geo | Strongly Recommended. See Geo object below. | |
BidRequest.device.dnt | dnt | Strongly Recommended | |
BidRequest.device.lmt | lmt | Strongly Recommended | |
BidRequest.device.ip | ip | Required. Note that ipv6 is also supported. | |
BidRequest.device.ifa | ifa | Strongly Recommended | |
User | BidRequest.user.geo | geo | Strongly Recommended if available. See Geo object below. |
BidRequest.user.ext.consent | ext.consent | Required for GDPR enforcement | |
Geo | BidRequest.device.geo.lat | lat | Strongly Recommended |
BidRequest.device.geo.lon | lon | Strongly Recommended | |
BidRequest.device.geo.type | type | Strongly Recommended | |
Source | BidRequest.source.pchain | pchain | Strongly Recommended |
BidRequest.source.ext.schain | ext.schain | Strongly recommended for intermediaries. For more information, see SupplyChain object spec. Note: Intermediaries should also host a sellers.json file on their company’s root domain (for example, openx.com/sellers.json). For more information, see sellers.json spec. |
Sample
As a publisher, you can request an ad from the OpenX Ad Exchange via an OpenRTB bid request. See the following sample.
Bid request for app display inventory sample
{
"id": "afVbta4q5tLDOzB2eP1IoQ",
"at": 1,
"tmax": 250,
"cur": ["USD"],
"regs": {
"coppa": 0,
"ext": {
"gdpr": 1
}
},
"source": {
"pchain": "PCHAIN"
},
"imp": [{
"secure": 1,
"id": "1",
"bidfloorcur": "USD",
"bidfloor": 0.01,
"banner": {
"h": 50,
"w": 320,
"pos": 0,
"api": [3, 5],
"format": [{
"w": 320,
"h": 50
}, {
"w": 300,
"h": 250
}]
}
}],
"device": {
"dnt": 0,
"ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 10_3_3 like Mac OS X) AppleWebKit/603.3.8 (KHTML, like Gecko) Mobile/14G60",
"ip": "123.145.167.10",
"ifa": "AA000DFE74168477C70D291f574D344790E0BB11",
"lmt": 0,
"geo": {
"lat": 35.012345,
"lon": -115.12345,
"type": 1
}
},
"app": {
"publisher": {
"id": "8953",
"name": "foobar.com",
"cat": [
"IAB3-1"
]
},
"name": "Foo App",
"domain": "foobar.com",
"storeurl": "https://itunes.apple.com/id123456789",
"cat": [
"IAB3-1"
],
"bundle": "123456789",
"id": "1122334455",
"user": {
"id": "PARTNER_ID",
"buyeruid": "OPENX_ID",
"ext": {
"consent": "[consent_string]"
}
}
}
}
NOTE
To learn more about these fields, refer to IAB’s OpenRTB 2.5 specification.