Bid response overview

INVIDI Pulse recommends DSPs to respond with multiple bids per bid response, at least one bid per impression.

Bid responses should be sent as JSON objects or protobuf objects of the same schema. See Bid response JSON example: Private marketplace.

If a DSP has no bid, it should be indicated as a bid response with the nbr field populated, or if that is not possible, as an HTTP 204 No Content response. See No bid response JSON example.

The following diagram includes only object data types and shows a high-level overview of the structure of a bid response as supported in Pulse.

Bid response high-level overview

Bid response object

Pulse expects the following fields to be returned in the top-level BidResponse object:

Field Type Description
id string

(Required) ID of the bid request to which this is a response. The value of this field should be populated from the BidRequest.id field.

bidid string

Bidder generated response ID to assist with logging/tracking.

cur string

Bid currency using ISO-4217 alpha codes, default USD.

nbr integer

Reason for not bidding when not bidding.

seatbid seatbid object array

Array of seatbid objects. Collection of bids made by the bidder on behalf of a specific seat. This field is only required if you are bidding on the bid request. See Seat bid object.

Seat bid object

BidResponse > seatbid

Each seatbid object represents a different bidder seat and contains one or more individual bids. Pulse expects the following fields to be returned in the seatbid object:

Field Type Description
seat string

ID of the bidder seat on whose behalf this bid is made. See Seat taxonomy for details.

bid bid object array

(Required) Array of bid objects, containing properties that describe the bid for the current impression, that is an offer to buy a specific impression under certain business terms. Multiple bids can relate to the same impression. See Bid object.

Bid object

BidResponse > seatbid > bid

Pulse expects the following fields to be returned in the bid object:

Field Type Description
id string

(Required) Bidder generated bid ID to assist with logging/tracking.

impid string

(Required) ID of the Imp object in the related bid request. You should populate this field from BidRequest.imp.id.

price float

(Required) Bid price expressed as CPM although the actual transaction is for a unit impression only.

adid string

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

nurl string

Specifies the win notice URL, which is called by the exchange to inform the bidder of their win and its details. Optional means of serving ad markup. See Supported macros for more information on the macros that are supported in the nurl field..

adm string

Optional means of conveying ad markup in case the bid wins. It supersedes the win notice if markup is included in both. See Supported macros for more information on the macros that are supported in the adm field.

adomain string array

Advertiser domain for blocklist checking (for example, ford.com).

In case more than one domain is provided, only the first domain in the array is considered, all other domains are ignored. This means that only the first domain will be considered when applying whitelist/blacklist and clash protection rules.

iurl string

URL without cache-busting to an image that is representative of the content of the campaign for ad quality/safety checking. Required when the publisher only allows pre-approved creatives.

cid string

Campaign ID to assist with ad quality checking; the collection of creatives for which iurl should be representative. Required when the publisher only allows pre-approved creatives.

crid string

Creative ID to assist with ad quality checking. Required when the publisher only allows pre-approved creatives.

dealid string

Reference to the BidRequest.imp.pmp.deal.id from the bid request if this bid pertains to a private marketplace direct deal. Required when bidding on a private marketplace.

Bid response JSON example: Private marketplace

