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.

{
  "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": {
        "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)"
    },
    "os": "(string)",
    "ip": "(string)",
    "ipv6": "(string)",
    "ua": "(string)",
    "devicetype": "(int)",
    "mccmnc": "(string)",
    "ifa": "(string)",
    "dnt": "(int)",
    "ext": {
      "oaid": "(string)",
      "gaid": "(string)",
      "idfa": "(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

Device.Ext object

Parameter

Description

Required

oaid

Device ID.

no

gaid

The ID for Android devices.

no

idfa

The ID for iOS devices.

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.

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

{
  "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": {
        "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": "RUS"
    },
    "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": ""
    }
  },
  "regs": {
    "coppa": 0,
    "ext": {
      "gdpr": 0,
      "nroa": {
        "version": "2",
        "mandatory": true
      }
    }
  },
  "at": 1,
  "ext": {
    "notifications": {
      "lurl": 1,
      "nurl": 1
    }
  }
}

Sample request — video ads

{
  "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
Tagging users
Next
Response