Supply Side Integration

Supply Side Partners issue HTTP POST messages containing OpenRTB bid requests. These requests are automatically forwarded to Demand Side Partners, and the AdMedia marketplace collects bids based on demand. The bids, containing the creative and tracking pixel, are collected into OpenRTB bid response messages and are sent as the HTTP response body to the original HTTP POST. The ad and tracking pixel, located within the bid response object, are ready for immediate display.

Supply Side Partners will configure their servers to issue bid requests during retrieval of web content. The ad markup will be provided in the bid response. Returning the ad markup inside the web content will acknowledge the bid response as the selected winner via the resource request for the tracking pixel. The following example illustrates a request and response for a simple banner ad:


CURL EXAMPLE

$ curl -H "Content-Type: application/json" -X POST -d "{\"id\":\"80ce30c53c16e6ede\",\"at\":1,\"cur\":[\"USD\"],\"imp\":[{\"id\":\"102\",\"bidfloor\":0.03,\"banner\":{\"h\":250,\"w\":300,\"pos\":0}}],\"site\":{\"id\":\"102855\",\"cat\":[\"IAB3-1\"],\"domain\":\"www.foobar.com\",\"page\":\"http://www.foobar.com/1234.html\",\"publisher\":{\"id\":\"8953\",\"name\":\"foobar.com\",\"cat\":[\"IAB3-1\"],\"domain\":\"foobar.com\"}},\"device\":{\"ua\":\"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/537.13 (KHTML, like Gecko) Version/5.1.7 Safari/534.57.2\",\"ip\":\"123.145.167.10\"},\"user\":{\"id\":\"55816b39711f9b5acf3b90e313ed29e51665623f\"}}" http://server_address

REQUEST BODY

{
  "id":"80ce30c53c16e6ede",
  "at":1,
  "cur":[
    "USD"
  ],
  "imp":[
    {
      "id":"102",
      "bidfloor":0.03,
      "banner":{
        "h":250,
        "w":300,
        "pos":0
      }
    }
  ],
  "site":{
    "id":"102855",
    "cat":[
      "IAB3-1"
    ],
    "domain":"www.foobar.com",
    "page":"http://www.foobar.com/1234.html",
    "publisher":{
00      "id":"8953",
      "name":"foobar.com",
      "cat":[
        "IAB3-1"
      ],
      "domain":"foobar.com"
    }
  },
  "device":{
    "ua":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/537.13 (KHTML, like Gecko) Version/5.1.7 Safari/534.57.2",
    "ip":"123.145.167.10"
  },
  "user":{
    "id":"55816b39711f9b5acf3b90e313ed29e51665623f"
  }
}


RESPONSE BODY

{
  "id":"80ce30c53c16e6ede",
  "bidid":"abc1123",
  "cur":"USD",
  "seatbid":[
    {
      "seat":"512",
      "bid":[
        {
          "id":"1",
          "impid":"102",
          "price":9.43,
          "adm":"<a href=\"clicks.com/id=djskj8383s\"><img src=\"adsource.com/1234\" width=728 height=90/></a><img src=\"trackingurl.com/imprid=102&price=9.43\"/ >",
          "nurl":"http://adserver.com/winnotice?impid=102",
          "iurl":"http://adserver.com/pathtosampleimage",
          "adomain":[
            "advertiserdomain.com"
          ],
          "cid":"campaign111",
          "crid":"creative112",
          "attr":[ 1, 2, 3, 4, 5, 6, 7, 12 ]
        }
      ]
    }
  ]
}

Bid Request

A bid request object is created each time a request is sent to the AdMedia marketplace. It is the top level object represented in JSON that describes the details of a request for bids. It must contain a unique "id" string in addition to at least one "imp" (impression) object. Each bid request issued by a Supply Side Partner is sent as the HTTP request body.

id: string

required

Unique ID of the Bid Request
imp: array of objects

required

Array of impression objects. Multiple impression auctions may be specified in a single bid request. At least one impression is required for a valid bid request.
site: object

recommended for websites

