Contact support
    • Monetization
    • Developer documentation
    • Supply inventory
    • Supply inventory with server-side header bidding

    Open RTB API integration: bid request specification (1)

    Table of Contents

    Overview BidRequest object Imp object Imp[].ext object Imp[].ext.bidder object App object Site object DOOH object Publisher.ext object Device object Qty object User object Data object Segment object Source object Regs object ext object ext.bid_feedback object ext.dsa object ext.dsa.transparency object

    Overview

    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).

    BidRequest object

    OpenRTB field Data type Necessity Description
    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.
    badv STRING ARRAY OPTIONAL Block list of advertisers by their domains (e.g., “ford.com").
    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.
    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).
    device OBJECT REQUIRED An object containing device information, such as hardware, platform, location, carrier etc.
    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.
    ext DICTIONARY OPTIONAL A placeholder for exchange specific extensions to OpenRTB. Contains bid_feedback information used for optimization of the bidding strategy towards DSPs.
    id STRING REQUIRED 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 Open RTB API integration: get started article.
    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.
    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.
    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.
    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.
    user OBJECT REQUIRED An object containing information known or derived from the human user of the device.

    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 Open RTB API integration: get started article.  

    OpenRTB field Data type Necessity Description
    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.
    banner OBJECT SEE DESCRIPTION A reference to a banner object. Either a banner, video or audio object must be included in an imp object. 
    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).
    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. 
    ext OBJECT OPTIONAL A placeholder for exchange-specific extensions to OpenRTB.
    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
    qty OBJECT OPTIONAL A reference to the qty object.
    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.
    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.
    tagid STRING REQUIRED A global placement ID unique to a specific ad placement or ad tag that was used to initiate the auction.
    video OBJECT SEE DESCRIPTION A reference to a video object. Either a banner, video or audio object must be included in an imp object. 

    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" in OpenRTB API integration: samples.

    Imp[].ext.bidder object

    The entire extension is optional and may be omitted. See "Inventory mapping sample" in OpenRTB API integration: samples.

     
    OpenRTB field Data type Necessity Description
    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.
    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.
    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.

    App object

    OpenRTB field Data type Necessity Description
    bundle STRING REQUIRED The application bundle or package name (for example, com.foo.mygame), intended to be a unique ID across multiple exchanges.
    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.
    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 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.
    name STRING OPTIONAL The application name; can be masked upon request.
    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.
    storeurl STRING OPTIONAL The App store URL for iOS Applications.

    Site object

    OpenRTB field Data type Necessity Description
    content OBJECT OPTIONAL An object describing the content in which the impression will appear.
    domain STRING REQUIRED The domain of the site, used for advertiser side blocking, e. g.: foo.com.
    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 } },
    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.
    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 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.
    page STRING REQUIRED The URL of the page where the impression will be shown.
    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.

    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
    content OBJECT OPTIONAL The content metadata within the DOOH placement.
    domain STRING REQUIRED The domain of the inventory owner (ads.txt) (e.g.: “Foo.com”)
    ext OBJECT OPTIONAL A placeholder for exchange-specific extensions to OpenRTB.
    id STRING OPTIONAL An exchange provided id for a placement or logical grouping of placements.
    keywords STRING OPTIONAL A comma separated list of keywords about the DOOH placement.
    name STRING OPTIONAL Name of the digital out-of-home placement.
    publisher OBJECT OPTIONAL The details about the publisher of the 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.
    venuetypetax INTEGER; always 1 OPTIONAL The venue taxonomy in use. 1 – OpenOOH - Digital Out-of-Home Screen Venue Types 1.0.x 2 – DPAA Device Venue (See AdCom), deprecated 3 – DMI Categorization of Venues 1.1 4 – OMA taxonomy

    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 Open Bidding 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
    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"
    dnt INTEGER OPTIONAL

    A field indicating if the “Do not track” browser setting is enabled or not.

    • 1 - Do not track is enabled
    • 0 - Do not track is not enabled
    dpidmd5 STRING OPTIONAL A MD5 hashed, platform-specific ID; e. g. Android ID or UDID for iOS; interpreted as case insensitive.
    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.
    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.
    geo OBJECT RECOMMENDED 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" in Open RTB API integration: bid request specification (2).
    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.
    ip STRING OPTIONAL The IPv4 address closest to the device.
    language STRING OPTIONAL The browser language, using alpha-2/ISO 639-1 codes.
    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).
    ppi INTEGER OPTIONAL The pixels per inch. Screen dimensions in inches can be calculated using ppi, w and h.
    ua STRING OPTIONAL The browser’s user agent string. See also IAB’s OTT/CTV User Agent Preliminary Guidelines

    Qty object

    OpenRTB field Data type Necessity Description
    ext OBJECT OPTIONAL A placeholder for vendor specific extensions to this object.
    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.

    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.consent STRING OPTIONAL A field indicating the user’s consent if the GDPR applies.
    ext.eids OBJECT OPTIONAL An array of extended IDs, as specified in the IAB specification. Equativ is following the OpenRTB 2.5 specification.

    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
    ext.omidpn STRING OPTIONAL The Open Measurement Interface Definition partner name, as per OpenRTB Advisory for Open Measurement SDK.
    ext.omidpv STRING OPTIONAL The Open Measurement Interface Definition partner version, as per OpenRTB Advisory for Open Measurement SDK.
    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:
    tid STRING OPTIONAL A transaction ID that must be common across all participants (e. g. multiple exchanges) in the given bid request.

    Regs object

    OpenRTB field Data type Necessity Description
    coppa INTEGER OPTIONAL

    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
    feedback_token STRING OPTIONAL The token related to the feedback, included in the bid response competing in the auction.
    loss INTEGER OPTIONAL The loss reason code (see section 5.25 in the OpenRTB 2.5 specification).
    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).

    See “ext.bid_feedback object sample” in OpenRTB API integration: samples.

    ext.dsa object

    OpenRTB field Data type Necessity Description
    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
    dsarequired INTEGER OPTIONAL

    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
    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
    dsaparams INTEGER ARRAY OPTIONAL An array for platform or sell-side use of any user parameters (using the list provided by DSA Transparency Taskforce). ⓘ Note: see definition and list of possible user parameters as listed here, applied consistently in both bid request and/or bid response.

    RELATED ARTICLES