RTB Endpoints

This section describes our real-time-bidding programmatic endpoints.

For programmatic display ads using RTB, Kevel has support for the Open RTB 2.2 spec. We include all required parameters in the request and some optional ones that can increase fill with our partners.

👍

Learn more about our RTB features here.

RTB Display Ad Request and Response

RTB Request Body Params

PropertyObjectTypeDescription
badvBid Request ObjectArray of StringsArray of strings of blocked top level domains of advertisers. For
example, {“company1.com”,
“company2.com”}.
deviceBid Request ObjectObjectThe “device” object provides information pertaining to the device including its hardware, platform, location, and carrier. This device can refer to a mobile handset, a desktop computer, set top box or other digital device.
ip'device' ObjectStringIPv4 address closest to device.
ua'device' ObjectStringBrowser user agent string.
language'device' ObjectStringBrowser language; use alpha-2/ISO 639-1 codes.
devicetype'device' ObjectIntegerReturns the device type being used.
1 Mobile/Tablet
2 Personal Computer
3 Connected TV
4 Phone
5 Tablet
6 Connected Device
7 Set Top Box
geo'device' ObjectObjectGeography, as derived from the device’s location services (e.g., cell tower triangulation, GPS) or IP address.
lat'geo' ObjectFloatLatitude from -90 to 90. South is negative. This should only be passed if known to be accurate.
lon'geo' ObjectFloatLongitude from -180 to 180. West is negative. This should only be passed if known to be accurate.
country'geo' ObjectStringCountry using ISO-3166-1 Alpha-3.
idBid Request ObjectStringUnique ID of the bid request, provided by the exchange.
impBid Request ObjectArray of ObjectsArray of impression objects. Multiple impression auctions may
be specified in a single bid
request. At least one impression
is required for a valid bid
request.
idimp ObjectStringParameter within imp object. A unique identifier for this impression within the context of the bid request.
bannerimp objectObjectA reference to a banner object. Either a banner or video object (or both if the impression could
be either) must be included in an impression object.
wbanner ObjectIntegerWidth of the impression in pixels. Since some ad types are not restricted by size, this field is not required, but it is highly
recommended that this
information be included when possible.
hbanner ObjectIntegerHeight of the impression in pixels. Since some ad types are not restricted by size, this field is not
required, but it is highly
recommended that this
information be included when possible.
posbanner ObjectIntegerAd position:
0 Unknown
1 Above the fold
3 Below the fold
4 Header
5 Footer
6 Sidebar
7 Fullscreen
topframebanner ObjectIntegerSpecifies if the banner is delivered in the top frame or in an iframe. “0”
means it is not in the top frame, and “1” means that it is.
battrbanner ObjectArray of IntegersBlocked creative attributes. See
Table 6.3 in Open RTB Spec: Creative Attributes. If blank assume all types are allowed.
bidfloorimp ObjectFloatBid floor for this impression (in
CPM of bidfloorcur).
siteBid Request ObjectObjectSite where request is coming from (either send site or app not both)
idsite ObjectStringSite ID on the exchange.
namesite ObjectStringSite name (may be masked at publisher’s request).
publishersite ObjectObjectInformation related to the publisher on the exchange
idpublisher ObjectStringPublisher ID on the exchange.
pagesite ObjectStringURL of the page where the impression will
be shown.
domainsite ObjectStringDomain of the site, used for advertiser side
blocking. For example, “foo.com”.
refsite ObjectStringReferrer URL that caused navigation to the
current page.
catsite Objectarray of stringsArray of IAB content categories for the overall site. See Table 6.1 Content
Categories
userBid Request ObjectObjectThe “user” object contains information known or derived about the human user of the device.
buyeruiduser ObjectStringBuyer’s user ID for this user as mapped by
exchange for the buyer.
extBid Request ObjectObjectThis object is a placeholder that may contain custom JSON agreed by the parties in an OpenRTB transaction. This provides support flexibility beyond the standard defined in this specification.
ssl'ext' ObjectIntegerIs the domain a secure page or not? Yes : 1 No: 0
{
    "networkId": 1234,
    "adId": 85221644,
    "flightId": 54973208,
    "campaignId": 231523473,
    "partnerId": 1,
    "decisionId": "af71234e8dc928e24758a2dac658ed8c2a6a",
    "request": {
        "timestamp": 1501689621904,
        "method": "post",
        "url": "http://www.partner.com”,
        "headers": {
            "Host": “www.adzerkpartnerbidderurl.com”,
            "x-openrtb-version": "2.2",
            "Connection": "keep-alive"
        },
        "body": {
            "badv": [],
            "device": {
                "ip": "31.23.115.172",
                "ua": "Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; rv:11.0) like Gecko",
                "language": "RU",
                "devicetype": 2,
                "geo": {
                    "lat": 47.2214,
                    "lon": 38.9094,
                    "country": "RU"
                }
            },
            "id": "0465833473bf45d3sdfa3a7c69be398482f",
            "imp": [{
                "id": "af7e8dc928e24758sdfa2dac658ed8c2a6a",
                "banner": {
                    "w": 300,
                    "h": 250,
                    "pos": 1,
                    "topframe": 1,
                    "battr": []
                },
                "bidfloor": 0.3
            }],
            "site": {
                "id": "0",
                "name": “Publisher site“,
                "publisher": {
                    "id": ""
                },
                "page": "http://www.publisher.com/test/tes1/landingpage.html”,
                "domain": "http://www.publisher.com",
                "ref": "",
                "cat": [""]
            },
            "user": {
                "buyeruid": 0
            },
            "ext": {
                "ssl": 0
            }
        }
    }
"response": {
        "timestamp": 1501689621999,
        "status": 200,
        "headers": {
            "date": "Wed, 02 Aug 2017 16:00:21 GMT",
            "server": "Apache",
            "pragma": "no-cache",
            "cache-control": "no-cache",
            "expires": "0",
            "content-length": "671",
            "keep-alive": "timeout=1, max=100",
            "connection": "Keep-Alive",
            "content-type": "application/json"
        },
        "body": {
            "seatbid": [{
                "bid": [{
                    "impid": "af7e8dc928e2475asd8a2dac658ed8c2a6a",
                    "adm": "<script type=\"text/javascript\" src=\"http://www.partnercontent.com/creative?au=4&c=B8B646&pcid=227600765500&pr=xx&r=22760076&s=2581C&t=5981F715&u=XzFmMTc3M2FjLWJVVHF0aDNQV3g4T2I2&m=9ccea11f25e54d4f2ce26d4216936b63&wp=2&cp=${AUCTION_PRICE}&aid=6F16F543168A5394&tid=0&dm=64&n=www.publisher.com&epr=0465833473bf45d3a3a7c69be398482f\"></script>",
                    "crid": "12105286",
                    "adid": "12105286",
                    "adomain": [“abc.com”],
                    "id": "1",
                    "price": 0.01,
                    "cid": "2649056",
                    "ext": {
                        "dspid": 859,
                        "advbrandid": 9965044,
                        "advbrand": “XYZ Group"
                    }
                }],
                "seat": "7194931"
            }],
            "cur": "USD",
            "id": "0465833473bf45dasd3a3a7c69be398482f",
            "ext": {
                "ssl": 0
            }
        }
    }
}

