The TheAgency marketplace provides Demand Side Partners/Publishers a standards-compliant integration solution using RESTful communication over HTTP via the OpenRTB version 2.2 API specification to send and receive JSON messages.
Demand Side integration has two areas of concern: configuring an ad server to respond to bid requests received from the TheAgency marketplace and configuring a user ID matching endpoint.
| Production Bidder Endpoint | The HTTP endpoint URL where TheAgency's RTB will send bid requests for live auctions |
| Testing Bidder Endpoint | The HTTP endpoint URL where TheAgency's RTB will send bid requests for testing and onboarding |
| User ID Match Endpoint | The HTTP endpoint URL where TheAgency's RTB will coordinate the user ID match process |
Typically, advertisers need to record information about the users viewing their ads, and this information is stored using a unique ID. Usually, cookies are used to identify unique users. Browser security features, however, disallow TheAgency servers from sharing cookies with ad servers. To provide user identification, TheAgency will map user IDs generated on the exchange server to user IDs known to the Demand Side Partner. This mapping can be performed using one of two elected options:
TheAgency servers can automatically map unique user IDs to Demand Side Partner IDs. To use this option, the partner must provide a User ID Match Endpoint, which is invoked when a new unique user is identified. This endpoint should inspect the user ID generated by TheAgency and return a redirect with the preferred partner user ID. The partner user ID can be any alpha-numeric identifier (up to 64 characters) but should be unique for the given TheAgency user ID.
The user ID match endpoint must contain a redirect parameter which TheAgency will populate with the redirect URL, the TheAgency user ID (d), and the {AD_SERVER_USER_ID} macro (u). {AD_SERVER_USER_ID} must be replaced with the partner user ID before redirecting.
For example, a user ID match endpoint request would have the form:
http://youradserver.com/match?redirect=http%3A%2F%2Fwww.TheAgency.com
%2Fxmatch%3Fd%3D123%26u%3D%7BAD_SERVER_USER_ID%7D
and the redirect URL decodes to:
http://www.TheAgency.com/xmatch?d=123&u={AD_SERVER_USER_ID}
Here, the TheAgency user ID is 123. If the desired partner user ID is abcd1234, the final redirect would resolve to:
http://www.TheAgency.com/xmatch
Once the initial user ID match has been made, all subsequent bid requests originating from the identified user will include the partner user ID in the buyeruid field of the user object of each bid request (See User Object).
Partners can also elect to perform the user ID mapping in their bidding servers. In this approach, the TheAgency user ID is found in the id field of the user object of each bid request (see User Object).
In order to help our partners perform the user ID mapping, TheAgency can initiate match requests to the partner which will include TheAgency's user ID. In order to take advantage of this service the partner must provide TheAgency with a match url into which TheAgency can substitute our user IDs. A sample URL might look like:
http://youradserver.com/match?d={AD_EXCHANGE_ID}&u={AD_USER_ID}
In the URL, {AD_EXCHANGE_ID} is some ID that the partner provides TheAgency® to identify itself, and {AD_USER_ID} is the user ID that TheAgency knows the user by. When the exchange partner receives the request, it should store a mapping between the {AD_USER_ID} and whatever ID it knows the user by. Unfortunately, in most cases this mapping cannot be stored in cookies because the cookies will not be available to the partner at bid time.
Bid request objects originate from web publishers and are distributed by the TheAgency marketplace to Demand Side Partners. The bid request is the top level object represented in JSON that describes the details of a request for bids. It will contain a unique "id" string in addition to at least one "imp" (impression) object for which an advertiser may decide to place a bid. This message will be received by the Demand Side server as the HTTP request body. The Demand Side server is expected to analyze the impression details and decide whether or not to place a bid, sending a bid response message in return.
| 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. See Content Categories. |
| 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. See Ad Position. |
| btype: | array of integers |
optional Blocked creative types. If blank, assume all types are allowed. See Banner Ad Types. |
| battr: | array of integers |
optional Blocked creative attributes. If blank assume all types are allowed. See Creative Attributes. |
| 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. See Expandable Direction. |
| api: | array of integers |
optional List of supported API frameworks for this banner. See API Frameworks. |
| 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. See Video Bid Response. |
| protocols: | array of integers |
recommended Video bid response protocols. At least one supported protocol must be specified in either the "protocol" or "protocols" attribute. See Video Bid Response. |
| 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. See Video Start Delay. |
| linearity: | integer | |
| sequence: | integer | |
| battr: | array of integers |
optional Blocked creative attributes. If blank, assume all types are allowed. See Creative Attributes. |
| 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. See Video Playback Methods. |
| delivery: | array of integers |
optional List of supported delivery methods (streaming, progressive). If blank, assume all are supported. See Content Delivery Methods. |
| pos: | integer |
optional Ad Position. See 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. See API Frameworks. |
| companiontype: | array of integers |
optional Recommended if companion objects are included. See VAST Companion Types. |
| 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. See Content Categories. |
| sectioncat: | array of strings |
optional Array of IAB content categories for the current subsection of the site. See Content Categories. |
| pagecat: | array of strings |
optional Array of IAB content categories for the current page. See Content Categories. |
| 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). See Video Linearity. 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. See Content Categories. |
| sectioncat: | array of strings |
optional Array of IAB content categories for the current subsection of the app. See Content Categories. |
| pagecat: | array of strings |
optional Array of IAB content categories for the current page/view of the app. See Content Categories. |
| 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. See Content Categories. |
| videoquality: | integer |
optional Video quality per the IAB's classification. See Video Quality. |
| 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.). See Content Context. |
| 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. See QAG Media Ratings. |
| 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. See Content Categories. |
|
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. See Content Categories. |
|
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. See Connection Type. |
|
devicetype: |
integer |
optional The device type being used. See Device Type. |
|
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. See Location Type. |
|
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", |
|
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. |
This bid request is an example of a request for bids on a banner ad impression.
{
"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"
}
}
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. See No-Bid Reason 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. |
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 TheAgency 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. See 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. |