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.

  • When using an <iframe> to include markup and/or pixel trackers, you should close the </iframe> properly as not doing so may result in discrepancies on some browsers.

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

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 (i.e., replaced with a zero-length string).

language*

string

The Alpha-2 ISO 639-1 code for the creative’s language, for example, ja. 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.

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"

Notes:

  • 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

  • When BidSwitch passes the creative ID to the Supplier it prepends the Buyer ID, using the the following syntax: {DSP_ID}_{Creative_ID}, for example 70_650029457 or 79_0RsSUxZety0O1.

  • When BidSwitch receives both adid and crid fields, the adid ID field is used to pass the creative ID to Suppliers

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:

  • Some Suppliers allow only one domain. To those Suppliers BidSwitch only sends the first domain from the list, for example, ["advertiser.com"]

  • BidSwitch invalids non-ascii domains. If you need to pass a domain that uses unicode character such as in the Cyrillic or Japanese script, use punycode

    e.g. детивнепитики.рф or faß.de

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 (e.g., com.foo.mygame)

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”

Notes:

  • Sometimes a Supplier’s CA Service bans creatives that are 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

  • When BidSwitch passes the creative ID to the Supplier it prepends the Buyer ID, using the the following syntax: {DSP_ID}_{Creative_ID}, for example 70_650029457 or 79_0RsSUxZety0O1.

  • When BidSwitch receives both adid and crid fields, the adid ID field is used to pass the creative ID to Suppliers

attr*

array of integers

Creative attributes as defined in the OpenRTB protocol, for example, [1,3].

dealid*

string

(Recommended) Reference to the deal.id from the bid request, if this bid pertains to a private deal, for example, "AA-1234"

  • Note: It is important to include this field if you want to bid on a private deal. Failure to do so may result in your bid not being submitted to the private auction or your bid being invalidated.

h*

integer

The height of the creative in pixels when an alternative ad size is used, relevant for banner ads only. 250. Required: For Pubmatic and YieldOne Banner ads.

w*

integer

The width of the creative in pixels when an alternative ad size is used, relevant for banner ads only. 300. Required: For Pubmatic and YieldOne Banner ads.

cat*

array of strings

The IAB category of the creative.

REQUIRED in bid responses to 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.

Required: for Xandr (Appnexus) mobile ads

  • "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"]

data*

array of object

Returns arbitrary data to the Supplier, each object can take data.name and data.value to describe the data, see the Data Response Object for more details.

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.

skadn*

object

Apple Ad Network Object, this will be used to pass app data from iOS 14 and newer releases. See SkAdNetwork Extension

dsa*

object

Digital Services Act (DSA) Ad Transparency information

SkAdNetwork Extension

skadn Ext Object Properties

Value

Type

Description

version

str

Version of SKAdNetwork desired. Must be “2.0” or above. From SKAdNetwork v2.2 onwards, this should be used in the fidelities object.

network*

str

Ad network identifier used in signature. Should match one of the items in the imp.ext.skadnetids array in the request

campaign*

str

Campaign ID compatible with Apple’s spec. As of 2.0, this should be an integer between 1 and 100, expressed as a string, e.g. "45"

fidelities*

array of objects

Supports multiple fidelity types introduced in SKAdNetwork v2.2, see the SkAdNetwork Fidelities object for details.

Note

From SKAdNetwork v2.2 onwards, this object wraps some of the other fields in this table into it. As a result, nonce, version, timestamp and signature should be used in the fidelities object and considered deprecated in this object.

itunesitem*

str

ID of advertiser’s app in Apple’s app store. Should match the seatbid.bid.bundle response field e.g "880047117"

nonce*

str

An ID unique to each ad response (GUID/UUID) e.g. "beeeb65e-b3de-02420004". From SKAdNetwork v2.2 onwards, this should be used in the fidelities object.

sourceapp*

str

ID of publisher’s app in Apple’s app store, this should match the imp.ext.skadn.sourceapp value

timestamp*

str

Unix time in millis string used at the time of signature. From SKAdNetwork v2.2 onwards, this should be used in the fidelities object.

signature*

str

SKAdNetwork signature as specified by Apple e.g. "MEQCIEQZRRyMyUXg==". From SKAdNetwork v2.2 onwards, this should be used in the fidelities object.

productpageid*