{
  "id": "80ce30c53c16e6ede735f123ef6e32361bfc7b22",
  "bidid": "4961e0fc-e623-4a10-9b24-d2cf3977dced",
  "cur": "USD",
  "seatbid": [
    {
      "seat": "Agency1",
      "bid": [
        {
          "id": "209b0d17-cff0-49ed-818c-f5d6124ab484",
          "impid": "1",
          "price": 10.5,
          "adid": "3378be5c-37a1-4b7c-8b39-f04da4b47224",
          "nurl": "http://mydsp.com?auction=${AUCTION_ID}&bidid=${AUCTION_BID_ID}&impid=${AUCTION_IMP_ID}&seatid=${AUCTION_SEAT_ID}&adid=${AUCTION_AD_ID}&price=${AUCTION_PRICE:RC4}",
          "adm": "<VAST version=\"2.0\"><Ad id=\"94594182-7fb3-4464-821f-69c2d7ab9a36\"><InLine><AdSystem>My DSP</AdSystem><AdTitle>Pepsi ad</AdTitle><Error><![CDATA[http://my.dsp/track/v2?aid=0&e=400&pid=10120102]]></Error><Impression><![CDATA[http://my.dsp/track/v2?aid=123456&e=0&pid=10120102]]></Impression><Creatives><Creative id=\"video\"><Linear><Duration>00:00:10</Duration><TrackingEvents><Tracking event=\"start\"><![CDATA[http://my.dsp/track/v2?aid=123456&e=start&pid=10120102]]></Tracking><Tracking event=\"midpoint\"><![CDATA[http://my.dsp/track/v2?aid=123456&e=midpoint&pid=10120102]]></Tracking><Tracking event=\"complete\"><![CDATA[http://my.dsp/track/v2?aid=123456&e=complete&pid=10120102]]></Tracking></TrackingEvents><VideoClicks><ClickThrough><![CDATA[http://my.dsp/track/v2?aid=123456&e=20&pid=10120102&redirect=http%3A%2F%2Fwww.pepsi.com]]></ClickThrough></VideoClicks><MediaFiles><MediaFile delivery=\"progressive\" type=\"video/mp4\" bitrate=\"892\" width=\"640\" height=\"360\" scalable=\"true\"><![CDATA[http://adcdn.cdn/assets/a9f430e2-64c8-43de-aedf-64cd24fcd079.mp4]]></MediaFile></MediaFiles></Linear></Creative></Creatives></InLine></Ad></VAST>",
          "adomain": "pepsi.com",
          "crid": "94594182-7fb3-4464-821f-69c2d7ab9a36",
          "dealid": "Oo-86a614d3-7a7f-42a4-af98-d7b81a878d70"
        }
      ]
    },
    {
      "seat": "Agency2",
      "bid": [
        {
          "id": "d57f85ef-4dc5-4c60-811c-d7c193140b3f",
          "impid": "1",
          "price": 20.5,
          "adid": "ab74a673-062e-4121-918a-ea0074df3a2f",
          "nurl": "http://mydsp.com?auction=80ce30c53c16e6ede735f123ef6e32361bfc7b22&bidid=d57f85ef-4dc5-4c60-811c-d7c193140b3f&impid=1&seatid=Agency2&adid=ab74a673-062e-4121-918a-ea0074df3a2f&price=${AUCTION_PRICE:RC4}",
          "adm": "<VAST version=\"2.0\"><Ad id=\"94594182-7fb3-4464-821f-69c2d7ab9a36\"><InLine><AdSystem>My DSP</AdSystem><AdTitle>Pepsi ad</AdTitle><Error><![CDATA[http://my.dsp/track/v2?aid=0&e=400&pid=10120102]]></Error><Impression><![CDATA[http://my.dsp/track/v2?aid=123456&e=0&pid=10120102]]></Impression><Creatives><Creative id=\"video\"><Linear><Duration>00:00:10</Duration><TrackingEvents><Tracking event=\"start\"><![CDATA[http://my.dsp/track/v2?aid=123456&e=start&pid=10120102]]></Tracking><Tracking event=\"midpoint\"><![CDATA[http://my.dsp/track/v2?aid=123456&e=midpoint&pid=10120102]]></Tracking><Tracking event=\"complete\"><![CDATA[http://my.dsp/track/v2?aid=123456&e=complete&pid=10120102]]></Tracking></TrackingEvents><VideoClicks><ClickThrough><![CDATA[http://my.dsp/track/v2?aid=123456&e=20&pid=10120102&redirect=http%3A%2F%2Fwww.pepsi.com]]></ClickThrough></VideoClicks><MediaFiles><MediaFile delivery=\"progressive\" type=\"video/mp4\" bitrate=\"892\" width=\"640\" height=\"360\" scalable=\"true\"><![CDATA[http://adcdn.cdn/assets/a9f430e2-64c8-43de-aedf-64cd24fcd079.mp4]]></MediaFile></MediaFiles></Linear></Creative></Creatives></InLine></Ad></VAST>",
          "adomain": "cocacola.com",
          "crid": "9b60e3ad-2925-40cb-b3cb-d5234e058e56",
          "dealid": "Oo-7bfce833-6f62-4dfd-b371-af59fffb5492"
        }
      ]
    }
  ]
}

No bid response JSON example

{
  "id": "80ce30c53c16e6ede735f123ef6e32361bfc7b22",
  "seatbid": [],
  "nbr": 8
}