Header Bidding API

Header Bidding API

API Overview

Header Bidding Platforms

This API can be used to request ads on Desktop and Mobile web. It is not intended for in-app usage.

API Format

This API was made to resemble the openRTB 2.3 format in order to increase general familiarity, and ease integration work. Only a limited number of openRTB parameters are supported in this API.


API Ad Request

Request Endpoint

  • The request endpoint for this API is: http://media.msg.dotomi.com/s2s/header

  • The API uses the POST HTTP request method and will not accept requests using GET, PUT, or DELETE.

  • There is no test endpoint, all ad requests will be received via the live API endpoint.

  • The request URL supports both secure (HTTPS/SSL) and non-secure requests.

Request Headers

  • No additional HTTP headers are required to successfully request ads from this API.

Request Parameters

Bid Request

Element Required Data Type Description Example
id REQUIRED String Unique ID for this ad request, provided by the exchange. "id" : "f24b0ff4-9bdb-4f00-b5ef-80a7437892a3"
imp REQUIRED Array Array of impression placement descriptions for this ad request. "imp" : [{...}]
site REQUIRED Object Object that described the site from which the ad request originated. "site" : {...}
device REQUIRED Object Object that describes the device on which the impression will be displayed. "device" : {...}
at REQUIRED Integer Auction type, should always equal 1 for "First Price". "at" : 1
user OPTIONAL Object Object that describes the user of the device in which the impression will be displayed. "user" : {...}

Imp Object

Element Required Data Type Description Example
id REQUIRED String A unique identifier for this impression within the context of the bid request. Typically starts at 1. "id" : "1"
banner REQUIRED Object Describes the banner impression opportunity. "banner" : {...}
displaymanager REQUIRED String Conversant provided identifier for the mediation partner or technology responsible for rendering the ad. "id" : ""
displaymanagerver REQUIRED String The version of the mediation partner, SDK, player, or other technology responsible for rendering the ad. "id" : "1.0.0"
bidfloor OPTIONAL Float Minimum bid for this impression expressed in CPM. "bidfloor" : 0.50
instl OPTIONAL Integer If the impression opportunity is for an interstitial placement. 0 for a non-interstitial placement, 1 for an interstitial placement.
If not provided, defaults to non-interstitial.
"instl" : "0"
clickbrowser OPTIONAL Integer Indicates the type of browser opened upon clicking the creative in an app, where 0 = embedded, 1 = native.
Note that the Safari View Controller in iOS 9.x+ devices is considered a native browser for the purposes of this attribute.
"clickbrowser" : "1"
secure OPTIONAL Integer If the impression requires secure HTTPS URL creative assets and markup. 0 for non-secure, 1 for secure.
If omitted, non-secure is assumed.
"secure" : 0
exp OPTIONAL Integer Advisory as to the number of seconds that may elapse between the auction and the actual impression. "exp" : 180

Banner Object

Element Required Data Type Description Example
h REQUIRED Integer Impression height in pixels. "h" : 50
w REQUIRED Integer Impression width in pixels. "w" : 320
pos OPTIONAL Integer Ad position on screen.
api OPTIONAL Array An array of the supported API frameworks for this impression. See API Framework Table in References.

Site Object

Element Required Data Type Description Example
id REQUIRED String The Conversant provided site ID. "id" : "54321"
mobile REQUIRED Integer Indicates whether the site is mobile optimized. "mobile" : 0
page OPTIONAL String URL of the page where the impression will be shown. "page" : "http://test.com/test/page"
privacypolicy OPTIONAL Integer If the site has a privacy policy. 0 for no, 1 for yes. "privacypolicy" : 1

Device Object

