Link Search Menu Expand Document

PDF

BidResponse Object

Demand Partners

Last updated on October 9, 2017


After parsing and processing a BidRequest from OpenX Ad Exchange, your bidding application should return a valid response. If you do not want to place a bid on a bid request, return one of the following:

  • A 204 No Content response.
  • A 200 OK response with an empty body.
  • A valid BidResponse object with an empty seatbid array.
  • A valid BidResponse object containing a bid with a price of 0.

Each OpenX Ad Exchange bid response contains a BidResponse object with a single SeatBid object, as shown in the diagram.

Each Bid object may include a notification URL in its BidResponse.seatbid.bid.nurl field. If that bid wins the auction, a GET request is made to the URL after any substitution macros in the URL are expanded.

NOTE

OpenX supports only one SeatBid object per BidResponse.

Successful bids must be submitted within 125 milliseconds, which means that OpenX Ad Exchange receives and registers the response within that time frame. If you send your response at 124 milliseconds, it is unlikely that OpenX Ad Exchange receives and registers the bid response within the allocated time. OpenX Ad Exchange reduces the number of bid requests it sends to bidders with excessive timeouts.

You can submit multiple bids for each bid response of a given auction. OpenX Ad Exchange accepts responses greater than 1 kB, but they may negatively impact performance. Try to keep responses ≤ 1 kB.

The following table describes required and optional fields for each BidResponse you send to OpenX Ad Exchange.

Field nameData typeDescriptionSent?
idstringThe unique ID for the auction, which OpenX Ad Exchange uses to identify the bid request that this bid response is for.
For example, 888b4a7a-d259-11e0-9912-000c29b0c11a
The value of this field should be populated from the BidRequest.id field.
Yes
seatbidarrayarray of seatbid objects. This field is only required if you are bidding on the bid request.No
bididstringA response ID generated by the bidder for tracking purposes.No

SeatBid Object

Last updated on October 9, 2017

BidResponse.seatbid


Each BidResponse object you send to OpenX Ad Exchange must contain an array with a single SeatBid object, which contains the list of bids for the impression.

Field nameData typeDescriptionSent?
bidarray
Bid object
An array of Bid objects containing properties that describe the bid for the current impression.Yes
seatstringThe unique ID of the bidder seat to which this bid response applies, such as a DSP’s account ID for the buyer.No

Bid Object

Last updated on September 27, 2018

BidResponse.seatbid.bid


Each SeatBid object must contain at least one Bid object that describes your bid for the impression. If you want to include more than one Bid object, see Multi-bid response.

Field nameData typeDescriptionSent?
idstringA response ID generated by the bidder for tracking purposes. OpenX currently ignores this field, but the IAB’s OpenRTB 2.5 specification requires it. You should include this field for future support.Yes
impidstringThe ID of the Imp object to which this bid applies. You should populate this field from BidRequest.imp.id.Yes
pricefloatThe bid price, expressed as CPM.Yes
nurlstringSpecifies the win notice URL, which is called to inform the bidder of their win and its details.

Note: OpenX requires the adoption of the winning price macro via the BidResponse.seatbid.bid.adm field to track both impressions and spend. See Win notifications. We recommend that you do not utilize nurl. Please note that OpenX does not honor any discrepancy disputes based on nurl.
No
lurlstringThe loss notice URL OpenX calls when a bid has lost the auction. OpenRTB substitution macros (the ${AUCTION_LOSS} macro, in particular) may be included. For details, see Loss notifications via LURL. To use this feature, please contact your Platform Development Manager to enable it for your account.No
admstringA string containing the markup for the proposed ad creative. In the case of a banner display ad, this may contain HTML that is displayed. In the case of a video ad, this may contain a VAST creative. In the case of a native ad, this might include the Native 1.0 response markup.

Note: OpenX does not currently support the return of the ad markup by the bidder in response to the nurl win notification. Ad markup must be returned in this field.
Yes
adomainarray (string)The list of advertiser domains for block list checking. OpenX also accepts a full landing page URL. Domains are not case-sensitive. For example, landingpage.comYes
bundlestring(App only) A platform-specific application identifier, which should be unique to the app and independent of the exchange.
   • For Android, this is the bundle or package name. For example, com.foo.mygame
   • For iOS, this is a numeric ID.
Yes
cridstringThe unique buyer-specific ID for the creative, which is useful for reporting content issues or defects.No
catarray (string)The list of IAB content categories for the ad, as defined in the IAB’s OpenRTB 2.5 specification.No
dealidstringA unique ID for the prearranged deal associated with the bid. This must match BidRequest.imp.pmp.deals.id
If the bid is a response to a deal in the request, the dealid field is required in the response.
No
wintegerWidth in device-independent pixels.Yes (if using Format object)
hintegerHeight in device-independent pixels.Yes (if using Format object)
extextensionsAn object containing properties that describe custom fields related to this Bid object.No
BidResponse.seatbid.bid.ext


