RTB Sell Documentation

This page describes Real-Time bidding using OpenRTB. When appropriate, partner sends a BidRequest object to a Sourceknowledge Real-time Bid URL. Each bid request contains a BidRequest object, a single Imp object, and may include other objects to provide additional information about the impression.

Request Example

{
  "id" : "2e170e9b9a3bc22c8f8e9f5a41ed9879",
  "imp" : [
    {
      "id" : "2e170e9b9a3bc22c8f8e9f5a41ed9879-001",
      "bidfloor" : 0.5,
      "native" : {
        "ext" : {
          "url" :"https://some-advertiser.com/some-url",
          "phrase" : "",
          "context": ""
        }
      }
    } ],
  "site" : {  
    "domain": "referral-domain-example.com", 
    "publisher" : {
      "id": "some-unique-publisher-id"
    }
  },
  "device" : {
    "ua" : "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/86.0.4240.75 Safari/537.36",
    "ip" : "70.58.114.84",
    "devicetype" : 1
  },
  "user" : {
    "id" : "24be3d8571494db20101d6d9093c0e5c"
  },
  "test" : 1
}

Field	Type	Description	Required?

Field	Type	Description	Required?
id	string	A unique ID for the request, which partner uses to identify the auction. We will return this back as part of response.	Always
imp	object	An object containing properties that describe the ad impression for which Partner is soliciting bids.	Always
site	object	An object containing properties that describe the website where the ad will display. At least the publisher ID must be provided	Always
device	object	An object containing properties that describe the user’s device. At least the user agent and IP address must be provided.	Always
user	object	An object containing properties that describe the user viewing the impression	Sometimes
test	integer	Used for testing only. Value ‘1' to enable. Makes all bid values 0	No

BidRequest.imp

Field	Type	description	Required?

Field	Type	description	Required?
id	string	A unique, user-defined ID assigned to each individual click. Each click should have a different ID for click-level tracking.	Always
native	object	An object containing properties that describe a native ad impression opportunity. A Native object is always sent for native ad impression opportunities.	Always
bidfoor	float	Minimum bid accepted. Zero if no bid floor.	Always

BidRequest.imp.native

Field	Type	Description	Required?

Field	Type	Description	Required?
ext	object	object that describe a native ad impression opportunity	Always

BidRequest.imp.native.ext

Field	Type	Description	Required?

Field	Type	Description	Required?
url	string	Url to the merchant or product that is being auctioned	Always
userid	string	ID of the Commerce user from which the request originated	Sometimes
phrase	string	Phrase being bid on	Sometimes
context	string	Additional helper keywords that add context to the phrase	Sometimes

BidRequest.site

Field	Type	Description	Required?

Field	Type	Description	Required?
id	string	The ID for the site associated with this inventory purchase	Optional
domain	string	Domain of the site (Referral Domain)	Optional
page	string	URL of the page where the click happened. (Referral Url)	Optional
publisher.id	string	Sub ID (AKA Source ID)	Always

BidRequest.device

Field	Type	Description	Required?

Field	Type	Description	Required?
ua	string	User Agent	Always
ip	string	IP Address (IPV4) with last octet obfuscated for GDPR/CCPA regions	Always
devicetype	integer	The detected device category for the user’s device as defined in the OpenRTB specification.	Always

BidRequest.user

Field	Type	Description	Required?

Field	Type	Description	Required?
id	string	User ID from publisher	Sometimes

Response Example

{
   "id":"2e170e9b9a3bc22c8f8e9f5a41ed9879",
   "seatbid":[
      {
         "bid":[
            {
               "id":"5f8726e8-defa-4cfa-865d-acee9993cf3d00a",
               "impid":"2e170e9b9a3bc22c8f8e9f5a41ed9879-001",
               "price":0,
               "adm":"{\"native\":{\"link\":{\"url\":\"https://lg.provenpixel.com/ck.php?oaparams=2__bannerid=65157__zoneid=7798__OXLCA=1__cb=ceur8824d__x_udomain=www.mytestsite.com__x_pid3=moc-na__vtag=I:5f8726e8-defa-4cfa-865d-acee9993cf3d00a;__oadest=https%3A%2F%2Fsome-advertiser.com%2Fsome-url\"}}}"
            }
         ],
         "seat":"sourceknowledge"
      }
   ],

The above response is from using test mode where the only difference is the bid price is always 0.

BidResponse.seatbid

Field	Type	Description	Returned?

Field	Type	Description	Returned?
bid	array	An object describing bid information	Always when HTTP 200
seat	string	Bidder ID	Always when HTTP 200

BidResponse.seatbid.bid

Field	Type	Description	Returned?

Field	Type	Description	Returned?
id	string	A response ID generated by the bidder for tracking purposes.	Always
impid	string	The ID of the Imp object to which this bid applies. BidRequest.imp.id	Always
price	float	The bid price, expressed as CPC	Always
adm	string	A string containing the markup for the proposed ad creative. native: link: Link Object url: Destination Url	Always

Curl Sample

curl -i -X POST \
   -H "Content-Type:application/json" \
   -d \
'{
  "id" : "2e170e9b9a3bc22c8f8e9f5a41ed9879",
  "imp" : [
    {
      "id" : "2e170e9b9a3bc22c8f8e9f5a41ed9879-001",
      "bidfloor" : 0,
      "native" : {
        "ext" : {
          "url" :"https://some-advertiser.com",
          "phrase" : "",
          "context": ""
        }
      }
    } ],
  "site" : {   
    "publisher" : {
      "id": "some-unique-publisher-id"
    }
  },
  "device" : {
    "ua" : "chrome-browser-agent",
    "ip" : "192.168.1.x",
    "devicetype" : 1
  },
  "user" : {
    "id" : "24be3d8571494db20101d6d9093c0e5c"
  },
  "test" : 1
}' \
 'https://rtb.provenpixel.com/bidder/click/bid.php?zoneid=[SK_ZONE_ID]'

Zone ID

zoneid can be passed via query string, it overrides the default pre-configured value if passed.