Element Required Data Type Description Example
ip REQUIRED String The IPv4 address of the device. "ip" : "54.74.144.20"
ua REQUIRED String The browser user agent string. "ua" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36"
geo OPTIONAL Object Location of the device, assumed to be the user's current location. "geo" : {...}
dnt OPTIONAL Integer Standard "Do Not Track" flag. 0 for unrestricted tracking, 1 for no tracking. If omitted, unrestricted tracking is assumed. "dnt" : 1
lmt OPTIONAL Integer "Limit Ad Tracking" flag. 0 for unrestricted tracking, 1 for limited tracking per commercial guidelines. If not present, unrestricted tracking. If omitted, unrestricted tracking is assumed. "lmt" : 0
devicetype OPTIONAL Integer The type of device. See Device Type Table in References. "devicetype" : 2
make OPTIONAL String Device manufacturer or maker. "make" : "Google Inc."
model OPTIONAL String Model of device. "model" : "iPhone"
make OPTIONAL String Device manufacturer or maker. "make" : "Apple Inc."
os OPTIONAL String Device operating system. "os" : "iOS"
osv OPTIONAL String Device operating system version. "osv" : "10.01"
hwv OPTIONAL String Hardware version of the device. "osv" : "6S"
h OPTIONAL Integer Physical height of the screen in pixels. "h" : 1920
w OPTIONAL Integer Physical width of the screen in pixels. "w" : 1080
pxratio OPTIONAL Integer The ratio of physical pixels to density independent pixels. "pxratio" : 2
language OPTIONAL String Browser language using ISO-639-1-alpha-2 "language" : "en"
carrier OPTIONAL String Carrier, ISP, or indicator of Wi-Fi "carrier" : "WIFI"
connectiontype OPTIONAL Integer Network connection type "connectiontype" : 1

Geo Object

Element Required Data Type Description Example
lat OPTIONAL Float Latitude from -90.0 to +90.0, where negative is south. "lat" : 34.15101
long OPTIONAL Float Longitude from -180.0 to +180.0, where negative is west. "lat" : 34.15101
type OPTIONAL Integer Source of location data, recommended when passing lat/long. Refer to Geo Type Table in References. "type" : 1
accuracy OPTIONAL Integer Estimated location accuracy in meters; recommended when lat/long are specified and derived from a device's location services. "accuracy" : 3
lastfix OPTIONAL Integer Number of seconds since this geolocation fix was established. Note that devices may cache location data across multiple fetches. Ideally, this value should be from the time the actual fix was taken. "lastfix" : 30
ipservice OPTIONAL Integer Service or provider used to determine geolocation from IP address if applicable. "ipservice" : 2
country OPTIONAL String Country code using ISO-3166-1-alpha-3 "country" : "US"
region OPTIONAL String Region code using ISO-3166-2. 2 letter state code if USA. "region" : "CA"
metro OPTIONAL String DMA code "metro" : "803"
city OPTIONAL String City using United Nations Code for Trade & Transport Locations "city" : "Apple Valley"
zip OPTIONAL String ZIP or Postal Code "zip" : "91359"

User Object

Element Required Data Type Description Example
id OPTIONAL String Exchange specific ID for the user. "user" : "c2aed5ee-8e00-46d4-b8fa- e677c1b4d52b"

Request Ad Size Options

These are the ad sizes available through the Conversant Header Bidding API:

Ad Type Request Requirements Ad Size Returned
Medium Rectangle banner.w = 300, banner.h = 250 300x250
Leaderboard banner.w = 728, banner.h = 90 728x90
Banner banner.w = 468, banner.h = 60 468x60
Small Banner banner.w = 320, banner.h = 50 320x50
Skyscraper banner.w = 120, banner.h = 600 120x600
Wide Skyscraper banner.w = 160, banner.h = 600 160x600

Request Query Examples

An example of the Conversant Header Bidding Request JSON object:


   "id":"3880112941c5e",
   "imp":[ 
      { 
         "id":"1",
         "banner":{ 
            "w":300,
            "h":250
         },
         "displaymanager":"example_partner",
         "displaymanagerver":"0.0.1"
      }
   ],
   "site":{ 
      "id":"97464",
      "mobile":0
   },
   "device":{ 
      "ua":"Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/50.0.2661.102 Safari/537.36"
   },
   "at":1
}

API Ad Responses

HTTP Response Status Codes

Conversant Server Side API responses mapped to standard HTTP response codes:

Code Name Category Definition Reason
200 OK 2xx: Success Indicates a nonspecific success. Ad request filled.
204 No Content 2xx: Success Response successful but not filled. Ad request accepted but not filled.
400 Bad Request 4xx: Client Error Indicates a nonspecific client error. Request was incorrect or missing parameters.
401 Unauthorized 4xx: Success Indicates client either provided invalid credentials or forgot to send them. Client had invalid credentials (Site ID is invalid or disabled).
401 Unauthorized 4xx: Success Indicates client either provided invalid credentials or forgot to send them. Client had invalid credentials (Site ID is invalid or disabled).
500 Internal Server Error 5xx: Server Error Tells the client that the API is having problems of its own. Used whenever a bad ad or other error occurs.
503 Service Unavailable 5xx: Server Error Tells the client that the API is overloaded or down. Used in the unlikely event that the Ad Server is offline or unavailable.

