Demand Side Integration

Demand Side Integration

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.

Partner Requirements

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

User ID Match URL

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:

Option 1: TheAgency Maps User ID

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).

Option 2: Partner Maps User ID

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

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 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. 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 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. 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 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. 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

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). 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

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. 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

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. 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 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. 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 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. 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 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. 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 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. 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 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.

Example: Banner Ad Bid Request

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"
                }
            }
            

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. 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.

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 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.