Mobile ads: Request from the OpenRTB host
- Request body
- Request parameters
- Bid Request object
- Ext object
- Ext.Notifications object
- Imp object
- Imp.Banner object
- Imp.Banner.Format object
- Imp.Native object
- Imp.Native.Request.Native.Assets object
- Imp.Native.Request.Native.Assets.Title object
- Imp.Native.Request.Native.Assets.Img object
- Imp.Native.Request.Native.Assets.Data object
- Imp.Native.Request.Native.Eventtrackers object
- Imp.Video object
- Imp.Ext object
- Imp.Ext.skadn object
- Imp.Ext.skadn.ext object
- App object
- App.Publisher object
- App.Content object
- Device object
- Device.Geo object
- Device.Ext object
- User object
- User.Ext object
- Regs object
- Regs.Ext object
- Ext.nroa object
- Source object
- Source.Ext object
- Source.Ext.Schain object
- Source.Ext.Schain.Nodes object
- Sample request for a banner ad
- Sample request for a native ad
- Sample request for a video ad
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 app, the end device, and the consumer (user). This information helps the DSP select ads and bids.
{
"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": {
"reward": "(int)",
"unmoderated": "(int)",
"skadn": {
"ext": {
"ask": "(int)"
},
"version": "(string)",
"versions": ["(array of strings)"],
"sourceapp": "(int)",
"skadnetids": [
"(array of strings)"
],
"fidelities": [
"(array of strings)"
]
}
},
"secure": "(int)",
"tagid": "(string)",
"banner": {
"api": [
"(array of int)"
],
"format": [
{
"h": "(int)",
"w": "(int)"
}
],
"h": "(int)",
"w": "(int)"
},
"displaymanagerver": "(string)",
"clickbrowser": "(int)"
}
],
"tmax": "(int)",
"app": {
"bundle": "(string)",
"cat": [
"(string)"
],
"name": "Cookingdom",
"publisher": {
"id": "(string)",
"name": "(string)"
},
"storeurl": "(string)",
"id": "(string)",
"content": {
"language": "(string)"
},
"ver": "(string)"
},
"bcat": [
"(array of strings)"
],
"cur": [
"(array of strings)"
],
"device": {
"lmt": "(int)",
"geo": {
"country": "(string)",
"lat": "(float)",
"lon": "(float)",
"region": "(string)",
"type": "(int)"
},
"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)",
"ifv": "(string)"
}
},
"regs": {
"coppa": "(int)",
"ext": {
"gdpr": "(int)",
"nroa": {
"version": "(string)",
"mandatory": "(bool)"
}
}
},
"at": "(int)",
"test": "(int)",
"ext": {
"notifications": {
"lurl": "(int)",
"nurl": "(int)"
}
}
}
Request parameters
Bid Request object
|
Parameter |
Description |
Required |
|
source |
Information about the request source, provided in the |
Yes |
|
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 |
Yes |
|
cur |
List of bid currencies. The following parameters are passed:
|
Yes |
|
bcat |
Blocked advertiser categories according to the IAB classification. |
No |
|
imp |
An array of |
Yes |
|
tmax |
The maximum response time in milliseconds within which the DSP must submit a bid, taking internet latency into account. |
Yes |
|
app |
App information provided in the |
Yes |
|
ext |
|
No |
|
device |
Information about the end device provided in the |
Yes |
|
regs |
Industry, legal, or government regulations that apply to all impressions in the request, provided in the |
No |
|
at |
Auction type. Possible values:
|
No |
|
test |
Test mode indicator. Possible values:
|
No |
Ext object
|
Parameter |
Description |
Required |
|
notifications |
|
No |
Ext.Notifications object
|
Parameter |
Description |
Required |
|
lurl |
Probability of triggering the loss‑notification callback. Possible values:
|
No |
|
nurl |
Probability of triggering the win‑notification callback. Possible values:
|
No |
Imp object
|
Parameter |
Description |
Required |
|
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 |
|
displaymanager |
Name of the ad monetization platform or SDK. |
No |
|
id |
ID of the ad unit on the HTML page. |
Yes |
|
instl |
Type of ads. Supported options:
|
Yes |
|
ext |
|
No |
|
secure |
Connection type. Supported options:
|
No |
|
tagid |
Placement ID. |
Yes |
|
banner |
|
Yes |
|
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:
|
Yes |
|
native |
|
Yes |
|
video |
|
No |
Imp.Banner object
|
Parameter |
Description |
Required |
|
api |
List of API-supported platforms. |
No |
|
format |
|
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.Native object
|
Parameter |
Description |
Required |
|
ver |
Native markup version. |
No |
|
request |
Contains an encoded string with a |
Yes |
|
aurlsupport |
Flag indicating support for returning an object link.
|
No |
|
privacy |
Privacy terms.
|
No |
|
plcmtcnt |
Number of ad units. |
No |
|
assets |
|
Yes |
|
eventtrackers |
|
No |
Imp.Native.Request.Native.Assets object
|
Parameter |
Description |
Required |
|
id |
Asset ID. |
Yes |
|
required |
Flag indicating whether the asset is required:
|
No |
|
title |
|
Yes |
|
img |
|
No |
|
data |
|
No |
Imp.Native.Request.Native.Assets.Title object
|
Parameter |
Description |
Required |
|
len |
Banner title length. |
Yes |
Imp.Native.Request.Native.Assets.Img object
|
Parameter |
Description |
Required |
|
wmin |
Minimum image width. |
Yes |
|
type |
Type of image. |
Yes |
|
hmin |
Minimum image height. |
Yes |
Imp.Native.Request.Native.Assets.Data object
|
Parameter |
Description |
Required |
|
len |
Maximum length of the response text. |
No |
|
type |
Type of asset data. |
Yes |
Imp.Native.Request.Native.Eventtrackers object
|
Parameter |
Description |
Required |
|
type |
Type of tracked events. |
Yes |
|
method |
Event tracking method. |
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:
|
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:
|
|
|
linearity |
Flag indicating whether the video banner is linear. Possible values:
|
|
|
pos |
Banner placement on screen. Possible values:
|
|
|
ext |
Object with additional parameters. |
Imp.Ext object
|
Parameter |
Description |
Required |
|
unmoderated |
Auction moderation status. Possible values:
|
Yes |
|
reward |
Rewarded ads. Possible values:
|
No |
Imp.Ext.skadn object
|
Parameter |
Description |
Required |
|
version |
Highest supported version for the request. |
No |
|
versions |
List of supported versions (varies by SDK and iOS version). |
No |
|
sourceapp |
App ID (same as the |
No |
|
skadnetids |
List of IDs retrieved from the SDK. |
No |
|
fidelities |
List of supported fidelity types (varies by SKAdNetwork and SDK version). |
No |
|
ext |
Object with additional parameters. |
No |
Imp.Ext.skadn.ext object
|
Parameter |
Description |
Required |
|
ask |
Flag indicating whether ASK control is supported for the request. Possible values:
|
No |
App object
|
Parameter |
Description |
Required |
|
bundle |
App ID in the App Store or Google Play. |
No |
|
cat |
IAB content categories for the app. For more information, see OpenRTB. |
No |
|
name |
App name (can be customized by the publisher). |
No |
|
publisher |
Site information provided in the |
Yes |
|
storeurl |
App store URL for the installed app. |
No |
|
id |
App ID. |
Yes |
|
content |
|
No |
|
ver |
App version. |
No |
App.Publisher object
|
Parameter |
Description |
Required |
|
id |
Ad platform ID. |
Yes |
|
name |
Ad platform name (can be customized by the publisher). |
No |
App.Content object
|
Parameter |
Description |
Required |
|
language |
App language. |
No |
Device object
|
Parameter |
Description |
Required |
|
lmt |
Flag indicating whether the device manufacturer has limited ad tracking.
|
Yes |
|
geo |
|
Yes |
|
carrier |
Mobile carrier or internet service provider. |
No |
|
connectiontype |
Network connection type.
|
No |
|
os |
Operating system. |
Yes |
|
ip |
IP address of the end device. |
Yes |
|
ipv6 |
IPv6 address of the end device. |
Yes |
|
dnt |
Flag indicating whether the user has limited ad tracking on the end device.
|
Yes |
|
ua |
|
Yes |
|
ifa |
Advertising ID for the end device. |
Yes |
|
devicetype |
Device type:
|
No |
|
make |
Device manufacturer. |
No |
|
mccmnc |
Unique mobile carrier ID generated by joining the MCC and MNC with a hyphen. |
No |
|
model |
Device model. |
No |
|
osv |
Version of the device's operating system. |
No |
|
h |
Device height. |
No |
|
w |
Device width. |
No |
|
language |
Language selected in the browser. Format: ISO-639-1 alpha-2. |
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 |
|
ext |
|
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
|
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 |
|
No |
User.Ext object
|
Parameter |
Description |
Required |
|
consent |
Consent to share buyer data. Possible values:
|
No |
Regs object
|
Parameter |
Description |
Required |
|
coppa |
Flag indicating whether the request is subject to COPPA (Children's Online Privacy Protection Act).
|
Yes |
|
ext |
|
No |
Regs.Ext object
|
Parameter |
Description |
Required |
|
gdpr |
Flag indicating whether the request is subject to the General Data Protection Regulation (GDPR).
|
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 |
No |
Source object
|
Parameter |
Description |
Required |
|
fd |
Final decision to serve an ad impression.
|
Yes |
|
sourcetype |
Request source.
|
Yes |
|
tid |
Impression ID. |
Yes |
|
ext |
|
No |
Source.Ext object
|
Parameter |
Description |
Required |
|
schain |
|
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:
|
Yes |
|
nodes |
Array of |
Yes |
|
ver |
Version of the |
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 |
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 |
Sample request for a banner ad
{
"source": {
"fd": 0,
"sourcetype": 3,
"tid": "",
"ext": {
"schain": {
"complete": 1,
"nodes": [
{
"asi": "yandex.com",
"sid": "12345",
"hp": 1,
"rid": "bidrequest123"
}
],
"ver": "1.0"
}
}
},
"id": "5834842956793170835",
"user": {
"buyeruid": "8fahfsfd9a",
"id": "108799773262946888",
"ext": {
"consent": "1"
}
},
"imp": [
{
"bidfloor": 0.01,
"bidfloorcur": "USD",
"displaymanager": "Yandex Mobile Ads SDK",
"id": "10",
"instl": 0,
"ext": {
"reward": 1,
"unmoderated": 0
},
"ext": {
"skadn": {
"ext": {
"ask": 1
},
"version": "2.0",
"versions": ["2.0", "2.1", "3.0"],
"sourceapp": "880047117",
"skadnetids": [
"dticjx1a9i.skadnetwork",
"8srfag4vvc.skadnetwork"
],
"fidelities": [
0,
1
]
}
},
"secure": 1,
"tagid": "123123-10",
"banner": {
"format": [
{
"h": 300,
"w": 300
},
{
"h": 50,
"w": 320
},
{
"h": 250,
"w": 300
},
{
"h": 100,
"w": 320
}
],
"h": 250,
"w": 300
},
"displaymanagerver": "3.5.0",
"clickbrowser": 1
}
],
"tmax": 200,
"app": {
"bundle": "ru.scanword.sloword",
"cat": [
"IAB9-30"
],
"name": "Cookingdom",
"publisher": {
"id": "4626422",
"name": "ABI GLOBAL LTD."
},
"id": "123123",
"content": {
"language": "ru"
},
"ver": "1.0.73"
},
"bcat": [
""
],
"cur": [
"RUB",
"USD",
"EUR",
"TRY",
"UAH",
"KZT",
"CHF"
],
"device": {
"lmt": 0,
"ua": "com.yandex.mobile.metrica.ads.sdk/2.10 (Apple iPhone7,1; iOS 11.2.6) 229abba2",
"ip": "",
"ifa": "1DB9B91B-7520-4807-8D87-BE362369646E",
"mccmnc": "",
"dpidmd5": "",
"geo": {
"country": "USA",
"lat": 31.17,
"lon": -99.68,
"region": "US-TX",
"type": 2
},
"dpidsha1": "",
"carrier": "",
"connectiontype": 0,
"model": "iPhone7,1",
"osv": "11.2.6",
"make": "Apple",
"os": "iOS",
"devicetype": 1,
"ipv6": "2a02:6b8:81:0:8cf6:c67:9042:972b",
"w": 414,
"h": 736,
"dnt": 0,
"language": "ru",
"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 native ad
{
"app": {
"bundle": "com.avito.android",
"cat": [
"IAB9-30"
],
"content": {
"language": "ru"
},
"id": "131313",
"name": "Cookingdom",
"publisher": {
"id": "2424224",
"name": "ABI GLOBAL LTD."
},
"storeurl": "https://play.google.com/store/apps/details?id=com.avito.android",
"ver": "183.6"
},
"at": 1,
"cur": [
"RUB",
"USD",
"EUR",
"TRY",
"UAH",
"KZT",
"CHF"
],
"device": {
"carrier": "Beeline",
"connectiontype": 6,
"devicetype": 4,
"dnt": 0,
"dpidmd5": "",
"dpidsha1": "",
"ext": {
"gaid": "",
"oaid": ""
},
"geo": {
"country": "RUS",
"latitude": 59.34,
"longitude": 29.61,
"region": "RU-LEN",
"type": 2
},
"h": 713,
"ifa": "e7ae-e7ae-e7ae-e7ae-08d5f943e89a",
"ip": "176.15.167.236",
"language": "ru",
"lmt": 0,
"make": "HUAWEI",
"mccmnc": "250-99",
"model": "ELE-L29",
"os": "Android",
"osv": "10",
"ua": "Dalvik/2.1.0 (Linux; U; Android 10; ELE-L29 Build/HUAWEIELE-L29)",
"w": 360
},
"ext": {
"notifications": {
"lurl": 1,
"nurl": 1
}
},
"id": "5327799747007558846",
"imp": [
{
"bidfloor": 0.5211128635,
"bidfloorcur": "USD",
"clickbrowser": 1,
"displaymanager": "Yandex Mobile Ads SDK",
"displaymanagerver": "6.0.1",
"ext": {
"unmoderated": 0
},
"id": "166",
"instl": 0,
"native": {
"request": "{\"native\":{\"ver\":\"1.2\",\"aurlsupport\":0,\"privacy\":0,\"plcmtcnt\":1,\"assets\":[{\"required\":1,\"title\":{\"len\":140},\"id\":1},{\"required\":1,\"img\":{\"wmin\":150,\"type\":3,\"hmin\":150},\"id\":2},{\"required\":0,\"data\":{\"len\":140,\"type\":2},\"id\":5},{\"required\":0,\"data\":{\"len\":10,\"type\":3},\"id\":6},{\"required\":0,\"data\":{\"len\":20,\"type\":4},\"id\":7},{\"required\":0,\"data\":{\"len\":20,\"type\":6},\"id\":8},{\"required\":0,\"data\":{\"len\":50,\"type\":11},\"id\":9},{\"required\":0,\"data\":{\"len\":15,\"type\":12},\"id\":10},{\"required\":0,\"img\":{\"wmin\":50,\"type\":1,\"hmin\":50},\"id\":11}],\"eventtrackers\":[{\"methods\":[1],\"event\":1}]}}",
"ver": "1.2"
},
"secure": 1,
"tagid": "134783-166"
}
],
"regs": {
"coppa": 0,
"ext": {
"gdpr": 0,
"nroa": {
"mandatory": true,
"version": "2"
}
}
},
"source": {
"ext": {
"schain": {
"complete": 1,
"nodes": [
{
"asi": "yandex.com",
"hp": 1,
"sid": "2412782"
}
],
"ver": "1.0"
}
},
"fd": 0,
"sourcetype": 3,
"tid": ""
},
"tmax": 500,
"user": {
"ext": {
"consent": ""
},
"id": "90994348844570239403757"
}
}
Sample request for a video ad
{
"app": {
"bundle": "com.app.name.gp",
"cat": [
"IAB9-30"
],
"id": "123456",
"name": "Cookingdom",
"publisher": {
"id": "654431",
"name": "ABI GLOBAL LTD."
},
"content": {
"language": "ru"
},
"ver": "1.0.0"
},
"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,
"skadn": {
"version": "2.0",
"versions": ["2.0", "2.1", "3.0"],
"sourceapp": "880047117",
"skadnetids": [
"dticjx1a9i.skadnetwork",
"8srfag4vvc.skadnetwork"
],
"fidelities": [
0,
1
]
}
},
"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": 2,
"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"
}
}
}