Recommendation Request¶

To get recommendations, you need to send a stripped down Open RTB bid request to LiteSwitch. The Open RTB fields used by LiteSwitch are described in the Bid Request Object section. In addition to the standard subset of fields expected for a valid bid request, LiteSwitch requires one additional unique field, the ext.seat_user_matched field.

The values in the imp.id and wseat fields are used to define which Buyers to target with each adslot in the subsequent response.

User Matched Object¶
Value	Type	Description
seat_user_matched	array of strings	(Optional) Indicates the buyers with whom you have synced users, the values should match some of those sent in the `wseat`.

Note

Fields marked with * are either recommended or optional

Bid Request Object¶

Bid Request Object Properties¶
Value	Type	Description
id	string	(Required) Unique ID of the bid request, for example, `"b5ba5ed2-547e-4e86-8a84-34a440dad6db"`
imp	array of objects	(Required) Array of objects representing the impressions offered. Must contain at least one Impression Object.
device*	object	(Recommended) Device Object with details about the device to which the impression will be delivered
site	object	(Required if `app` is not present) The Site Object describing the site. Either `Site`, or `App` must be present.
app	object	(Required if `site` is not present) The App Object describing the mobile application. Either `Site`, or `App` must be present.
wseat	array of strings	(Required) An array of Buyer seats allowed to bid on this auction, for example [“58”, “61”, “99”]. A bid request may contain multiple seat IDs using the Supplier taxonomy. The bid response should contain the appropriate seat value corresponding to one of the values of the `wseat` field
user*	object	(Recommended) User Object which describes the user.
source*	object	(Optional) Source Object Indicates the entity responsible for the final impression sale decision.
at*	integer	(Optional) Auction type, the default value is `2` `1`: the first price auction `2`: the second price auction
ext*	object	(Optional) Ext Object used for Supplier specific properties

Device Object¶

Device Object Properties¶
Value	Type	Description
geo*	object	(Recommended) Geo Object as derived from the device’s location services, or supplied by the Supplier if the device IP is missing. For more information, see the Geo Object Properties section.
ip*	string	(Semi-Required) Specifies the IPv4 address closest to the device. One of IP or IPv6 required Required for almost all requests, any containing invalid IP addresses will be discarded based on IP Validation e.g. `87.224.77.0` Note: This field is only optional for Connected TV inventory
ipv6*	string	(Semi-Required) One of IP or IPv6 required. IP address in IPv6, for example, `fe80:0:0:0:200:f8ff:fe21:67cf`
ua*	string	(Recommended) Browser or application user agent string, for example, `"Mozilla/5.0 (Windows NT 6.3; WOW64; rv:35.0)Gecko/20100101Firefox/35.0"`
language*	string	(Optional) Alpha-2/ISO 639-1 code of browser language, for example, `en`
model*	string	(Optional) Device mode, for example, `iPhone`
os*	string	(Optional) Device operating system, for example, `iOS`
osv*	string	(Optional) Device operating system version, for example, `3.1.2`
ifa*	string	(Optional) In-app user ID

Device Geo Object¶

Geo Object Properties¶
Value	Type	Description
country*	string	(Recommended) Country using `ISO-3166-1` Alpha-2, for example `NL`
region*	string	(Recommended) Region using ISO-3166-2 region codes, for example, `NY`
lat*	float	(Recommended) Latitude from -90 to 90, for example, `52.35`. South is negative.
lon*	float	(Recommended) Longitude from -180 to 180, for example, `4.9167`. West is negative.
city*	string	(Optional) City name.

Impression Object¶

Impression Object Properties¶
Value	Type	Description
id	string	(Required) ID of the impression being shown, unique within the bid request, for example `"1"`
banner	object	Required for banner impressions.
video	object	Required for video impressions.
audio	object	Required for audio impressions.
native	object	Required for native impressions.
tagid*	string	(Recommended) Identifier for specific ad placement or ad tag that was used to initiate the auction.
secure*	integer	(Recommended) Specifies if the page is SSL compliant: `0`: for insecure pages, the default value. `1`: for secure pages. Creative assets for secure pages should be SSL-compliant.
pmp*	object	(Optional) The private marketplace used for direct deals between Buyers and Suppliers.
instl*	integer	(Optional) Specifies if the ad is an interstitial. `0` = not interstitial, the default value. `1` = the ad is interstitial or full screen
rwdd*	integer	(Optional) whether the user receives a reward for viewing the ad, where `0` = no, `1` = yes. Typically video ad implementations allow users to read an additional news article for free, receive an extra life in a game, or get a sponsored ad-free music session. The reward is typically distributed after the video ad is completed.
bidfloor*	float	(Optional) Bid floor in CPM as set by the Supplier, for example, `0.01080`

Impression Banner Object¶

