Partners

Open RTB 2.3 Bid Response Specifications

BidResponse 🔗

The BidResponse object contains the following fields:

Field Description Notes
id Bidder-generated bid ID to assist with logging/tracking.  
seatbid Array of objects containing seat & bid information. Required. We support only one bid per bid response.
bidid Bidder-generated response ID to assist with logging/tracking.  
cur Currency. Should always be set to 'USD'.

BidResponse.seatbid (Array[Object]) 🔗

Field Description Notes
bid Array of bid objects containing details of the bid. Should contain a single bid object.
seat Name of the client making the bid.  

BidResponse.seatbid[].bid (Array[Object]) 🔗

Field Description Notes
id Bidder-generated bid ID to assist with logging/tracking. Required
impid Must match the imp.id from the auction’s bid request. Required
price Bid price expressed as CPM. Required
nurl Win notice URL called by the exchange if the bid wins. (not necessarily indicative of a delivered, viewed, or billable ad). Substitution macros are supported. Optional
burl Notification URL to be called from device once impression is shown. Required* OpenRTB macros are supported here. Either burl or ext.imptrackers must be provided for impression tracking.
lurl Notification URL to be called from our server immediately following an auction, to notify of win/loss/error outcome of your bid. Substitution macros are supported. Optional
adm Only supported method of sending payload. Required OpenRTB macros are supported here.
adid ID of a preloaded ad to be served if the bid wins. Optional
adomain Advertiser domain for block list checking (e.g., “ford.com”). Required
bundle Package id for Android or iTunes Store id for iOS of the advertised app. Required* If your advertisement is for a Google Play Store or iTunes Store app, this field is required, else is it optional.
cid Campaign ID. Optional
crid Creative ID. Recommendation: prefix with a DSP identifying string to enhance uniqueness of the id, e.g. “crid”:”acme_123” vs. “crid”:”123”. Required
cat Array containing IAB content categories of the creative. Highly Recommended
api API required by the markup if applicable. Refer to List 5.6 in 2.5 specifications. Optional
protocol Video response protocol of the markup if applicable. Refer to List 5.8 in 2.5 specifications. Recommended
attr Creative attributes of the returned ad. Optional* For User-Interactive ads, this field is required and the value should be [13].
dealid String that references deal.id from the bid request if this bid pertains to a private marketplace direct deal. Only Required for PMP Deals.
ext.imptrackers Array of URLs that will be hit from device when impression is shown on the screen. Required*, OpenRTB macros are supported here. Either burl or ext.imptrackers must be provided for billable impression tracking.
ext.crtype String which defines payload format. Required. If bidding with a User-Interactive ad this value must be set to "MRAID playable" or the bid response will be rejected; else set to one of the following: "VAST 2.0", "VAST 3.0", "MRAID 1.0", "MRAID 2.0", "MRAID 3.0", "HTML".
ext.buttonPlacement String to communicate which corner to display close button in an MRAID response. Accepted values are “top-right” or “top-left”. Optional

Example Response 🔗

DSPs can refer to the sample bid responses:

Static/Banner ad response (HTML/MRAID) 🔗 

