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