Server to Server Integration

Overview

The TripleLift Server to Server integration is compliant with OpenRTB 2.2 Specs. This defines the structure for bid (combination of price, identifier, assets, etc.) request format and bid response format. This documentation will highlight items required by our Server to Server integration. Below you'll see the typical structure of a bid request and bid response object.

Endpoints

The Server to Server integration is initiated by a bid request from the client's server to this endpoint: "https://tlx.3lift.com/s2s/auction". TL will provide supplier id, which will be appended as query string in requests.

Bid Request

Bid Request Structure (Web)

Our server to server integration expects bid requests formatted with the following fields:

Parameter	Sub Parameter	Sub Parameter	Scope	Notes
id			Required	ID of the bid request
imp			Required	The imp array will consist of one object
imp	id		Required	This will always be "1"
imp	banner		Required	The TripleLift native implementation uses the Banner Object for native impressions
imp	banner	id	Optional	Client banner ID
imp	banner	w	Required	Banner width
imp	banner	h	Required	Banner height
imp	tagid		Required	This is a slot level identifier.
imp	bidfloor		Optional	Hard floor. TripleLift will not return bids below this number.
site			Recommended	The URL of the page the ad will be served onto.
site	id		Optional	Client ID for site
site	domain		Optional	Domain of site
site	page		Recommended	Full URL of site
site	publisher		Optional	Publisher of site
site	publisher	id	Optional	Client ID for publisher
site	publisher	name	Optional	Name of publisher
site	publisher	domain	Optional	Publisher Domain
device	-		Recommended	User's device data
device	ua		Recommended	Browser user agent string
device	ip		Recommended	Device IP address when available
device	geo		Optional
device	geo	country	Optional	Country. In ISO3
device	geo	region	Optional	Region
device	geo	metro	Optional	Designated Metropolitan Area (DMA)
device	geo	city	Optional	City
device	geo	zip	Optional	Zip Code
device	language		Recommended	User Language
device	make		Optional	Device make ("Apple")
device	model		Optional	Device Model ("iPhone")
device	os		Optional	Operating System ("iOS 9")
user	-		Required	Information on user
user	id		Optional	Client ID for user
user	buyeruid		Required	TripleLift user ID
user	geo		Optional	Geo location of user
user	geo	country	Optional	Country of user

Bid Request Sample (Web)

{
  "id": "SyKwQTKcTR0Uaq60I1DXoA",
  "site": {
    "id": "11f3cc632fa62d843fa080a76af1df44c02e41bf",
    "name": "website.co.uk",
    "domain": "website.co.uk",
    "ref": "https://t.co/izY76pbBbP",
    "keywords": "apse={\"shouldSampleLatency\":false,\"chunkRequests\":false}",
    "publisher": {
      "id": "376"
    },
    "page": "https://www.website.co.uk/tvshowbiz/article-6276669/Will-Worlds-Hottest-Grandma-OLDEST-Maxim-cover-girl-history.html"
  },
  "device": {
    "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 12_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/12.0 Mobile/15E148 Safari/604.1",
    "geo": {
      "country": "AR",
      "city": "Buenos Aires",
      "zip": "1871"
    },
    "ip": "190.137.17.208"
  },
  "ext": {
    "hb": 1
  },
  "imp": [
    {
      "id": "1wKqk3HPX1aO2xxTrsD3eA",
      "banner": {
        "w": 900,
        "h": 250,
        "pos": 0
      },
      "instl": 0,
      "tagid": "leader_bottom",
      "secure": 1
    }
  ],
  "at": 1,
  "cur": [
    "USD"
  ],
  "tmax": 300
}

Bid Request Structure (App)

Our server to server integration expects bid requests formatted with the following fields:

