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

Property	Object	Type	Description
`badv`	Bid Request Object	Array of Strings	Array of strings of blocked top level domains of advertisers. For example, {“company1.com”, “company2.com”}.
`device`	Bid Request Object	Object	The “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' Object	String	IPv4 address closest to device.
`ua`	'device' Object	String	Browser user agent string.
`language`	'device' Object	String	Browser language; use alpha-2/ISO 639-1 codes.
`devicetype`	'device' Object	Integer	Returns 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' Object	Object	Geography, as derived from the device’s location services (e.g., cell tower triangulation, GPS) or IP address.
`lat`	'geo' Object	Float	Latitude from -90 to 90. South is negative. This should only be passed if known to be accurate.
`lon`	'geo' Object	Float	Longitude from -180 to 180. West is negative. This should only be passed if known to be accurate.
`country`	'geo' Object	String	Country using ISO-3166-1 Alpha-3.
`id`	Bid Request Object	String	Unique ID of the bid request, provided by the exchange.
`imp`	Bid Request Object	Array of Objects	Array 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.
`id`	`imp` Object	String	Parameter within `imp` object. A unique identifier for this impression within the context of the bid request.
`banner`	`imp` object	Object	A 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.
`w`	`banner` Object	Integer	Width 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.
`h`	`banner` Object	Integer	Height 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.
`pos`	`banner` Object	Integer	Ad position: 0 Unknown 1 Above the fold 3 Below the fold 4 Header 5 Footer 6 Sidebar 7 Fullscreen
`topframe`	`banner` Object	Integer	Specifies 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.
`battr`	`banner` Object	Array of Integers	Blocked creative attributes. See Table 6.3 in Open RTB Spec: Creative Attributes. If blank assume all types are allowed.
`bidfloor`	`imp` Object	Float	Bid floor for this impression (in CPM of bidfloorcur).
`site`	Bid Request Object	Object	Site where request is coming from (either send site or app not both)
`id`	`site` Object	String	Site ID on the exchange.
`name`	`site` Object	String	Site name (may be masked at publisher’s request).
`publisher`	`site` Object	Object	Information related to the publisher on the exchange
`id`	`publisher` Object	String	Publisher ID on the exchange.
`page`	`site` Object	String	URL of the page where the impression will be shown.
`domain`	`site` Object	String	Domain of the site, used for advertiser side blocking. For example, “foo.com”.
`ref`	`site` Object	String	Referrer URL that caused navigation to the current page.
`cat`	`site` Object	array of strings	Array of IAB content categories for the overall site. See Table 6.1 Content Categories
`user`	Bid Request Object	Object	The “user” object contains information known or derived about the human user of the device.
`buyeruid`	`user` Object	String	Buyer’s user ID for this user as mapped by exchange for the buyer.
`ext`	Bid Request Object	Object	This 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' Object	Integer	Is 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

Parameter	Object	Type	Description
`timestamp`	Bid Response	Integer	Time in EPOCH when impression happened.
`status`	Bid Response	Integer	Server code for status of response.
`headers`	Bid Response	Object	Top level info sent by exchange in the response.
`body`	Bid Response	Object	Content of the response.
`seatbid`	`body` Object	Object	Objects for each bidder seat for the auction with its bit and contents.
`bid`	`seatbid` Object	Array of Objects	Array 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.
`impid`	`bid` Object	String	ID of the impression object to which this bid applies.
`adm`	`bid` Object	String	Actual ad markup. XHTML if a response to a banner object, or VAST XML if a response to a video object.
`crid`	`bid` Object	String	Creative 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.
`adid`	`bid` Object	String	ID that references the ad to be served if the bid wins.
`adomain`	`bid` Object	Array of Strings	Advertiser’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.
`id`	`bid` Object	String	ID 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.
`price`	`bid` Object	Float	Bid price in CPM.
`cid`	`bid` Object	String	Campaign ID or similar identifier that appears within the ad markup.
`ext`	`bid` Object	Object	This 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.
`dspid`	`ext` Object	String	The ID of the DSP, as passed by the exchange.
`advbrandid`	`ext` Object	String	The ID of the advertiser, as passed by the exchange.
`advbrand`	`ext` Object	String	Name of the advertiser, as passed by the exchange.
`seat`	`seatbid` Object	String	ID of the bidder seat on whose behalf this bid is made.
`cur`	`body` Object	Array of Strings	An 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.
`id`	`body` Object	String	The ID of the bid request.
`ext`	`body` Object	Object	This 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` Object	Integer	Is 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:

Property	Description
`key`	The UserID of the user requesting the ad.
`decisions`	An object containing all placements from the request. In this example, there is one placement named "azk1."
`adId`	ID of the ad (creative mapped to flight).
`creativeId`	ID of the Kevel creative.
`flightId`	ID of the Kevel flight.
`campaignId`	ID of the Kevel campaign.
`impressionUrl`	The URL that, when hit, will count an impression in Kevel
`contents`	Object of the creative returned from Bidtellect.
`assets`	Object containing all creative assets.
`id`	Unique asset ID assigned by the exchange.
`title`	The title object, which defines the title element.
`text`	The creative's text string.
`img`	The Image object.
`url`	The URL of the creative image.
`w`	Width of the image.
`h`	Height of the image.
`ext`	Placeholder name for a custom object agreed to by Bidtellect and Kevel.
`viewabilitytrackers`	Viewable impression tracking link for the advertiser.
`link`	Click tracking link for the advertiser.
`imptrackers`	Impression tracking link for the advertiser.
`nurl`	The URL that, when called, indicates that the bid has won the auction.
`events`	Tracking 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" } }