To provide additional details about the bid, include an Extensions object in your BidResponse.

The Extensions object contains the MatchingAdId object.

Field nameData typeDescriptionSent?
brand_idstringThe bidder’s ID for the actual underlying brand of the ad.No
buyeridstringThe bidder’s ID for the primary buyer in their system (typically a network or agency).No
imptrackersarray (string)(Non-video, mobile app only) A single impression notice URL called by OpenX if the ad was displayed to a user. The URL must be unique per impression. This field is not necessarily indicative of a billable ad.
For example, https://adserver1.com/impressionnotice?impid=42

Note: For pre-rendered content, like cached ads, you must specify the impression tracking URL in the imptrackers field rather than in the ad markup (adm) field. Use of the imptrackers field is required to reduce discrepancies between OpenX-reported impressions and DSP-reported impressions. OpenX does not currently support specifying multiple impression notice URLs, and the imptrackers field should be set to an array length of 1.
No
matching_ad_idMatchingAdId objectThe MatchingAdId object corresponding to the bid. If specified, must match one of the matching_ad_id values passed in the bid request because it is used for tracking.

Note: This attribute is recommended but not required.
No
BidResponse.seatbid.bid.ext.matching_ad_id


The MatchingAdId object includes the following fields.

Field nameData typeDescriptionSent?
campaign_idintegerThe ID for the business unit that the matching ad belongs to. This is the “Legacy ID” available via the Business Units tab.Yes
creative_idintegerThe ID for the matching ad.Yes
placement_idintegerThe ID for the traffic set to which the matching ad belongs.Yes

Multi-bid Response

Last updated on February 27, 2017

Although OpenX Ad Exchange supports only one SeatBid object per BidResponse object, OpenX accepts a bid response that contains multiple bids. This means putting several BidResponse.SeatBid.Bid objects into a single BidResponse.SeatBid object in your bid response (as shown in the BidResponse Object diagram on top of this page).

Submitting multiple bids in a single response has the key advantage of helping you hedge against your bid getting discarded, for example, due to a publisher block on the advertiser or an OpenX block against the creative itself. By submitting multiple bids to a single bid request, you have a higher chance of winning the auction and getting the impression. OpenX only submits the highest bid from your bid request to the auction. In other words, your bids are not used against you to floor your bid.

This method of sending bid responses can have advantages for you in certain situations, such as:

  • Submitting a bid for multiple brands to a bid request: As a DSP, you may want to submit a bid for multiple brands to a single bid request instead of one brand.
  • Submitting multiple ad sizes to a bid request: Using a multi-bid response can be advantageous when an impression can be filled by multiple ad sizes instead of just one. To submit ads of different sizes, refer to the format field in the banner object of the bid request to understand which sizes are possible for the impression. The format field is an array of format objects. Each format object describes an ad size that is allowed by the impression.

Multi-bid BidResponse object example

{
    "id": "xxxxxxxxxxxxxxxxxxxxxxxxx",
    "seatbid": [{
        "bid": [{
            "id": "123456789",
            "impid": "xxxxxxxxxxxxxxxxxxxxxxxxx",
            "price": 0.35,
            "adid": "123456789",
            "adm": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy",
            "adomain": ["xyz.com"],
            "iurl": "http://abcd.png",
            "crid": "568970",
            "cat": ["IAB18", "IAB18-5"],
            "ext": {
                "buyerid": "11"
            }
        }]
    }, {
        "bid": [{
            "id": "987654321",
            "impid": "xxxxxxxxxxxxxxxxxxxxxxxxx",
            "price": 0.466,
            "adid": "987654321",
            "adm": "wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww",
            "adomain": ["efg.com"],
            "iurl": "http://hikj.png",
            "crid": "567611",
            "cat": ["IAB20"],
            "ext": {
                "buyerid": "14"
            }
        }]
    }, {
        "bid": [{
            "id": "234567890",
            "impid": "xxxxxxxxxxxxxxxxxxxxxxxxx",
            "price": 1.3,
            "adid": "234567890",
            "adm": "zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz",
            "adomain": ["lmn.com"],
            "iurl": "http://opqr.png",
            "crid": "568157",
            "cat": ["IAB2-3", "IAB2"],
            "ext": {
                "buyerid": "21"
            }
        }]
    }],
    "cur": "USD"
}

If you need additional assistance implementing multi-bid responses, please contact your Platform Development Manager.