Response Parameters

Ad Response

Element Data Type Description
id String Unique ID for this ad request, provided by partner.
seatbid Object Array Array of impression placement descriptions for this ad request.
cur String Currency using ISO-4217 alpha codes. Default "USD"

Seatbid

Element Data Type Description
bid Object Array Array of bid objects each related to an impression. Multiple bids can relate to the same impression.

Bid

Element Data Type Description
id String Generated ID to assist with logging/tracking
impid String ID of the imp object in the related ad request.
price Float Bid Price of impression expressed as CPM although the actual transaction is for a unit impression only.
adm String Contains the ad markup
nurl String Contains the Conversant impression tracker.
adomain Array Advertiser domain for block list checking.
iurl String URL without cahce-busting to an image that is representative of the content of the campaign for ad quality / safety checking.
crid String Campaign ID to assist with ad quality checking; the collection of creatives for which the iurl should be representative.

Ad Response Examples

window.pbjs.conversantResponse({"cur" : "USD","seatbid" : [{"bid" : [{"nurl" : "http://media.msg.dotomi.com/w/impix.cgi?sid=97464&mid=2139779&tp=8&d=j&t=n&sys=1&nozzle=11&format=fragment&upsid =89327625397824&UD=CQAAAAAAAOA-EQAAAAAAAAAAGQAAAAAAAAAAIThm2ZPA5iw- KAAwADgDSPQDUABiDTM4ODAxMTI5NDFjNWV6JGRmNzk5ZWQyLTE1M2QtNGMyNi1hYjZiLWE4YzQxNjk0ZDA3MYIBEjUxMzMzNTIz OTE1NzYxODYxMogBg82CAZABob_fBZgBuPkFoAEGqAEIwAEA8AEAoAIAqAIAsgIPMTM0LjIwMS4yNTAuMTU1wAK4lAHwAgGYAwSgA 34&cid=11001761","adm" : "<script type="text\/javascript" src="https:\/\/voken.eyereturn.com\/?1331277&click=http://media.msg.dotomi.com/w/click.here?cid=11001761;mid=2139779;m =6;sid=97464;c=0;tp=8;UD=CQAAAAAAAOA-EQAAAAAAAAAAGQAAAAAAAAAAIThm2ZPA5iw- KAAwADgDSPQDUABaDjg5MzI3NjI1Mzk3ODI0Yg0zODgwMTEyOTQxYzVleiRkZjc5OWVkMi0xNTNkLTRjMjYtYWI2Yi1hOGM0MTY5NG QwNzGCARI1MTMzMzUyMzkxNTc2MTg2MTKIAYPNggGQAaG- nwWYAbj5BaABBqgBCMABAPABAKACAKgCALICDzEzNC4yMDEuMjUwLjE1NcACuJQB8AIBmAMEoAN_;upsid=89327625397824;force d_click=¶ms=20160725213818"><\/script><script type="text\/javascript">(function(){document.write('<span id="1617132345"><sc'+'ript type="text\/javascript" src="'+(("https:"==document.location.protocol)?"https:\/\/s- ":"http:\/\/")+'usweb.dotomi.com\/adinfo\/script\/prod\/?w=300&h=250&cid=2000&plc=tr&lang=&loc=us&optout_options=glo bal"><\/scr'+'ipt><\/span>');}());<\/script>\n","crid" : "2139779","impid" : "1","price" : 0.220500,"adomain" : ["http://www.kimcrawfordwines.com"],"iurl" : "http://media.msg.dotomi.com/w/win.bid?sid=97464&mid=2139779&tp=8&d=j&t=n&sys=1&nozzle=11&format=fragment&upsid= 89327625397824&UD=CQAAAAAAAOA-EQAAAAAAAAAAGQAAAAAAAAAAIThm2ZPA5iw- KAAwADgDSPQDUABiDTM4ODAxMTI5NDFjNWV6JGRmNzk5ZWQyLTE1M2QtNGMyNi1hYjZiLWE4YzQxNjk0ZDA3MYIBEjUxMzMzNTIz OTE1NzYxODYxMogBg82CAZABob_fBZgBuPkFoAEGqAEIwAEA8AEAoAIAqAIAsgIPMTM0LjIwMS4yNTAuMTU1wAK4lAHwAgGYAwSgA 34"}]}],"id" : "3880112941c5e"})

API Ad Events

Conversant ads will fire a variety of different events for tracking impressions, click-throughs, and other actions. Common trackers are outlined below.

Impression Tracker

The Conversant Impression tracker will be present in the bid.nurl field of the bid response. The nURL must be called when the Conversant ad is rendered in order to properly record the ad impression. In the case of a secure (SSL) bid request, a secure version of the nURL will be returned.

Impression Tracker Endpoint http://media.msg.dotomi.com/w/impix.cgi https://secure-media.msg.dotomi.com/w/impix.cgi

https://secure- media.msg.dotomi.com/w/impix.cgi?sid=84002&mid=2136346&tp=8&d=j&t=n&sys=1&nozzle=11&format=fragment&upsid=35060 631133472&UD=CQAAAAAAABhAEQAAAAAAAAAAGQAAAAAAAAAAIZ3c71AU6GM- KAAwADgDSKgoUABiDzUwMDI2OWU0OTVhNmMyYXokMzNlY2U4ZmItNjNiOC00NGZjLTkxMDEtYTQ3OTA2Nzc5NWU0ggESMjk3Mz M0NjgzNzk5MTg5NzM0iAGasoIBkAGVxZ8FmAGikAWgAQaoAQjAAQDwAQCgAgCoAgCyAg42NC4xNTYuMTY3LjE2MMACuJQB8AIBmA MEoAN_&cid=11002517

Click Tracker

The Conversant click tracker will fire upon a click, in case of a secure (SSL) request, secure versions of these trackers will be returned.

Click Tracker Endpoints

  • http://media.msg.dotomi.com /w/clk.notify
  • https://secure-media.msg.dotomi.com /w/clk.notify
  • http://media.msg.dotomi.com/w/click.here
  • https://secure-media.msg.dotomi.com/w/click.here
http://media.msg.dotomi.com/w/clk.notify?cid=612270&mid=2080825&m=17&sid=84002&c=0&tp=19&UD=WhIzOTk2MjM4MjMx MzYzNzg2OTKIAbmAf5ABrq8lmAGikAWgARGoARPqAScwOzc7MTE7MTswOzIuMC4yLmNzczsyLjEuMC5qczs2NTE1MTA2ODDwAQCy Ag44Ni4xODMuMTczLjE0NtICJDg0OTA3OTUxLUJEMzItNEEzQi1CNTg2LTAyNDczRDdEMEMyMvACA5gDA6ADBA&upsid=3996238231 36378692&sys=15&idfa=84907951-BD32-4A3B-B586-02473D7D0C22&z=1457742045944440&oadest=
http://media.msg.dotomi.com/w/click.here?cid=596339&mid=2013582&m=16&sid=87293&c=0&tp=18&UD=WhIzOTk2MjM4MjMx MzYzNzg2OTKIAY7zepAB87IkmAH9qQWgARCoARLqAScwOzc7MTE7MTswOzIuMC4yLmNzczsyLjEuMC5qczs2NTE1MTA2ODDwAQCy Ag44Ni4xODMuMTczLjE0NtICJDg0OTA3OTUxLUJEMzItNEEzQi1CNTg2LTAyNDczRDdEMEMyMvACApgDA6ADBA&upsid=3996238231 36378692&sys=15&idfa=84907951-BD32-4A3B-B586-02473D7D0C22

Reference

API Frameworks

Value Description
1 VPAID 1.0
2 VPAID 2.0
3 MRAID 1.0
4 ORMMA
5 MRAID 2.0

Device Types

Value Description
1 Mobile/Tablet
2 Personal Computer
3 Connected TV
4 Phone
5 Tablet
6 Connected Device
7 Set Top Box

Ad Position

Value Description
0 Unknown
1 Above the Fold
2 DEPRECATED
3 Below the Fold
4 Header
5 Footer
6 Sidebar
7 Full Screen

Geo Type

Value Description
1 GPS/Location Services
2 IP Address
3 User Provided

IP Location Services

Value Description
1 Ip2location
2 Neustar (Quova)
3 MaxMind