Parameter	Sub Parameter	Sub Parameter	Scope	Notes
id			Required	ID of the bid request
imp			Required	The imp array will consist of one object
imp	id		Required	This will always be "1"
imp	banner		Required	The TripleLift native implementation uses the Banner Object for native impressions
imp	banner	id	Optional	Client banner ID
imp	banner	w	Required	Banner width
imp	banner	h	Required	Banner height
imp	bidfloor		Optional	Hard floor. TripleLift will not return bids below this number.
app			Recommended	The URL of the page the ad will be served onto.
app	id		Optional	Client ID for site
app	name		Recommended	Application name (may be masked at publisher’s request).
app	domain		Optional	Domain of the application (e.g., “mygame.foo.com”).
app	cat		Optional	Array of IAB content categories for the overall application.
app	bundle		Required	Application bundle or package name (e.g., com.foo.mygame). This is intended to be a unique ID across multiple exchanges.
app	storeurl		Optional	i.e. "https://itunes.apple.com/app/id50234631398"
app	ext	iTunesId	Optional	i.e. "iTunesId": "50423631398"
app	keywords		Optional	List of keywords describing this app in a comma separated string.
app	publisher		Optional	Publisher of site
app	publisher	id	Optional	Client ID for publisher
app	publisher	name	Optional	Name of publisher
app	publisher	domain	Optional	Publisher’s highest level domain name, for example “foopub.com”.
device	-		Recommended	User's device data
device	ifa		Required	Native identifier for advertisers; an opaque ID assigned by the device or browser for use as an advertising identifier.
device	ua		Recommended	Browser user agent string
device	ip		Recommended	Device IP address when available
device	geo		Optional
device	geo	country	Optional	Country. In ISO3
device	geo	region	Optional	Region
device	geo	metro	Optional	Designated Metropolitan Area (DMA)
device	geo	city	Optional	City
device	geo	zip	Optional	Zip Code
device	language		Recommended	User Language
device	make		Optional	Device make ("Apple")
device	model		Optional	Device Model ("iPhone")
device	os		Optional	Operating System ("iOS 9")
user	-		Required	Information on user
user	id		Optional	Client ID for user
user	geo		Optional	Geo location of user
user	geo	country	Optional	Country of user

Bid Request Sample (App)

{
  "id": ".7-amQa.APqP.TIkiL7VsQ",
  "app": {
    "id": "f78a9a4efd9446118c21b44a4a7b360a",
    "name": "Binghamton Daily - iOS - mDTB",
    "keywords": "TEST",
    "publisher": {
      "id": "4656"
    },
    "ext": {
      "iTunesId": "50423631398"
    },
    "bundle": "504631398",
    "storeurl": "https://itunes.apple.com/app/id50234631398"
  },
  "device": {
    "h": 736,
    "w": 414,
    "lmt": 0,
    "make": "Apple",
    "model": "iPhone10,5",
    "os": "iOS",
    "osv": "12.0.1",
    "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 12_0_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/16A404",
    "ifa": "5A4CA1AF-5694-4B34-9871-3DBF544EA839",
    "geo": {
      "country": "US",
      "city": "Binghamton",
      "zip": "21236"
    },
    "ext": {
      "idfa": "5A4CA1AF-5694-4B34-9871-3DBF544EA839",
      "idfasha1": "6ea507fdf6df11c5918cffa1549e068b58a18bc3"
    },
    "connectiontype": 6,
    "ip": "107.77.202.202"
  },
  "ext": {
    "hb": 1
  },
  "imp": [
    {
      "id": ".7-amQa.APqP.TIkiL7VsQ",
      "banner": {
        "w": 300,
        "h": 250,
        "pos": 0
      },
      "instl": 0,
      "tagid": "b99fb24e-1b92-4c97-8c39-198f944b66f9",
      "secure": 1
    }
  ],
  "at": 1,
  "cur": [
    "USD"
  ],
  "tmax": 400
}

Bid Response

Bid Response (Web and App)

Our response will contain the following fields:

