Bid request overview

All fields are populated in the request if available and configured by the publisher to send through. INVIDI Pulse never passes null values or empty strings.

Bid requests are sent in JSON or protobuf format, depending on the DSP’s preference. See Bid request JSON example: Private marketplace.

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

Bid request high-level overview diagram

Note: An extension object is an object of undefined structure that can be added to any other object to convey exchange-specific extensions to the standard.

Bid request object

Some fields in each bid request must always be sent and others are optional. Required and recommended fields are noted in the Description column.

Pulse supports the following fields in the top-level BidRequest object:

Field Type Description
id string

(Required) Unique ID of the bid request.

test integer

Only provided when running in test mode (1), which means that auctions are not billable.

at integer

Auction type. Pulse uses 2nd price auctions (2).

tmax integer

100ms; Maximum time in milliseconds to submit a bid to avoid timeout.

wseat string array

Whitelist of buyer seats allowed to bid on this impression. Omission implies no seat restrictions. See Seat taxonomy for details.

cur string array

Array of allowed currencies for bids on this bid request using ISO-4217 alpha codes. Pulse supports USD, GBP, EUR, SEK, and NOK.

badv string array

Blocklist of advertisers by their domains (for example, ford.com).

imp object array

(Required) The impressions offered in this bid request. Pulse supports a single impression per bid request. See Impression object.

site object

(Recommended) Provides details about the publisher’s website. Only applicable and recommended for websites. See Site object.

app object

(Recommended) Provides details about the publisher’s app (that is, non-browser applications). Only applicable and recommended for apps. See App object.

device object

(Recommended) Provides details about the user’s device to which the impression will be delivered. See Device object.

user object

(Recommended) Provides details about the human user of the device; the advertising audience. See User object.

regs object

Specifies any industry, legal, or governmental regulations in force for this request. See Regulations object.

ext object

Placeholder for exchange-specific extensions to OpenRTB. See Bid request extension object.

Impression object

BidRequest > imp

We support the following fields in the imp object, which describe the impression being auctioned. Pulse supports a single impression per bid request.

Field Type Description
id string

(Required) A unique identifier for this impression within the context of the bid request. Typically, starts with 1 and increments.

tagid string

Identifier for specific ad placement or ad tag that was used to initiate the auction. This can be useful for debugging of any issues, or for optimization by the buyer.

bidfloor float

Minimum bid for this impression expressed in CPM.

To be ignored in case of private marketplace. BidRequest.imp.pmp.deal.bidfloor should be used instead.

bidfloorcur string

Currency specified using ISO-4217 alpha codes. This may be different from bid currency returned by bidder if this is allowed by the exchange.

To be ignored in case of private marketplace. BidRequest.imp.pmp.deal.bidfloorcur should be used instead.

secure integer

Flag to indicate if the impression requires secure HTTPS URL creative assets and markup, where 0 = nonsecure, 1 = secure. If omitted, the secure state is unknown, but non-secure HTTP support can be assumed.

Note: We recommend responding with secure (HTTPS) creative asset URLs.
video object

Required if the impression is offered as video ad opportunity. See Video object.

pmp object

Specifies information about a private marketplace deal that is in effect for this impression. See Private marketplace object.

Video object

BidRequest > imp > video

Pulse supports the following fields in the video object:

Field Type Description
mimes string array

(Required) Content MIME types supported.

minduration integer

(Recommended) Minimum video ad duration in seconds.

maxduration integer

(Recommended) Maximum video ad duration in seconds.

protocols string array

(Recommended) 2,3 (inline VAST 2.0 & 3.0) supported.

startdelay integer
(Recommended) Video ad position, where:
  • 0 = Pre-Roll
  • -1 = Generic Mid-Roll
  • -2 = Generic Post-Roll
  • > 0 = Mid-Roll (value indicating start delay in seconds)
linearity integer

Only 1 (linear video ads) supported.

battr integer array

Blocked creative attributes.

maxbitrate integer

Maximum bitrate in Kbps.

w integer

(Recommended) Width of the video player in pixels.

h integer

(Recommended) Height of the video player in pixels.

api integer array

List of supported API frameworks for this impression.

Private marketplace object

BidRequest > imp > pmp

Pulse supports the following fields in the pmp object:

Field Type Description
private_auction integer

Indicator of auction eligibility to seats named in the Direct Deals object, where 0 = all bids are accepted, 1 = bids are restricted to the deals specified and the terms thereof.

