Overview

For formats that do not work with Prebid, ServerBid offers its unified auction via API. As opposed to a Prebid auction, the API provides a pure server-to-server RTB. For that reason, API access requires a separate snippet for user syncing, which is critical to high yield.

API Setup Instructions

Description


Use the API to request an ad decision. To make a request, you must POST a JSON representation of the request.

Set the Content-Type in the header as application/json. (The API will also accept text/plain to support applications that cannot change the content type, such as older versions of IE.)


Definition


POST engine.adzerk.net/api/v2

Or to make a secure request:

POST https://engine.adzerk.net/api/v2


Arguments


Required


placements
(object)
One or more Placement Objects. Required.
divName
(string
The div ID of the placement.
networkId
(int)
Always 9969.
siteId
(int)
The ID of the site.
adTypes[]
(int array)
The ID of the ad size of the placement. Although an array, this is usually one int.
zoneIds[]
(int array)
Array of ints (not strings), though in most cases this will only be one int. Required if zone IDs were provided for the placement, should not be included if not.
includePricingData
(bool)
This is what gives back price, clearPrice, ecpm, etc.


Optional


user.key
(string)
Optional; recommended (the userkey is used when syncing with partner IDs).
referrer
(string)
Optional; recommended. ServerBid generally passes the referrer URL to RTB partners.
ip
(string)
Optional; recommended for targeting purposes.
url
(string)
Optional; highly recommended for targeting.
enableBotFiltering
(bool)
Depends on if server- or client-side. For server-side, do not include this. For client-side, you generally want to include this.


User Syncing

The following iframe will need to be loaded on the browser page containing the ad call - before the code doing the ad call. This is so cookies can be read and written.


HTML
<iframe width="0"
        height="0"
        style="display:none;visibility:hidden"
        src="https://t-9969.adzerk.net/9969/i.html">
</iframe>


cURL 
curl https://engine.adzerk.net/tag/9969/i.html


API Test Instructions

Below is an example JSON placement request and cURL request which should always return an ad.


API JSON Request 
{
  "placements": [
    {
      "divName": "div1",
      "networkId": 9969,
      "siteId": 980639,
      "adTypes": [5],
      "zoneIds": [178503]
    }
  ],
  "user" : {
    "key": "ad39231daeb043f2a9610414f08394b5"
  },
  "referrer": "...",
  "ip": "10.123.123.123",
  "url": "http://www.google.com",
  "includePricingData": false,
  "enableBotFiltering": false
}


cURL 
curl -i -X POST \
   -H "Content-Type:application/json" \
   -d \
'{
  "placements": [
    {
      "divName": "div1",
      "networkId": 9969,
      "siteId": 980639,
      "adTypes": [5],
      "zoneIds": [178503]
    }
  ],
  "user" : {
    "key": "ad39231daeb043f2a9610414f08394b5"
  },
  "referrer": "...",
  "ip": "10.123.123.123",
  "url": "http://www.google.com",
  "includePricingData": false,
  "enableBotFiltering": false
}' \
 'http://engine.adzerk.net/api/v2'


Below is an example response to the above request.


JSON 
{
  "user": {
    "key": "ue1-example-user-key"
  },
  "decisions": {
    "div1": {
      "adId": 7023906,
      "creativeId": 4215845,
      "flightId": 6943676,
      "campaignId": 666731,
      "clickUrl": "https://e.serverbid.com/r?e=[truncated]",
      "impressionUrl": "https://e.serverbid.com/i.gif?e=[truncated]",
      "contents": [
        {
          "type": "rtb",
          "body": "[truncated rtb creative data]",
          "data": {
            "height": 250,
            "width": 300,
            "rtb": null
          }
        }
      ],
      "height": 250,
      "width": 300,
      "events": [],
      "pricing": {
        "price": 0,
        "clearPrice": 0.3238704,
        "revenue": 0.0003238704,
        "rateType": 2,
        "eCPM": 0
      }
    }
  }
}