This article outlines the technical specifications and steps required to interact with the Sovrn Real-Time Bidding API.
The Sovrn Real-Time Bidding interface allows ad buyers to bid in real-time on impressions across the Sovrn publisher network. The bidding process requires multiple steps and interactions. The basic bidding process is outlined below.
- A reader visits a site in the Sovrn publisher network and renders a Sovrn ad tag.
- The Sovrn ad request is selected as a valid Real-Time Bidding impression by the Sovrn RTB engine.
- The Sovrn RTB Engine sends HTTP-based bid requests to all available Ad Buyers.
- The Ad Buyer receives the bid request and returns an HTTP response indicating their desired bid and other creative and data details required to fulfill a bid.
- Based on a first-price auction model, Sovrn will choose the winning bidder based on their actual bid price. Auction Type (at) will be specified in bid requests to buyers.
- The winning bidder’s ad creative is then delivered to the reader on the Sovrn publisher site and the ad is impressed.
Bid Requests
When an impression is available for bidding within the Sovrn network, a bid request is sent to each ad buyer. All bid requests are HTTP GET requests that contain all necessary data as encoded URL parameters or HTTP POST requests that pass the data in a JSON object (we currently only support JSON encoded bid requests). Bid requests will be sent to the ad buyer via HTTP to a URL specified by the buyer.
Object List and Definitions
RTB transactions are initiated when an exchange or other supply source send a bid request to a bidder. The bid request consists of a bid request object, at least one impression object, and may optionally include additional objects providing impression context. Please note that any mobile app or video integration could require additional integrations within the Sovrn system.
Objects and attributes that are required will be noted. All other objects and attributes are recommended for optimal performance.
|
Object |
Description |
|
Bid Request (required) |
Top-level object |
|
Source |
Request source details on post-auction decisioning (e.g., header bidding) |
|
Regs |
Contains any legal, governmental, or industry regulations that apply to the request |
|
Impression (required) |
Description of a specific impression. At least one is required in a bid request |
|
Metric |
A quantifiable, often historical, data point about an impression |
|
Banner |
Details for a banner impression. Required if the impression is a banner ad opportunity |
|
Video |
Details for a video impression. Required if the impression is a video ad opportunity |
|
Format |
Allowed sizes for an impression |
|
Pmp |
Collection of private marketplace (PMP) deals applicable to this impression |
|
Deal |
Deal terms pertaining to this impression between a seller and buyer |
|
Site |
Details of the website calling for the impression |
|
Device |
Details of the device on which the content and impressions are displayed |
|
Geo |
Location of the device or user's home base depending on the parent object |
|
User |
Human user of the device; audience for advertising |
Bid Request Object
A bid request id attribute is required as is at least one impression object.
|
Field |
Type |
Description |
|
id |
string (required) |
Unique ID of the bid request, provided by the exchange |
|
imp |
object array (required) |
Array of Imp objects representing the impressions offered. At least 1 Imp object is required |
|
site |
object |
Details about the publisher's website. Only applicable and recommended for websites |
|
device |
object |
Details about the user's device to which the impression will be delivered |
|
user |
object |
Details about the human user of the device; the advertising audience |
|
at |
integer |
Auction type, where 1 = first price, 2 = second price. Default is 2 |
|
tmax |
integer |
Maximum time in milliseconds Sovrn allows for bids to be received to avoid timeout |
|
bcat |
string array |
Blocked advertiser categories using the IAB content categories1 |
|
badv |
string array |
Blocklist of advertisers by their domains |
|
source |
object |
A Source object that provides data about the inventory source and which entity makes the final decision |
|
ext |
object |
Placeholder for exchange-specific extensions to OpenRTB |
Sovrn implements the IAB categories denoted in Table 6.1 here.
Ext Object (Applied to Bid Request Object)
|
Field |
Type |
Description |
|
pchain |
string |
Payment ID chain string containing embedded syntax described in the TAG Payment ID Protocol v1.0 |
Source Object
|
Field |
Type |
Description |
|
pchain |
string |
Payment ID chain string containing embedded syntax described in the TAG Payment ID Protocol v1.03 |
TAG Payment ID Protocol document can be found here.
Regs Object
|
Field |
Type |
Description |
|
ext.gdpr |
integer |
IAB consent string provided when a request is subject to GDPR |
Imp Object
At least one impression object is required.
|
Field |
Type |
Description |
|
id |
string (required) |
Unique identifier for this impression within the context of the bid request |
|
metric |
object array |
An array of Metric objects |
|
banner |
object |
Required if this impression is offered as a banner ad opportunity |
|
video |
object |
Required if this impression is offered as a video ad opportunity |
|
pmp |
object |
Contains any private marketplace deals in effect for this impression |
|
displaymanager |
string |
Name of ad mediation partner, SDK technology, or player responsible for rendering ad (typically video or mobile) |
|
displaymanagerver |
string |
Version of ad mediation partner, SDK technology, or player responsible for rendering ad (typically video or mobile) |
|
instl |
integer |
1 = ad is interstitial or full screen, 0 = not interstitial. Default is 0 |
|
tagid |
string |
Identifier for specific ad placement or ad tag that was used to initiate the auction. This can be useful for debugging or optimization |
|
bidfloor |
float |
Minimum bid for this impression expressed in CPM |
|
secure |
integer |
Flag to indicate if the impression requires secure HTTPS URL creative assets and markup, where 0 = non-secure, 1 = secure |
|
ext |
object |
Placeholder for exchange-specific extensions to OpenRTB |
Ext Object (Applied to Imp Object)
|
Field |
Type |
Description |
|
deals |
string array |
List of unique identifiers for a private marketplace or deal ID to be passed through the bid response |
Metric Object
|
Field |
Type |
Description |
|
type |
string |
Type of metric being presented using exchange curated string names |
|
value |
float |
Number representing the value of the metric. Probabilities must be in the range of 0.0 - 1.0 |
|
vendor |
string |
Source of the value using exchange curated string names. If the exchange itself is the source versus a third party, "EXCHANGE" is recommended |
Banner Object
|
Field |
Type |
Description |
|
format |
object array (recommended) |
Array of format objects representing the banner sizes permitted. If none are specified, then use of the h and w attributes |
|
w |
integer (required) |
Exact width in device independent pixels (DIPS) |
|
h |
integer (required) |
Exact height in device independent pixels (DIPS) |
|
battr |
integer array |
Blocked creative attributes. Refer to Table 6.3. If blank assume all types are allowed |
|
pos |
integer |
Ad position on screen. Use Table 6.5 |
|
topframe |
integer |
Indicates if the banner is in the top frame as opposed to an iframe, where 0 = no, 1 = yes |
|
expdir |
integer array |
Directions in which the banner may expand. Refer to Table 6.11 |
|
id |
string |
Unique identifier for this banner object. Useful for tracking multiple banner objects. Combination of banner ID should be unique |
Video Object
|
Field |
Type |
Description |
|
mimes |
string array (required) |
Content MIME types supported (e.g. "video/x-ms-wmv", "video/mp4") |
|
minduration |
integer (required) |
Minimum video ad duration in seconds |
|
maxduration |
integer (required) |
Maximum video ad duration in seconds |
|
protocols |
integer |
Supported video protocols. Refer to Table 6.7 |
|
w |
integer (required) |
Width of the video player in device independent pixels (DIPS) |
|
h |
integer (required) |
Height of the video player in device independent pixels (DIPS) |
|
startdelay |
integer |
Indicates the start delay in seconds for pre-roll, mid-roll, or post-roll ad placements. Refer to Table 6.9 |
|
linearity |
integer |
Indicates if the impression must be linear, nonlinear, etc. Refer to List 5.7 |
|
maxbitrate |
integer |
Maximum bit rate in Kbps |
|
playbackmethod |
integer array |
Playback methods that may be in use. If none are specified, any method may be used. Refer to List 5.10. Only one method is typically used in practice |
|
pos |
integer |
Ad position on the screen. Refer to List 5.4 |
|
companionad |
object array |
Array of Banner objects if companion ads are available |
|
api |
integer array |
List of supported API frameworks for this impression. Refer to List 5.6. If an API is not explicitly listed, it is assumed not to be supported |
Format Object
|
Field |
Type |
Description |
|
w |
integer |
Width in device independent pixels (DIPS) |
|
h |
integer |
Height in device independent pixels (DIPS) |
Pmp Object
|
Field |
Type |
Description |
|
private_auction |
integer |
Indicator of auction eligibility to seats named in the Direct Deals object. 0 = all bids are accepted, 1 = bids are restricted to the deals specified and the terms thereof |
|
deals |
object array |
Array of Deal objects that convey the specific deals applicable to this impression |
Deal Object
|
Field |
Type |
Description |
|
id |
string (required) |
Unique identifier for the direct deal |
|
bidfloor |
float |
Minimum bid for this impression expressed in CPM |
|
bidfloorcur |
string |
Currency specified using ISO-4217 alpha codes. Default is USD |
|
at |
integer |
Optional override of the overall auction type of the bid request, where 1 = First Price, 2 = Second Price Plus, 3 = the value passed in the bidfloor is the agreed-upon deal price |
Site Object
|
Field |
Type |
Description |
|
id |
string |
Site ID on the exchange |
|
domain |
string |
Domain of the site |
|
cat |
string array |
Array of IAB content categories of the site |
|
pagecat |
string array |
Array of IAB content categories that describe the current page or view of the site |
|
page (required) |
string |
URL of the page where the impression will be shown |
|
ref |
string |
Referrer URL that caused navigation to the current page |
|
mobile |
integer |
Indicates if the site has been programmed to optimize layout when viewed on mobile devices, where 0 = no, 1 = yes |
|
publisher |
object |
Details about the Publisher of the site |
|
keywords |
string |
Comma-separated list of keywords about the site |
App Object
|
Field |
Type |
Description |
|
id |
string |
Exchange-specific app ID |
|
name |
string |
App name |
|
bundle |
string (required) |
Platform-specific application identifier unique to the app. On Android, this should be a bundle or package name. On iOS, it is typically a numeric ID |
|
domain |
string |
Domain of the app |
|
storeurl |
string |
App store URL for an installed app |
|
cat |
string array |
Array of IAB content categories of the app |
|
ver |
string |
Application version |
|
paid |
integer |
0 = app is free, 1 = the app is a paid version |
|
publisher |
object |
Details about the Publisher of the app |
Publisher Object
|
Field |
Type |
Description |
|
id |
string (required) |
Publisher ID on the exchange, must match the Sovrn affiliate ID |
Device Object
|
Field |
Type |
Description |
|
ua |
string |
Browser user agent string |
|
geo |
object |
Location of the device assumed to be the user's current location defined by a Geo object |
|
dnt |
integer |
"Do Not Track" flag as set in the header by the browser, where 0 = tracking is unrestricted, 1 = do not track |
|
ip |
string |
IPv4 address closest to device |
|
devicetype |
integer |
The general type of device. Refer to List 5.21 |
|
make |
string |
Device make (e.g., "Apple") |
|
model |
string |
Device model (e.g., "iPhone") |
|
os |
string |
Device operating system (e.g., "iOS") |
|
osv |
string |
Device operating system version (e.g., "3.1.2") |
|
language |
string |
Browser language using ISO-639-1-alpha-2 |
|
carrier |
string |
Carrier or ISP (e.g., "VERIZON") using exchange curated string names |
|
connectiontype |
integer |
Network connection type. Refer to List 5.22 |
Geo Object
|
Field |
Type |
Description |
|
lat |
float |
Latitude from -90.0 to +90.0, where negative is south |
|
lon |
float |
Logitude from -180.0 to +180.0, where negative is west |
|
type |
integer |
Source of location data (GPS, IP address, user provided) |
|
country |
string |
Country code using ISO-3166-1-alpha-3 |
|
region |
string |
Region code using ISO-3166-2; 2-letter state code if USA |
|
metro |
string |
Google metro code; similar to but not exactly Nielsen DMAs. See Appendix A for a link to the codes |
|
city |
string |
City using United Nations Code for Trade & Transport Locations. See Appendix A for a link to the codes |
|
zip |
string |
Zip or postal code |
User Object
|
Field |
Type |
Description |
|
id |
string (recommended) |
Exchange-specific ID for the user |
|
buyeruid |
string (required) |
Buyer-specific ID for the user as mapped by the exchange for the buyer |
Ext Object (Applied to User Object)
|
Field |
Type |
Description |
|
consent |
string |
IAB consent string provided when the request is subject to GDPR |
Bid Request Limitations
Bid Requests will only be sent 1 time per impression per ad buyer
Bid Responses must occur within the specified time (in ms) within the tmax field of the Bid Request start time. The entire round trip transaction cannot exceed the time specified in the tmax field.
Please scroll down to the end of this article to see sample bid requests.
Bid Responses
Bid Responses are JSON formatted content returned as the body of a response to Bid Request HTTP calls. Note: Any object in the hierarchy may include an extensions object to the parameter ext. Extensions could also be configured to be its own object if needed. Objects and attributes that are required will be noted. All other objects and attributes are recommended for optimal performance, but not required.
|
Object |
Description |
|
Bid Response (required) |
Top-level object |
|
Seat Bid (required) |
Collection of bids made by the bidder on behalf of a specific seat |
|
Bid (required) |
An offer to buy a specific impression under certain business terms |
Bid Response Object
|
Field |
Type |
Description |
|
id (required) |
string |
ID of the bid request to which this is a response |
|
seatbid (required) |
object array |
Array of seatbid objects; 1+ required if a bid is to be made |
Seat Bid Object
|
Field |
Type |
Description |
|
bid (required) |
object array |
Array of 1+ bid objects; each bid object is related to an impression. Multiple bids can relate to the same impression |
|
seat |
string |
ID of the buyer seat on whose behalf this bid is made |
Bid Object
|
Field |
Type |
Description |
|
id (required) |
string |
Bidder generated bid ID to assist with logging/tracking |
|
impid (required) |
string |
ID of the Imp object in the related bid request |
|
price (required) |
float |
Bid price expressed as CPM although the actual transaction is for a unit impression only |
|
adm (required) |
string |
Ad markup. XHTML if in response to a banner object, or VAST XML if in response to a video object |
|
adid (required) |
string |
ID that references the ad to be served if the bid wins |
|
adomain |
string array |
Advertiser domain for block list checking |
|
crid (required) |
string |
Creative ID to assist with ad quality checking and reporting |
|
dealid |
string |
Reference to the deal.id from the bid request if this bid pertains to a private marketplace direct deal |
Bid Response Limitations
All bid requests received after the specified timeout (in ms) within the tmax field will be ignored
For a no bid, the bidder can either respond with a CPM of 0, or send an HTTP 204 No Content response. (The later is actually preferred as it will save a lot of bandwidth and CPU on both sides)
Please scroll down to the end of this article to see sample bid responses.
Ad Delivery
Ad Delivery for Winning Bids
Winning bids will have their Ad Delivery Creative processed for macros and appended to the publisher page for rendering to the reader.
Bid Macro Values
Bid Macros can be passed as URL parameters on the notification urls in the Bid Response.
|
Macro |
Description |
|
$(AUCTION_ID} |
ID of the bid request; from “id” attribute |
|
$(AUCTION_BID_ID} |
ID of the bid; from “bidid” attribute |
|
$(AUCTION_IMP_ID} |
ID of the impression just won; from “impid” attribute |
|
$(AUCTION_SEAT_ID} |
ID of the bidder’s seat for whom the bid was made |
|
$(AUCTION_AD_ID} |
ID of the ad markup the bidder wishes to serve; from “adid” attribute |
|
$(AUCTION_PRICE} |
Settlement price using the same currency as the bid` |
|
$(AUCTION_CURRENCY} |
The currency used in the bid (explicit or implied); for confirmation only |
Cookie Data Merging
For instructions on setting up a new cookie sync pixel for a publisher, see our guide here.
Bid Merge Requests
Bid Merge Requests or “cookie syncing” are HTTP requests initiated by the winning Ad Buyers creative that calls sovrn utilizing a request that provides the Ad Buyers unique reader ID that corresponds to the reader detailed in the original Bid Request.
Merge Request Example
GET
- /merge?pid=53&3pid=21434621
Bid Merge Request Limitations
Bid Merge Requests may only be made 1 time per unique reader in a 24 hour period.
Bid Merge Request Parameters
|
Parameter Name |
Size |
Description |
Required? |
|
pid |
12 |
Ad Buyer Provider ID |
Y |
|
3pid |
24 |
Ad Buyer Reader ID |
Y |
Impression Merge Requests
Impression Merge Requests are HTTP requests initiated by sovrn that call an Ad Buyer’s server using a pixel that enables the Ad Buyer to read and/or set cookie on a sovrn reader. This request should redirect to the “Bid Merge Request” url with the appropriate fields.
Ad Buyer provides:
- A pixel URI that sovrn can deliver to the reader’s browser that accepts the sovrn unique reader id.
- A redirect to the “Bid Merge Request” URI that provides the fields detailed in the “Bid Merge Request Parameters”
Sample Bid Requests
Here is an example of a simple banner bid request:
POST / HTTP/1.0
Host: localhost
Connection: close
Content-Type: application/json
Content-Length: 420
x-openrtb-version: 2.5
{
"id": "e4d9f65c-941d-4160-9562-3b795d47189f",
"imp": [
{
"id": "1",
"metric": [
{
"type": "viewability",
"value": 0.6,
"vendor": "EXCHANGE"
}
],
"banner": {
"w": 728,
"h": 90,
"pos": 1,
"expdir": [4]
}
}
],
"site": {
"id": "136854",
"page": "falseprecision.com",
"mobile": 1
},
"device": {
"ua": "Mozilla/5.0 (X11; Linux i686) AppleWebKit/535.19 (KHTML, like Gecko) Chrome/18.0.1025.162 Safari/535.19",
"ip": "67.50.84.126",
"geo": {
"country": "US",
"region": "CO",
"type": 2
},
"language": "en"
},
"user": {
"buyeruid": "50abbbffd67f218d1808d0ac"
},
"source:=": {
"pchain": "ABCDE12C34AC7F4C-FAFDF38B16Bf6B2B:1288"
},
"at": 1,
"tmax": 200
}
Here is an example of a PMP bid request with a Direct Deal:
POST / HTTP/1.0
Host: localhost
Connection: close
Content-Type: application/json
Content-Length: 420
x-openrtb-version: 2.2
{
"id": "e4d9f65c-941d-4160-9562-3b795d47189f",
"imp": [
{
"id": "1",
"banner": {
"w": 728,
"h": 90,
"pos": 1,
"expdir": [
4
]
"pmp": {
"private_auction": 1,
"deals": [
{
"id": "Deal-1",
“at”: 2
},
{
"id": "Deal-2",
“at”: 2
}
]
}
}
],
"site": {
"id": "136854",
"page": "falseprecision.com"
},
"device": {
"ua": "Mozilla/5.0 (X11; Linux i686) AppleWebKit/535.19 (KHTML, like Gecko) Chrome/18.0.1025.162 Safari/535.19",
"ip": "67.50.84.126",
"geo": {
"country": "US",
"region": "CO",
"type": 2
},
"language": "en"
},
"user": {
"buyeruid": "50abbbffd67f218d1808d0ac"
},
"at": 2
}
Sample Bid Responses
Here is an example of a bid response with multiple seats:
{
"id": "ec0bf5f0-8d42-4544-b6f5-63eb24ba1565",
"cur": "USD",
"seatbid": [
{
"bid": [
{
"id": "1",
"impid": "1",
"price": 10,
"adid": "347564",
"adm": "<script type=\"text/javascript\" src=\"http://adserver.com/creative1?cp=${AUCTION_PRICE}\"></script>",
"adomain": [
"flatironchef.com"
]
}
],
"seat": "167"
},
{
"bid": [
{
"id": "2",
"impid": "1",
"price": 6,
"adid": "455929",
"adm": "<script type=\"text/javascript\" src=\"http://adserver.com/creative2?cp=${AUCTION_PRICE}\"></script>"
"adomain": [
"flatironchef.com"
],
}
],
"seat": "543"
}
]
}
Here is an example of a bid response with a Deal ID:
{
"id": "ec0bf5f0-8d42-4544-b6f5-63eb24ba1565",
"cur": "USD",
"seatbid": [
{
"bid": [
{
"id": "1",
"impid": "1",
"price": 10,
"dealid": "ABC-1234-6789",
"adid": "347564",
"adm": "<script type=\"text/javascript\" src=\"http://adserver.com/creative1?cp=${AUCTION_PRICE}\"></script>",
"adomain": [
"flatironchef.com"
]
}
],
"seat": "167"
},
]
}
Reference
All reference lists are actively maintained by the IAB on the OpenRTB web site.
As such, implementers should ensure they are working off of the latest lists and enumerations. For reference visit this oRTB spec from the IAB and below are the page numbers that each table can be found.
- 6.1 Content Categories pg 64
- 6.2 Banner Ad Types pg 77
- 6.3 Creative Attributes pg 77
- 6.4 API Frameworks pg 78
- 6.5 Ad Position pg 78
- 6.6 Video Linearity pg 80
- 6.7 Video Bid Response Protocols pg 80
- 6.8 Video Playback Methods pg 80
- 6.9 Video Start Delay pg 81
- 6.10 Connection Type pg 81
- 6.11 Expandable Direction pg 81
- 6.12 Content Delivery Methods pg 82 6.13 Content Context pg 82
- 6.14 Video Quality pg 83
- 6.15 Location Type pg 83
- 6.16 Device Type pg 83
- 6.17 VAST Companion Types pg 84
- 6.18 QAG Media Ratings pg 84
- 6.19 No-Bid Reason Codes pg 84
- Appendix A: Additional Information