// Static/Banner ad response (HTML/MRAID)
{
  "id": "9d554579-f21a-4f6f-a33e-42c41b09b206",
  "bidid": "rtb-9d554579-f21a-4f6f-a33e-42c41b09b206",
  "cur": "USD",
  "seatbid": [
    {
      "seat": "foobar",
      "bid": [
        {
          "impid": "05f2322fee88b9bf6892e6257bfabea83939b4c4",
          "adomain": [
            "foobar.com"
          ],
          "attr": [],
          "bundle": "com.foobar.game",
          "id": "rtb-9d554579-f21a-4f6f-a33e-42c41b09b206",
          "crid": "foobar:190d3bfd",
          "cid": "190d3bfd",
          "cat": ["IAB9-30"],
          "price": 15.2625,
          "adid": "190d3bfd",
          "burl": "https://lb-www2.foobar.com/ads/notify.php?auction_id=${AUCTION_ID}&winning_price=${AUCTION_PRICE}",
          "lurl": "https://lb-www2.foobar.com/ads/notify.php?auction_id=${AUCTION_ID}&win_loss_other=${AUCTION_LOSS}&minbid=${MIN_BID_TO_WIN}",
          "adm": "<!DOCTYPE html><html lang=\"en\"><div id=\"foobarad\" style=\"background-color:black; position:relative; width:100%; height:100%;\"><a href=\"https://some.clickthrough.link\"><img style=\"position:absolute;top: 0;left: 0;bottom: 0;right: 0;margin:auto; max-width:100%; max-height:100%\" src=\"https://some.cdn/image.jpg\" alt=\"none\"></a></div>\n\n",
          "ext": {
            "imptrackers": [
              "https://lb-www2.foobar.com/ads/notify.php?auction_id=${AUCTION_ID}&winning_price=${AUCTION_PRICE}"
            ],
            "crtype": "MRAID 2.0"
          }
        }
      ]
    }
  ]
}

MRAID Playable ad response 🔗 

// MRAID Playable ad response
{
  "id": "9d554579-f21a-4f6f-a33e-42c41b09b206",
  "bidid": "rtb-9d554579-f21a-4f6f-a33e-42c41b09b206",
  "cur": "USD",
  "seatbid": [
    {
      "seat": "foobar",
      "bid": [
        {
          "impid": "05f2322fee88b9bf6892e6257bfabea83939b4c4",
          "adomain": [
            "foobar.com"
          ],
          "attr": [13],
          "api": 3,
          "bundle": "com.foobar.game",
          "id": "rtb-9d554579-f21a-4f6f-a33e-42c41b09b206",
          "crid": "foobar:190d3bfd",
          "cid": "190d3bfd",
          "cat": ["IAB9-30"],
          "price": 15.2625,
          "adid": "190d3bfd",
          "burl": "https://lb-www2.foobar.com/ads/notify.php?auction_id=${AUCTION_ID}&winning_price=${AUCTION_PRICE}",
          "lurl": "https://lb-www2.foobar.com/ads/notify.php?auction_id=${AUCTION_ID}&win_loss_other=${AUCTION_LOSS}&minbid=${MIN_BID_TO_WIN}",
          "adm": "<!DOCTYPE html><html lang=\"en\"><div id=\"foobarad\" style=\"background-color:black; position:relative; width:100%; height:100%;\"><a href=\"https://some.clickthrough.link\"><img style=\"position:absolute;top: 0;left: 0;bottom: 0;right: 0;margin:auto; max-width:100%; max-height:100%\" src=\"https://some.cdn/image.jpg\" alt=\"none\"></a></div>\n\n",
          "ext": {
            "imptrackers": [
              "https://lb-www2.foobar.com/ads/notify.php?auction_id=${AUCTION_ID}&winning_price=${AUCTION_PRICE}"
            ],
            "crtype": "MRAID playable",
            "buttonPlacement": "top-right"
          }
        }
      ]
    }
  ]
}

Video ad response (VAST) 🔗 

