Adform OpenRTB Handler: Bid Response Specifications

id

string; required

ID of the bid request to which this is a response.

yes

seatbid

object array

Array of seatbid objects; 1+ required if a bid is to be made.

yes

bidid

string

Bidder generated response ID to assist with logging/tracking.

no

cur

string; default “USD”

Bid currency using ISO-4217 alpha codes.

yes

customdata

string

Optional feature to allow a bidder to set data in the exchange’s cookie.  The string must be in base85 cookie safe characters and be in any format.  Proper JSON encoding must be used to include “escaped” quotation marks.

no

nbr

integer

Reason for not bidding. 

no

ext

object

Placeholder for bidder-specific extensions to OpenRTB.

no

bid

object array; required

Array of 1+ Bid objects each related to an impression.  Multiple bids can relate to the same impression.

yes

seat

string

ID of the buyer seat (e.g., advertiser, agency) on whose behalf this bid is made.

yes

group

integer; default 0

0 = impressions can be won individually; 1 = impressions must be won or lost as a group.

no

ext

object

Placeholder for bidder-specific extensions to OpenRTB.

no

id

string; required

Bidder generated bid ID to assist with logging/tracking.

yes

impid

string; required

ID of the Imp object in the related bid request.

yes

price

float; required

Bid price expressed as CPM although the actual transaction is for a unit impression only.  Note that while the type indicates float, integer math is highly recommended when handling currencies (for example, BigDecimal in Java).

yes

nurl

string

Win notice URL called by the exchange if the bid wins (not necessarily indicative of a delivered, viewed, or billable ad); optional means of serving ad markup.  Substitution macros may be included in both the URL and optionally returned markup.

yes*

For native assets only.

burl

string

Billing notice URL called by the exchange when a winning bid becomes billable based on exchange-specific business policy (for example, typically delivered, viewed, etc.). Substitution macros may be included.

no

lurl

string

Loss notice URL called by the exchange when a bid is known to have been lost.  Substitution macros may be included. Exchange-specific policy may preclude support for loss notices or the disclosure of winning clearing prices resulting in ${AUCTION_PRICE} macros being removed (for example, replaced with a zero-length string).

no

adm

string

Optional means of conveying ad markup in case the bid wins; supersedes the win notice if markup is included in both. Substitution macros may be included.

yes

adid

string

ID of a preloaded ad to be served if the bid wins.

no

adomain

string array

Advertiser domain for block list checking (for example, “ford.com”). This can be an array of for the case of rotating creatives. Exchanges can mandate that only one domain is allowed.

yes

bundle

string

A platform-specific application identifier intended to be unique to the app and independent of the exchange. On Android, this should be a bundle or package name (for example, com.foo.mygame). On iOS, it is a numeric ID.

no

iurl

string

URL without cache-busting to an image that is representative of the content of the campaign for ad quality/safety checking.

no

cid

string

Campaign ID to assist with ad quality checking; the collection of creatives for which iurl should be representative.

no

crid

string

Creative ID to assist with ad quality checking.

yes

tactic

string

Tactic ID to enable buyers to label bids for reporting to the exchange the tactic through which their bid was submitted. The specific usage and meaning of the tactic ID should be communicated between buyer and exchanges a priori.

no

cat

string array

IAB content categories of the creative. 

yes

attr

integer array

Set of attributes describing the creative. 

no

api

integer

API required by the markup if applicable. 

no

protocol

integer

Video response protocol of the markup if applicable. 

no

qagmediarating

integer

Creative media rating per IQG guidelines. 

no

language

string

Language of the creative using ISO-639-1-alpha-2. The non- standard code “xx” may also be used if the creative has no linguistic content (for example, a banner with just a company logo).

no

dealid

string

Reference to the deal.id from the bid request if this bid pertains to a private marketplace direct deal.

yes

w

integer

Width of the creative in device independent pixels (DIPS).

yes

h

integer

Height of the creative in device independent pixels (DIPS).

yes

wratio

integer

Relative width of the creative when expressing size as a ratio. Required for Flex Ads.

no

hratio

integer

Relative height of the creative when expressing size as a ratio. Required for Flex Ads.

no

exp

integer

Advisory as to the number of seconds the bidder is willing to wait between the auction and the actual impression.

no

dur

integer

Duration of the video creative in seconds.

yes

ext

object

Placeholder for bidder-specific extensions to OpenRTB.

behalf

string

Advertiser Transparency: Free UNICODE text string with a name of whose behalf the ad is displayed.

yes

Maximum 100 characters

paid

string

Advertiser Transparency: Free UNICODE text string of who paid for the ad.

yes

Will always be included even if it's the same as what is listed in the behalf attribute. Maximum 100 characters

transparency

array of object

Array of objects of the entities that applied user parameters and the parameters they applied.

yes

adrender

Integer

Flag to indicate that buyer/advertiser will render their own DSA transparency information inside the creative.

yes

0 = buyer/advertiser will not render

1 = buyer/advertiser will render

domain

string

Domain of the entity that applied user parameters

yes

params

array of integer

Array of buy-side applied user parameter targeting

yes

1 = Profiling. Information about the user, collected and used across contexts, that is about the user's activity, interests, demographic information, or other characteristics.

2 = Basic Advertising. Use of real-time information about the context in which the ad will be shown, to show the ad, including information about the content and the device, such as: device type and capabilities, user agent, URL, IP address, non-precise geolocation data.

3 = Precise geolocation. The precise real-time geolocation of the user, for example, GPS coordinates within 500-meter radius precision.