Browse the documentation

OpenRTB 2.x — Banner

Hosts: {rtb_domain} is your network's RTB domain, used by the bidder endpoints; a network without a dedicated RTB domain uses its ad domain there. {ad_domain} is the network's ad-serving domain. Inside the panel both are filled in for you.

Standard display creatives. We accept HTML, IFrame, or XML AdMarkup as the response.

Endpoint#

Single unified endpoint for every protocol flavour we support — OpenRTB, RTB JSON, RTB XML — the feed (SSP campaign) settings decide which shape to expect and which response format to return. For OpenRTB requests the gateway also picks up the ad type from the imp content (imp.banner / imp.video / imp.native) plus ext.type and imp.instl markers. token is the SSP campaign token (required) and may also be sent as Authorization: Bearer <token> header.

URL

POST https://{rtb_domain}/openrtb/get.go?token={token}

Bid Request#

Sent by us to your endpoint as POST application/json. tagid is the placement id you provisioned. bidfloor is the publisher floor in bidfloorcur.

User-context fields must reflect the END VISITOR, not your server. That means: device.ip is the visitor's IP (we use it for geo + fraud), device.ua is the visitor's User-Agent header, device.language is the visitor's browser language, device.geo.country is the ISO-3 country code (e.g. NLD) — we derive it from device.ip when missing, but pass it explicitly when you already know it. device.w / device.h are the visitor's viewport / screen dimensions in pixels (used for responsive creative selection). user.id is the persistent visitor identifier (cookie / device id). Same expectation in reverse when you bid into us — include the real visitor's data, never the bidder server's.

Example

{
  "id": "your_id",
  "imp": [{
    "id": "your_id",
    "tagid": "placementid",
    "bidfloor": 0.00,
    "bidfloorcur": "USD",
    "banner": {
      "w": 300,
      "h": 250,
      "format": [{ "w": 300, "h": 250 }],
      "pos": 1
    },
    "ext": { "subid": "" }
  }],
  "site": {
    "id": "1",
    "domain": "site.com",
    "publisher": { "id": "1" },
    "page": "http://site.com/page.html"
  },
  "device": {
    "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
    "ip": "{client_ip}",
    "language": "{language}",
    "geo": { "country": "{country}", "ipservice": 3 },
    "ext": {
      "accept_language": "{accept_language}",
      "remote_addr": "{client_ip}",
      "requested_with": "{requested_with}"
    },
    "h": {browser_h}, "w": {browser_w}
  },
  "user": { "id": "5a80e2e5857d86a298e013ab0091c17e" },
  "curr": ["USD"],
  "at": 1
}

Bid Response#

Three accepted shapes. Pick one — adm is parsed in this order: HTML markup → IFrame URL → XML AdMarkup.

HTML adm

{
  "id": "your id",
  "seatbid": [{
    "bid": [{
      "id": "our id",
      "impid": "your_id",
      "price": 0.0272,
      "nurl": "https://your-dsp.com/win?bid=${AUCTION_BID_ID}&price=${AUCTION_PRICE}",
      "adm": "<a href='https://site.com' target='_blank'><img src='path_to_image' width='300' height='250' border='0'></a>"
    }]
  }]
}

IFrame adm (URL)

{
  "id": "your id",
  "seatbid": [{
    "bid": [{
      "id": "our id",
      "impid": "your_id",
      "price": 0.0272,
      "nurl": "https://your-dsp.com/win?bid=${AUCTION_BID_ID}&price=${AUCTION_PRICE}",
      "adm": "//site.com/iframe.html"
    }]
  }]
}

XML AdMarkup

{
  "id": "your id",
  "seatbid": [{
    "bid": [{
      "id": "our id",
      "impid": "your_id",
      "price": 0.0272,
      "nurl": "https://your-dsp.com/win?bid=${AUCTION_BID_ID}&price=${AUCTION_PRICE}",
      "adm": "<?xml version=\"1.0\" encoding=\"ISO-8859-1\"?><ad><imageAd><clickUrl><![CDATA[https://site.com/page.html]]></clickUrl><imgUrl><![CDATA[https://site.com/banner.png]]></imgUrl></imageAd></ad>"
    }]
  }]
}

AdMarkup XML — Image

<?xml version="1.0" encoding="ISO-8859-1"?>
<ad>
  <imageAd>
    <clickUrl><![CDATA[https://site.com/page.html]]></clickUrl>
    <imgUrl><![CDATA[https://site.com/banner.png]]></imgUrl>
  </imageAd>
</ad>

AdMarkup XML — IFrame

<?xml version="1.0" encoding="ISO-8859-1"?>
<ad>
  <iframeAd>
    <url><![CDATA[https://site.com/iframe.html]]></url>
  </iframeAd>
</ad>

Win notice (nurl)#

Optional: put a nurl on your bid and we call it (server-side GET) when your bid wins. When you send no nurl but do send burl, we call burl instead. The standard OpenRTB auction macros in the URL are filled in before the call — see the list below. Banner, video, native, push and full-page wins: we call it once, when the ad is actually shown. Pop, redirect and mail-click wins have no render step, so we call it right after the auction. Leave nurl out and no win notice is sent.

Example

https://your-dsp.com/win?bid=${AUCTION_BID_ID}&price=${AUCTION_PRICE}

Supported macros

${AUCTION_PRICE}     winning price, same unit and currency as bid.price
${AUCTION_CURRENCY}  always USD
${AUCTION_BID_ID}    your bid.id
${AUCTION_IMP_ID}    the impid of the winning bid
${AUCTION_ID}        the id of our bid request