--- metadata: - name: generator content: Diplodoc Platform v5.50.3 alternate: - https://yandex.com/dev/rtb/doc/en/api/web/request.md - https://yandex.com/dev/rtb/doc/ru/api/web/request.md --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/rtb/doc/en/llms.txt # Web advertising. OpenRTB host request The invitation to participate in an auction is sent using the POST method in JSON format (Content-Type: application/json). ## Request body The request body contains the Bid Request object. Its parameters describe the site, endpoint device, and consumer. These characteristics help the DSP select an ad and a bid. ```json { "id": "(string)", "user": { "buyeruid": "(string)", "id" : "(string)", "ext": { "consent": "(string)" } }, "cur": [ "(array of strings)" ], "bcat": [ "(array of strings)" ], "imp": [ { "secure": "(int)", "bidfloor": "(float)", "bidfloorcur": "(string)", "banner": { "format": [ { "h": "(int)", "w": "(int)" } ], "h": "(int)", "w": "(int)" }, "id": "(string)", "ext": { "reward": "(int)", "unmoderated": "(int)" }, "tagid": "(string)", "instl": "(int)" } ], "tmax": "(int)", "site": { "page": "(string)", "domain": "(string)", "publisher": { "id": "(string)" }, "id": "(string)", "content": { "language": "(string)" } }, "device": { "lmt": "(int)", "geo": { "country": "(string)", "lat": "(float)", "lon": "(float)", "region": "(string)", "type": "(int)" }, "os": "(string)", "ip": "(string)", "ipv6": "(string)", "ua": "(string)", "devicetype": "(int)", "mccmnc": "(string)", "ifa": "(string)", "dnt": "(int)", "ext": { "oaid": "(string)", "gaid": "(string)", "idfa": "(string)", "ifv": "(string)" } }, "regs": { "coppa": "(int)", "ext": { "gdpr": "(int)", "nroa": { "version": "(string)", "mandatory": "(bool)" } } }, "source": { "fd": "(int)", "sourcetype": "(int)", "tid": "(string)", "ext": { "schain": { "complete": "(int)", "nodes": [ { "asi": "(string)", "sid": "(string)", "hp": "(int)", "rid": "(string)" } ], "ver": "(string)" } } }, "at": "(int)", "test": "(int)", "ext": { "notifications": { "lurl": "(int)", "nurl": "(int)" } } } ``` ## Request parameters ### Bid Request object #| || **Parameter** | **Description** | **Required** || || id | ID of the auction, assigned by the RTB host. The DSP returns this ID in the response. | yes || || user | Information about the ad buyer in the `User` object. | yes || || ext | The `Ext` object with additional parameters. | no || || cur | List of currencies for bids. The following parameters are passed: - RUB — Russian ruble; - USD — United States dollar; - EUR — Euro; - CHF — Swiss franc; - TRY — Turkish lira; - KZT — Kazakhstani tenge. | yes || || bcat | Categories of blocked advertisers according to the IAB classification.. | no || || imp | Array of `Imp` objects that contain the parameters for rendering the banner. Each object corresponds to a single ad unit on the HTML page. In the current implementation, only one object is passed. | yes || || tmax | The maximum response time in milliseconds during which bids need to be placed, taking into account the delay arising from the internet connection. | yes || || site | Information about the web site in the `Site` object. | yes || || device | Information about the endpoint in the `Device` object. | yes || || regs | Industry, legal, or government regulations that apply to all impressions in the request, in the `Regs` object. | no || || at | Auction type. Allowed values: - 1 — First price auction; - 2 — Second price auction. | no || || test | Test mode indicator. Allowed values: - 0 — Sending real traffic; - 1 — Sending test traffic. | no || || source | Information about the request source in the `Source` object. | yes || |# ### Ext object #| || **Parameter** | **Description** | **Required** || || notifications | The `Ext.Notifications` object with the URLs of notifications about winning or losing the bid. | no || |# ### Ext.Notifications object #| || **Parameter** | **Description** | **Required** || || lurl | The probability of calling a loss notification link. Possible statuses: - 0 — no; - 1 — yes; - 2 — Maybe. | no || || nurl | The probability of calling a win notification link. Possible statuses: - 0 — no; - 1 — yes; - 2 — Maybe. | no || |# ### Imp object #| || **Parameter** | **Description** | **Required** || || bidfloor | The minimum cost per impression for the current auction, specified in CPM format. | yes || || bidfloorcur | Currency letter code in ISO-4217 format. May differ from the offer currency returned by the bidder if permitted by the exchange. | yes || || displaymanager | Monetizer or SDK name. | no || || id | ID of the ad unit on the HTML page. | yes || || instl | Ad type. Acceptable values: - 0 — Non-interstitial ads; - 1 — Interstitial ads. | yes || || ext | The `Imp.Ext` object with additional parameters. | no || || secure | Type of connection. Acceptable values: - 0 — Unsecured connection (HTTP); - 1 — Secured connection (HTTPS). | no || || tagid | ID of the ad placement. | yes || || displaymanagerver | Monetizer or SDK version. | yes || || clickbrowser | Type of browser that opens when you tap the creative in the app. Allowed values: - 0 — Built-in browser; - 1 — Native browser. | yes || || video | The `Imp.Video` object with video display parameters. | no || |# ### Imp.Banner object #| || **Parameter** | **Description** | **Required** || || format | The `Imp.Banner.Format` object with acceptable ad unit dimensions. | yes || || h | Height of the block in pixels. | yes || || w | Width of the block in pixels. | yes || |# ### Imp.Banner.Format object #| || **Parameter** | **Description** | **Required** || || h | Height of the block in pixels. | yes || || w | Width of the block in pixels. | yes || |# ### Imp.Video object #| || **Parameter** | **Description** | **Required** || || mimes | Supported MIME content types. | yes || || protocols | Supported video transfer protocols. | no || || h | Height of the video player in pixels. | no || || w | Width of the video player in pixels. | no || || api | List of supported APIs for this impression. | no || || minduration | Minimum duration of a video in seconds. | no || || maxduration | Maximum duration of a video in seconds. | no || || skip | Shows if a video player has a skipping video function: - 0 — no; - 1 — yes. | no || || playbackmethod | Possible video playback options. If nothing is specified, you can use any option. | no || || minbitrate | Minimum bitrate in kb/s. | no || || maxbitrate | Maximum bitrate in kb/s. | no || || startdelay | Shows the playback delay in seconds for ad placement: - In the beginning of the video. - In the middle of the video. - At the end. | no || || placement | Video banner placement type: - 1 — In-Stream. Playback before, during, or after the broadcast of video content (Pre-roll, Mid-roll, Post-roll); - 2 — In-Banner. Playback inside a web banner placed on a page; - 3 — In-Article. Placement in the text of a web page; - 4 — In-Feed. Placement in the news feed; - 5 — Interstitial/Slider/Floating. Placement on top of the screen. Interstitial banners (for example, banners for mobile apps) differ from floating/slider banners by the value of the `imp.instl` field. | no || || linearity | Linearity of the video banner. Allowed values: - 1 — Linear; - 2 — Non-Linear. | no || || pos | Location of the banner on the screen. Allowed values: - 0 — Unknown; - 1 — Above the Fold; - 3 — Below the Fold; - 4 — Header; - 5 — Footer; - 6 — Sidebar; - 7 — Full Screen. | no || || ext | Object with additional parameters. | no || |# ### Imp.Ext object #| || **Parameter** | **Description** | **Required** || || unmoderated | Auction moderation status. Allowed values: - 0 — Unmoderated auction. - 1 — Moderated auction. | yes || || reward | Rewarded ads. Acceptable values: - 0 - no; - 1 - yes. | no || |# ### Site object #| || **Parameter** | **Description** | **Required** || || page | URL of the page to serve the ad on. | no || || domain | Site domain. | no || || publisher | Information about the placement in the Site.Publisher object. | yes || || id | The site ID. | yes || || content | The Site.Content object with information about the site content. | no || |# ### Site.Publisher object #| || **Parameter** | **Description** | **Required** || || id | The placement ID. | yes || |# ### Site.Content object #| || **Parameter** | **Description** | **Required** || || language | Site language. | no || |# ### Device object #| || **Parameter** | **Description** | **Required** || || lmt | Ad tracking restriction set by the manufacturer of the endpoint device. - 0 — Tracking is not limited.; - 1 — Tracking is limited. | yes || || geo | The `Device.Geo` object with a description of the location of the endpoint device. | yes || || carrier | Telecom operator or internet service provider. | no || || connectiontype | Network connection type. - 0 — Not defined; - 1 — Ethernet (local area network); - 2 — WI-FI; - 3 — Cellular network; - 4 — Cellular network 2G; - 5 — Cellular network 3G; - 6 — Cellular network 4G. | no || || os | Operating system. | yes || || ip | The IP address of the endpoint device. | yes || || ipv6 | The IPv6 address of the endpoint device. | yes || || dnt | Ad tracking restriction set by the endpoint device user. 0 — Tracking is not limited.; 1 — Tracking is limited. | yes || || ua | The value of the HTTP User-Agent header — The name of the application on the endpoint device. | yes || || ifa | The advertising ID of the endpoint device. | yes || || devicetype | The type of device. - 1 — Phone; - 3 — Smartphone; - 4 — Tablet; - 5 — Desktop. | no || || make | The device manufacturer. | no || || mccmnc | The unique mobile operator ID that is a combination of MCC and MNC codes separated by a hyphen. | no || || model | The device model. | no || || osv | The device's operating system version. | no || || h | The height of the device. | no || || w | The width of the device. | no || || language | The language selected in the browser. The format used is ISO-639-1-alpha-2. | no || || dpidsha1 | The device platform identifier (for example, the Android identifier) hashed by the SHA1 algorithm. | no || || dpidmd5 | The device platform identifier (for example, the Android identifier) hashed by the MD5 algorithm. | no || || ext | The `Device.Ext` object with additional parameters | no || |# ### Device.Geo object #| || **Parameter** | **Description** | **Required** || || country | The ISO-3166-1 Alpha-3 country geocode. | yes || || lat | Latitude from -90.0 to +90.0, where negative is south. | no || || lon | Longitude from -180.0 to +180.0, where negative is west. | no || || region | Region code using ISO-3166-2; 2-letter state code if USA. | no || || type | Source of location data; recommended when passing `lat`/`lon`. - 1 — GPS/Location Services; - 2 — IP Address; - 3 — User provided (e.g., registration data). | no || |# ### Device.Ext object #| || **Parameter** | **Description** | **Required** || || oaid | Device ID. | no || || gaid | The ID for Android devices. | no || || idfa | The ID for iOS devices. | no || || ifv | ID of device in that publisher. Only passed when IDFA is unavailable or all zeros. | no || |# ### User object #| || **Parameter** | **Description** | **Required** || || id | Exchange ID of the user. | no || || buyeruid | Buyer ID. | no || || ext |The `User.Ext` object with additional parameters. | no || |# ### User.Ext object #| || **Parameter** | **Description** | **Required** || || consent | Consent to transmit information about the buyer. Allowed values: - 0 — Consent is not given; - 1 — Consent is given. | no || |# ### Regs object #| || **Parameter** | **Description** | **Required** || || coppa | Flag indicating whether the request must comply with the Children's Online Privacy Protection Act (COPPA). - 0 — no; - 1 — yes. | yes || || ext | The Regs.Ext object with additional parameters. | no || |# ### Regs.Ext object #| || **Parameter** | **Description** | **Required** || || gdpr | Flag indicating whether the request must comply with the General Data Protection Regulation (GDPR). - 0 — no; - 1 — yes. | yes || || nroa | The parent object for the extension. | no || |# ### Ext.nroa object #| || **Parameter** | **Description** | **Required** || || version | Version number. For the current version, see the [annex](https://yandex.com/dev/rtb/doc/en/api/annex.md). | no || || mandatory | When the value is `true`, notifies that DSP responses without complete and correct information about the contracts will not be admitted to the auction. | no || |# ### Source object #| || **Parameter** | **Description** | **Required** || || fd | Final decision about serving the ad. - 0 — Exchange; - 1 — Original source. | yes || || sourcetype | Request source. - 1 — The request is received from a source other than Header bidding auction; - 2 — The request comes from the auction's client side; - 3 — The request comes from the server side. | yes || || tid | Impression ID. | yes || || ext | The Source.Ext object with additional parameters. | no || |# ### Source.Ext object #| || **Parameter** | **Description** | **Required** || || schain | The Source.Ext.Schain object with all participants in the inventory sales chain specified. | no || |# ### Source.Ext.Schain object #| || **Parameter** | **Description** | **Required** || || complete | The flag indicates whether the chain contains all nodes up to the original inventory source. Allowed values: - 0 — no; - 1 — yes. | yes || || nodes | Array of `Source.Ext.Schain.Nodes` objects with the order of participants in the chain. | yes || || ver | Supply chain specification version. Currently only version 1.0 exists. | yes || |# ### Source.Ext.Schain.Nodes object #| || **Parameter** | **Description** | **Required** || || asi | The canonical domain of the organization, must match the domain from ads.txt if such a domain exists. | yes || || sid | The same `seller_id` for the publisher as in the sellers.json file. | yes || || hp | Specifies whether this node should be included in the chain of inventory payment participants. If the value is 1, then the organization specified in the `asi` field pays the seller specified in the `sid` field. The seller is the organization that is responsible for paying the previous node in the chain. For version 1.0, the value should always be 1. | yes || || rid | OpenRTB RequestId sent by the seller. | no || || name | The official name of the organization, the field should not be present in the object if the organization is specified in sellers.json. | no || || domain | The official domain of the organization, the field should not be present in the object if the organization is specified in sellers.json. | no || |# ## Sample request — banner advertising ```json { "id": "5881455945172700775", "user": { "buyeruid": "8fahfsfd9a", "id": "108799773262946888", "ext": { "consent": "1" } }, "source": { "fd": 0, "sourcetype": 3, "tid": "", "ext": { "schain": { "complete": 1, "nodes": [ { "asi": "yandex.com", "sid": "12345", "hp": 1, "rid": "bidrequest123" } ], "ver": "1.0" } } }, "cur": [ "RUB", "USD", "EUR", "TRY", "UAH", "KZT", "CHF" ], "bcat": [ "" ], "imp": [ { "secure": 1, "bidfloor": 0.01, "bidfloorcur": "USD", "banner": { "format": [ { "h": 0, "w": 0 }, { "h": 250, "w": 300 }, { "h": 600, "w": 300 }, { "h": 400, "w": 240 } ], "h": 600, "w": 300 }, "id": "55", "ext": { "reward": 1, "unmoderated": 0 }, "tagid": "215876-55", "instl": 0 } ], "tmax": 200, "site": { "page": "https://banners.adfox.ru/201208/adfox/1300062/2b9df8c5d7bd3400f1c1702953801bc8_index.html", "domain": "adfox.ru", "publisher": { "id": "944028" }, "id": "215876", "content": { "language": "ru" } }, "device": { "lmt": 0, "geo": { "country": "USA", "lat": 31.17, "lon": -99.68, "region": "US-TX", "type": 2 }, "os": "Windows", "ip": "", "ipv6": "2a02:6b8:b081:8124::1:29", "ua": "Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/92.0.4515.159 YaBrowser/21.8.3.607 Yowser/2.5 Safari/537.36", "devicetype": 1, "mccmnc": "", "ifa": "", "dnt": 0, "ext": { "gaid": "", "idfa": "1DB9B91B-7520-4807-8D87-BE362369646E", "oaid": "", "ifv": "CA827336-38F6-4586-9FFF-F8B9D6440A2F" } }, "regs": { "coppa": 0, "ext": { "gdpr": 0, "nroa": { "version": "2", "mandatory": true } } }, "at": 1, "ext": { "notifications": { "lurl": 1, "nurl": 1 } } } ``` ## Sample request — video ads ```json { "site": { "page": "https://banners.adfox.ru/201208/adfox/1300062/2b9df8c5d7bd3400f1c1702953801bc8_index.html", "domain": "adfox.ru", "publisher": { "id": "944028" }, "id": "215876", "content": { "language": "ru" } }, "at": 1, "cur": [ "RUB", "USD", "EUR", "TRY", "UAH", "KZT", "CHF" ], "device": { "carrier": "MTS RUS", "connectiontype": 2, "devicetype": 1, "dnt": 0, "dpidmd5": "", "dpidsha1": "", "ext": { "gaid": "851391a2-cb10-4edf-8e89-cdasdf9430", "idfa": "", "oaid": "" }, "geo": { "country": "RUS" }, "h": 838, "ifa": "851391a2-cb10-4edf-8e89-cdasdf9430", "ip": "109.252.147.115", "ipv6": "::ffff:109.252.147.115", "language": "ru", "lmt": 0, "make": "motorola", "mccmnc": "250-1", "model": "moto g(20)", "os": "Android", "osv": "11", "ua": "Dalvik/2.1.0 (Linux; U; Android 11; moto g(20) Build/RTAS31.68-29-2)", "w": 411 }, "ext": { "notifications": { "lurl": 1, "nurl": 1 } }, "id": "2613544480608676485", "imp": [ { "bidfloor": 0.0001567892, "bidfloorcur": "USD", "clickbrowser": 1, "displaymanager": "Yandex Mobile Ads SDK", "displaymanagerver": "4.4.1", "ext": { "reward": 0, "unmoderated": 0 }, "id": "14", "instl": 0, "secure": 1, "tagid": "1354193-14", "video": { "h": 400, "mimes": [ "video/mp4" ], "protocols": [ 3, 6, 7, 8 ], "w": 240, "api": [ 5 ], "minduration": 5, "maxduration": 30, "skip": 0, "playbackmethod": [ 2 ], "minbitrate": 400, "maxbitrate": 1000, "startdelay": -1, "placement": 1, "linearity": 1, "pos": 0, "ext": { "nroa": { "markup_version": 1 } } } } ], "regs": { "coppa": 0, "ext": { "gdpr": 0, "nroa": { "version": "2", "mandatory": true } } }, "source": { "fd": 0, "sourcetype": 3, "tid": "", "ext": { "schain": { "complete": 1, "nodes": [ { "asi": "yandex.com", "sid": "12345", "hp": 1, "rid": "bidrequest123" } ], "ver": "1.0" } } }, "tmax": 500, "user": { "id": "108799773262946888", "ext": { "consent": "0" } } } ```