OpenRTB Bid Response Objects and Parameters

Document created by catherine.racette on Sep 3, 2017Last modified by catherine.racette on Sep 3, 2017
Version 9Show Document
  • View in full screen mode

OpenRTB 2.3 Documentation 

OpenRTB 2.3 Introduction 

OpenRTB 2.3 Integration Plan 

OpenRTB Bid Request Objects and Parameters 

OpenRTB Bid Response Objects and Parameters 

OpenRTB 2.3 PubMatic Extensions 

Open RTB 2.3 Examples 

OpenRTB Ad Server API Cookie Sync 

OpenRTB 2.3 Click Tracking 

OpenRTB 2.3 Win/Loss Notification 

OpenRTB 2.3 API Performance 

OpenRTB 2.3 Known Limitations & Reference 

PubMatic supports Ad Serving integration using OpenRTB 2.3, as well as a proprietary API. This document covers the OpenRTB Ad Serving integration.

PubMatic Response Objects and Parameters Supported

 

For a valid request, PubMatic will send back response in OpenRTB standard with 200 OK. All fields, which can be sent by PubMatic, are listed in tables below. If the wrong request is served, if a mandatory parameter is missing or if PubMatic finds no creative, it will return back 204 no content.

 

PubMatic supports either adm or nurl for video, which can be configured upon request.

Object: BidResponse

                                 

AttributeTypeDescriptionSupported
idStringID of the bid request to which this is a response.Yes
seatbidObjectArray of seatbid objects; 1+ required if a bid is to be madeYes
bidid StringBidder generated response ID to assist with logging/tracking.Yes
curStringBid currency using ISO-4217 alpha codes.Yes

Object: SeatBid

                     

AttributeTypeDescriptionSupported
bidObjectArray required Array of 1+ Bid objects each related to an impression. Multiple bids can relate to the same impression.Yes
seatStringID of the bidder seat on whose behalf this bid is made.Yes

Object: Bid

                                                                                 

AttributeTypeDescriptionSupported
idStringBidder generated bid ID to assist with logging/tracking.Yes
impidStringID of the Imp object in the related bid request.Yes
priceStringBid price expressed as CPM although the actual transaction is for a unit impression only.Yes
cidStringCampaign ID to assist with ad quality checking; the collection of creatives for which iurl should be representative. Yes
admStringMeans of conveying ad markup in case the bid wins.Yes
adomainString ArrayAdvertiser domain for block list checking (e.g., "ford.com"). This can be an array of for the case of rotating creatives.Yes
iurlStringURL without cache-busting to an image that is representative of the content of the campaign for ad quality/safety checking.Yes
cridStringCreative ID to assist with ad quality checkingYes
adidStringID of a preloaded ad to be served if the bid wins.Yes
dealidStringReference to the deal.id from teh bid requeest if this bid pertains to a private marketplace dierct deal.No
extObjectPlaceholder for bidder-specific extensions to OpenRTBYes
hIntegerHeight of the creative in pixels.Yes
wIntegerWidth of the creative in pixelsYes

Object: Bid.ext

                     

AttributeTypeDescriptionSupported
dspidStringDsp IDYes
advidStringAdvertiser IDYes

Integration Step

Once contract is completed, PubMatic will share the end point with publisher. End point will be similar to http://openbid.pubmatic.com/translator. On this end point, publisher can send open RTB request to PubMatic.

 

Examples

Request Sample

{
    "id": "93D3BAD6-E2E2-49FB-9D89-920B1761C865",
    "at": 1,
    "bcat": ["IAB25", "IAB7-39", "IAB8-18", "IAB8-5", "IAB9-9"],
    "regs": {
        "coppa": 0
    },
    "imp": [{
        "id": "1",
        "instl": 1,
        "bidfloor": 1.2,
        "bidfloorcur": "USD",
        "iframebuster": ["vendor1.com", "vendor2.com"],
        "secure": 1,
        "banner": {
            "w": 728,
            "h": 90,
            "pos": 1,
            "topframe": 0,
            "battr": [1, 2, 16],
            "expdir": [1, 2]
        },
        "ext": {
            "pmZoneId": "XY"
        }
    }, {
        "id": "2",
        "instl": 1,
        "bidfloor": 1.2,
        "bidfloorcur": "USD",
        "iframebuster": ["vendor1.com", "vendor2.com"],
        "secure": 1,
        "banner": {
            "w": 728,
            "h": 90,
            "pos": 1,
            "topframe": 0,
            "battr": [1, 2, 16],
            "expdir": [1, 2]
        },
        "ext": {
            "pmZoneId": "XY"
        }
    }],
    "site": {
        "cat": ["IAB3-1"],
        "pagecat": ["IAB3-1"],
        "page": "http://sitexyz.com/sample.html",
        "ref": "http://referringsite.com/referringpage.html",
        "publisher": {
            "id": "35169"
        }
    },
    "device": {
        "ip": "12.34.56.78",
        "dnt": 1,
        "ua": " Mozilla/5.0 (Windows NT 6.1; WOW64; rv:43.0) Gecko/20100101 Firefox/43.0 ",
        "language": "en-US,en;q=0.5",
        "geo": {
            "country": "US",
            "region": "MA",
            "city": "EastLongmeadow",
            "lat": 42.062000,
            "lon": -72.498901,
            "zip": "01028",
            "type": 2
        }
    },
    "user": {
        "buyeruid": "169F3707-380A-4D76-BE37-B2DB05992D4A",
        "yob": 2010,
        "gender": "F",
        "id": "fCgI95ehkzsr4S0vBXHr9Ue9",
        "geo": {
            "country": "US",
            "region": "MA",
            "city": "EastLongmeadow",
            "lat": 42.062000,
            "lon": -72.498901,
            "zip": "01028",
            "type": 2
        }
    },
    "badv": ["badv.com", "badv1.com", "badv2.com"]
}

Response Sample

{
    "id": "93D3BAD6-E2E2-49FB-9D89-920B1761C865",
    "seatbid": [{
        "bid": [{
            "id": "613673EF-A07C-4486-8EE9-3FC71A7DC73D",
            "impid": "1",
            "price": 100,
            "adid": "916",
            "adm": "cr=<html><a href=\"http://www.pubmatic.com\" target=\"_blank\"><img src = http://blog.gamenightphotos.com/wp-content/uploads/2012/08/300X250-sample-3.png /></a></html>",
            "adomain": ["www.addomain.com"],
            "iurl": "http://localhost11",
            "crid": "creative111",
            "dealid": "dealabc",
            "ext": {
                "dspid": "abc",
                "advid": "xyz"
            }
        },
        {
            "id": "613673EF-A07C-4486-8EE9-3FC71A7DC73D",
            "impid": "2",
            "price": 100,
            "adid": "916",
            "adm": "cr=<html><a href=\"http://www.pubmatic.com\" target=\"_blank\"><img src = http://blog.gamenightphotos.com/wp-content/uploads/2012/08/300X250-sample-3.png /></a></html>",
            "adomain": ["www.addomain.com"],
            "iurl": "http://localhost11",
            "crid": "creative111",
            "dealid": "dealabc",
            "ext": {
                "dspid": "abc",
                "advid": "xyz"
            }
        }],
        "seat": "pubmatic"
    }],
    "cur": "USD"
}

 

NOTE:

To support creative scan publisher needs to replace:

${AUCTION_PRICE} macro with actual bid price in case pubmatic win bid.
${AUCTION_PRICE} macro with AUDIT in case its creative scan.

Attachments

    Outcomes