burl Field Overview¶

The burl field was introduced with v5.2 of the BidSwitch protocol to comply with the latest updates to the OpenRTB specification. The idea behind the introduction of the burl field is to standardise the billing mechanism for Server-to-Server (s2s) notifications sent to Buyers. As such, it has the following properties when used with BidSwitch:

It must contain the win price macro
It is always a server-to-server (S2S) call
It can be used in conjunction with the adm or nurl field, as well as used independently. See the burl Response Examples, and the 5.x Updating Overview section for more information.

What does the burl represent?¶

The burl call signifies that BidSwitch has recorded an impression on its side. How that represents what happened on the Supplier side differs from Supplier to Supplier, specifically in the following ways:

Some Suppliers offer a separate call and affirm that it represents a true impression. In this case, the number of impressions may be less than the number of pure pixel calls from the creative markup, as this model covers creative pre-caching.
For the rest of the Suppliers, BidSwitch places a pixel in the creative markup and records the impression when this pixel is called by the browser.
For video and native impressions, BidSwitch receives the standard impression tracking call. For video this means the VAST impression call, and for Native it means the impression tracker. These are true impression calls by definition. For more information about Video and Native impression tracking, see the Impression Delivery and Tracking section.

Server to Server Restriction¶

Including the price macro in the adm field is not allowed for bid requests that use server to server impression notification. These are marked with the ext.s2s_nurl = 1 flag.

For server to server notifications, it is required to provide the win price macro in the nurl field, or from v5.2 onwards the burl field.

burl Response Examples¶

As of v5.2, when responding to Bid Requests, a win price macro can be given in the burl field, and the adm or nurl field.

Note

The win price macro cannot be given in the adm and nurl field simultaneously. See the 5.x Updating Overview section for more details.
The examples used in this section are extracts from a complete Bid Response, see the Bid Response JSON Examples section for full details.

burl Response¶

{
  "seatbid":[
    {
      "bid":[
        {
          "language":"en",
          "burl":"https://adserver.com/winnotice?impid=102&winprice=${AUCTION_PRICE}",
          "adm":"<a href=\"https://adserver.com/clickadid=12345&tracker=${CLICK_URL:URLENCODE}\"><img src=\"https://image1.cdn.com/impid=102\"/></a>",
          "cat":[
            "IAB12"
          ]
        }
      ]
    }
  ]
}

burl + adm Response¶

In this response, both the burl and adm fields contain the win price macro. The nurl field is not given as it is optional with the use of the burl field..

{
  "seatbid":[
    {
      "bid":[
        {
          "language":"en",
          "burl":"https://adserver.com/winnotice?impid=102&winprice=${AUCTION_PRICE}",
          "cat":[
            "IAB12"
          ],
          "adm":"<iframe src=\"http://dsp.com/imp?bc=12345aaabbb&price=${AUCTION_PRICE}\"><\/iframe>"
        }
      ]
    }
  ]
}

burl + nurl Response¶

In this response, both the burl and nurl fields contain the win price macro. The adm field does not.

{
  "seatbid":[
    {
      "bid":[
        {
          "language":"en",
          "burl":"https://adserver.com/imp?impid=102&winprice=${AUCTION_PRICE}",
          "cat":[
            "IAB12"
          ],
          "adm":"<a href=\"https://adserver.com/clickadid=12345&tracker=${CLICK_URL:URLENCODE}\"><img src=\"https://image1.cdn.com/impid=102\"/></a>",
          "nurl":"https://adserver.com/winnotice?impid=102&winprice=${AUCTION_PRICE}"
        }
      ]
    }
  ]
}