// Video ad response(VAST)
{
  "id": "9d554579-f21a-4f6f-a33e-42c41b09b206",
  "bidid": "rtb-9d554579-f21a-4f6f-a33e-42c41b09b206",
  "cur": "USD",
  "seatbid": [
    {
      "seat": "foobar",
      "bid": [
        {
          "impid": "05f2322fee88b9bf6892e6257bfabea83939b4c4",
          "adomain": [
            "foobar.com"
          ],
          "attr": [],
          "api": 2,
          "protocol": 3,
          "bundle": "com.foobar.game",
          "id": "rtb-9d554579-f21a-4f6f-a33e-42c41b09b206",
          "crid": "foobar:190d3bfd",
          "cid": "190d3bfd",
          "cat": ["IAB9-30"],
          "price": 15.2625,
          "adid": "190d3bfd",
          "burl": "https://lb-www2.foobar.com/ads/notify.php?auction_id=${AUCTION_ID}&winning_price=${AUCTION_PRICE}",
          "lurl": "https://lb-www2.foobar.com/ads/notify.php?auction_id=${AUCTION_ID}&win_loss_other=${AUCTION_LOSS}&minbid=${MIN_BID_TO_WIN}",
          "adm": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><VAST version=\"3.0\"><Ad id=\"idleheros-gp-001\"><InLine><AdSystem>Chartboost</AdSystem><Error></Error><AdTitle>idleheros-gp-001</AdTitle><Impression><![CDATA[https://testbid.chartboost.com/impression?ssp=cbbidder&creative_id=7&model_id=SM-N900T&cpi_price=10.0&exchange=chartboost&impression_id=05f2322fee88b9bf6892e6257bfabea83939b4c4&cpm_price=5.95&ip_address=73.84.99.99&app_bundle=com.foo.bar&city=West Palm Beach&country=USA&region=FL&cpm_bid=60.0&ssp_fields=%7B%22ad_group%22%3A%2232%22%7D&model=SM-N900T&identifier=7c0ffa99-9238-459e-82ff-9465634bb8a1&os=5.0]]></Impression><Creatives><Creative><Linear><Duration>00:00:29</Duration><MediaFiles><MediaFile bitrate=\"906\" delivery=\"progressive\" height=\"320\" maintainAspectRatio=\"true\" scalable=\"true\" type=\"video/mp4\" width=\"568\"><![CDATA[http://v.chartboost.com/videoads/5a2863cf55fbf70b8e3d35d0_568-1512596432.mp4]]></MediaFile></MediaFiles><VideoClicks><ClickThrough><![CDATA[https://testbid.chartboost.com/click?ssp=cbbidder&creative_id=7&model_id=SM-N900T&cpi_price=10.0&exchange=chartboost&impression_id=05f2322fee88b9bf6892e6257bfabea83939b4c4&cpm_price=5.95&ip_address=73.84.99.99&app_bundle=com.foo.bar&city=West Palm Beach&country=USA&region=FL&cpm_bid=60.0&ssp_fields=%7B%22ad_group%22%3A%2232%22%7D&model=SM-N900T&identifier=7c0ffa99-9238-459e-82ff-9465634bb8a1&os=5.0]]></ClickThrough></VideoClicks></Linear></Creative><Creative><CompanionAds><Companion assetHeight=\"473\" assetWidth=\"841\" height=\"473\" width=\"841\"><StaticResource creativeType=\"image/jpeg\"><![CDATA[https://a.chartboost.com/creatives/582e0b9ff6cd451685c344cc/3a079f4abd4b649aea509a81ebd3972992b3d18b.jpeg]]></StaticResource><CompanionClickThrough><![CDATA[https://testbid.chartboost.com/click?ssp=cbbidder&creative_id=7&model_id=SM-N900T&cpi_price=10.0&exchange=chartboost&impression_id=05f2322fee88b9bf6892e6257bfabea83939b4c4&cpm_price=5.95&ip_address=73.84.99.99&app_bundle=com.foo.bar&city=West Palm Beach&country=USA&region=FL&cpm_bid=60.0&ssp_fields=%7B%22ad_group%22%3A%2232%22%7D&model=SM-N900T&identifier=7c0ffa99-9238-459e-82ff-9465634bb8a1&os=5.0]]></CompanionClickThrough></Companion></CompanionAds></Creative></Creatives></InLine></Ad></VAST>",
          "ext": {
            "imptrackers": [
              "https://lb-www2.foobar.com/ads/notify.php?auction_id=${AUCTION_ID}&winning_price=${AUCTION_PRICE}"
            ],
          "crtype": "VAST 3.0"
          }
        }
      ]
    }
  ]
}