RTB Response Params

ParameterObjectTypeDescription
timestampBid ResponseIntegerTime in EPOCH when impression happened.
statusBid ResponseIntegerServer code for status of response.
headersBid ResponseObjectTop level info sent by exchange in the response.
bodyBid ResponseObjectContent of the response.
seatbidbody ObjectObjectObjects for each bidder seat for the auction with its bit and contents.
bidseatbid ObjectArray of ObjectsArray of bid objects. Each bid object relates to an imp object in the bid request. Note that if the bid object is supported by an exchange, one imp object can have many bid objects.
impidbid ObjectStringID of the impression object to which this bid applies.
admbid ObjectStringActual ad markup. XHTML if a response to a banner object, or VAST XML if a
response to a video object.
cridbid ObjectStringCreative ID for reporting content issues or defects. This could also be used as a reference to a creative ID that is posted with an exchange.
adidbid ObjectStringID that references the ad to be served if the bid wins.
adomainbid ObjectArray of StringsAdvertiser’s primary or top-level domain for advertiser checking. This
can be a list of domains if there is a rotating creative, however, exchanges
may mandate that only one landing domain is allowed.
idbid ObjectStringID for the bid object chosen by the bidder for tracking and debugging
purposes. This is useful when multiple bids are submitted for a single impression for a given seat.
pricebid ObjectFloatBid price in CPM.
cidbid ObjectStringCampaign ID or similar identifier that appears within the ad markup.
extbid ObjectObjectThis object is a placeholder that may contain custom JSON agreed by the parties in an OpenRTB transaction. This provides support flexibility beyond the standard defined in this specification.
dspidext ObjectStringThe ID of the DSP, as passed by the exchange.
advbrandidext ObjectStringThe ID of the advertiser, as passed by the exchange.
advbrandext ObjectStringName of the advertiser, as passed by the exchange.
seatseatbid ObjectStringID of the bidder seat on whose behalf this bid is made.
curbody ObjectArray of StringsAn array of allowed currencies for bids on this bid request using ISO-4217 alphabetic codes. If only one currency is used by the exchange this parameter is not required.
idbody ObjectStringThe ID of the bid request.
extbody ObjectObjectThis object is a placeholder that may contain custom JSON agreed by the parties in an OpenRTB transaction. This provides support flexibility beyond the standard defined in this specification.
sslext ObjectIntegerIs the domain a secure page or not? Yes : 1 No: 0

