Bid Object

Note

(*) Fields marked with an asterisk are usually optional, but may be required for some Suppliers, check for usage notes

Bid Object Properties
Value Type Description
id string A bidder generated ID for the bid object, used for tracking and debugging purposes, for example 3.
impid string The ID of the impression object (imp) from the bid request to which this bid response applies, for example "1"
price float The bid price as a float value, expressed as CPM. All prices assumed to be in USD if the cur parameter is omitted, for example 1.23
adm* string

Creative markup for banner ads.

  • For protocol version 4.x this field should not contain the win price macro.
  • From version 5.x, this field can contain the win price macro unless the bid request contains ext.s2s_nurl field value equal to 1, see the 5.x Updating Overview section for more information.
  • This field is required for banner ads, and is ignored for video or native bid responses.
  • The adm field is supported from protocol 4.0, so bid responses containing the adm field but not containing the ext.protocol value of 4.0+ are deemed invalid.
  • No more than one win price macro can be used in the adm field, otherwise BidSwitch records multiple impression events.

<a href=\"http://adserver.com/click?adid=125&tracker=${CLICK_URL:URLENCODE}\"> <img src=\"http://image1.cdn.com/impid=102\"/></a>

burl string

Specifies the billing notice URL called by BidSwitch using a server-to-server call when BidSwitch records a billable impression.

  • Introduced with v5.2 of the BidSwitch protocol, the burl is always a Server-to-Server(s2s) notification, see Server-to-Server (s2s) Calls for more details.
  • This field should contain the win price macro, see the Macros section
  • See the Using the burl Field section for more details.
  • BidSwitch expects that burl calls should return a HTTP status 200, 204, or 30x, see the Server-to-Server (s2s) Calls section for more information.
  • The field is supported in protocol 5+ versions only.
  • You can respond with a non-secure burl for secure bid requests:

"burl":"http://adserver.com/winnotice?impid=102&winprice=${AUCTION_PRICE}"

nurl string

The win notice URL called if the bid wins.

  • This field should NOT be used for submitting creative markup.
  • The URL can contain the win price macro, see the Macros and 5.x Updating Overview sections.
  • This URL will be mostly called from the user’s browser and should thus be SSL-compliant for requests with imp.secure set to 1. But if this URL is to be called using a s2s call as specified in the Bid Request (imp.ext.s2s_nurl set to 1) then is is recommended that it be non-SSL-compliant.
  • For video responses, you should use the bid.ext.vast_url field to pass the VAST URL, see Video Ext Object.
  • For v5.0 and v5.1, if the Bid Request set the ext.s2s_nurl field value to 1 this URL will be called by a s2s call.
  • BidSwitch expects that nurl calls for Bid Requests with ext.s2s_nurl set to 1 should return a HTTP status 200, 204, or 30x, see the Server-to-Server (s2s) Calls section for more information.
  • As of v5.2, if the bid request set the ext.s2s_nurl field value to 1, only the burl field will be called. Therefore, use the burl field to pass the win price macro. See the burl Field Overview section for more details.

http://adserver.com/winnotice?impid=102&winprice=${AUCTION_PRICE}

Note: This describes the behaviour in version 4.0+, which changed since version 2.x. For more information about the 2.x behaviour, see the nurl Response Difference section.

iurl* string

Sample image URL (without cache busting) for content checking, e.g. "http://adserver.com/preview?impid=102"

REQUIRED: for banner bid requests.

language* string

The Alpha-2 ISO 639-1 code for the creative’s language, for example, jp. The nonstandard code "xx" may also be used if the creative has no linguistic content (e.g., a banner with just a company logo).

Use this field instead of the deprecated bid.ext.language field.

REQUIRED in bid responses to BrightRoll SSP (rmx).

adid* string

ID that references the ad to be served if the bid wins. Either the adid field or crid field should be present in the response, for example "3021"

Note: Sometimes a Supplier’s CA Service bans creatives that seen in both secure (https) and non-secure (http) forms. Therefore it is recommended to have separate IDs for secure and non-secure versions of the same creative, e.g. cr_123 & cr_123_ssl

adomain array of strings Advertiser’s primary or top-level domain for advertiser checking. This can be a list of domains if there is a rotating creative. Note that some Suppliers allow only one domain. To those Suppliers BidSwitch only sends the first domain from the list, for example, ["advertiser.com"]
cid* string

Campaign ID or similar that is used by the Buyer to track and organize their campaigns, for example, 102

REQUIRED in responses for Rubicon, Nexage, Smaato and MoPub.

crid* string

Creative ID to assist with ad quality checking. Either the adid field or crid field should be present in the response, for example “3021”

Note: Sometimes a Supplier’s CA Service bans creatives that seen in both secure (https) and non-secure (http) forms. Therefore it is recommended to have separate IDs for secure and non-secure versions of the same creative, e.g. cr_123 & cr_123_ssl

attr* array of integers Creative attributes as defined in the OpenRTB protocol, for example, [1,3].
dealid* string Reference to the deal.id from the bid request, if this bid pertains to a private marketplace direct deal, for example, "AA-1234"
h* integer The height of the creative in pixels when an alternative ad size is used, relevant for banner ads only. 250
w* integer The width of the creative in pixels when an alternative ad size is used, relevant for banner ads only. 300
cat* array of strings

The IAB category of the creative.

