Sovrn Ad Exchange

Server to Server & oRTB

Sovrn oRTB Specs

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	Minimum video ad duration in seconds
maxduration	integer	Maximum video ad duration in seconds
protocols	integer	Supported video protocols. Refer to Table 6.7
w	integer	Width of the video player in device independent pixels (DIPS)
h	integer	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	Exchange-specific ID for the user
buyeruid	string	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