See Site Object
app: object

recommended for native apps

See App Object
device: object

recommended

See Device Object
user: object

recommended

See User Object
at: integer

optional

Auction Type. If "1", then first price auction. If "2", then second price auction. Default is "2".
tmax: integer

optional

Maximum amount of time in milliseconds to submit a bid (e.g. 120 means the bidder has 120ms to submit a bid before the auction is complete).
wseat: array of strings

optional

Array of buyer seats allowed to bid on this auction. Seats are an optional feature of exchange. For example, ["4", "34", "82", "A45"] indicates that only advertisers using these exchange seats are allowed to bid on the impressions in this auction.
allimps: integer

optional

Flag to indicate whether exchange can verify that all impressions offered represent all of the impressions available in context (e.g., all impressions available on the web page; all impressions available for a video [pre, mid and postroll spots], etc.) to support road-blocking. A true value should only be passed if the exchange is aware of all impressions in context for the publisher. "0" means the exchange cannot verify, and "1" means that all impressions represent all impressions available. Default is "0".
cur: array of strings

optional

Array of allowed currencies for bids on this bid request using ISO-4217 alphabetic codes.
bcat: array of strings

optional

Blocked Advertiser Categories. Note that there is no existing categorization / taxonomy of advertiser industries. However, as a substitute exchanges may decide to use IAB categories as an approximation.
badv: array of strings

optional

Array of strings of blocked top-level domains of advertisers. For example, ["company1.com", "company2.com"].
regs: object

optional

This object is a container for any legal, governmental, or industry regulations in force for the request.
ext: object

optional

This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Impression Object

Impression objects contain information describing the specific details of one or more impressions to auction. Every impression must specify a unique "id" string which will be returned by bids in the bid response.

id: string

require

A unique identifier for this impression within the context of the bid request (Typically, the value starts with 1, and increments up to n for n impressions.).
banner: object

required for banner impressions

A reference to a banner object. Either a banner or video object (or both, if the impression could be either) must be included in an impression object. See Banner Object.
video: object

required for video impressions

A reference to a video object. Either a banner or video object (or both if the impression could be either) must be included in an impression object. See Video Object.
displaymanager: string

recommended for video and native apps

Name of ad mediation partner, SDK technology, or native player responsible for rendering ad (typically video or mobile). Used by some ad servers to customize ad code by partner.
displaymanagerver: string

recommended for video and native apps

Version of ad mediation partner, SDK technology, or native player responsible for rendering ad (typically video or mobile). Used by some ad servers to customize ad code by partner.
instl: integer

optional

1 if the ad is interstitial or full screen, else 0 (i.e., no). Default is 0.
tagid: string

optional

Identifier for specific ad placement or ad tag that was used to initiate the auction. This can be useful for debugging any issues, or for optimization by the buyer.
bidfloor: float

optional

Bid floor for the impression (in CPM of bidfloorcur). Default is 0.
bidfloorcur: string

optional

If bid floor is specified and multiple currencies supported per bid request, then currency should be specified here using ISO-4217 alphabetic codes. Note, this may be different from bid currency returned by bidder, if this is allowed on an exchange. Default is "USD".
secure: integer

optional

Flag to indicate whether the impression requires secure HTTPS URL creative assets and markup. A value of "1" means that the impression requires secure assets. A value of "0" means non-secure assets. If this field is omitted, the bidder should interpret the secure state is unknown and assume HTTP is supported.
iframebuster: array of strings

optional

Array of names for supported iframe busters. Exchange specific.
pmp: object

optional

A reference to the PMP object containing any deals eligible for the impression object. See the PMP object definition.
ext: object

optional

This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Banner Object

Banner objects are required in impressions that define banner displays or rich media. They may be included optionally for video impressions to describe companion banners.

w: integer

recommended

Width of the impression in pixels. Since some ad types are not restricted by size, this field is not required, but it's highly recommended that this information be included when possible.

h: integer

recommended

Height of the impression in pixels. Since some ad types are not restricted by size, this field is not required, but it's highly recommended that this information be included when possible.

