1. Sovrn //Advertising
  2. 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. 

  1. A reader visits a site in the Sovrn publisher network and renders a Sovrn ad tag. 
  2. The Sovrn ad request is selected as a valid Real-Time Bidding impression by the Sovrn RTB engine. 
  3. The Sovrn RTB Engine sends HTTP-based bid requests to all available Ad Buyers. 
  4. 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. 
  5. 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. 
  6. 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

0 indicates request is not subject to GDPR. 1 indicates 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