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 app, 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": {
    "buyeruid": "(string)",
    "id": "(string)",
    "ext": {
      "consent": "(string)"
    }
  },
  "imp": [
    {
      "bidfloor": "(float)",
      "bidfloorcur": "(string)",
      "displaymanager": "(string)",
      "id": "(string)",
      "instl": "(int)",
      "ext": {
        "unmoderated": "(int)"
      },
      "ext": {
        "skadn": {
          "version": "(string)",
          "versions": ["(array of strings)"],
          "sourceapp": "(int)",
          "skadnetids": [
            "(array of strings)"
          ]
        }
      }
      "secure": "(int)",
      "tagid": "(string)",
      "native": {
        "request": "{ \"native\": {\"ver\": \"(string)\",\"aurlsupport\": (int),\"privacy\": (int),\"plcmtcnt\": (int),\"assets\": [{\"required\":(int),\"title\": {\"len\": (int)},\"id\": (int)}, {\"required\": (int),\"img\": {\"wmin\": (int),\"type\": (int),\"hmin\": (int)},\"id\": (int)},{\"required\": (int),\"data\": {\"len\": (int),\"type\": (int)},\"id\": (int)},{\"required\": (int),\"data\": {\"len\": (int),\"type\": (int)},\"id\": (int)},{\"required\": (int),\"data\":{\"len\":(int),\"type\": (int)},\"id\": (int)},{\"required\": (int),\"img\":{\"wmin\": (int),\"type\": (int),\"hmin\": (int)},\"id\": (int)}],\"eventtrackers\":[{\"methods\":[(int)],\"event\": (int)}]}}",
        "ver": "(string)"
      },
      "displaymanagerver": "(string)",
      "clickbrowser": "(int)"
    }
  ],
  "tmax": "(int)",
  "app": {
    "bundle": "(string)",
    "id": "(string)",
    "publisher": {
      "id": "(string)"
    },
    "storeurl": "(string)",
    "content": {
      "language": "(string)"
    }
  },
  "bcat": [
    "(array of strings)"
  ],
  "cur": [
    "(array of strings)"
  ],
  "device": {
    "lmt": "(int)",
    "geo": {
      "country": "(string)"
    },
    "carrier": "(string)",
    "mccmnc": "(string)",
    "connectiontype": "(int)",
    "os": "(string)",
    "ip": "(string)",
    "ipv6": "(string)",
    "dnt": "(int)",
    "ifa": "(string)",
    "ua": "(string)",
    "devicetype": "(int)",
    "make": "(string)",
    "model": "(string)",
    "osv": "(string)",
    "h": "(int)",
    "w": "(int)",
    "language": "(string)",
    "dpidsha1": "(string)",
    "dpidmd5": "(string)",
    "ext": {
      "oaid": "(string)",
      "gaid": "(string)",
      "idfa": "(string)"
    }
  },
  "ext": {
    "notifications": {
      "lurl": "(int)",
      "nurl": "(int)"
    }
  },
  "regs": {
    "coppa": "(int)",
    "ext": {
      "gdpr": "(int)",
      "nroa": {
        "version": "(string)",
        "mandatory": "(bool)"
      }
    }
  },
  "at": "(int)",
  "test": "(int)"
}
Copied to clipboard
Request parameters
Parameter Description Required
Bid Request object
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
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
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
app Information about the app in the App object. yes
ext The Ext object with additional parameters. 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 object
notifications The Ext.Notifications 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

The monetizer or SDK name on the mobile mediation platform.

yes
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. yes
secure
Type of connection. Acceptable values:
  • 0 — Unsecured connection (HTTP).
  • 1 — Secured connection (HTTPS).
no
tagid ID of the ad placement. yes
native The Imp.Native object with ad unit parameters. 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
Imp.Native object
ver Native Markup version. no
request Contains an encoded string with the Native object. See a Sample request. yes
aurlsupport

Flag indicating support for the option to return an object link.

  • 0 — Not supported.
  • 1 — Supported.
no
privacy

Privacy terms.

  • 1 — Native advertising contains a privacy notice for the user.
  • 0 — No privacy notice.
