Partners

Open RTB 2.6 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
attr Creative attributes of the returned ad. Optional* For User-Interactive ads, this field is required and the value should be [13].
apis List of supported APIs for the markup. If an API is not explicitly listed, it is assumed to be unsupported. Refer to List: API Frameworks in AdCOM 1.0. Required if markup applicable
api NOTE: Deprecated in favor of the apis integer array. API required by the markup if applicable. Refer to List: API Frameworks in AdCOM 1.0. Required if markup applicable
protocol Video response protocol of the markup if applicable. Refer to List: Creative Subtypes - Audio/Video in AdCOM 1.0. Required if markup applicable
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.
mtype Type of the creative markup so that it can properly be associated with the right sub-object of the BidRequest.Imp.Values: 1 = Banner, 2 = Video, 3 = Audio, 4 = Native Highly Recommended
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 Responses 🔗

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": [],
          "mtype": 1,
          "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],
          "apis": [5],
          "mtype": 1,
          "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": [],
          "apis": [8],
          "protocol": 3,
          "mtype": 2,
          "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"
          }
        }
      ]
    }
  ]
}