REQUIRED in bid responses to BrightRoll SSP (RMX), MoPub, Smaato and YieldOne bids. If the Supplier only accepts one category in the bid response the first array element will be used, for example, ["IAB1"]

Note: For backward compatibility, this field can also be a string when using the BidSwitch 4.0 protocol.

ext* object This field may be required under certain circumstances, see Bid Ext Object.

Bid Ext Object

Bid Ext Object Properties
Value Type Description
at1* int

Indicates that the Buyer wishes their bid to be used in the Supplier 1st price auction before being passed to any upstream auction e.g. header bidding. This field currently only takes the following value:

  • 1 indicates that the field should be included in the first-price auction before being passed further upstream
  • This field is only valid with the following Supplier: Nexage (a.k.a Millennial Media in the myBidSwitch UI)
asid* string Required only for Microad premium inventor responses. If you are using a 3rd party ad server you must specify which one, for example, "Sizmek/Sizmek". See the MicroAd 3PAS List section for more information
country* string Required only for Microad premium inventory responses and uses ISO 3166-1 Alpha-3 country codes, for example JPN. Specifies the target country of the Ad campaign. If you have multiple GEO targets, set the main one here.
advertiser_name* string

The name of the advertiser serving the creative, for example, "Coca-Cola"

  • REQUIRED in bid responses to Ströer (AdScale), Centro, and BRX.
  • Recommended in responses to YieldOne bids.
agency_name* string

The name of the agency representing the advertiser, for example, "CCA"

REQUIRED in bids responses to Ströer (AdScale) bids.

agency_id* string ID of the agency representing the advertiser, for example, “123”
lpdomain* array of strings

The actual landing page URL of the creative. We highly recommend that you always fill this field, especially for mobile application ads, and for all Google responses, for example:

  • "adomain":["angrybirds.com"]
  • "lpdomain":["https://itunes.apple.com/ru/app/angry-birds/id343200656?mt=8", "https://play.google.com/store/apps/details?id=com.rovio.angrybirds"]
language* string

The Alpha-2 ISO 639-1 code for the creative’s language, for example, jp.

Deprecated since version 5.2.: Use seatbid.bid.language instead.

google* object Contains additional information for Google bids. This field is recommended. See the Supplier Specific Fields section for more details.
yieldone* object Contains additional information for YieldOne bids. This field is recommended. See the Supplier Specific Fields section for more details.
vast_url* string

The URL pointing to the location of the VAST document for bid responses to video traffic, for example, "http://adserver.com/vast?impid=102"

  • Required if the video.ext.vast_url_rq bid request field is set to 1.
  • If the video.ext.vast_url_rq bid request field is set to 0 or missing, you can include the VAST URL in the nurl field.

For more information see the Video Ext Object section.

Note:

  • The VAST URL should NOT contain a win price macro.
  • The VAST document should NOT contain impression tracking URLs with win price macros.
daast_url* string

The URL pointing to the location of the DAAST document for the bid response, for example, "http://adserver.com/daast?impid=102"

REQUIRED for bid responses to audio traffic.

Note:

  • The DAAST URL should NOT contain a win price macro.
  • The DAAST document should NOT contain impression tracking URLs with win price macros.
duration* integer

Video ad duration in seconds, for example, 13

REQUIRED in bid responses to BrightRoll Video (brx).

native* object Contains the details of the native response, for more information, see Native Response Object.
deal* string

This is the ID of the deal between a publisher and a seat. It is used only if an exchange supports private auctions.

If the bid is associated with a direct deal then this field is required and its value should be equal to one of the elements in the pmp.deals field in the bid request object.

Deprecated since version 2.5: use seatbid.bid.dealid instead.

img_url* string

The URL of the creative image. In order to receive the user cookie and win price, this URL should point to the Buyer handler and redirect to the actual creative location. The url may contain the win price macro, e.g. ${AUCTION_PRICE}, but not the click macro.

If this field is present, the nurl field of the bid response will be ignored.

Note: This field is only valid in 2.x bid responses, see the Deprecated 2.x Properties section for more details.

click_url* string

The creative click URL. Required if the img_url field is present.

Note: This field is only valid in 2.x bid responses, see the Deprecated 2.x Properties section for more details.

js_url* string

A Javascript-based win notice URL.

  • For in-app inventory, the ad markup should be returned using this URL.
  • For website or video inventory this field may be used as a substitute for the nurl field.
  • Ad markup should be in JavaScript format.
  • The URL may contain macros, see the Macros section for more details.

Note: This field is only valid in 2.x bid responses, see the Deprecated 2.x Properties section for more details.

Note

Some of the fields are required by certain Suppliers. Responses to bid requests from these Suppliers without the required fields will be discarded.

Required Bid Response Fields Per Supplier

Required Bid Response Fields Per Supplier
Supplier Required field(s)
BrightRoll Video (brx) ext.advertiser_name, ext.duration
BrightRoll SSP (rmx) cat, ext.language
Centro ext.advertiser_name
LiveIntent Ad markup should contain the ad image tag and no more than one pixel.
MicroAd (For Premium Inventory) cat, ext.country, ext.asid. See also the MicroAd 3PAS List section.
Millennial Media (nexage) cid
MoPub cid, cat
Rubicon cid
Smaato cid, cat
Ströer (adscale) ext.advertiser_name, ext.agency_name
YieldOne cat