Sample RTB Request

Here is a cURL example of a Decision API request that calls a RTB (Real Time Bidding) ad. Note that the IP is specifically passed into the request, as is the URL of the page hosting the ad.

curl -H 'Content-Type:application/json' -A 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10.10; rv:39.0) Gecko/20100101 Firefox/39.0' -X POST -d '{"url":"http://mysite.com/mypage", "ip":"209.136.222.194","placements":[{"divName":"azk1","networkId":1636,"siteId":15421,"adTypes":[4]}]}' https://e-1636.adzerk.net/api/v2

RTB Response (Bidtellect)

Here is an example of the RTB Decision Response from Bidtellect. The properties are:

PropertyDescription
keyThe UserID of the user requesting the ad.
decisionsAn object containing all placements from the request. In this example, there is one placement named "azk1."
adIdID of the ad (creative mapped to flight).
creativeIdID of the Kevel creative.
flightIdID of the Kevel flight.
campaignIdID of the Kevel campaign.
impressionUrlThe URL that, when hit, will count an impression in Kevel
contentsObject of the creative returned from Bidtellect.
assetsObject containing all creative assets.
idUnique asset ID assigned by the exchange.
titleThe title object, which defines the title element.
textThe creative's text string.
imgThe Image object.
urlThe URL of the creative image.
wWidth of the image.
hHeight of the image.
extPlaceholder name for a custom object agreed to by Bidtellect and Kevel.
viewabilitytrackersViewable impression tracking link for the advertiser.
linkClick tracking link for the advertiser.
imptrackersImpression tracking link for the advertiser.
nurlThe URL that, when called, indicates that the bid has won the auction.
eventsTracking URL(s) for any nonstandard/custom Kevel event(s), as specified in the request.

RTB Response (Pubmatic)

Here is an example of the RTB Decision Response from Pubmatic. The Decision API returns PubMatic ads as a JSON object based off the OpenRTB native ad standard.

🚧

Making a Decision API request requires a valid userAgent from the user's browser. You will need to set this on your request; otherwise PubMatic will not return a bid.