Parameter	Sub Parameter	Sub Parameter	Scope	Notes
id			Required	ID of the bid request
seatbid			Required	Array of seatbid objects
seatbid	bid		Required	Array of bid objects
seatbid	bid	id	Required	ID for the bid object chosen by the bidder for tracking and debugging purposes. Useful when multiple bids are submitted for a single impression for a given seat.
seatbid	bid	impid	Required	This will always be "1"
seatbid	bid	price	Required	Bid Price in CPM
seatbid	bid	adm	Required	Ad Markup. This can just be placed on the page where the ad should render.
cur			Optional	Currency of bid response

Bid Response Sample (Web and App)

{ 
   "id":"14_132",
   "seatbid":[ 
      { 
         "bid":[ 
            { 
               "id":"182826794766055180",
               "impid":"1",
               "price":0.779999,
               "adm":"<script>document.createElement('IMG').src=\"https://tlx.3lift.com/s2s/notify?px=1&amp;aid=182826794766055180&amp;n=CAERAAAAAAAAAAAaRWh0dHA6Ly9lYzItNTItNTctNDAtNjAuZXUtY2VudHJhbC0xLmNvbXB1dGUuYW1hem9uYXdzLmNvbTo4MDc3L25vdGlmeSCLvz4oz%2F8uMN%2FNLzgAQABIAVAAYLDjLWgCcK40ei0IzhcQjJsBGLQOILASKL0TML%2FsFDiljgFCC1RydXRoRmluZGVySAFYJGABcAGAAeSSA4gBAJABAPgBAIACAIgCAZACAJgCAA%3D%3D\";window.tl_auction_response_388859=\"dynamicCreativeRender({\\\"settings\\\":{\\\"advertiser_name\\\":\\\"TruthFinder\\\",\\\"type\\\":\\\"image\\\",\\\"additional_data\\\":{\\\"bmid\\\":\\\"3022\\\",\\\"ts\\\":\\\"1474300882\\\",\\\"clid\\\":\\\"18213\\\",\\\"brid\\\":\\\"19852\\\",\\\"tid\\\":\\\"341567\\\",\\\"aid\\\":\\\"182826794766055180\\\",\\\"advid\\\":\\\"1844\\\",\\\"liid\\\":\\\"2493\\\",\\\"ioid\\\":\\\"2352\\\"},\\\"format_id\\\":1,\\\"render_options_bm\\\":0},\\\"assets\\\":[{\\\"asset_id\\\":51556,\\\"image_id\\\":3349230,\\\"image_url\\\":\\\"\\/\\/images.3lift.com\\/3349230.jpg\\\",\\\"image_width\\\":1024,\\\"image_height\\\":536,\\\"heading\\\":\\\"Type&nbsp;In&nbsp;Your&nbsp;Name(or&nbsp;anyone\\'s)&nbsp;-&nbsp;This&nbsp;is&nbsp;Addicting\\\",\\\"caption\\\":\\\"Just&nbsp;type&nbsp;in&nbsp;a&nbsp;Name&nbsp;and&nbsp;select&nbsp;a&nbsp;State..&nbsp;Then&nbsp;brace&nbsp;yourself&nbsp;for&nbsp;what&nbsp;you&nbsp;might&nbsp;find&nbsp;on&nbsp;you&nbsp;or&nbsp;anyone&nbsp;else!\\\",\\\"clickthrough_url\\\":\\\"http:\\/\\/tracking.truthfinder.com\\/?a=353&amp;oc=27&amp;c=303&amp;dip=&amp;s1=Add&amp;s2=Shadow&amp;s3=Desktop\\\",\\\"img_server_params\\\":\\\"v=9\\\"}]});\";&lt;/script&gt;&lt;script&nbsp;src=\"//ib.3lift.com/ttj?inv_code=androidcentral_all_rightrail_btf\"&nbsp;data-auction-response-id=\"388859\"&gt;&lt;/script>"
            }
         ]
      }
   ],
   "cur":"USD"
}