Link Search Menu Expand Document

PDF

OpenRTB Bid Requests

Publishers

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
ObjectField locationField nameWeb inventory
BidRequestBidRequest.ididRequired
 BidRequest.impimpRequired, 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.sitesiteRequired. See Site object below.
 BidRequest.devicedeviceRequired. See Device object below.
 BidRequest.useruserRequired. See User object below.
 BidRequest.atatRequired
 BidRequest.tmaxtmaxRequired for partners with variable timeouts and strongly recommended otherwise.
 BidRequest.curcurStrongly Recommended
 BidRequest.sourcesourceStrongly Recommended
RegsBidRequest.regs.coppacoppaStrongly Recommended
 BidRequest.regs.ext.gdprext.gdprRequired for GDPR enforcement
 BidRequest.regs.ext.us_privacyext.us_privacyRequired for CCPA compliance
ImpBidRequest.imp.ididRequired
 BidRequest.imp.bannerbannerRequired for banner impression opportunities
 BidRequest.imp.videovideoRequired for video impression opportunities
 BidRequest.imp.bidfloorbidfloorStrongly Recommended
 BidRequest.imp.bidfloorcurbidfloorcurStrongly Recommended
 BidRequest.imp.securesecureRequired for the support of secure traffic.
BannerBidRequest.imp.banner.formatformatStrongly Recommended
 BidRequest.imp.banner.wwRequired
 BidRequest.imp.banner.hhRequired
 BidRequest.imp.banner.posposStrongly Recommended
FormatBidRequest.imp.banner.format.wwStrongly Recommended
 BidRequest.imp.banner.format.hhStrongly Recommended
VideoBidRequest.imp.video.mimesmimesRequired
 BidRequest.imp.video.mindurationmindurationStrongly Recommended
 BidRequest.imp.video.maxdurationmaxdurationStrongly Recommended
 BidRequest.imp.video.protocolsprotocolsStrongly Recommended
 BidRequest.imp.video.wwStrongly Recommended
 BidRequest.imp.video.hhStrongly Recommended
 BidRequest.imp.video.startdelaystartdelayStrongly Recommended
 BidRequest.imp.video.apiapiStrongly Recommended
 BidRequest.imp.video.posposStrongly Recommended
SiteBidRequest.site.ididRequired
 BidRequest.site.namenameStrongly Recommended
 BidRequest.site.domaindomainStrongly Recommended
 BidRequest.site.catcatStrongly Recommended
 BidRequest.site.pagepageRequired
 BidRequest.site.refrefStrongly Recommended
 BidRequest.site.publisherpublisherRequired. see Publisher object below.
PublisherBidRequest.site.publisher.ididRequired
 BidRequest.site.publisher.namenameStrongly Recommended
 BidRequest.site.publisher.catcatStrongly Recommended
 BidRequest.site.publisher.domaindomainStrongly Recommended
DeviceBidRequest.device.uiuaRequired
 BidRequest.device.dntdntStrongly Recommended
 BidRequest.device.ipipRequired. Note that ipv6 is also supported.
UserBidRequest.user.ididStrongly Recommended
 BidRequest.user.buyeruidbuyeruidStrongly Recommended
 BidRequest.user.ext.consentext.consentRequired for GDPR enforcement
SourceBidRequest.source.pchainpchainStrongly Recommended
 BidRequest.source.ext.schainext.schainStrongly 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
ObjectField locationField nameMobile app inventory
BidRequestBidRequest.ididRequired
 BidRequest.impimpRequired. See Imp object below.
 BidRequest.appappRequired. See App object below.
 BidRequest.devicedeviceRequired. See Device object below.
 BidRequest.useruserRequired. See User object below.
 BidRequest.atatRequired
 BidRequest.tmaxtmaxRequired for partners with variable timeouts and strongly recommended otherwise.
 BidRequest.curcurStrongly Recommended
 BidRequest.sourcesourceStrongly Recommended
RegsBidRequest.regs.coppacoppaStrongly Recommended
 BidRequest.regs.ext.gdprext.gdprRequired for GDPR enforcement
 BidRequest.regs.ext.us_privacyext.us_privacyRequired for CCPA compliance
ImpBidRequest.imp.ididRequired
 BidRequest.imp.bannerbannerRequired for banner impression opportunities
 BidRequest.imp.videovideoRequired for video impression opportunities
 BidRequest.imp.bidfloorbidfloorStrongly Recommended
 BidRequest.imp.bidfloorcurbidfloorcurStrongly Recommended
 BidRequest.imp.securesecureRequired for the support of secure traffic.
BannerBidRequest.imp.banner.formatformatStrongly Recommended
 BidRequest.imp.banner.wwRequired
 BidRequest.imp.banner.hhRequired
 BidRequest.imp.banner.posposStrongly Recommended
FormatBidRequest.imp.banner.format.wwStrongly Recommended
 BidRequest.imp.banner.format.hhStrongly Recommended
VideoBidRequest.imp.video.mimesmimesRequired
 BidRequest.imp.video.mindurationmindurationStrongly Recommended
 BidRequest.imp.video.maxdurationmaxdurationStrongly Recommended
 BidRequest.imp.video.protocolsprotocolsStrongly Recommended
 BidRequest.imp.video.wwStrongly Recommended
 BidRequest.imp.video.hhStrongly Recommended
 BidRequest.imp.video.startdelaystartdelayStrongly Recommended
 BidRequest.imp.video.apiapiStrongly Recommended
 BidRequest.imp.video.posposStrongly Recommended
AppBidRequest.app.ididRequired
 BidRequest.app.namenameStrongly Recommended
 BidRequest.app.bundlebundleRequired
 BidRequest.app.domaindomainStrongly Recommended
 BidRequest.app.storeurlstoreurlRequired
 BidRequest.app.catcatStrongly Recommended
 BidRequest.app.publisherpublisherStrongly Recommended. See Publisher object below.
PublisherBidRequest.app.publisher.ididStrongly Recommended
 BidRequest.app.publisher.namenameStrongly Recommended
 BidRequest.app.publisher.catcatStrongly Recommended
DeviceBidRequest.device.uauaRequired
 BidRequest.device.geogeoStrongly Recommended. See Geo object below.
 BidRequest.device.dntdntStrongly Recommended
 BidRequest.device.lmtlmtStrongly Recommended
 BidRequest.device.ipipRequired. Note that ipv6 is also supported.
 BidRequest.device.ifaifaStrongly Recommended
UserBidRequest.user.geogeoStrongly Recommended if available. See Geo object below.
 BidRequest.user.ext.consentext.consentRequired for GDPR enforcement
GeoBidRequest.device.geo.latlatStrongly Recommended
 BidRequest.device.geo.lonlonStrongly Recommended
 BidRequest.device.geo.typetypeStrongly Recommended
SourceBidRequest.source.pchainpchainStrongly Recommended
 BidRequest.source.ext.schainext.schainStrongly 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.