OpenRTB host request

The invitation to participate in an auction is sent using the POST method in JSON format (Content-Type: application/json).

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.

{
  "source": {
    "fd": "(int)",
    "sourcetype": "(int)",
    "tid": "(string)",
    "ext": {
      "schain": {
        "complete": "(int)",
        "nodes": [
          {
            "asi": "(string)",
            "sid": "(string)",
            "hp": "(int)",
            "rid": "(string)"
          }
        ],
        "ver": "(string)"
      }
    }
  },
  "id": "(string)",
  "user": {
    "id": "(string)",
    "ext": {
      "consent": "(string)"
    }
  },
  "imp": [
    {
      "bidfloor": "(float)",
      "bidfloorcur": "(string)",
      "displaymanager": "(string)",
      "id": "(string)",
      "instl": "(int)",
      "ext": {
        "reward": "(int)",
        "unmoderated": "(int)"
      },
      "secure": "(int)",
      "tagid": "(string)",
      "displaymanagerver": "(string)",
      "clickbrowser": "(int)",
      "video": {
        "h": "(int)",
        "mimes": [
          "(array of strings)"
        ],
        "protocols": [
          "(array of int)"
        ],
        "w": "(int)",
        "api": [
          "(array of int)"
        ],
        "minduration": "(int)",
        "maxduration": "(int)",
        "skip": "(int)",
        "playbackmethod": [
          "(array of int)"
        ],
        "minbitrate": "(int)",
        "maxbitrate": "(int)",
        "startdelay": "(int)",
        "placement": "(int)",
        "linearity": "(int)",
        "pos": "(int)",
        "ext": {
          "nroa": {
            "markup_version": (int)
          }
        }
      }
    }
  ],
  "tmax": "(int)",
  "site": {
      "content": {
        "language": "(string)"
      },
      "domain": "(string)",
      "id": "(string)",
      "page": "(string)",
      "publisher": {
        "id": "(string)"
    }
  },
  "cur": [
    "(array of strings)"
  ],
  "device": {
    "lmt": "(int)",
    "geo": {
      "country": "(string)"
    },
    "carrier": "(string)",
    "connectiontype": "(int)",
    "os": "(string)",
    "ip": "(string)",
    "ipv6": "(string)",
    "dnt": "(int)",
    "ifa": "(string)",
    "ua": "(string)",
    "devicetype": "(int)",
    "make": "(string)",
    "mccmnc": "(string)",
    "model": "(string)",
    "osv": "(string)",
    "h": "(int)",
    "w": "(int)",
    "language": "(string)",
    "dpidsha1": "(string)",
    "dpidmd5": "(string)",
    "ext": {
      "oaid": "(string)",
      "gaid": "(string)",
      "idfa": "(string)"
    }
  },
  "regs": {
    "coppa": "(int)",
    "ext": {
      "gdpr": "(int)",
      "nroa": {
        "version": "(string)",
        "mandatory": "(bool)"
      }
    }
  },
  "at": "(int)",
  "test": "(int)",
  "ext": {
    "notifications": {
      "lurl": "(int)",
      "nurl": "(int)"
    }
  }
}
Copied to clipboard