deals Deal object array

Specifies information about the deals for this bid. See Deal object.

Deal object

BidRequest > imp > pmp > deal

Pulse supports the following fields in the deal object:

Field Type Description
id string

(Required) A unique identifier for the direct deal.

bidfloor float

Minimum bid for this impression expressed in CPM.

bidfloorcur string

Currency specified using ISO-4217 alpha codes. This may be different from bid currency returned by bidder if this is allowed by the exchange.

at integer
Optional override of the overall auction type of the bid request, where:
  • 1 = First Price
  • 2 = Second Price Plus
  • 3 = the value passed in bidfloor is the agreed upon deal price

Additional auction types can be defined by the exchange.

wseat string array

Whitelist of buyer seats allowed to bid on this deal. Seat IDs must be communicated between bidders and the exchange a priori. Omission implies no seat restrictions. See Seat taxonomy for details.

wadomain string array

Array of advertiser domains (for example, advertiser.com) allowed to bid on this deal. Omission implies no advertiser restrictions.

Site object

BidRequest > site

Pulse supports the following fields in the site object:

Field Type Description
id string

(Recommended) Unique ID of the site.

domain string

Domain of the site (for example, mysite.foo.com).

cat string array

Array of IAB content categories of the site.

page string

URL of the page where the impression will be shown.

content object

Details about the content within the site. See Content object.

publisher object

Details about the publisher of the site. See Publisher object.

Content object

BidRequest > site > content

Pulse supports the following fields in the content object:

Field Type Description
id string

Unique ID of the content.

len integer

Length of content in seconds; appropriate for video or audio.

App object

BidRequest > app

Pulse supports the following fields in the app object:

Field Type Description
id string

(Recommended) Unique ID of the app.

name string

App name (may be aliased at the publisher’s request).

ver string

Application version.

bundle string

Application bundle or package name (for example, com.foo.mygame); intended to be a unique ID across exchanges.

storeurl string

App store URL for an installed app, for QAG 1.5 compliance.

publisher object

Details about the publisher of the app. See Publisher object.

Publisher object

BidRequest > site > publisher OR BidRequest > app > publisher

Pulse supports the following fields in the publisher object:

Field Type Description
id string

Unique ID of the publisher of the site OR the publisher of the app.

name string

Publisher name (may be aliased at the publisher’s request).

Device object

BidRequest > device

Pulse supports the following fields in the device object:

Field Type Description
ua string

(Recommended) Browser user agent string.

dnt integer

(Recommended) Standard Do Not Track flag as set in the header by the browser, where 0 = tracking is unrestricted, 1 = do not track.

ip string

(Recommended) IPv4 address closest to device. Provided if available and ipv6 not available.

ipv6 string

IP address closest to device as IPv6. Provided if available.

devicetype integer
The type of device from which the impression originated:
  • 1 = Mobile/Tablet
  • 2 = Personal Computer
  • 3 = Connected TV
  • 4 = Phone
  • 5 = Tablet
  • 6 = Connected Device
  • 7 = Set Top Box
make string

Device make (for example, Apple).

model string

Device model (for example, iPhone).

os string

Device operating system (for example, iOS).

osv string

Device operating system version (for example, 3.1.2).

h integer

Physical height of the screen in pixels.

w integer

Physical width of the screen in pixels.

js integer

Support for JavaScript, where 0 = no, 1 = yes.

ifa string

ID sanctioned for advertiser use in the clear (that is, not hashed).

geo object

(Recommended) Location of the device assumed to be the user’s current location. See Geo object.

Geo object

BidRequest > device > geo

Pulse supports the following fields in the geo object:

Field Type Description
country string

Country code using ISO-3166-1-alpha-3.

User object

BidRequest > user

Pulse supports the following fields in the user object:

Field Type Description
id string

(Recommended) Exchange-specific ID for the user. At least one of id or buyeruid is recommended.

buyeruid string

(Recommended) Buyer-specific ID for the user as mapped by the exchange for the buyer. Included when available.

ext object

Placeholder for exchange-specific extensions to OpenRTB. See User extension object.

User extension object

BidRequest > user > ext

Pulse supports the following fields in the user.ext object:

Field Type Description
consent string

GDPR Consent String, built up according to the Transparency and Consent String with Global Vendor and CMP List Formats specification.

Regulations object

BidRequest > regs

Pulse supports the following fields in the regs object:

Field Type Description
ext object