no
plcmtcnt The number of ad placement blocks. no
assets The Imp.Native.Request.Native.Assets object with asset parameters. yes
eventtrackers The Imp.Native.Request.Native.Eventtrackers object with event tracking parameters. no
Imp.Native.Request.Native.Assets object
id Asset ID. yes
required

Flag indicating whether the asset is mandatory.

  • 1 — Required asset.
  • 0 — Optional asset.
no
title The Imp.Native.Request.Native.Assets.Title object with asset title parameters. yes
img The Imp.Native.Request.Native.Assets.Img object with asset image parameters. no
data The Imp.Native.Request.Native.Assets.Data object with asset content parameters. no
Imp.Native.Request.Native.Assets.Title object
len Banner title length. yes
Imp.Native.Request.Native.Assets.Img object
wmin Minimum image width. yes
type Image type. yes
hmin Minimum image height. yes
Imp.Native.Request.Native.Assets.Data object
len Response text minimum length. no
type Asset data type. yes
Imp.Native.Request.Native.Eventtrackers object
type Type of tracked events. yes
method Event tracking method. yes
Imp.Ext object
unmoderated
Auction moderation status. Allowed values:
  • 0 — Unmoderated auction.
  • 1 — Moderated auction.
yes
Imp.Ext.skadn object
version

The oldest version supported by the request.

no
versions

List of supported versions (depending on the SDK version and iOS version).

no
sourceapp

App identifier (matches with the app.bundle field).

no
skadnetids

List of identifiers obtained from the SDK.

no
App object
bundle App ID in the App Store or Google Play. yes
publisher Information about the placement in the App.Publisher object. yes
storeurl URL of the app store for the installed app. no
id The app ID. yes
content The App.Content object with information about the app contents. no
App.Publisher object
id The placement ID. yes
App.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
mccmnc The unique mobile operator ID that is a combination of MCC and MNC codes separated by a hyphen. 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
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
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
ext The Device.Ext object with additional parameters. 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
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
buyeruid Buyer ID. 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
Parameter Description Required
Bid Request object
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
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
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
app Information about the app in the App object. yes
ext The Ext object with additional parameters. 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 object
notifications The Ext.Notifications 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

The monetizer or SDK name on the mobile mediation platform.

yes
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. yes
secure
Type of connection. Acceptable values:
  • 0 — Unsecured connection (HTTP).
  • 1 — Secured connection (HTTPS).
no
tagid ID of the ad placement. yes
native The Imp.Native object with ad unit parameters. 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
Imp.Native object
ver Native Markup version. no
request Contains an encoded string with the Native object. See a Sample request. yes
aurlsupport

Flag indicating support for the option to return an object link.

  • 0 — Not supported.
  • 1 — Supported.
no
privacy

Privacy terms.

  • 1 — Native advertising contains a privacy notice for the user.
  • 0 — No privacy notice.
no
plcmtcnt The number of ad placement blocks. no
assets The Imp.Native.Request.Native.Assets object with asset parameters. yes
eventtrackers The Imp.Native.Request.Native.Eventtrackers object with event tracking parameters. no
Imp.Native.Request.Native.Assets object
id Asset ID. yes
required

Flag indicating whether the asset is mandatory.

  • 1 — Required asset.
  • 0 — Optional asset.
no
title The Imp.Native.Request.Native.Assets.Title object with asset title parameters. yes
img The Imp.Native.Request.Native.Assets.Img object with asset image parameters. no
data The Imp.Native.Request.Native.Assets.Data object with asset content parameters. no
Imp.Native.Request.Native.Assets.Title object
len Banner title length. yes
Imp.Native.Request.Native.Assets.Img object
wmin Minimum image width. yes
type Image type. yes
hmin Minimum image height. yes
Imp.Native.Request.Native.Assets.Data object
len Response text minimum length. no
type Asset data type. yes
Imp.Native.Request.Native.Eventtrackers object
type Type of tracked events. yes
method Event tracking method. yes
Imp.Ext object
unmoderated
Auction moderation status. Allowed values:
  • 0 — Unmoderated auction.
  • 1 — Moderated auction.
