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 Banner object Video object Audio object Imp[].ext object Imp[].ext.bidder object Pmp object Deal object Metric object imp.ext.bid_feedback object App object Site object Publisher.ext object DOOH object Device object Geo object Qty object User object Eid object Uid object Data object Segment object Source object SupplyChain object SupplyChainNode object Regs object regs.ext.dsa object regs.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
    acat STRING ARRAY OPTIONAL Not supported. Allowed 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.
    allimps INTEGER OPTIONAL

    A flag indicating if the exchange can verify that the impressions offered represent all of the impressions available in context, for example: “all on the web page” or “all video spots” (pre/mid/post roll) to support road-blocking.

    0: no or unknown (Default)

    1: yes, the impressions offered represent all that are available.
    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.
    at INTEGER OPTIONAL

    The auction type.

    1: First Price

    2: Second Price Plus (Default)

    Exchange-specific auction types can be defined using values 500 and greater.
    badv STRING ARRAY OPTIONAL A block list of advertisers by their domains (e.g., “ford.com").
    bapp STRING ARRAY OPTIONAL Not supported. A block list of applications by their app store IDs. See OTT/CTV Store Assigned App Identification Guidelines for more details about expected strings for CTV app stores. For mobile apps in Google Play Store, these should be bundle or package names (e.g. com.foo.mygame). For apps in Apple App Store, these should be a numeric ID.
    bcat STRING ARRAY OPTIONAL The 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.
    bseat STRING ARRAY OPTIONAL Not supported. A block list of buyer seats (e.g., advertisers, agencies) restricted from bidding on this impression. IDs of seats and knowledge of the buyer’s customers to which they refer must be coordinated between bidders and the exchange *a priori*. At most, only one of wseat and bseat should be used in the same request. Omission of both implies no seat restrictions.
    cattax INTEGER OPTIONAL The taxonomy in use for bcat. Refer to the AdCOM 1.0 list List: Category Taxonomies for values. Default: 1. 
    cur STRING ARRAY 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 imp 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.
    test INTEGER OPTIONAL

    An indicator of the test mode in which auctions are not billable.

    0: live mode (Default)

    1: test mode
    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.
    wlang STRING ARRAY OPTIONAL Not supported. An allowed list of languages for creatives using ISO-639-1-alpha-2. Omission implies no specific restrictions, but buyers are advised to consider the language attribute in the Device and/or Content objects if available. Only one of wlang or wlangb should be present.
    wlangb STRING ARRAY OPTIONAL Not supported. An allowed list of languages for creatives using IETF BCP 47I. Omission implies no specific restrictions, but buyers are advised to consider the language attribute in the Device and/or Content objects if available. Only one of wlang or wlangb should be present.
    wseat STRING ARRAY OPTIONAL The allowed list of buyer seats (e.g., advertisers, agencies) allowed to bid on this impression. IDs of seats and knowledge of the buyer’s customers to which they refer must be coordinated between bidders and the exchange *a priori*. At most, only one of wseat and bseat should be used in the same request. Omission of both implies no seat restrictions.

    Imp object

    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 bid request is not capable of reading an audio object.
    banner OBJECT SEE DESCRIPTION A Banner object; required if this impression is offered as a banner ad opportunity.
    bidfloor FLOAT REQUIRED The bid floor for this impression (as a CPM in bid floor currency). Default: 0.
    bidfloorcur STRING OPTIONAL The currency specified using ISO-4217 alpha code, 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.
    clickbrowser INTEGER OPTIONAL

    Not supported. Indicates the type of browser opened upon clicking the creative in an app.

    0: embedded

    1: native. Note that the Safari View Controller in iOS 9.x devices is considered a native browser for purposes of this attribute.
    displaymanager STRING OPTIONAL The name of ad mediation partner, SDK technology, or player responsible for rendering ad (typically video or mobile). Used by some ad servers to customize ad code by partner. Recommended for video and/or apps.
    displaymanagerver STRING OPTIONAL The version of the ad mediation partner, SDK technology, or player responsible for rendering the ad (typically video or mobile). Used by some ad servers to customize ad code by partner.
    Recommended for video and/or apps.
    dt FLOAT OPTIONAL A timestamp in Unix format (milliseconds since the epoch) when the item is estimated to be fulfilled, for example, when a digital out-of-home (DOOH) impression will be displayed.
    exp INTEGER OPTIONAL Not supported. An advisory as to the number of seconds that may elapse between the auction and the actual impression.
    ext OBJECT OPTIONAL A placeholder for exchange-specific extensions to OpenRTB.
    id STRING REQUIRED A unique identifier for this impression within the content of the bid request (typically, starts with 1 and increments).
    iframebuster STRING ARRAY OPTIONAL An array of exchange-specific names of supported iframe busters.
    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 (Default)
    metric OBJECT ARRAY OPTIONAL An array of Metric objects.
    native OBJECT SEE DESCRIPTION A Native object; required if this impression is offered as a native ad opportunity.
    pmp OBJECT OPTIONAL An object containing any private marketplace deals in effect for this impression.
    qty OBJECT OPTIONAL A means of passing a multiplier in the bid request, representing the total quantity of impressions for ads that display to more than one person.
    refresh OBJECT OPTIONAL Not supported. The details about ad slots being refreshed automatically.
    rwdd INTEGER OPTIONAL A field indicating whether the user receives a reward for viewing the ad.
    1: the user receives a reward.
    0: the user does not receive a reward (Default).
    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.
    ssai INTEGER OPTIONAL

    A field indicating if a server-side ad insertion—for example, stitching an ad into an audio or video stream—is in use and its impact on asset and tracker retrieval.

    0: status unknown (Default).

    1: all client-side (not server-side)

    2: assets stitched server-side but tracking pixels fired client-side

    3: all server-side
    tagid STRING REQUIRED A global placement ID unique to a 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.
    video OBJECT SEE DESCRIPTION A reference to a video object. Either a banner, video or audio object must be included in an imp object.

     

    OpenRTB field Data type Necessity Description
    btype INTEGER ARRAY OPTIONAL The blocked banner ad types.
    1 - XHTML Text Ad
    2 - XHTML Banner Ad
    3 - JavaScript Ad
    4 - iframe
    expdir INTEGER ARRAY OPTIONAL The directions in which the banner may expand. Refer to List: Expandable Directions in AdCOM 1.0.
    id STRING OPTIONAL Not supported. A unique identifier for this banner object. Recommended when Banner objects are used with a Video object to represent an array of companion ads. Values usually start at 1 and increase with each object; should be unique within an impression.
    topframe INTEGER OPTIONAL

    A field indicating if the banner is in the top frame as opposed to an iframe.

    0 - no

    1 - yes
    vcm INTEGER OPTIONAL

    Not supported. A field indicating the companion banner rendering mode relative to the associated video.

    0- concurrent

    1 - end-card

    Relevant only for Banner objects used with a Video object in an array of companion ads. 

    Video object

    OpenRTB field Data type Necessity Description
    boxingallowed INTEGER OPTIONAL Default: 1. A field indicating if letter-boxing of 4:3 content into a 16:9 window is allowed, where 0=no, 1=yes.
    companionad OBJECT ARRAY OPTIONAL An array of Banner objects if companion ads are available.
    companiontype INTEGER ARRAY OPTIONAL The supported VAST companion ad types. Refer to List: Companion Types in AdCOM 1.0. Recommended if companion Banner objects are included via the companionad array. If one of these banners will be rendered as an end-card, this can be specified using the vcm attribute with the particular banner.
    delivery INTEGER ARRAY OPTIONAL The supported delivery methods (e.g., streaming, progressive). If none specified, assume all are supported. Refer to List: Delivery Methods in AdCOM 1.0.
    durfloors OBJECT ARRAY OPTIONAL Not supported. An array of DurFloors objects indicating the floor prices for video creatives of various durations that the buyer may bid with.
    ext OBJECT OPTIONAL Not supported. A placeholder for exchange-specific extensions to OpenRTB.
    maxbitrate INTEGER OPTIONAL The maximum bit rate in Kbps (kilobits per second).
    maxextended INTEGER OPTIONAL The maximum extended ad duration if extension is allowed. If blank or 0, extension is not allowed. If -1, extension is allowed, and there is no time limit imposed. If greater than 0, then the value represents the number of seconds of extended play supported beyond the maxduration value.
    maxseq INTEGER OPTIONAL, RECOMMENDED Not supported. A field indicating the maximum number of ads that may be served into a “dynamic” video ad pod (where the precise number of ads is not predetermined by the seller).
    minbitrate INTEGER OPTIONAL The minumim bit rate in Kbps (kilobits per second).
    mincpmpersec FLOAT OPTIONAL Not supported. The minimum CPM per second. This is a price floor for the "dynamic" portion of a video ad pod, relative to the duration of bids an advertiser may submit.
    playbackend INTEGER OPTIONAL The event that causes playback to end. Refer to List: Playback Cessation Modes in AdCOM 1.0.
    poddedupe ENUM ARRAY OPTIONAL Not supported. A field Indicating pod deduplication settings that will be applied to bid responses. Refer to List: Pod Deduplication in AdCOM 1.0.
    poddur INTEGER OPTIONAL, RECOMMENDED Not supported. A field Indicating the total amount of time in seconds that advertisers may fill for a “dynamic” video ad pod, or the dynamic portion of a “hybrid” ad pod. This field is required only for the dynamic portion(s) of video ad pods. This field refers to the length of the entire ad break, whereas minduration/maxduration/rqddurs are constraints relating to the slots that make up the pod.
    podid STRING OPTIONAL Not supported. A unique identifier indicating that an impression opportunity belongs to a video ad pod. If multiple impression opportunities within a bid request share the same podid, this indicates that those impression opportunities belong to the same video ad pod.
    podseq INTEGER OPTIONAL Not supported. Default: 0. The sequence (position) of the video ad pod within a content stream. Refer to in AdCOM 1.0 for guidance on the use of this field.
    protocols INTEGER ARRAY OPTIONAL, RECOMMENDED An array of supported video protocols. Refer to List: Creative Substypes - Audio/Video in AdCOM 1.0.
    rqddurs INTEGER ARRAY OPTIONAL Not supported. The precise acceptable durations for video creatives in seconds. This field specifically targets the Live TV use case where non-exact ad durations would result in undesirable ‘dead air’. This field is mutually exclusive with minduration and maxduration; if rqddurs is specified, minduration and maxduration must not be specified and vice versa.
    sequence INTEGER OPTIONAL Default: 0. Deprecated. If multiple ad impressions are offered in the same bid request, the sequence number will allow for the coordinated delivery of multiple creatives.
    skipafter INTEGER OPTIONAL Default: 0. The number of seconds a video must play before skipping is enabled; only applicable if the ad is skippable.
    skipmin INTEGER OPTIONAL Not supported. Default: 0. Videos of total duration greater than this number of seconds can be skippable; only applicable if the ad is skippable.
    slotinpod INTEGER OPTIONAL Not supported. Default: 0. A field for video ad pods indicating that the seller can guarantee delivery against the indicated slot position in the pod. Refer to List: Slot Position in Pod in AdCOM 1.0 guidance on the use of this field.

    Audio object

    OpenRTB field Data type Necessity Description
    feed INTEGER OPTIONAL The type of audio feed. Refer to List: Feed Types in AdCOM 1.0.

    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.

    Pmp object

    OpenRTB field Data type Necessity Description
    deals OBJECT ARRAY OPTIONAL An array of Deal objects that convey the specific deals applicable to this impression.
    ext OBJECT OPTIONAL Not supported. A placeholder for exchange-specific extensions to OpenRTB.
    private_auction INTEGER OPTIONAL

    An indicator of auction eligibility to seats named in the Direct Deals object, where:

    • 0: all bids are accepted (default)
    • 1: bids are restricted to the deals specified and the terms thereof.

    Deal object

    OpenRTB field Data type Necessity Description
    at INTEGER OPTIONAL

    An 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.
    bidfloor FLOAT OPTIONAL The minimum bid for this impression, expressed in CPM. Default: 0.
    bidfloorcur STRING OPTIONAL The currency specified using ISO-4217 alpha codes. This may be different from the bid currency returned by bidder if this is allowed by the exchange. This field does not inherit from Imp.bidfloorcur; it is either explicitly specified or defaults to USD.
    durfloors OBJECT ARRAY OPTIONAL Not supported. A container for floor price by duration information, to be used if a given deal is eligible for video or audio demand. An array of DurFloors objects.
    ext OBJECT OPTIONAL Not supported. A placeholder for exchange-specific extensions to OpenRTB.
    guar INTEGER OPTIONAL

    Not supported. A field indicating if the deal is of type ‘guaranteed’, requiring the bidder to bid on the deal.

    • 0: not a guaranteed deal (default)
    • 1: guaranteed deal
    id STRING REQUIRED A unique identifier for the direct deal.
    mincpmpersec FLOAT OPTIONAL Not supported. The minimum CPM per second. This is a price floor for video or audio impression opportunities, relative to the duration of bids an advertiser may submit.
    wadomain STRING ARRAY OPTIONAL Not supported. An array of advertiser domains—for example, advertiser.com—allowed to bid on this deal. Omission implies no advertiser restrictions.
    wseat STRING ARRAY OPTIONAL An allowed list of buyer seats, allowed to bid on this deal, for example, advertisers or agencies. IDs of seats and the buyer’s customers to which they refer must be coordinated between bidders and the exchange a priori. Omission implies no seat restrictions.

    Metric object

    OpenRTB field Data type Necessity Description
    ext OBJECT OPTIONAL A placeholder for exchange-specific extensions to OpenRTB.
    type STRING REQUIRED

    The type of metric being presented using exchange curated string names which should be published to bidders a priori.
    Recommended values:

    • click_through_rate
    • video_completion_rate
    • viewability
    value FLOAT REQUIRED A number representing the value of the metric. Probabilities must be in the range 0.0 – 1.0.
    vendor STRING OPTIONAL Recommended. The source of the value using exchange curated string names which should be published to bidders a priori. If the exchange itself is the source versus a third party, EXCHANGE is recommended.

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

    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.
    cat STRING ARRAY OPTIONAL An array of IAB Tech Lab content categories of the app. The taxonomy to be used is defined by the cattax field. If no cattax field is supplied, Content Category Taxonomy 1.0 is assumed.
    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.
    ref STRING OPTIONAL The referrer URL that caused navigation to the current page.

    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

    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

    Device object

    OpenRTB field Data type Necessity Description
    carrier STRING OPTIONAL The carrier or ISP, for example “VERIZON”, using exchange curated string names which should be published to bidders a priori.
    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.atts INTEGER OPTIONAL An integer passed to represent the app's app tracking authorization status (for iOS only).
    0: not determined
    1: restricted
    2: denied
    3: authorized
    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).
    h INTEGER OPTIONAL The physical height of the screen in pixels.
    hwv STRING OPTIONAL The hardware version of the device, for example, “5S” for iPhone 5S.
    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.
    pxratio FLOAT OPTIONAL The ratio of physical pixels to device-independent pixels (DIPS).
    sua OBJECT OPTIONAL The structured user agent information defined by a UserAgent object. If both ua and sua are present in the bid request, sua should be considered the more accurate representation of the device attributes. This is because the ua may contain a frozen or reduced user agent string.
    ua STRING OPTIONAL The browser’s user agent string. See also IAB’s OTT/CTV User Agent Preliminary Guidelines
    w INTEGER OPTIONAL The physical width of the screen in pixels.

    Geo object

    OpenRTB field Data type Necessity Description
    accuracy INTEGER OPTIONAL The estimated location accuracy in meters; recommended when lat/lon are specified and derived from a device’s location services, for example, type = 1. Note that this is the accuracy as reported from the device. Consult OS specific documentation, such as Android or iOS, for exact interpretation.
    metro STRING OPTIONAL The Google metro code; similar to but not exactly matching the Nielsen DMAs.
    utcoffset INTEGER OPTIONAL Local time as the number +/- of minutes from UTC.

    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.

    Eid object

    OpenRTB field Data type Necessity Description
    ext OBJECT OPTIONAL Not supported.
    source STRING OPTIONAL The source or technology provider responsible for the set of
    included IDs. Expressed as a top-level domain.
    uids OBJECT ARRAY OPTIONAL An array of extended ID UID objects from the given source. 

    Uid object

    OpenRTB field Data type Necessity Description
    atype INTEGER OPTIONAL The type of user agent the ID is from. It is highly recommended to set this, as many DSPs separate app-native IDs from browser-based IDs and require a type value for ID resolution.
    ext OBJECT OPTIONAL Not supported.
    id STRING OPTIONAL The identifier for the user. 

    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 disclosing to buyers all the parties involved in the selling or reselling of a bid request. 

    Related documentation:

    Send either schain or ext.schain, but not both.

    For more information, see section “SupplyChain object” later in this document. 
    ext.schain.nodes OBJECT ARRAY REQUIRED

    An array of SupplyChainNode objects in the order of the chain.

    For more information, see section "SupplyChainNode object" later in this document.
    fd INTEGER OPTIONAL

    Recommended. The entity responsible for the final impression sale decision.

    0: exchange

    1: upstream source.
    pchain STRING OPTIONAL The Payment ID chain string containing embedded syntax described in the TAG payment ID Protocol v1.0.

    schain

     

    		 OBJECT OPTIONAL

    An object representing both the links in the supply chain as well as an indicator whether or not the supply chain is complete. For more information, see section “SupplyChain object” later in this document.

    Send either schain or ext.schain, but not both. 
    tid STRING OPTIONAL A transaction ID that must be common across all participants (e. g. multiple exchanges) in the given bid request.

    SupplyChain object

    OpenRTB field Data type Necessity Description
    complete INTEGER REQUIRED

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

    0: no

    1: yes.
    ext OBJECT OPTIONAL Not supported. A placeholder for exchange-specific extensions to OpenRTB.
    nodes OBJECT ARRAY REQUIRED An array of SupplyChainNode 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, i.e. 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.
    ver STRING REQUIRED The version of the supply chain specification in use, in the format of “major.minor”. For example, for version 1.0 of the spec, use the string “1.0”.

     

    SupplyChainNode object

    OpenRTB field Data type Necessity Description
    asi STRING REQUIRED The canonical domain name of the SSP, Exchange, Header Wrapper, or similar entity that bidders connect to. This may be the operational domain of the system—if different from the parent corporate domain—to facilitate WHOIS and reverse IP lookups to establish clear ownership of the delegate system. The value used here must match the domain used to identify the seller in an ads.txt file, if one exists.
    domain STRING OPTIONAL The business domain name of the entity represented by this node. This value is optional and must NOT be included if it exists in the advertising system’s sellers.json file.
    ext OBJECT OPTIONAL Not supported. A placeholder for exchange-specific extensions to OpenRTB.
    hp INTEGER OPTIONAL A field indicating whether this node will be involved in the flow of payment for the inventory. When set to 1, the advertising system in the asi field pays the seller in the sid field, who is responsible for paying the previous node in the chain. When set to 0, this node is not involved in the flow of payment for the inventory. For version 1.0 of SupplyChain, this property should always be 1. Implementers should ensure that they propagate this field onwards when constructing SupplyChain objects in bid requests sent to a downstream advertising system.
    name STRING OPTIONAL 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.
    rid STRING OPTIONAL The OpenRTB RequestId of the request as issued by this seller.
    sid STRING REQUIRED The identifier associated with the seller or reseller account within the advertising system. This must contain the same value used in transactions (i.e. OpenRTB bid requests) in the field specified by the SSP/exchange. Typically, in OpenRTB, this is publisher.id. For OpenDirect it is typically the publisher’s organization ID. It must be limited to 64 characters in length.

    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.
    gdpr INTEGER OPTIONAL

    A flag that indicates whether or not the request is subject to GDPR regulations.

    0: No

    1: Yes, omission indicates unknown.
    gpp STRING OPTIONAL A field containing the Global Privacy Platform’s consent string. See the Global Privacy Platform specification for more details.
    gpp_sid INTEGER ARRAY OPTIONAL An array of sections of the consent string to be applied for this transaction. Generally, this field contains one and only one value, but there are edge cases where more than one may apply. GPP Section 3 (Header) and 4 (Signal Integrity) do not need to be included. See the GPP Section Information for more details.
    us_privacy STRING OPTIONAL The communicated signals regarding consumer privacy under US privacy regulation. See US Privacy String specifications.

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

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