Placeholder for exchange-specific extensions to OpenRTB. See Regulations extension object.

Regulations extension object

BidRequest > regs > ext

Pulse supports the following fields in the regs.ext object:

Field Type Description
gdpr integer

Marker for whether this Bid Request is subject to GDPR regulations. Indicated by an integer, where 0 means the request is not subject, and 1 means it is subject to the regulations.

Bid request extension object

BidRequest > ext

Pulse supports the following fields in the BidRequest.ext object:

Field Type Description
schain object

Specifies the Supply Chain fields included in the OpenRTB bid request for supply path transparency. See Supply chain object (schain).

Supply chain object (schain)

BidRequest > ext > schain

Pulse supports the following fields in the schain object:

Field Type Description
ver string

(Required) Version of the supply chain specification in use, in the format of major.minor. Currently using version 1.0 of the spec.

complete integer

(Required) Flag indicating whether the chain contains all nodes involved in the transaction leading back to the owner of the site, app, or other medium of the inventory, where 0 = no, 1 = yes.

nodes Node object array

(Required) Array of supply chain node objects in the order of the chain.

  • In a complete supply chain, the first node represents the initial advertising system and seller ID involved in the transaction, that is the owner of the site, app, or other medium.
  • In an incomplete supply chain, it represents the first known node.
  • The last node represents the entity sending this bid request, which will be the INVIDI Pulse node.

See Supply chain node object.

Supply chain node object

BidRequest > ext > schain > node

Pulse supports the following fields in the node object:

Field Type Description
asi string

(Required) The canonical domain name of the SSP, Exchange, or Header Wrapper system that bidders connect to. This may be the operational domain of the system, if that is different than the parent corporate domain, to facilitate WHOIS and reverse IP lookups to establish clear ownership of the delegate system.

This should be the same value as used to identify sellers in an ads.txt file if one exists. For the INVIDI Pulse node that domain will be invidi.com.

sid string

(Required) The identifier associated with the seller or reseller account within the advertising system.

rid string

The OpenRTB RequestId of the request as issued by the seller.

name string

The name of the company (the legal entity) that is paid for inventory transacted under the given seller_id.

This value is optional and should NOT be included if it exists in the advertising system’s sellers.json file.

hp integer

(Required) Indicates whether this node will be involved in the flow of payment for the inventory. For version 1.0 of supply chain, this property should always be 1.

Bid request JSON example: Private marketplace

{
  "id": "80ce30c53c16e6ede735f123ef6e32361bfc7b22",
   "cur": [
     "EUR",
     "GBP",
     "USD",
     "SEK",
     "NOK"
  ],
  "imp": [
    {
      "id": "1",
      "secure": "1",
      "video": {
          "mimes": [
            "video/mp4"
          ],
          "startdelay": 0,
          "linearity": 1,
          "maxbitrate": 1000 	
      },
      "bidfloor": 0,
      "bidfloorcur": "USD",
      "pmp": {
        "private_auction": 1,
        "deals": [
          {
            "id":"Oo-86a614d3-7a7f-42a4-af98-d7b81a878d70",
            "at": 3,
            "bidfloor": 10.5,
            "bidfloorcur": "USD",
            "wseat": [ 
                "Agency1" 
            ]
          },
          {
            "id":"Oo-7bfce833-6f62-4dfd-b371-af59fffb5492",
            "at": 3,
            "bidfloor": 20.0,
            "bidfloorcur": "USD",
            "wseat": [ 
                "Agency2" 
            ]
          }
        ]
      }
    }
  ],
  "site": {
    "domain": "foobar.com",
    "cat": [ 
        "IAB9-1" 
        ],
    "page": "http://www.foobar.com/1234.html"
  },
  "device": {
    "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/537.13 (KHTML, like Gecko) Version/5.1.7 Safari/534.57.2",
    "dnt": 0,
    "ip": "123.145.167.10"
  },
  "user": {
    "buyeruid": "55816b39711f9b5acf3b90e313ed29e51665623f"
  },
  "ext": {
    "schain": {
      "complete": 1,
      "nodes": [
        {
          "asi": "invidi.com",
          "sid": "505e9g35-abc8-4fba-bb1c-3fc7a21ec85a",
          "rid": "80ce30c53c16e6ede735f123ef6e32361bfc7b22",
          "name": "FoobarTV",
          "hp": 1,
        }
      ],
      "ver": "1.0"
    }
  }  
}