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 ]
}
]
}
]
}
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 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 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 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 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 |
| content: | object |
optional |
| 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 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 |
| content: | object |
optional |
| 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 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 |
| 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 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 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 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 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 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 |
|
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 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 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 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 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 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. |
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. |
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. |
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. |