Web ads: Request from the OpenRTB host

The auction participation request is sent via the POST method in JSON format (Content‑Type: application/json).

Request body

The request body contains a Bid Request object. Its parameters describe the site, end device, and consumer (user). This information helps the DSP select ads and bids.

{
  "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

Auction ID assigned by the RTB host. The DSP returns this ID in its response.

Yes

user

Information about the ad buyer provided in the User object.

Yes

ext

Ext object with additional parameters.

No

cur

List of bid currencies. The following parameters are passed:

  • RUB: Russian ruble.
  • USD: US dollar.
  • EUR: Euro.
  • CHF: Swiss franc.
  • TRY: Turkish lira.
  • UAH: Ukrainian hryvnia.
  • KZT: Kazakhstani tenge.

Yes

bcat

Blocked advertiser categories according to the IAB classification.

No

imp

An array of Imp objects that contain banner rendering parameters. Each object corresponds to one ad unit on the HTML page. The current implementation passes a single object.

Yes

tmax

The maximum response time in milliseconds within which the DSP must submit a bid, taking internet latency into account.

Yes

site

Site information provided in the Site object.

Yes

app

App information provided in the App object.

Yes

device

Information about the end device provided in the Device object.

Yes

regs

Industry, legal, or government regulations that apply to all impressions in the request, provided in the Regs object.

No

at

Auction type. Possible values:

  • 1: First-price auction.
  • 2: Second-price auction.

No

test

Test mode indicator. Possible values:

  • 0: Send real traffic.
  • 1: Send test traffic.

No

source

Information about the request source in the Source object.

Yes

Ext object

Parameter

Description

Required

notifications

Ext.Notifications object containing URLs for win‑ and loss‑notification callbacks.

No

Ext.Notifications object

Parameter

Description

Required

lurl

Probability of triggering the loss‑notification callback. Possible values:

  • 0: No.
  • 1: Yes.
  • 2: Possible.

No

nurl

Probability of triggering the win‑notification callback. Possible values:

  • 0: No.
  • 1: Yes.
  • 2: Possible.

No

Imp object

Parameter

Description

Required

secure

Connection type. Supported options:

  • 0: Insecure connection (HTTP).
  • 1: Secure connection (HTTPS).

No

bidfloor

Minimum cost per thousand impressions (CPM) for the current auction.

Yes

bidfloorcur

Currency's alphabetic code in ISO 4217 format. This may differ from the bid currency returned by the bidder if allowed by the exchange.

Yes

banner

Imp.Banner object with default ad unit dimensions.

Yes

id

ID of the ad unit on the HTML page.

Yes

ext

Imp.Ext object with additional parameters.

Yes

tagid

Placement ID.

Yes

instl

Type of ads. Supported options:

  • 0: Non-fullscreen ads.
  • 1: Fullscreen ads.

Yes

displaymanager

Name of the ad monetization platform or SDK.

No

displaymanagerver

Version of the ad monetization platform or SDK.

Yes

clickbrowser

Type of browser that opens when a user taps the creative inside the app. Possible values:

  • 0: In-app browser.
  • 1: Native browser.

Yes

video

Imp.Video object with video display parameters.

No

Imp.Banner object

Parameter

Description

Required

format

Imp.Banner.Format object with allowed ad unit sizes.

Yes

h

Ad unit height in pixels.

Yes

w

Ad unit width in pixels.

Yes

Imp.Banner.Format object

Parameter

Description

Required

h

Ad unit height in pixels.

Yes

w

Ad unit width in pixels.

Yes

Imp.Video object

Parameter

Description

Required

mimes

Supported MIME content types.

Yes

protocols

Supported video delivery 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 video duration in seconds.

No

maxduration

Maximum video duration in seconds.

No

skip

Flag indicating whether the video player allows skippable ads:

  • 0: No.
  • 1: Yes.

No

playbackmethod

Allowed video playback methods. If not specified, any method can be used.

No

minbitrate

Minimum bitrate in kbps.

No

maxbitrate

Maximum bitrate in kbps.

No

startdelay

Playback start delay in seconds for pre-roll, mid-roll, and post-roll ad placements.

No

placement

Video ad placement type:

  • 1: In-stream. The video ad plays before, during, or after streaming video content (pre-roll, mid-roll, post-roll).
  • 2: In-banner. The video ad plays within a web banner placed on the page.
  • 3: In-article. The video banner is placed within the text of a web page.
  • 4: In-feed. The video banner is placed within a content feed.
  • 5: Interstitial, slider, or floating ad. The video banner overlays the screen. Fullscreen interstitial banners (such as mobile app ads) differ from floating and slider units by the value in the imp.instl field.

No

linearity

Flag indicating whether the video banner is linear. Possible values:

  • 1: Linear.
  • 2: Non-linear.

No

pos

Banner placement on screen. Possible values:

  • 0: Unknown.
  • 1: Above the fold.
  • 3: Below the fold.
  • 4: Header.
  • 5: Footer.
  • 6: Sidebar.
  • 7: Fullscreen.

No

ext

Object with additional parameters.

No

Imp.Ext object

Parameter

Description

Required

unmoderated

Auction moderation status. Possible values:

  • 0: Unmoderated auction.
  • 1: Moderated auction.

Yes

reward

Rewarded ads. Supported options:

  • 0: No.
  • 1: Yes.

No

Site object

Parameter

Description

Required

page

URL of the page that shows the ad.

No

domain

Site domain.

No

publisher

Site information provided in the Site.Publisher object.

Yes

id

Site ID.

Yes

content

Site.Content object with information about the site content.

No

Site.Publisher object

Parameter

Description

Required

id

Ad platform ID.

Yes

Site.Content object

Parameter

Description

Required

language

Site language.

No

Device object

Parameter

Description

Required

lmt

Flag indicating whether the device manufacturer has limited ad tracking.

  • 0: Ad tracking not limited.
  • 1: Ad tracking limited.

Yes

geo

Device.Geo object with information about the location of the end device.

Yes

os

Operating system.

Yes

ip

IP address of the end device.

Yes

ipv6

IPv6 address of the end device.

Yes

ua

The value of the User-Agent HTTP header: the name of the app on the end device.

Yes

devicetype

Device type.

  • 1: Cellphone.
  • 3: Smartphone.
  • 4: Tablet.
  • 5: Desktop.

No

mccmnc

Unique mobile carrier ID generated by joining the MCC and MNC with a hyphen.

No

ifa

Advertising ID for the end device.

Yes

dnt

Flag indicating whether the user has limited ad tracking on the end device.

  • 0: Ad tracking not limited.
  • 1: Ad tracking limited.

Yes

language

Language selected in the browser. Format: ISO-639-1 alpha-2.

No

ext

Device.Ext object with additional parameters.

No

carrier

Mobile carrier or internet service provider.

No

connectiontype

Network connection type.

  • 0: Unknown.
  • 1: Ethernet (local network).
  • 2: Wi-Fi.
  • 3: Mobile data.
  • 4: Mobile data (2G).
  • 5: Mobile data (3G).
  • 6: Mobile data (4G).

No

make

Device manufacturer.

No

model

Device model.

No

osv

Version of the device's operating system.

No

h

Device height.

No

w

Device width.

No

dpidsha1

Device platform ID (such as Android ID) hashed using the SHA-1 algorithm.

No

dpidmd5

Device platform ID (such as Android ID) hashed using the MD5 algorithm.

No

Device.Geo object

Parameter

Description

Required

country

Country code in ISO 3166-1 alpha-3 format.

Yes

lat

Latitude from -90.0 to +90.0, where negative values indicate south.

No

lon

Longitude from -180.0 to +180.0, where negative values indicate west.

No

region

Region code formatted as ISO 3166-2, or two-letter US state code.

No

type

Location data source. We recommend passing it with lat/lon.

  • 1: GPS or other system.
  • 2: IP address.
  • 3: User-provided (for example, registration data).

No

Device.Ext object

Parameter

Description

Required

oaid

Device ID.

No

gaid

ID of the Android device.

No

idfa

ID of the iOS device.

No

ifv

Publisher-specific device ID. This ID is only passed if the standard device ID is unavailable or consists of all zeros.

No

User object

Parameter

Description

Required

id

User ID assigned by the ad exchange.

No

buyeruid

Buyer ID.

No

ext

User.Ext object with additional parameters.

No

User.Ext object

Parameter

Description

Required

consent

Consent to share buyer data. Possible values:

  • 0: No consent.
  • 1: Consent.

No

Regs object

Parameter

Description

Required

coppa

Flag indicating whether the request is subject to COPPA (Children's Online Privacy Protection Act).

  • 0: No.
  • 1: Yes.

Yes

ext

Regs.Ext object with additional parameters.

No

Regs.Ext object

Parameter

Description

Required

gdpr

Flag indicating whether the request is subject to the General Data Protection Regulation (GDPR).

  • 0: No.
  • 1: Yes.

Yes

nroa

Parent object for extension.

No

Ext.nroa object

Parameter

Description

Required

version

Version number. See the current version in the app.

No

mandatory

When this parameter is set to true, DSP responses lacking complete and valid contract information are excluded from the auction.

No

Source object

Parameter

Description

Required

fd

Final decision to serve an ad impression.

  • 0: Ad exchange.
  • 1: Original source.

Yes

sourcetype

Request source.

  • 1: The request comes from a Header Bidding auction.
  • 2: The request comes from the client side of the auction.
  • 3: The request comes from the server side.

Yes

tid

Impression ID.

Yes

ext

Source.Ext object with additional parameters.

No

Source.Ext object

Parameter

Description

Required

schain

Source.Ext.Schain object listing all participants in the inventory supply chain.

No

Source.Ext.Schain object

Parameter

Description

Required

complete

Flag indicating whether the supply chain contains all nodes back to the original inventory source. Possible values:

  • 0: No.
  • 1: Yes.

Yes

nodes

Array of Source.Ext.Schain.Nodes objects representing the ordered list of the supply chain participants.

Yes

ver

Version of the supply chain specification. Currently, only version 1.0 exists.

Yes

Source.Ext.Schain.Nodes object

Parameter

Description

Required

asi

Canonical domain of the organization. It must match the domain in ads.txt if one exists.

Yes

sid

Same seller_id for the publisher as in the sellers.json file.

Yes

hp

Flag indicating whether this node participates in the payment flow for the inventory. If this parameter is set to 1, the organization specified in the asi field pays the seller specified in the sid field. The seller is the organization responsible for paying the previous node in the chain. For version 1.0, this value must always be 1.

Yes

rid

OpenRTB RequestId passed by the seller.

No

name

Official name of the organization. This field must be omitted from the object if the organization is listed in sellers.json.

No

domain

Official domain of the organization. This field must be omitted from the object if the organization is listed in sellers.json.

No

 
{
  "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 for a video ad

{
  "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"
    }
  }
}
Previous
User tagging
Next
Response