wmax: integer

optional

Maximum width of the impression in pixels. If included, it indicates that a range of sizes is allowed with this maximum width, and "w" is taken as recommended. If not included, then "w" should be considered an exact requirement.

hmax: integer

optional

Maximum height of the impression in pixels. If included, it indicates that a range of sizes is allowed with this maximum height, and "h" is taken as recommended. If not included, then "h" should be considered an exact requirement.

wmin: integer

optional

Minimum width of the impression in pixels. If included, it indicates that a range of sizes is allowed with this minimum width, and "w" is taken as recommended. If not included, then "w" should be considered an exact requirement.

hmin: integer

optional

Minimum height of the impression in pixels. If included, it indicates that a range of sizes is allowed with this minimum height, and "h" is taken as recommended. If not included, then "h" should be considered an exact requirement.

id: string

recommended when subordinate to a video object

Unique identifier for this banner object. Useful for tracking multiple banner objects (e.g., in companion banner array). Usually starts with 1, increasing with each object. Combination of impression id banner object should be unique.

pos: integer

optional

Ad Position.

btype: array of integers

optional

Blocked creative types. If blank, assume all types are allowed.

battr: array of integers

optional

Blocked creative attributes. If blank assume all types are allowed.

mimes: array of strings

optional

Whitelist of content MIME types supported. Popular MIME types include, but are not limited to, "image/jpg", "image/gif" and "application/x-shockwave-flash".

topframe: integer

optional

Specify if the banner is delivered in the top frame or in an iframe. "0" means it is not in the top frame, and "1" means that it is. Default is 0.

expdir: array of integers

optional

Specify properties for an expandable ad.

api: array of integers

optional

List of supported API frameworks for this banner.

ext: object

optional

This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Video Object

Video objects are required to define information about in-stream video ad auctions.

mimes: array of strings

required

Content MIME types supported. Popular MIME types include, but are not limited to, "video/x-ms-wmv" for Windows Media, and "video/x-flv" for Flash Video.

minduration: integer

required

Minimum video ad duration in seconds.

maxduration: integer

required

Maximum video ad duration in seconds.

protocol: integer

optional

Video bid response protocols. Note: Use "protocols" when multiple protocols are supported. Its use is also highly recommended, even for one, since this "protocol" attribute is likely to be deprecated in a future version. At least one supported protocol must be specified in either the "protocol" or "protocols" attribute.

protocols: array of integers

recommended

Video bid response protocols. At least one supported protocol must be specified in either the "protocol" or "protocols" attribute.

w: integer

recommended

Width of the player in pixels. This field is not required, but it's highly recommended that this information be included.

h: integer

recommended

Height of the player in pixels. This field is not required, but it's highly recommended that this information be included.

startdelay: integer

recommended

Indicates the start delay in seconds for preroll, midroll, or postroll ad placement.

linearity: integer  
sequence: integer  
battr: array of integers

optional

Blocked creative attributes. If blank, assume all types are allowed.

maxextended: integer

optional

Maximum extended video ad duration, if extension is allowed. If blank or 0, extension is not allowed. If -1, extension is allowed, and there is no time limit imposed. If greater than 0, then the value represents the number of seconds of extended play supported beyond the maxduration value.

minbitrate: integer

optional

Minimum bit rate in Kbps. Exchange may set this dynamically, or universally across their set of publishers. Default accepts any bitrate.

maxbitrate: integer

optional

Maximum bit rate in Kbps. Exchange may set this dynamically, or universally across their set of publishers. Default accepts any bitrate.

boxingallowed: integer

optional

If exchange publisher has rules preventing letter boxing of 4x3 content to play in a 16x9 window, then this should be set to false. Default setting is true, which assumes that boxing of content to fit into a window is allowed. "1" indicates boxing is allowed. "0" indicates it is not allowed.

playbackmethod: array of integers

optional

List of allowed playback methods. If blank, assume that all are allowed.

delivery: array of integers

optional

List of supported delivery methods (streaming, progressive). If blank, assume all are supported.

