You are here: Demand Partners > Real-time bidding APIs > Proprietary API > BidResponse


Last updated on February 24, 2017

After parsing and processing a BidRequest from Ad Exchange, your bidding application must return a BidResponse message, even if you do not want to place a bid.

Successful bids must be submitted within 125 milliseconds, which means that Ad Exchange receives and registers the response within that interval. If you send your response at 124 milliseconds, it is unlikely that Ad Exchange will receive and register the BidResponse within the allocated time.

Ad Exchange reduces the number of bid requests it sends to bidders with excessive timeouts.

For each BidResponse in a given auction, you can submit multiple bids. Although Ad Exchange accepts responses greater than 1 kB, try to keep responses less than or equal to 1 kB in size.

If you do not want to place a bid, return a BidReponse with one of the following:

  • An empty list of bids

  • An HTTP code of 204

  • An empty protobuf

Multiple fields in the BidResponse message use CPMCost per mille, a pricing method which calculates cost based on the number of impressions (per 1000). micros to express their values. The conversion for a CPM micro is: $1.00 USD = 1,000,000 micros. For example:

  • $0.01 = 10,000 micros

  • $0.10 = 100,000 micros

  • $1.00 = 1,000,000 micros

  • $3.27 = 3,270,000 micros

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

Note: Some fields in the BidResponse have been deprecated and are now part of the Bid structure for each BidResponse.


Field name Data type Description Required?
api_version int32

The version of the API that you are using to respond to Ad Exchange

Note: This value must match the api_version in the BidRequest.

auction_id int32

The unique ID for the auction, which Ad Exchange generates and uses to identify the BidRequest that this BidResponse is for

For example: 888b4a7a-d259-11e0-9912-000c29b0c11a

Note: This value should match the auction_id value in the BidRequest.

bids array (Bid object)

An array of objects containing properties that describe bids to return for the BidRequest

You can submit multiple bids for a single auction.

Note: To submit a "no bid" response, include an empty list of bids, a list of bids with a cpm_bid_micros of 0, an HTTP 204, or an empty protobuf.

next_highest_bid_micros int64

The next highest bid after the bids in this response, expressed in CPM micros.

For example, a value of 1,250,000 CPM micros equals $1.25 (if the currency is dollars).


See also:

Feedback form