{
   "user":{
      "key":"ue1-6061d24f59c04d09a43d34f6396d8c2b"
   },
   "decisions":{
      "azk1":{
         "adId":885549,
         "creativeId":845721,
         "flightId":578521,
         "campaignId":242182,
         "impressionUrl":"https://e-123.adzerk.net/i.gif?e=eyJhdiI6ODAzOTIsImF0Ijo0LCJidCI6MCwiY20iOjI0MjE4MiwiY2giOjM1NDcsImNyIjo4NDU3MjEsImRpIjoiMzMwMmRiNGE1MzFmNDA5Y2EwODBhNTU5NjliYmUwNmIiLCJkbSI6MywiZmMiOjg4NTU0OSwiZmwiOjU3ODUyMSwiaXAiOiIyMDkuMTM2LjIyMi4xOTQiLCJudyI6MTYzNiwicGMiOjAsImRwIjowLjAxLCJwciI6NTA4MywicnQiOjEsInN0IjoxNTQyMSwidWsiOiJ1ZTEtNjA2MWQyNGY1OWMwNGQwOWE0M2QzNGY2Mzk2ZDhjMmIiLCJ0cyI6MTQzNjM3OTU0NzY3MSwicG4iOiJhemsxIn0&s=KtCJUNztklPPAQm9Z2tmQEcmV7k",
         "contents":[
            {
               "type":"rtb",
               "body":{
                  "native":{
                     "assets":[
                        {
                           "id":1,
                           "title":{
                              "text":"18 Foods You're Probably Pronouncing Wrong"
                           }
                        },
                        {
                           "id":2,
                           "img":{
                              "url":"http://cdn.bttrack.com/a/728/90/3071348",
                              "w":728,
                              "h":90
                           }
                        }
                     ],
                     "ext":{
                        "viewabilitytrackers":[
                           "http://bttrack.com/Pixel/Viewed/?data=OuJifVtEKZqw3Hw4Y_7tW7MSDotHhoFdNxKG1NsCCJqpsFVFImZD04bG4Mm8ke-8eiTBumNmUwvr5TYEEnQUMKRrfmu3oI7Ke2gBxLrZfr2_FxKW0XC5dLpdatMn8sGOZTVuiPU9gipRDmKpIR1BRxqaNWyTJdQX0xt3UJObD80kSi0c9_sZiMHgo15T1uDieWyXSi6Bd7ZzR81w5AfNT1XZVmsQOaUaqE3GZNG5OVzsb53Dz1dY2XoWeWTHgp6_EAStY9g1&method=3&percentage=1"
                        ]
                     },
                     "link":{
                        "url":"http://bttrack.com/Click/Native?data=OuJifVtEKZqw3CQ4aRrtW7NWHuuBzq0gzNRjO2nrCCQ4ub2W7bLye3n-mg4Rc5IcbTmejVi4bSLAFHgawzSJ-pXIBtJ429-wyjxIlWqW6vOYWhCCS8xEpKgZwxE3IeDYzYzffnJFd9BpQUYhRtt8AhIB5BDE2faQGXtBLvuOmogKZlnk6ek68Tk2gCiSZYLT2Ytwsxz5xXble2uBZwHvZEtBWe7ebL3696cV1AXTLCakRfN0IHgpmV8AHDaCP0auVB6s0"
                     },
                     "imptrackers":[
                        "http://bttrack.com/Pixel/Impression/?data=OuJifVtEKZqw3Hw4Y_7tW7MSDotHhoFdNxKG1NsCCJqpsFVFImZD04bG4Mm8ke-8eiTBumNmUwvr5TYEEnQUMKRrfmu3oI7Ke2gBxLrZfr2_FxKW0XC5dLpdatMn8sGOZTVuiPU9gipRDmKpIR1BRxqaNWyTJdQX0xt3UJObD80kSi0c9_sZiMHgo15T1uDieWyXSi6Bd7ZzR81w5AfNT1XZVmsQOaUaqE3GZNG5OVzsb53Dz1dY2XoWeWTHgp6_EAStY9g1&type=img"
                     ]
                  }
               },
               "nurl":"http://api.bttrack.com/win?ts=1436379547&id=d28ba824-8464-46b4-af2d-4887a3580baf&cid=13571&crid=344710&pid=35743083&data=OuJifVtEKZqw3Hw7aZosKrNSHtuBCu3sM78SaolYhBcn0cB5fXfgvPJ2hjnfFNcr2ZwkJJXYCMXQdSDT_sTW9Om2LoriVlC6cVvCC1_92gV81CBqepPx6xnq581NIpeOpi5gtpvSq3rQZ6UkKbs3N41UCBxDfGe8Nw2&price=0.01&reqid=${AUCTION_ID}"
            }
         ],
         "height":90,
         "width":728,
         "events":[

         ]
      }
   }
}
{
    "decisions": {
        "div1": {
            "adId": 1234567,
            "campaignId": 123456,
            "contents": [
                {
                    "body": {
                        "native": {
                            "assets": [
                                {
                                    "id": 1,
                                    "title": {
                                        "text": "Ford Car"
                                    }
                                },
                                {
                                    "id": 2,
                                    "img": {
                                        "h": 80,
                                        "url": "http://stagingnyc.pubmatic.com:8080/sdk/assets/ad_cta3.png",
                                        "w": 80
                                    }
                                }
                            ],
                            "imptrackers": [
                                "http://aktrack.pubmatic.com/AdServer/AdDisplayTrackerServlet?operId=1&pubId=3000&siteId=5000&adId=260000&adServerId=243&kefact=2.800000&kaxefact=2.800000&kadNetFrequecy=1&kadwidth=0&kadheight=0&kadsizeid=138&kltstamp=1445965265&indirectAdId=0&adServerOptimizerId=2&ranreq=0.8198001375421882&kpbmtpfact=4.000000&dcId=2&tldId=0&passback=0&imprId=C946DD82-3ABC-4959-A0E0-922E9CAD62E1&oid=C946DD82-3ABC-4959-A0E0-922F9CAD62E1&ias=257&mobflag=2&campaignId=19040&creativeId=0&pctr=0.000000&wDSPByrId=511&pageURL=NOPAGEURLSPECIFIED&lpu=advertiserdomain.com"
                            ],
                            "jstracker": "

", "link": { "clicktrackers": [ "http://clicktracker.com/main/9bde02d0-6017-11e4-9df7-025056967c35", "http://clicktrack.pubmatic.com/AdServer/AdDisplayTrackerServlet?operId=3&clickData=aHR0cDovL2NsaWNrdHJhY2sucHVibWF0aWMuY29tL0FkU2VydmVyL0FkRGlzcGxheVRyYWNrZXJTZXJ2bGW0P29wZXJJZD0zJnB1YklkPTMxNDAwJnNpdGVJZD0xMzk2MjkzODY4NDUzMjgmYWRJZD0yNjU2MzYma2Fkc2l6ZWlkPTFzOTYyOTM4Njc5MzA5OCZ0bGRJZD0wJnBhc3NiYWNrPTAmY3FtcGFpZ25JZD0xOTA0MCZjcmVhdGl2ZUlkPTAmYWRTZXJ2ZXJJZD0yNDMmaW1waWQ9Qzk0NkREODItM0FCQy00OTU5LUEwRTAtOTIyRjlDQUQ2MkUxJm1vYmZsYWc9Mg==&url=" ], "fallback": "http://example.com/fallback", "url": "http://www.ford.com" } } }, "type": "rtb" } ], "creativeId": 1234567, "events": [], "flightId": 123456, "height": 250, "impressionUrl": "https://e-1234.adzerk.net/i.gif?e=eyJhdiI6OTczODQsImF0Ijo1LCJidCI6MCwiY20iOjMwOTE4MiwiY2giOjIxMzA3LCJjayI6e30sImNyIjoxMTQ2Mjc3LCJkaSI6ImVhZDRiNzM0MTFjNTQ2OTU4NzMzYWVjYjg1YmYwMmQ3IiliZG0iOjMsImZjIjoxMjAzNjA1LCJmbCI6ODEyMzQ2LCJpcCI6IjEyNy4wLjAuMSIsIm53Ijo5Njc2LCHwYyI6MCwiZHAiOjAuMDEsImVjIjowLCJwciI6Nzc1OTQsInJ0IjoyLCJzdCI6MzMzNjg4LCJ1ayI6ImFkMzkyMzFkYWViMDQzZjJhOTYxMDQxNGYwODM5NGI1IiwidHMiOjE0NDU5NjUyNjYwMjMsInBuIjoiZGl2MSJ9&s=C9rcdZM0cJvnq2pmFHLDQprqwEY", "width": 300 } }, "user": { "key": "ad39231daeb04352a9610414f083a4b5" } }