pos: integer

optional

Ad Position.

companionad: array of objects

optional

If companion ads are available, they can be listed as an array of banner objects. See Banner Object.

api: array of integers

optional

List of supported API frameworks for this impression.

companiontype: array of integers

optional

Recommended if companion objects are included.

ext: object

optional

This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Site Object

Site objects specify information about the website offering the impression. Note: Site and App objects are mutually exclusive, so a Site object should not be provided if an App object is defined.

id: string

recommended

Site ID on the exchange.

name: string

optional

Site name (may be masked at publisher's request).

domain: string

optional

Domain of the site, used for advertiser side blocking. For example, "foo.com".

cat: array of strings

optional

Array of IAB content categories for the overall site.

sectioncat: array of strings

optional

Array of IAB content categories for the current subsection of the site.

pagecat: array of strings

optional

Array of IAB content categories for the current page.

page: string

recommended

URL of the page where the impression will be shown.

privacypolicy: integer

optional

Specifies whether the site has a privacy policy. "1" means there is a policy. "0" means there is not.

ref: string

optional

Referrer URL that caused navigation to the current page.

search: string

optional

Search string that caused navigation to the current page.

publisher: object

optional

See Publisher Object.

content: object

optional

See Content Object.

keywords: string

optional

List of keywords describing this site in a comma separated string.

ext: object

optional

This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

App Object

App objects specify information about native mobile apps that offer impressions. Note: Site and App objects are mutually exclusive, so an App object should not be provided if a Site Object is defined.

id: string

recommended

Application ID on the exchange.

optional

Indicates whether the ad impression must be linear, non-linear or can be of any type (field not set).

optional

If multiple ad impressions are offered in the same bid request, the sequence number will allow for the coordinated delivery of multiple creatives. Default is 1.

name: string

optional

Application name (may be masked at publisher's request).

domain: string

optional

Domain of the application (e.g., "mygame.foo.com").

cat: array of strings

optional

Array of IAB content categories for the overall application.

sectioncat: array of strings

optional

Array of IAB content categories for the current subsection of the app.

pagecat: array of strings

optional

Array of IAB content categories for the current page/view of the app.

ver: string

optional

Application version.

bundle: string

recommended

Application bundle or package name (e.g., com.foo.mygame). This is intended to be a unique ID across multiple exchanges.

privacypolicy: integer

optional

Specifies whether the app has a privacy policy. "1" means there is a policy, and "0" means there is not.

paid: integer

optional

"1" if the application is a paid version, else "0" (i.e., free).

publisher: object

optional

See Publisher Object.

content: object

optional

See Content Object.

keywords: string

optional

List of keywords describing this app in a comma separated string.

storeurl: string

optional

For QAG 1.5 compliance, an app store URL for an installed app, should be passed in the bid request.

ext: object

optional

This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Content Object

Content objects describe the published website or app content in which the impression will be displayed.

id: string

optional

ID uniquely identifying the content.

episode: integer

optional

Content episode number (typically applies to video content).

title: string

optional

Content title.

Video examples: "Search Committee" (television) or "A New Hope" (movie) or "Endgame" (made for web)

Non-video example: "Why an Antarctic Glacier Is Melting So Quickly" (Time magazine article)

series: string

optional

Content series.

Video examples: "The Office" (television) or "Star Wars" (movie) or "Arby 'N' The Chief" (made for web)

Non-video example: "Ecocentric" (Time magazine blog)

season: string

optional

Content season. E.g., "Season 3" (typically applies to video content).

url: string

optional

Original URL of the content, for buy-side contextualization or review.

cat: array of strings

optional

Array of IAB content categories for the content.

videoquality: integer

optional

Video quality per the IAB's classification.

keywords: string

optional

Comma separated list of keywords describing the content.

contentrating: string

optional

Content rating (e.g., MPAA).

userrating: string

optional

User rating of the content (e.g., number of stars, likes, etc.).

context: string

optional

Specifies the type of content (game, video, text, etc.).

livestream: integer

optional

Is content live? E.g., live video stream, live blog. "1" means content is live. "0" means it is not live.

sourcerelationship: integer

optional

1 for "direct"; 0 for "indirect".

producer: object

optional

See Producer Object.

len: integer

optional

Length of content (appropriate for video or audio) in seconds.

qagmediarating: integer

optional

Media rating of the content, per QAG guidelines.

embeddable: integer

optional

From QAG Video Addendum. If content can be embedded (such as an embeddable video player) this value should be set to "1". If content cannot be embedded, then this should be set to "0".

language: string

optional

Language of the content. Use alpha-2/ISO 639-1 codes.

ext: object

optional

This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Publisher Object

Publisher objects provide information about the Supply Side Provider given to bidders.

id:

string

recommended

Publisher ID on the exchange.

name:

string

optional

Publisher name (may be masked at publisher's request).

cat:

array of strings

optional

Array of IAB content categories for the strings publisher.

domain:

string

optional

Publisher's highest level domain name, for example "foopub.com".

ext:

object

optional

This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Producer Object

Producer objects are used when content is syndicated and may appear on a different publisher.

id:

string

optional

Content producer or originator ID. Useful if content is syndicated, and may be posted on a site using embed tags.

name:

string

optional

Content producer or originator name (e.g., "Warner Bros").

cat:

array of strings

optional

Array of IAB content categories for the content producer.

domain:

string

optional

URL of the content producer.

ext:

object

optional

This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Device Object

Device objects contain information related to the physical device presenting the ad to the user, including hardware, platform, location, and carrier. The IP address should always be provided.

dnt:

integer

recommended

If "0", then do not track is set to false. If "1", then do no track is set to true in browser.

ua:

string

recommended

Browser user agent string.

ip:

string

recommended if geo object is not supplied

IPv4 address closest to device.

geo:

object

recommended if IP is not supplied

Geography as derived from the device's location services (e.g., cell tower triangulation, GPS) or IP address. See Geo Object.

didsha1:

string

optional

SHA1 hashed device ID; IMEI when available, else MEID or ESN. OpenRTB's preferred method for device ID hashing is SHA1.

didmd5:

string

optional

MD5 hashed device ID; IMEI when available, else MEID or ESN. Should be interpreted as case insensitive.

dpidsha1:

string

optional

SHA1 hashed platform-specific ID (e.g., Android ID or UDID for iOS). OpenRTB's preferred method for device ID hash is SHA1.

dpidmd5:

string

optional

MD5 hashed platform-specific ID (e.g., Android ID or UDID for iOS). Should be interpreted as case insensitive.

macsha1:

string

optional

SHA1 hashed MAC address of the device.

macmd5:

string

optional

MD5 hashed MAC address of the device.

ipv6:

string

optional

IP address in IPv6.

carrier:

string

optional

Carrier or ISP derived from the IP address. Should be specified using Mobile Network Code (MNC).

language:

string

optional

Browser language; use alpha-2/ISO 639-1 codes.

make:

string

optional

Device make (e.g., "Apple").

model:

string

optional

Device model (e.g., "iPhone").

os:

string

optional

Device operating system (e.g., "iOS").

osv:

string

optional

Device operating system version (e.g., "3.1.2").

js:

integer

optional

"1" if the device supports JavaScript, else "0".

connectiontype:

integer

optional

The detected data connection type for the device.

devicetype:

integer

optional

The device type being used.

flashver:

string

optional

The Flash version detected.

ifa:

string

optional

Native identifier for advertisers; an opaque ID assigned by the device or browser for use as an advertising identifier (e.g. Apple's IFA, Android's Advertising ID, etc).

ext:

object

optional

This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Geo Object

Geo objects encapsulate information about the geolocation of the device at the time the impression is offered.

lat:

float

optional

Latitude from -90 to 90. South is negative. This should only be passed if known to be accurate (for example, not the centroid of a postal code).

lon:

float

optional

Longitude from -180 to 180. West is negative. This should only be passed if known to be accurate.

country:

string

optional

Country using ISO-3166-1 Alpha-3.

region:

string

optional

Region using ISO 3166-2.

regionfips104:

string

optional

Region of a country using FIPS 10-4 notation (alternative to ISO 3166-2).

metro:

string

optional

Pass the metro code. Metro codes are similar to but not exactly the same as Nielsen DMAs.

city:

string

optional

City using United Nations Code for Trade and Transport Locations.

zip:

string

optional

Zip/postal code.

type:

integer

recommended

Indicate the source of the geo data (GPS, IP address, user provided). Type should be provided when lat/lon is provided.

ext:

object

optional

This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

User Object

User objects contain known information about the human user viewing the ad.

id:

string

recommended (or buyeruid)

Unique consumer ID of this user on the exchange.

buyeruid:

string

recommended (or id)

Buyer's user ID for this user as mapped by exchange for the buyer.

yob:

integer

optional

Year of birth as a 4-digit integer.

gender:

string

optional

Gender as "M" male, "F" female, "O" Other. (Null indicates unknown).

keywords:

string

optional

Comma separated list of keywords of consumer interests or intent.

customdata:

string

optional

If supported by the exchange, this is custom data that the bidder had stored in the exchange's cookie. The string may be in base85 cookie-safe characters and be in any format. This may be useful for storing user features. Note: Proper JSON encoding must be used to include "escaped" quotation marks.

geo:

object

optional

Home geo for the user (e.g., based off of registration data). This is different from the current location of the access device (That is defined by the geo object embedded in the Device Object.). See Geo Object.

data:

array of objects

optional

See Data Object.

ext:

object

optional

This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Data Object

Data objects wrap Segment objects which assist in conveying user information to bidders.

id:

string

optional

Exchange specific ID for the data provider.

name:

string

optional

Data provider name.

segment:

array of objects

optional

Array of segment objects.

ext:

object

optional

This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Segment Object

Segment objects contain detailed user information that is conveyed to bidders.

id:

string

optional

ID of a data provider's segment applicable to the user.

name:

string

optional

Name of a data provider's segment applicable to the user.

value:

string

optional

String representing the value of the segment. The method for transmitting this data should be negotiated offline with the data provider. For example: For gender, "male" or "female"; for age, "30-40".

ext:

object

optional

This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Regulations Object

Regulations objects specify any legal, governmental, or industry regulations related to the bid request.

coppa:

integer

optional

Flag indicating whether or not this request falls under the COPPA regulations established by the USA FTC, where 0 = no, 1 = yes.

ext:

object

optional

This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

PMP Object

PMP objects are "Private Marketplace" parent objects that contain Direct Deal objects.

private_auction:

integer

optional

An integer flag indicating that this impression is a private auction eligible only to seats named in the Direct Deals object (e.g., 1 = bids for this impression are restricted to the deals specified and the terms thereof; 0 = all bids are accepted).

deals:

array of objects

optional

A collection of "deal" objects encapsulating a list objects of direct deals eligible for this impression.

ext:

object

optional

This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Direct Deals Object

Direct deal objects contain the terms of a deal that is struck a priori between a buyer and seller.

id:

string

required

A unique identifier for the direct deal.

bidfloor:

float

optional

Bid floor for this impression (in CPM of bidfloorcur). Default is 0.

bidfloorcur:

string

optional

If bid floor is specified and multiple currencies supported per bid request, then currency should be specified here using ISO-4217 alphabetic codes. Note, this may be different from bid currency returned by bidder, if this is allowed on an exchange. Default is "USD".

wseat:

array of strings

optional

Array of buyer seats allowed to bid on this Direct Deal. Seats are an optional feature of an exchange. For example, ["4","34","82","45"] indicates that only advertisers using these exchange seats are allowed to bid on this direct deal.

wadomain:

array of strings

optional

Array of advertiser domains allowed to bid on this Direct Deal. For example, ["advertiser1.com","advertiser2.com"] indicates that only the listed advertisers are allowed to bid on this direct deal.

at:

integer

optional

Auction type. If "1", then first price auction. If "2", then second price auction. If "3", the passed bidfloor indicates the apriori agreed upon deal price. Additional auction types can be defined per the exchange's business rules.

ext:

object

optional

This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Bid Response

Every bid request received by the Demand Side Partner server must respond with a bid response object, whether or not the server decides to bid on any impressions. Bid Responses must be returned as a JSON document in the body of each HTTP response. The "id" of the bid response must be set to the "id" of the originating bid request. Bid responses will contain the complete ad and tracking pixel and are ready for immediate display.

Bid responses that place bids must return with an HTTP 200 status code. If the server elects not to bid on a impressions from a particular bid request, it must return with an HTTP 204 status, which represents no-bid response. All other HTTP status codes follow the standard conventions.

Demand Side servers are allowed up to 200 milliseconds to respond to each bid request.

id:

string

required

ID of the bid request.

seatbid:

array of objects

required

Array of seatbid objects.

bidid:

string

optional

Bid response ID to assist tracking for bidders. This value is chosen by the bidder for cross-reference.

cur:

string

optional

Bid currency using ISO-4217 alphabetic codes. Default is "USD".

customdata:

string

optional

This is an optional feature, which allows a bidder to set data in the exchange's cookie. The string may be in base85 cookie-safe characters and be in any format. This may be useful for storing user features. Note: Proper JSON encoding must be used to include "escaped" quotation marks.

nbr:

integer

optional

Reason for not bidding.

ext:

object

optional

This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Seat Bid Object

Each seat bid represents a bidder seat that has bid on one or more impressions. The bids are specified as an array within the "bid" field.

bid:

array of objects

required

Array of bid objects; each bid object relates to an imp object in the bid request. Note that, if supported by an exchange, one imp object can have many bid objects.

seat:

string

optional

ID of the bidder seat on whose behalf this bid is made.

group:

integer

optional

"1" means impressions must be won/lost as a group. Default is "0".

ext:

object

optional

This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.

Bid Object

Individual bid objects must contain the HTML ad markup that is to be displayed if the bid wins the auction in the "adm" field. Any impression tracking pixels for the purposes of bookkeeping and reporting should be included in this markup. The ad markup may contain OpenRTB substitution macros which will be replaced by the AdMedia marketplace with the corresponding value (See Substitution Macros).

id:

string

required

ID for the bid object chosen by the bidder for tracking and debugging purposes. Useful when multiple bids are submitted for a single impression for a given seat.

impid:

string

required

ID of the impression object to which this bid applies.

price:

float

required

Bid price in CPM. Note: Although this value is a float, OpenRTB strongly suggests using integer math for accounting to avoid rounding errors.

adid:

string

optional

ID that references the ad to be served if the bid wins.

nurl:

string

optional

Win notice URL. Note that ad markup is also typically, but not necessarily, returned via this URL.

adm:

string

optional

Actual ad markup. XHTML if a response to a banner object, or VAST XML if a response to a video object.

adomain:

array of strings

optional

Advertiser's primary or top-level domain for advertiser checking. This can be a list of domains if there is a rotating creative. However, exchanges may mandate that only one landing domain is allowed.

iurl:

string

optional

Sample image URL (without cache busting) for content checking.

cid:

string

optional

Campaign ID or similar that appears within the ad markup.

crid:

string

optional

Creative ID for reporting content issues or defects. This could also be used as a reference to a creative ID that is posted with an exchange.

attr:

array of integers

optional

Array of creative attributes.

dealid:

string

optional

A unique identifier for the direct deal associated with the bid. If the bid is associated and in response to a dealid in the request object, it is required in the response object.

h:

integer

optional

Width of the ad in pixels. If the bid request contained the wmax/hmax and wmin/hmin optional fields, it is recommended that the response bid contains this field to signal the size of ad chosen.

w:

integer

optional

Height of the ad in pixels. If the bid request contained the wmax/hmax and wmin/hmin optional fields, it is recommended that the response bid contains this field to signal the size of ad chosen.

ext:

object

optional

This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.