Banner Object Properties¶
Value	Type	Description
pos*	integer	(Recommended) Ad Position as defined in the OpenRTB protocol, for example, `1`
topframe*	integer	(Recommended) Indicates if the banner is in the top frame where `0` is No, `1` is Yes
w*	integer	(Recommended) Width of the impression in pixels, for example, `300`
h*	integer	(Recommended) Height of the impression in pixels, for example `250`
format*	array of objects	(Optional) An array of banner format objects denoting the alternative sizes that may be used for bidding.

Banner Format Object¶

Banner Format Object Properties¶
Value	Type	Description
w*	integer	(Optional) Width of the impression in pixels, for example, `300`
h*	integer	(Optional) Height of the impression in pixels, for example `250`

Impression Video Object¶

Video Object Properties¶
Value	Type	Description
w*	integer	(Recommended) Width of the impression in pixels, for example, `300`
h*	integer	(Recommended) Height of the impression in pixels, for example `250`
maxduration*	integer	(Optional) Maximum video ad duration in seconds, for example, `15`

Impression Private Marketplace Object¶

Private Marketplace Object Properties¶
Value	Type	Description
private_auction*	integer	(Recommended) A value of `1` indicates that only bids submitted inside pmp. Deals will take part in the auction. A value of `0` indicates that bids without deal information may also be considered for serving
deals	array of objects	(Required) Array of Deals objects

Deals Object¶

Deals Object Properties¶
Value	Type	Description
id	string	(Required) Deal ID, for example, `AA-1234` Note: Do not use any of the following symbols in the Deal ID, as doing so will result in request invalidation: , # % $ @ * & ? ! ` ~ " ' / \ \| ( ) { } [ ]+ = ^ :
wseat*	array of strings	(Optional) Array of Buyer seats allowed to bid on this Direct Deal, for example, [“58”, “99”].

Site Object¶

Site Object Properties¶
Value	Type	Description
publisher	object	(Required) Publisher object
id*	string	(Recommended) An exchange specific identifier.
domain*	string	(Recommended) Domain of the site, used for advertiser side blocking. `"testsite.com"`
page*	string	(Recommended) URL of the page where the impression will be shown. `"http://testsite.com/main.asp"`

App Object¶

App Object Properties¶
Value	Type	Description
publisher	object	(Required) Publisher object
id*	string	(Recommended) The application ID.
domain*	string	(Recommended) The domain of the app, for example, `"mygame.example.com"`
bundle*	string	(Recommended) Application bundle or package name, for example, `"com.example.mygame"`

Publisher Object¶

Publisher Object Properties¶
Value	Type	Description
id	string	(Required) Exchange-specific publisher ID, e.g `"abc-123"`. Note: Do not use any of the following symbols in the publisher ID, as doing so may cause issues: , # % $ @ * & ? ! ` ~ " ' / \ \| ( ) { } [ ]+ = ^

User Object¶

User Object Properties¶
Value	Type	Description
id	string	(Recommended) Website user ID
buyeruid*	string	(Optional) Buyer-specific ID for the user as mapped by the exchange for the Buyer

Source Object¶

Source Object Properties¶
Value	Type	Description
schain*	object	(Optional) This object represents both the links in the supply chain as well as an indicator whether or not the supply chain is complete.

SupplyChain Object¶

SupplyChain Object Properties¶
Value	Type	Description
complete	integer	(Required) Flag indicating whether the chain contains all nodes involved in the transaction leading back to the owner of the site, app or other medium of the inventory, where `0` = no, `1` = yes.

Example Request¶

The following example includes all possible fields. In practice, only app fields are expected for in-app inventory and likewise site for website inventory.

Complete Banner Example¶

{
  "site": {
    "id": "ed2265d8",
    "page": "http://ad32.answers.com/click.php?source=fb&param4=fb-us-de-red&param3=www.answers.com%2Farticle%2F31029589%2Finsanely-useful-life-hacks-to-make-everything-easier&param1=tattoo&param2=67660042&param5=10153631993521186&param6=6049542139960&adt=4342",
    "publisher": {
      "id": "946353442_12535"
    },
    "domain": "answers.com"
  },
  "wseat": [
    "165",
    "16"
  ],
  "ext": {
    "seat_user_matched": [
      "16"
    ]
  },
  "user": {
    "id": "5e29eb00-c30a-416e-9d2a-2e18901f0916",
    "buyeruid": "CAESEHL-9O4oJOAiC1Y0O2EHTcE"
  },
  "device": {
    "language": "en",
    "model": "G100",
    "w": 1920,
    "geo": {
      "country": "US",
      "region": "FL"
    },
    "osv": "11",
    "h": 1080,
    "ua": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:47.0) Gecko/20100101 Firefox/47.0"
  },
  "imp": [
    {
      "pmp": {
        "private_auction": 1,
        "deals": [
          {
            "id": "14a44.a7993.d401",
            "wseat": "abc123"
          }
        ]
      },
      "id": "1",
      "banner": {
        "topframe": 1,
        "pos": 1,
        "h": 600,
        "w": 160
      },
      "tagid": "25108",
      "secure": 0
    }
  ]
}