Bid Response Objects and Parameters
Page Tree
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 Supported Parameters
On valid requests, PubMatic returns responses in OpenRTB standard format with
200 OK
success code. The tables below list all fields PubMatic may include in responses. For incorrect requests, missing required mandatory parameters, or missing creatives, PubMatic returns,
204 no content.
PubMatic supports either
adm or nurl for video, which PubMatic can configure for you upon request.Object: BidResponse
| Attribute | Type | Description | Supported |
|---|---|---|---|
id | String | ID of the bid request to which this is a response. | Yes |
seatbid | Object | Array of seatbid objects; 1+ required if a bid is to be made | Yes |
bidid | String | Bidder generated response ID to assist with logging/tracking. | Yes |
cur | String | Bid currency using ISO-4217 alpha codes. | Yes |
Object: SeatBid
| Attribute | Type | Description | Supported |
|---|---|---|---|
bid | Object | Array required Array of 1+ Bid objects each related to an impression. Multiple bids can relate to the same impression. | Yes |
seat | String | ID of the bidder seat on whose behalf this bid is made. | Yes |
Object: Bid
| Attribute | Type | Description | Supported |
|---|---|---|---|
id | String | Bidder generated bid ID to assist with logging/tracking. | Yes |
impid | String | ID of the Imp object in the related bid request. | Yes |
| api | integer | API required by the markup if applicable. Refer to List 5.6. | Yes (if enabled for publisher) |
| protocol | integer | Video response protocol of the markup if applicable. Refer to List 5.8. | Yes (if enabled for publisher) |
ext.video.duration | Integer | Video Ad Duration of Creative. | Yes (if configured for publisher) |
| ext.crtype | string | Applovin OpenRTB Extension supported. | Yes (if configured for publisher) |
price | String | Bid price expressed as CPM although the actual transaction is for a unit impression only. | Yes |
cid | String | Campaign ID to assist with ad quality checking; the collection of creatives for which iurl should be representative. | Yes |
adm | String | Means of conveying ad markup in case the bid wins. | Yes |
adomain | String Array | Advertiser domain for block list checking (e.g., "ford.com"). This can be an array of for the case of rotating creatives. | Yes |
iurl | String | URL without cache-busting to an image that is representative of the content of the campaign for ad quality/safety checking. | Yes |
burl | String | Billing notice URL called by the exchange when a winning bid becomes billable based on exchange-specific business policy (e.g., typically delivered, viewed, etc.). needs to replace ${AUCTION_PRICE} macro with actual bid price in case pubmatic win bid. | Yes |
crid | String | Creative ID to assist with ad quality checking | Yes |
adid | String | ID of a preloaded ad to be served if the bid wins. Please contact your account manager to enable this. | Yes |
dealid | String | Reference to the deal.id from teh bid requeest if this bid pertains to a private marketplace dierct deal. | No |
ext | Object | Placeholder for bidder-specific extensions to OpenRTB | Yes |
h | Integer | Height of the creative in pixels. | Yes |
w | Integer | Width of the creative in pixels | Yes |
Object: Bid.ext
| Attribute | Type | Description | Supported |
|---|---|---|---|
dspid | String | Dsp ID | Yes |
advid | String | Advertiser ID | Yes |
third_party_buyer_token | String | The third_party_buyer_token attribute lets publishers identify a response and keep the mapping on their side to resolve any billing discrepancies. | Yes |
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
Examples below apply to Desktop and Mobile Web only…
Request and Response may vary from the samples below. Contact PubMatic's Solutions Engineering for appropriate sample code for your integration type.
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"
}
To support creative scan on PubMatic, publisher must replace…
${AUCTION_PRICE}macro with actual bid price in case pubmatic win bid.${AUCTION_PRICE}macro with AUDIT in case its creative scan.