Equativ provides an OpenRTB API for suppliers which is able to receive OpenRTB bid requests. Equativ then runs an auction for each request so Equativ’s demand partners can bid on the opportunity. This guide contains the bid request specification (part 1).
The unique ID of the bid request, provided by the exchange. A new ID is always generated before Equativ sends the bid request to its bidders.
imp
OBJECT ARRAY
REQUIRED
An array of impression objects. At least one impression object is required for a valid bid request. For more details, read sections "Multi-impression-type bid requests" and "Multi-imp-object bid requests" in the OpenRTB API for suppliers — Getting started article.
app
OBJECT
SEE DESCRIPTION
An object to be included if the ad-supported content is part of a mobile application (as opposed to a mobile website). A bid request can contain either an app object, a site object or a dooh object. The app object itself and all of its parameters are optional, so default values are not provided. If an optional parameter is not specified, it will be considered unknown. Providing an App ID or Bundle ID is strongly recommended.
site
OBJECT
SEE DESCRIPTION
An object to be included if the ad-supported content is part of a website (as opposed to an application). A bid request can contain either an app object, a site object or a dooh object.
dooh
OBJECT
SEE DESCRIPTION
An object to be included if the ad-supported content is digital out-of-home. A bid request can contain either an app object, a site object or a dooh object.
device
OBJECT
REQUIRED
An object containing device information, such as hardware, platform, location, carrier etc.
user
OBJECT
REQUIRED
An object containing information known or derived from the human user of the device.
tmax
INTEGER
OPTIONAL
The maximum amount of time in milliseconds to submit a bid. For example, 120 means the bidder has 120 ms to submit a bid before the auction is complete. If this value never changes across an exchange, then the exchange can supply this information offline. The tmax value sent to Equativ's bidders is always lower to allow for sufficient time when processing the bid responses.
cur
STRING[]
OPTIONAL
An array of allowed currencies for bids on the given bid request, using ISO-4217 alpha codes. Default: USD. Equativ will convert the bidPrice of its bid response to cur[0] (or the following if the first one is unknown).
source
OBJECT
SEE DESCRIPTION
An object describing the nature and behavior of the entity that is the source of the bid request, upstream from the exchange (see OpenRTB SupplyChain object). See description of child fields which may imply that this object is required.
regs
OBJECT
SEE DESCRIPTION
An object specifying any industry, legal, or governmental regulations in force for the given bid request. See description of child fields which may imply that this object is required.
ext
DICTIONARY
OPTIONAL
A placeholder for exchange specific extensions to OpenRTB. Contains bid_feedback information used for optimization of the bidding strategy towards DSPs.
bcat
STRING ARRAY
OPTIONAL
Blocked advertiser categories using the specified category taxonomy. The taxonomy to be used is defined by the cattax field. If no cattax field is supplied IAB Content Taxonomy 1.0 is assumed. Only one of acat or bcat should be present.
cattax
INTEGER
OPTIONAL
default:1; The taxonomy in use for bcat. Refer to the AdCOM 1.0 list List: Category Taxonomies for values.
badv
STRING ARRAY
OPTIONAL
Block list of advertisers by their domains (e.g., “ford.com").
Imp object
For more details on how the Equativ SSP processes the imp object, read sections "Multi-impression-type bid requests" and "Multi-imp-object bid requests" in the OpenRTB API for suppliers — Getting started article.
OpenRTB field
Data type
Necessity
Description
banner
OBJECT
SEE DESCRIPTION
A reference to a banner object. Either a banner, video or audio object must be included in an imp object.
video
OBJECT
SEE DESCRIPTION
A reference to a video object. Either a banner, video or audio object must be included in an imp object.
audio
OBJECT
SEE DESCRIPTION
A reference to an audio object. The audio object will be converted into a video object (with audio mime types) if Equativ’s demand partner receiving the bidRequest is not capable of reading an audio object.
tagid
STRING
REQUIRED
A global placement ID unique to a specific ad placement or ad tag that was used to initiate the auction.
bidfloor
FLOAT
REQUIRED
The bid floor for this impression (as a CPM in bid floor currency).
bidfloorcur
STRING
OPTIONAL
The currency to be specified using ISO-4217 alpha codes, if bidfloor is specified and multiple currencies are supported per bid request. Equativ converts the currency to the currency of the requested DSP (default: USD).
instl
INTEGER
OPTIONAL
A field indicating if the ad is an interstitial or a full screen ad:
1 - the ad is an interstitial or a full screen ad
0 - the ad is neither an interstitial nor a full screen ad
secure
INTEGER
OPTIONAL
A field indicating if the impression requires secure (HTTPS) URLs for creative assets and markup.
1 - the impression requires secure assets
0 - the impression does not require secure assets
If this field is omitted, the secure state is considered as being unknown and HTTP support is assumed.
rwdd
INTEGER
OPTIONAL
A field indicating whether the user receives a reward for viewing the ad, where:
1 - the user receives a reward
0 - the user does not receive a reward
If omitted, non-rewarded is assumed. A reward could be a news article for free, receiving an extra life in a game, or getting a sponsored ad-free music session. Rewards are usually distributed after the video ad is completed.
dt
FLOAT
OPTIONAL
A timestamp in Unix format (i.e. milliseconds since the epoch) when the item is estimated to be fulfilled – e.g. when a digital out-of-home (DOOH) impression will be displayed.
qty
OBJECT
OPTIONAL
A reference to the qty object.
ext
OBJECT
OPTIONAL
A placeholder for exchange-specific extensions to OpenRTB.
Imp[].ext object
OpenRTB field
Data type
Necessity
Description
bidder
OBJECT
OPTIONAL
Optional bidder extensions. See Inventory mapping sample for further details and examples. See "Inventory mapping sample" here.
Imp[].ext.bidder object
Note that the entire extension is optional and may be omitted. See "Inventory mapping sample" here.
OpenRTB field
Data type
Necessity
Description
siteId
INTEGER
OPTIONAL
The Equativ site ID to link to the corresponding placement object defined in Equativ’s platform for inventory syncing. Any combination of one or more of the fields siteId / pageId / formatId is accepted.
pageId
INTEGER
OPTIONAL
The Equativ page ID to link to the corresponding placement object defined in Equativ’s platform for inventory syncing. Any combination of one or more of the fields siteId / pageId / formatId is accepted.
formatId
INTEGER
OPTIONAL
The Equativ format ID to link to the corresponding placement object defined in Equativ’s platform for inventory syncing. Any combination of one or more of the fields siteId / pageId / formatId is accepted.
App object
OpenRTB field________________
Data type
Necessity
Description
name
STRING
OPTIONAL
The application name; can be masked upon request.
bundle
STRING
REQUIRED
The application bundle or package name (for example, com.foo.mygame), intended to be a unique ID across multiple exchanges.
storeurl
STRING
OPTIONAL
The App store URL for iOS Applications.
publisher
OBJECT
OPTIONAL
An object describing the publisher of the app in which the ad will be displayed. The publisher object itself and all of its parameters are optional, so default values are not provided. If a parameter is not specified, it will be considered as unknown.
keywords
STRING
OPTIONAL
A list of semicolon-separated strings of keywords describing this site; e.g.: keywords: 'content=cook;content=sports;type=news', Use case: You can use keywords to declare custom segments and target SSP delivery rules to keywords; this way, you can trigger a delivery rule only if a specific keyword is sent via the site.keywords or app.keywords objects of the bid request.
inventorypartnerdomain
STRING
OPTIONAL
A pointer to the domain of the partner (of the site/app owner) with ownership of some portion of ad inventory on the site/app. The partner’s ads.txt or app-ads.txt file will be hosted here.
When a site or an app contains ad inventory that is owned by another partner, the app or site should list all domains for those partners via this directive.
Site object
OpenRTB field________________
Data type
Necessity
Description
domain
STRING
REQUIRED
The domain of the site, used for advertiser side blocking, e. g.: foo.com.
page
STRING
REQUIRED
The URL of the page where the impression will be shown.
keywords
STRING
OPTIONAL
A semicolon-separated string of keywords describing this site. e.g.: keywords: 'content=cook;content=sports;type=news', Use case: You can use keywords to declare custom segments and target SSP delivery rules to keywords; this way, you can trigger a delivery rule only if a specific keyword is sent via the site.keywords or app.keywords objects of the bid request.
publisher
OBJECT
OPTIONAL
An object describing the publisher of the site in which the ad will be displayed. The publisher object itself and all of its parameters are optional, so default values are not provided. If a parameter is not specified, it will be considered as unknown.
content
OBJECT
OPTIONAL
An object describing the content in which the impression will appear.
inventorypartnerdomain
STRING
OPTIONAL
A pointer to the domain of the partner (of the site/app owner) with ownership of some portion of ad inventory on the site/app. The partner’s ads.txt or app-ads.txt file will be hosted here.
When a site or an app contains ad inventory that is owned by another partner, the app or site should list all domains for those partners via this directive.
ext.amp
INTEGER
OPTIONAL
A field indicating if the request comes from AMP inventory or not.
1 - the request comes from AMP inventory
0 - the request does not come from AMP inventory
If not defined it is considered as 0 (not AMP). Example: "site": { "page": "mypage.com", "ext": { "amp": 1|0 } },
DOOH object
The DOOH object contains fields for digital out-of-home advertising. A bid request can contain either an app object, a site object or a dooh object.
Open RTB field
Data Type
Necessity
Description
id
STRING
OPTIONAL
An exchange provided id for a placement or logical grouping of placements.
name
STRING
OPTIONAL
Name of the digital out-of-home placement.
venuetype
INT ARRAY
OPTIONAL
The type of digital out-of-home venue. The taxonomy to be used is defined by the venuetax field. If no venuetax field is supplied, the OpenOOH Venue Taxonomy is assumed.
The domain of the inventory owner (ads.txt) (e.g.: “Foo.com ”)
keywords
STRING
OPTIONAL
A comma separated list of keywords about the DOOH placement.
content
OBJECT
OPTIONAL
The content metadata within the DOOH placement.
ext
OBJECT
OPTIONAL
A placeholder for exchange-specific extensions to OpenRTB.
Publisher.ext object
Open RTB field
Data Type
Necessity
Description
directpay
BOOLEAN
OPTIONAL
A boolean indicating if the bid request comes from a Google Open Bidding publisher using Google OB's direct pay feature. For more information, see Google Open Bidding (Google OB): Direct pay. The directpay field can be sent only once per bid request in one of the following objects:
for web requests: site.publisher.ext
for app requests: app.publisher.ext
for dooh requests: dooh.publisher.ext
Device object
OpenRTB field
Data type
Necessity
Description
dnt
INTEGER
OPTIONAL
A field indicating if the “Do not track” browser setting is enabled or not.
The geolocation as derived from the device’s location services (cell tower triangulation, GPS etc.), if the IP address is not supplied (see "Geo object" here).
dpidsha1
STRING
OPTIONAL
A SHA1 hashed, platform-specific ID; e. g. Android ID or UDID for iOS. OpenRTB’s preferred device ID hash function is SHA1.
dpidmd5
STRING
OPTIONAL
A MD5 hashed, platform-specific ID; e. g. Android ID or UDID for iOS; interpreted as case insensitive.
make
STRING
OPTIONAL
The device make (e.g.: Apple).
model
STRING
OPTIONAL
The device model (e.g.: iPhone).
os
STRING
OPTIONAL
The device operating system (e.g.: iOS).
osv
STRING
OPTIONAL
The device operating system version (e.g.: 3.1.2).
connectiontype
STRING
OPTIONAL
The detected data connection type for the device.
devicetype
STRING ARRAY
OPTIONAL
The device type being used. Digital out-of-home devices must be identified per type 8 - "OOH Device"
language
STRING
OPTIONAL
The browser language, using alpha-2/ISO 639-1 codes.
ppi
INTEGER
OPTIONAL
The pixels per inch. Screen dimensions in inches can be calculated using ppi, w and h.
ifa
STRING
OPTIONAL
A native, opaque identifier assigned by the device or browser to be used for advertising purposes; e.g.: Apple's IFA, Android's Advertising ID, etc.
ext.ifa_type
STRING
OPTIONAL
The types of IFA are Device, Publisher (including apps), SSP and Session. The following are recommended values for the ifa_type parameter:
dpid: The generic “device provided id”, but based on historical usage, common device type specific values can be used.
rida: Roku id
aaid : Android id
idfa : Apple id
afai : Amazon Fire id
msai : Microsoft id
ppid : publisher provided id
sspid : SSP provided id
sessionid : session id / synthetic id
Note - Case-insensitive processing is recommended since some platforms may be using upper case values for backwards compatibility.
Qty object
OpenRTB field
Data type
Necessity
Description
multiplier
FLOAT
REQUIRED
The quantity of billable events which will be deemed to have occurred if this item is purchased. For example, a DOOH opportunity may be considered to be 14.2 impressions. Equivalent to qtyflt in OpenRTB 3.0. In other words: the estimated quantity of viewers for the given slot.
sourcetype
INTEGER
OPTIONAL
The source type of the quantity measurement. 0 – Unknown (default) 1 – Measurement Vendor Provided 2 – Publisher Provided 3 – Exchange Provided
vendor
STRING
REQUIRED (if sourcetype is present and set to 1 )
The top level business domain name of the measurement vendor providing the quantity measurement.
ext
OBJECT
OPTIONAL
A placeholder for vendor specific extensions to this object.
User object
OpenRTB field
Data type
Necessity
Description
buyeruid
STRING
REQUIRED
The buyer’s user ID for the given user as mapped by the exchange for the buyer. The buyeruid must be Equativ's ID for the user and will be used to send matched traffic to demand partners. ⚠️ Warning: Unmatched browser traffic will be discarded and must therefore be filtered out and not sent. The buyeruid field cannot be processed if privacy regulations (GDPR, CCPA etc.) apply and prohibit the processing of the field. Therefore, such traffic must not be sent.
data
OBJECT ARRAY
OPTIONAL
Additional user data. Each Data object represents a different data source.
eids
OBJECT
OPTIONAL
An array of extended IDs, as specified in the IAB specification. Equativ is following the OpenRTB 2.6 specification.
ext.eids
OBJECT
OPTIONAL
An array of extended IDs, as specified in the IAB specification. Equativ is following the OpenRTB 2.5 specification.
ext.consent
STRING
OPTIONAL
A field indicating the user’s consent if the GDPR applies.
Data object
OpenRTB field
Data type
Necessity
Description
id
STRING
OPTIONAL
An exchange-specific ID for the data provider.
name
STRING
OPTIONAL
An exchange-specific name for the data provider.
segment
OBJECT ARRAY
OPTIONAL
An array of Segment objects that contain the actual data values.
Segment object
OpenRTB field
Data type
Necessity
Description
id
STRING
OPTIONAL
The ID of the data segment specific to the data provider.
name
STRING
OPTIONAL
The name of the data segment specific to the data provider.
value
STRING
OPTIONAL
The string representation of the data segment value.
Source object
OpenRTB field
Data type
Necessity
Description
tid
STRING
OPTIONAL
A transaction ID that must be common across all participants (e. g. multiple exchanges) in the given bid request.
ext.schain
OBJECT
REQUIRED (except in case of owned and operated inventory)
The supply chain object discloses to buyers all the parties involved in the selling or reselling of a bid request. Related documentation:
Sellers json and SupplyChain Object; see chapter “What premium sales houses, aggregators and ad networks need to do“ containing Equativ’s supply chain object policy for suppliers.
A field indicating if the given request is subject to the COPPA regulations established by the USA FTC, where:
1 - the given request is subject to COPPA
0 - the given request is not subject to COPPA
ext
INTEGER
OPTIONAL
An extension containing the gdpr flag indicating if the GDPR applies:
1 - the GDPR applies
0 - the GDPR does not apply
If omitted, it is considered as unknown.
ext object
OpenRTB field
Data typer
Necessity
Description
bid_feedback
OBJECT
OPTIONAL
A feedback on bids submitted in a previous response. Contains the minimumbidtowin feedback signal used for optimization of the bidding strategy towards DSPs.
dsa
OBJECT
OPTIONAL
The DSA transparency information.
ext.bid_feedback object
OpenRTB field
Data type
Necessity
Description
price
FLOAT
OPTIONAL
The clearing price of the auction when a bid is lost. The second highest price of the auction when a bid wins (LossReason=0).
loss
INTEGER
OPTIONAL
The loss reason code (see section 5.25 in the OpenRTB 2.5 specification).
feedback_token
STRING
OPTIONAL
The token related to the feedback, included in the bid response competing in the auction.
A flag to indicate if DSA information should be made available. This will signal if the bid request belongs to an Online Platform/VLOP, such that a buyer should respond with DSA Transparency information based on the pubrender value.
0 - Not required
1 - Supported, bid responses with or without DSA object will be accepted
2 - Required, bid responses without DSA object will not be accepted
3 - Required, bid responses without DSA object will not be accepted, Publisher is an Online Platform
pubrender
INTEGER
OPTIONAL
A flag to indicate if the publisher will render the DSA Transparency info. This will signal if the publisher is able to and intends to render an icon or other appropriate user-facing symbol and display the DSA transparency info to the end user.
0 - Publisher can't render
1 - Publisher could render depending on adrender
2 - Publisher will render
datatopub
INTEGER
OPTIONAL
The indication of whether transparency data are to be sent. Independent of the pubrender parameter, the publisher may need the transparency data for audit purposes.
0 - do not send transparency data
1 - optional to send transparency data
2 - send transparency data
transparency
OBJECT ARRAY
OPTIONAL
An array of objects of the entities that applied user parameters and the parameters they applied.
ext.dsa.transparency object
OpenRTB field
Data type
Necessity
Description
domain
STRING
OPTIONAL
The domain of the entity that applied user parameters