yes
Imp.Ext.skadn object
version

The oldest version supported by the request.

no
versions

List of supported versions (depending on the SDK version and iOS version).

no
sourceapp

App identifier (matches with the app.bundle field).

no
skadnetids

List of identifiers obtained from the SDK.

no
App object
bundle App ID in the App Store or Google Play. yes
publisher Information about the placement in the App.Publisher object. yes
storeurl URL of the app store for the installed app. no
id The app ID. yes
content The App.Content object with information about the app contents. no
App.Publisher object
id The placement ID. yes
App.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
mccmnc The unique mobile operator ID that is a combination of MCC and MNC codes separated by a hyphen. 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
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
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
ext The Device.Ext object with additional parameters. 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
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
buyeruid Buyer ID. 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

{
  "app": {
    "bundle": "336435697",
    "id": "1466531",
    "publisher": {
      "id": "0"
    },
    "content": {
      "language": "ru"
    }
  },
  "at": 1,
  "cur": [
    "RUB",
    "USD",
    "EUR",
    "TRY",
    "UAH",
    "KZT",
    "CHF"
  ],
  "device": {
    "carrier": "23410",
    "connectiontype": 0,
    "devicetype": 1,
    "dnt": 0,
    "dpidmd5": "306ae45f631d9cba6df9450b2d06cce1",
    "dpidsha1": "9e9b90848b103d23e99be99d99ecff397b45024e",
    "ext": {},
    "geo": {
      "country": "GBR"
    },
    "ip": "2.217.22.0",
    "ipv6": "::ffff:2.217.22.0",
    "language": "en",
    "lmt": 0,
    "make": "apple",
    "mccmnc": "",
    "model": "ipad",
    "os": "iOS",
    "osv": "14.7.1",
    "ua": "Mozilla/5.0 (iPad; CPU iPad OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148"
  },
  "ext": {
    "notifications": {
      "lurl": 1,
      "nurl": 1,
      "gaid": ,
      "idfa": "1DB9B91B-7520-4807-8D87-BE362369646E",
      "oaid":
    }
  },
  "id": "1235558418521588268",
  "imp": [
    {
      "bidfloor": 1.54,
      "bidfloorcur": "RUB",
      "clickbrowser": 1,
      "displaymanager": "",
      "displaymanagerver": "2022.01.0305",
      "ext": {
        "unmoderated": 0
      },
      "ext": {
        "skadn": {
          "version": "2.0",
          "versions": ["2.0", "2.1", "3.0"],
          "sourceapp": "880047117",
          "skadnetids": [
            "dticjx1a9i.skadnetwork",
            "8srfag4vvc.skadnetwork"
          ]
        }
      }
      "id": "1",
      "instl": 0,
      "native": {
        "request": "{\"native\":{\"ver\":\"1.2\",\"aurlsupport\":0,\"privacy\":0,\"plcmtcnt\":1,\"assets\":[{\"title\":{\"len\":\"50\"},\"id\":\"1\"},{\"data\":{\"type\":\"2\",\"len\":\"150\"},\"id\":\"2\"},{\"data\":{\"type\":\"12\",\"len\":\"15\"},\"id\":\"3\"},{\"id\":\"4\",\"img\":{\"wmin\":\"50\",\"hmin\":\"50\",\"type\":\"1\"}},{\"required\":\"1\",\"img\":{\"wmin\":\"320\",\"hmin\":\"160\",\"type\":\"3\"},\"id\":\"5\"}],\"eventtrackers\":[{\"methods\":[1],\"event\":1}]}}",
        "ver": "1.2"
      },
      "secure": 1,
      "tagid": "1466531-1"
    }
  ],
  "regs": {
    "coppa": 0,
    "ext": {
      "gdpr": 1,
      "nroa": {
        "version": "2",
        "mandatory": true
      }
    }
  },
  "source": {
    "fd": 0,
    "sourcetype": 3,
    "tid": ""
  },
  "tmax": 200,
  "user": {
    "id": "108799773262946888",
    "buyeruid": "8fahfsfd9a",
    "ext": {
      "consent": "0"
    }
  }
}
Copied to clipboard