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.

Using the `burl` Field¶

Display¶

The burl field is only valid from v5.2 onwards.
The burl should contain the ${AUCTION_PRICE} macro.
The ${AUCTION_PRICE} macro should be a part of a valid URL.
If the burl field is given, the nurl field becomes optional. Both fields are called, unless the Bid Request specifies a s2s notification only by setting the imp.ext.s2s_nurl field set to 1.
If the Bid Request sets the imp.ext.s2s_nurl field value to 1, only the burl field will be called. Therefore, use the burl field to pass the win price macro.
It is allowed to respond with a non-secure burl for secure bid requests.
When using the ${AUCTION_PRICE} macro in the burl field, it may be simultaneously present in either the adm or nurl field, not both. Using ${AUCTION_PRICE} in the nurl and adm at the same time is not allowed. If using either of these fields, you should NOT omit the ${AUCTION_PRICE} macro in the burl field.
No more than one win price macro can be used in the adm field, otherwise BidSwitch records multiple impression events.

Video/Native¶

Video and Native use the same logic as Display.

If the Bid Request specifies a s2s notification only, using ext.s2s_nurl set to 1, then only one of either the nurl or burl fields may be used. As it is an s2s call only, if the the burl field is given, the nurl field is ignored. Therefore, you should set the ${AUCTION_PRICE} macro in the field that will be called.
If the Bid Request does not explicitly set an s2s call, then nurl, burl, or both can be used and both will be called. In this scenario, both fields can contain the ${AUCTION_PRICE} macro.

"burl":"http://adserver.com/winnotice?impid=102&winprice=${AUCTION_PRICE}",

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}"
        }
      ]
    }
  ]
}