Request parameters
Bid Request object
Parameter	Description	Required
`source`	Information about the request source in the Source object.	yes
`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
`imp`	Array of Impression 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
`app`	Information about the app in the App object.	yes
`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. UAH — Ukrainian hryvnia. KZT — Kazakhstani tenge.	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
`ext`	The Ext object with additional parameters.	no
Ext object
`notifications`	The Ext.Notifiactions object with the URLs of notifications about winning or losing the bid.	no
Ext.Notifications object
`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
`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
`secure`	Type of connection. Acceptable values: 0 — Unsecured connection (HTTP). 1 — Secured connection (HTTPS).	no
`ext`	The Imp.Ext object with additional parameters.	yes
`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.Video object
`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
Video.Ext object
`nroa`	The parent object for the extension.	no
Video.Ext.nroa object
`markup_version`	The video labeling version number.	no
Imp.Ext object
`reward`	Rewarded ads. Acceptable values: 0 — No. 1 — Yes.	no
`unmoderated`	Auction moderation status. Allowed values: 0 — Unmoderated auction. 1 — Moderated auction.	yes
Site object
`publisher`	Information about the placement in the Site.Publisher object.	yes
`id`	The app ID.	yes
`content`	The `Site.Content` object with information about the app contents.	no
`page`	URL of the page to serve the ad on.	no
`domain`	Site domain.	no
Site.Publisher object
`id`	The placement ID.	yes
Site.Content object
`language`	The app language.	no
Device object
`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 – 2G cellular network. 5 – 3G cellular network. 6 – 4G cellular network.	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
`ifa`	The advertising ID of the endpoint device.	yes
`ua`	The value of the HTTP User-Agent header — The name of the application on 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
`country`	The ISO-3166-1 Alpha-3 country geocode.	yes
Device.Ext object
`oaid`	Device ID.	no
`gaid`	The ID for Android devices.	no
`idfa`	The ID for iOS devices.	no
User object
`id`	Exchange ID of the user.	no
`ext`	The User.Ext object with additional parameters.	no
User.Ext object
`consent`	Consent to transmit information about the buyer. Allowed values: 0 – Consent is not given. 1 – Consent is given.	no
Regs object
`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
`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
`version`	Version number. For the current version, see the app.	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
`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
`schain`	The Source.Ext.Schain object with all participants in the inventory sales chain specified.	no
Source.Ext.Schain object
`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
`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

Request parameters
Bid Request object
Parameter	Description	Required
`source`	Information about the request source in the Source object.	yes
`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
`imp`	Array of Impression 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
`app`	Information about the app in the App object.	yes
`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. UAH — Ukrainian hryvnia. KZT — Kazakhstani tenge.	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
`ext`	The Ext object with additional parameters.	no
Ext object
`notifications`	The Ext.Notifiactions object with the URLs of notifications about winning or losing the bid.	no
Ext.Notifications object
`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
`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
`secure`	Type of connection. Acceptable values: 0 — Unsecured connection (HTTP). 1 — Secured connection (HTTPS).	no
`ext`	The Imp.Ext object with additional parameters.	yes
`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.Video object
`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
Video.Ext object
`nroa`	The parent object for the extension.	no
Video.Ext.nroa object
`markup_version`	The video labeling version number.	no
Imp.Ext object
`reward`	Rewarded ads. Acceptable values: 0 — No. 1 — Yes.	no
`unmoderated`	Auction moderation status. Allowed values: 0 — Unmoderated auction. 1 — Moderated auction.	yes
Site object
`publisher`	Information about the placement in the Site.Publisher object.	yes
`id`	The app ID.	yes
`content`	The `Site.Content` object with information about the app contents.	no
`page`	URL of the page to serve the ad on.	no
`domain`	Site domain.	no
Site.Publisher object
`id`	The placement ID.	yes
Site.Content object
`language`	The app language.	no
Device object
`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 – 2G cellular network. 5 – 3G cellular network. 6 – 4G cellular network.	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
`ifa`	The advertising ID of the endpoint device.	yes
`ua`	The value of the HTTP User-Agent header — The name of the application on 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
`country`	The ISO-3166-1 Alpha-3 country geocode.	yes
Device.Ext object
`oaid`	Device ID.	no
`gaid`	The ID for Android devices.	no
`idfa`	The ID for iOS devices.	no
User object
`id`	Exchange ID of the user.	no
`ext`	The User.Ext object with additional parameters.	no
User.Ext object
`consent`	Consent to transmit information about the buyer. Allowed values: 0 – Consent is not given. 1 – Consent is given.	no
Regs object
`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
`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
`version`	Version number. For the current version, see the app.	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
`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
`schain`	The Source.Ext.Schain object with all participants in the inventory sales chain specified.	no
Source.Ext.Schain object
`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
`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

{
  "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"
    }
  }
}
Copied to clipboard