str

Passes the custom product page UUID 45812c9b-c296-43d3-c6a0-c5a02f74bf6e

sourceidentifier*

str

A four-digit integer that ad networks define to represent the ad campaign. Used in SKAdNetwork 4.0+, replaces Campaign ID campaign. Buyers must generate signatures in 4.0+ using the Source Identifier. Please refer to the SKAdNetwork 4 release notes for more details

SkAdNetwork Fidelities

Fidelities Object Properties

Value

Type

Description

fidelity*

int

The fidelity-type of the attribution to track e.g 1

nonce*

str

An ID unique to each ad response (GUID/UUID) e.g. "beeeb65e-b3de-02420004"

timestamp*

str

Unix time in millis string used at the time of signature

signature*

str

SKAdNetwork signature as specified by Apple e.g. "MEQCIEQZRRyMyUXg=="

DSA Extension

DSA Object Properties

Value

Type

Description

behalf*

string

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

paid*

string

Advertiser Transparency: Free UNICODE text string of who paid for the ad. Must always be included even if it’s the same as what is listed in the behalf attribute. Maximum 100 characters

transparency*

array of objects

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

adrender*

integer

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

  • 0: buyer/advertiser will not render

  • 1: buyer/advertiser will render

Transparency Object

DSA Transparency Object Properties

Value

Type

Description

domain*

string

Domain of the entity that applied user parameters

dsaparams*

array of integers

Array of buy-side applied User Parameters targeting (using the list provided by DSA Transparency Taskforce). Include support for multiple vendors who may add their own user-targeting parameters.

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)

Fyber

seatbid.bid.bundle

MicroAd (For Premium Inventory)

seatbid.bid.cat, seatbid.bid.ext.country, seatbid.bid.ext.asid. See also the MicroAd 3PAS List section.

Millennial Media (nexage)

cid

MoPub

seatbid.bid.cid, seatbid.bid.cat

PubMatic

seatbid.bid.w, seatbid.bid.h required for banner ads

Rubicon

seatbid.bid.cid

Smaato

seatbid.bid.cid, seatbid.bid.cat

Ströer (adscale)

seatbid.bid.ext.advertiser_name, seatbid.bid.ext.agency_name

TrustX

seatbid.bid.burl, seatbid.bid.nurl

Xandr (AppNexus) mobile ads

seatbid.bid.ext.lpdomain

YieldOne

seatbid.bid.cat

Suppliers Supporting LURL Field

Supplier

AUCTION MIN TO WIN

AUCTION PRICE

AUCTION LOSS

LURL Support Restrictions

AdColony

No

No

Yes

The reason from the publisher is required, following Loss Reason Codes defined by IAB

Fyber

No

No

Yes

Minimum bid to win is not supported, but eligible to win as long as it is above the floor price

ironSource

Yes

Yes

No information

Supported only for ironSource’s own banner ad format (320x50)

Xandr

No information

No information

No information

Currently in closed beta testing

Sonobi

No

No information

No information

Following IAB standard support

Magnite DV+

Yes for Magnite DV

No

Yes for Magnite DV

Only for DV+, following Loss Reason Codes defined by IAB

MobileFuse

No

No information

Yes

No information

Smart AdServer

No

Yes

Yes

Supposed to be launched late Q2 2023

Outbrain

No information

No information

No information

Following codes by both IAB and Outbrain

PubMatic

No information

No information

No information

No information

TripleLift

No

Direct connections only

Direct connections only

Direct connections only

Unity

Yes

No information

No information

About 15 loss code reasons

Yieldmo

No information

No information

No information

No known restriction, more information required

Bidmachine

No

No information

Yes

Following Loss Reason Codes defined by IAB

OpenX

No

No information

Yes

Loopme

Yes (on the roadmap)

Yes

Yes

Also supports ${AUCTION_PRICE}

Improve Digital

No

No

Yes

Also supports:

  • ${AUCTION_ID} - ID of the bid request; from BidRequest.id attribute.

  • ${AUCTION_BID_ID} - ID of the bid; from BidResponse.bid.id attribute.

  • ${AUCTION_SEAT_ID} - ID of the bidder seat for whom the bid was made.

  • ${AUCTION_AD_ID} - ID of the ad markup the bidder wishes to serve; from bid.adid attribute.