ironSource Exchange OpenRTB 2.5 specs
The article below specifies the objects and parameters that are supported by ironSource Exchange, please ensure you have the OpenRTB 2.5 Specification Guide available while reviewing the spec.
Bid Request
Request Object
| Parameter | Type | Always passed | Description |
| id | String | Yes | Unique id of the bid request. This id must be returned in the bid response object. |
| imp | Object | Yes | ironSource supports one impression object per bid request. See Impression. |
| at | integer | Yes | The auction type used. ironSource supports first price auction only. |
| app | Object | Yes | App description. See App. |
| device | Object | Yes | Device description. See Device. |
| user | Object | Yes | User description. See User. |
| tmax | integer | Yes | Maximum time in milliseconds ironSource allows for bids to be received. |
| bcat | String array | Yes | Blocked advertiser categories using the IAB content categories. |
| badv | String array | No | Block list of advertisers by their domains |
| bapp | String array | No | Block list of applications. On Android, these should be bundle or package names (e.g., com.foo.mygame). On iOS, these are numeric IDs. |
| source | Object | Yes | A Source object that provides data about the inventory source and which entity makes the final decision. |
| regs | Object | Yes | A Regs object that specifies any industry, legal, or governmental regulations in force for this request. |
| ext | Object | No | Placeholder for ironSource specific extensions to OpenRTB. |
Impression Object
| Parameter | Type | Always passed | Description |
| id | String | Yes | ironSource supports a single impression object per Bid Request. |
| video | Object | For Video only | The object is used to describe a video impression. See video. |
| banner | Object | For Display only | The object is used to describe a display impression. See banner. |
| instl | integer | No | 1 = the ad is interstitial or full screen, 0 = not interstitial. |
| secure | integer | Yes | ironSource requires the impression to have secure HTTPS URL creative assets and markup. |
| pmp | Object | Yes | A Pmp object containing any private marketplace deals in effect for this impression |
| bidfloor | Float | Yes | Minimum bid for this impression expressed in CPM. |
| bidfloorcur | String | Yes | ironSource accepts USD only |
| ext | Object | No | Placeholder for ironSource specific extensions to OpenRTB. |
Video Object
| Parameter | Type | Always passed | Description |
| mimes | String array | Yes | Content mime types supported. |
| minduration | integer | Yes | Minimum video ad duration in seconds. |
| maxduration | integer | Yes | Maximum video ad duration in seconds. |
| protocols | integer array | Yes | Array of supported video protocols |
| w | integer | Yes | Width of the video player in device independent pixels (DIPS). |
| h | integer | Yes | Height of the video player in device independent pixels (DIPS). |
| placement | integer | Yes | Placement type for the impression. |
| Skip | integer | Yes | Indicates if the player will allow the video to be skipped or not. |
| battr | integer array | Yes | Blocked creative attributes. |
| playbackmethod | integer | Yes | Playback methods that may be in use. |
| pos | integer | Yes | Ad position on screen. |
| api | integer array | Yes | List of supported API frameworks for this impression |
| ext.rewarded | integer | Yes | Indicates whether the request is for a rewarded video ad unit. 1 = yes, 0 = no |
Banner Object
| Parameter | Type | Always passed | Description |
| w | integer | Yes | Width of the video player in device independent pixels (DIPS). |
| h | integer | Yes | Height of the video player in device independent pixels (DIPS). |
| pos | integer | Yes | Ad position on screen. |
| btype | integer array | Yes | Blocked banner ad types. |
| battr | integer array | Yes | Blocked creative attributes. |
| api | integer array | Yes | List of supported API frameworks for this impression |
Format Object
Used when multiple sizes are permitted.
| Parameter | Type | Always passed | Description |
| w | integer | Yes | Width of the video player in device independent pixels (DIPS). |
| h | integer | Yes | Height of the video player in device independent pixels (DIPS). |
App Object
| Parameter | Type | Always passed | Description |
| id | String | Yes | ironSource specific application id |
| bundle | String | Yes | A platform-specific application identifier. On Android, this should be a bundle or package name (e.g., com.foo.mygame). On iOS, it is typically a numeric ID. |
| name | String | Yes | Application name |
| storeurl | String | Yes | App Store URL |
| cat | String array | Yes | IAB content categories of the app |
Device Object
| Parameter | Type | Always passed | Description |
| ua | String | Yes | Browser user agent string. |
| geo | Object | Yes | Location of the device assumed to be the user’s current location defined by a Geo object/ |
| lmt | integer | Yes | “Limit Ad Tracking” signal, where 0 = tracking is unrestricted, 1 = tracking must be limited per commercial guidelines. |
| ip | String | Yes | IPv4 address closest to device. |
| devicetype | integer | Yes | The general type of device. |
| make | String | Yes | Device make. |
| model | String | Yes | Device model. |
| os | String | Yes | Operation system |
| osv | String | Yes | Operation system version |
| language | String | Yes | language string Browser language using ISO-639-1-alpha-2. |
| connectiontype | integer | Yes | Network connection type |
| ifa | String | Yes | ID sanctioned for advertiser use in the clear (i.e., not hashed) |
| ext.ifv | String | Yes | (iOS Only) The Identifier for Vendors assigned to all apps by one developer. Listed as ifv to match ifa field format. |
| ext.atts | integer | Yes | (iOS Only) represent the app’s app tracking authorization status, where 0 = not determined 1 = restricted 2 = denied 3 = authorized |
User Object
| Parameter | Type | Always passed | Description |
| id | String | Yes | ironSource-specific ID for the user |
| ext.impdepth | Float | Yes | An impression count for specific placement in a given app session. The impression depth is reset once the session ends. |
Source Object
| Parameter | Type | Always passed | Description |
| ext.schain | Object | Yes | Schain object containing sellers.json information |
| ext.schain.nodes | Object array | Yes | Publisher’s Application sellers.json information |
| ext.headerBidding | Integer | Yes | Indicates the waterfall’s type, where 1=Bidding, 0=Instances |
Regs Object
| Parameter | Type | Always passed | Description |
| ext.gdpr | String | Yes | Specifies if the request is subject to GDPR regulations. |
Geo Object
| Parameter | Type | Always passed | Description |
| lat | Float | Yes | Latitude from -90.0 to +90.0, where negative is south. |
| lon | Float | Yes | Longitude from -180.0 to +180.0, where negative is west. |
| type | Integer | Yes | Source of location data |
| ipservice | Integer | Yes | Service or provider used to determine geolocation from IP address if applicable |
| country | String | Yes | Country code using ISO-Country code using ISO-3166-1-alpha-3.3166-1-alpha-3.-3 |
| region | String | Yes | Region code using ISO-3166-2; 2-letter state code if USA. |
| metro | String | Yes | Google metro code. |
| city | String | Yes | City using United Nations Code for Trade & Transport Locations. |
| zip | String | Yes | zip string Zip or postal code. |
Bid Response
Bid Response Object
| Parameter | Type | Requirement | Description |
| id | String | Required | ironSource request id must be passed back on the Bid Response. |
| cur | String | Required | ironSource supports USD only; any other ISO currency code will result in the bid response being ignored. |
| bidid | String | Recommended | Bidder generated response ID to assist with logging/tracking. |
| nbr | Integer | Recommended | Reason for not bidding. Refer to List 5.22 in OpenRTB 2.3 Spec. |
| seatbid | Object array | Recommended | Multiple seatbid objects are allowed in a response, however, ironSource currently only uses one seatbid object. The seatbid object chosen will contain:bid.id = impression.id |
Seat Bid Object
| Parameter | Type | Requirement | Description |
| bid | Object array | Required | ironSource expected at least one bid. |
Bid Object
| Parameter | Type | Requirement | Description |
| id | String | Required | Bidder generated bid ID to assist with logging/tracking. |
| impid | String | Recommended | ID of the impression to which this bid applies. This value will match the impression id provided in the bid request. |
| price | Float | Required | Bid price in CPM. A value that is equal to, or less than zero will be ignored. |
| nurl | String | Recommended | Win notice URL called by ironSource when the bid wins the auction (not necessarily indicative of a delivered, viewed, or billable ad). When burl isn’t present, the nurl will replace it, and report Billing notice. |
| burl | String | Required | Billing notice URL called by ironSource when a winning bid becomes billable. |
| lurl | String | Recommended | Loss notice URL called by ironSource when a bid is known to have been lost. ironSource supports the ${MIN_BID_TO_WIN} macro, to indicate the minimum bid required to win the final auction. |
| cid | String | Recommended | Campaign ID to assist with ad quality checking. |
| crid | String | Recommended | Creative ID to assist with ad quality checking. |
| adm | String | Required | Required means of conveying ad markup in case the bid wins. |
| adomain | String array | Required (if bid.bundle=null) | Advertiser domain for blacklist checking |
| bundle | String | Required (if bid.adomain=null) | A platform-specific application identifier. On Android, this should be a bundle or package name (e.g., com.foo.mygame). On iOS, it is typically a numeric ID. |
| cat | String array | Recommended | IAB content categories of the creative. |
| attr | Integer array | Recommended | Set of attributes describing the creative. |
| w | Integer | Required | Width of the creative in device independent pixels (DIPS). |
| h | Integer | Required | Height of the creative in device independent pixels (DIPS). |
No Bid Response
Bidders can respond with any of the following that will be considered a ‘no bid” within ironSource. It is important to use any of the following responses to explicitly signal you do not want to bid on the impression, otherwise the response may be interpreted as a timeout error.
No bid (e.g. no demand, no interest in buying the impression):
- HTTP 204 No Content
- An empty JSON object: “{}”
- A well-formed no bid response (NBR): {“id”: “1234567890”, “seatbid”: []} No bid due to an issue
- A well-formed no bid response: {“id”: “1234567890”, “seatbid”: [], “nbr”: 2}
- The list of issue code that can be used for nbr can be found below:
| Value | Description |
| 0 | Unknown Error |
| 1 | Technical Error |
| 2 | Invalid Request |
| 3 | Known web spider |
| 4 | Suspected non-human traffic |
| 5 | Cload, Data Center, or proxy IP |
| 6 | Unsupported device |
| 7 | Blocked publisher |
| 8 | Unmatched user |
Samples Bid Requests & Responses
Video Bid Request
{
id: “1627786837177779624_a5850b20-f274-11eb-947b-0ded24f22667_237775956_client_name”,
imp: [
{
id: “1”,
video: {
mimes: [
“video/mp4”,
“video/3gpp”,
“application/x-mpegURL”
],
minduration: 1,
maxduration: 120,
protocols: [
2,
5,
3,
6
],
w: 480,
h: 320,
placement: 5,
skip: 0,
playbackmethod: [
5
],
pos: 7,
api: [
7
],
companiontype: [
1,
2
],
ext: {
rewarded: 1
}
},
pmp: {
deals: [
{
id: “104v4ahb53bb5800016dqa9a”,
bidfloor: 8,
bidfloorcur: “USD”
}
]
},
displaymanager: “ironsource”,
bidfloor: 8,
bidfloorcur: “USD”,
secure: 1
}
],
app: {
id: “113551”,
name: “Jetpack Joyride”,
bundle: “457446957”,
storeurl: “https://itunes.apple.com/app/id457446957”,
cat: [
“IAB9”
],
publisher: {
id: “146249”,
name: “Halfbrick Studios Pty Ltd”
}
},
device: {
ua: “Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148”,
geo: {
lat: 41.7405,
lon: -87.6587,
type: 2,
ipservice: 3,
country: “USA”,
region: “IL”,
metro: “602”,
city: “Chicago”,
zip: “60620”
},
lmt: 0,
ip: “74.93.69.246”,
devicetype: 4,
make: “Apple”,
model: “iPhone13,2”,
os: “ios”,
osv: “14.7.1”,
language: “es”,
connectiontype: 2,
ifa: “01234567-89ABCDEF-01234567-89ABCDEF”,
ext: {
acceptLang: “es-xl”,
atts: 3
}
},
user: {
id: “01234567-89ABCDEF-01234567-89ABCDEF”
},
at: 1,
tmax: 996,
bcat: [
“IAB23”,
“IAB25”,
“IAB26”,
“IAB8-18”,
“IAB8-5”,
“IAB9-9”,
“IAB11-4”,
“IAB14-1”,
“IAB14-3”,
“IAB17-16”,
“IAB9-7”,
“IAB7-39”,
“IAB3-7”,
“IAB18-5”
],
badv: [
“bigo.tv”
],
source: {
ext: {
omidpn: “Ironsrc”,
omidpv: “7”,
schain: {
ver: “1.0”,
complete: 1,
nodes: [
{
asi: “ironsrc.com”,
sid: “146249”,
hp: 1,
rid: “1627786837177779624_a5850b20-f274-11eb-947b-0ded24f22667_237775956_client_name”,
name: “Halfbrick Studios Pty Ltd”,
domain: “halfbrick.com”
}
]
}
}
},
“regs”: {}
}
Display Bid Request
{
id: “1627791578182182085_af5e8df0-f27f-11eb-9a60-f72fd6932f89_1452093813_client_name_b”,
imp: [
{
id: “1”,
banner: {
w: 320,
h: 480,
btype: [
1,
4
],
battr: [
3,
6,
7,
8,
9,
14,
10
],
pos: 7,
api: [
5,
3,
7
]
},
displaymanager: “ironsource”,
instl: 1,
bidfloor: 1.6,
bidfloorcur: “USD”,
secure: 1
}
],
app: {
id: “318613”,
name: “Subway Surfers (non-COPPA)”,
bundle: “com.kiloo.subwaysurf”,
storeurl: “https://play.google.com/store/apps/details?id=com.kiloo.subwaysurf”,
cat: [
“IAB9”
],
publisher: {
id: “235297”,
name: “SYBO Games”
}
},
device: {
ua: “Mozilla/5.0 (Linux; Android 6.0.1; SM-G532M Build/MMB29T; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/92.0.4515.115 Mobile Safari/537.36”,
geo: {
lat: 19.3617,
lon: -98.2338,
type: 2,
ipservice: 3,
country: “MEX”,
region: “TLA”,
metro: “0”,
city: “Tlaxcala City”,
zip: “90000”
},
lmt: 0,
ip: “189.167.5.112”,
devicetype: 4,
make: “samsung”,
model: “SM-G532M”,
os: “android”,
osv: “6.0.1”,
js: 1,
language: “es”,
connectiontype: 2,
ifa: “01234567-89ABCDEF-01234567-89ABCDEF”
},
user: {
id: “01234567-89ABCDEF-01234567-89ABCDEF”
},
at: 1,
tmax: 998,
bcat: [
“IAB23”,
“IAB25”,
“IAB26”,
“IAB8-18”,
“IAB8-5”,
“IAB9-9”,
“IAB11-4”,
“IAB14-1”,
“IAB14-3”,
“IAB17-16”,
“IAB9-7”,
“IAB7-39”,
“IAB3-7”,
“IAB18-5”
],
badv: [
“caliente.mx”,
“yoox.com”,
“wine.com.br”
],
source: {
ext: {
omidpn: “Ironsrc”,
omidpv: “7”,
schain: {
ver: “1.0”,
complete: 1,
nodes: [
{
asi: “ironsrc.com”,
sid: “235297”,
hp: 1,
rid: “1627791578182182085_af5e8df0-f27f-11eb-9a60-f72fd6932f89_1452093813_client_name_b”,
name: “SYBO Games”,
domain: “sybogames.com”
}
]
}
}
},
“regs”: {}
}
Footer Bid Request
{
id: “1627783392367073418_a03b6950-f26c-11eb-a9af-31ac778e44a2_1539835153_client_name”,
imp: [
{
id: “1”,
banner: {
format: [
{
w: 320,
h: 50
},
{
w: 300,
h: 50
}
],
w: 320,
h: 50,
pos: 5,
api: [
5,
3
]
},
displaymanager: “ironsource”,
tagid: “2708683”,
bidfloor: 0.0128,
bidfloorcur: “USD”,
secure: 1
}
],
app: {
id: “353553”,
name: “Tile Connect – Classic Match Game”,
bundle: “1529839083”,
storeurl: “https://itunes.apple.com/app/id1529839083”,
cat: [
“IAB9”
],
publisher: {
id: “249491”,
name: “HIGGS TECHNOLOGY CO.,LIMITED”
}
},
device: {
ua: “Mozilla/5.0 (iPhone; CPU iPhone OS 14_6 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148”,
geo: {
lat: 39.9357,
lon: -75.1832,
type: 2,
ipservice: 3,
country: “USA”,
region: “PA”,
metro: “504”,
city: “Philadelphia”,
zip: “19146”
},
lmt: 0,
ip: “76.98.251.72”,
devicetype: 4,
make: “Apple”,
model: “iPhone9,2”,
os: “ios”,
osv: “14.6.0”,
language: “en”,
connectiontype: 2,
ifa: “01234567-89ABCDEF-01234567-89ABCDEF”,
ext: {
acceptLang: “en-us”,
atts: 3
}
},
user: {
id: “01234567-89ABCDEF-01234567-89ABCDEF”
},
at: 1,
tmax: 996,
bcat: [
“IAB23”,
“IAB25”,
“IAB26”,
“IAB8-18”,
“IAB8-5”,
“IAB9-9”,
“IAB11-4”,
“IAB14-1”,
“IAB14-3”,
“IAB17-16”,
“IAB9-7”,
“IAB7-39”,
“IAB3-7”,
“IAB18-5”
],
badv: [
“gratonresortcasino.com”
],
source: {
ext: {
schain: {
ver: “1.0”,
complete: 1,
nodes: [
{
asi: “ironsrc.com”,
sid: “249491”,
hp: 1,
rid: “1627783392367073418_a03b6950-f26c-11eb-a9af-31ac778e44a2_1539835153_client_name”,
name: “HIGGS TECHNOLOGY CO.,LIMITED”,
domain: “higgsgamestudio.com”
}
]
}
}
},
“regs”: {}
}
Vast Bid Response
{
id: “1543190416705343377_ip-172-31-13-147_41965ed0-f10e-11e8-b7cd-fd40aa7b8b5f”,
seatbid: [
{
bid: [
{
id: “opp_100”,
impid: “opp_100”,
price: 15,
adm: “VAST_XML”,
adomain: [
“AD_DOMAIN”
],
cid: “6b3gxrn”,
crid: “aqgwb3x7”
}
],
seat: “2821”
}
],
cur: “USD”
}
Display Interstitial Bid Response
{
id: “1543190412223390473_ip-172-31-13-147_3eea9fc0-f10e-11e8-9915-1beb61037050”,
seatbid: [
{
bid: [
{
id: “46-45347979-4f8b-4547-8376-2cea2c3ac12a-1”,
impid: “opp_100”,
price: 9.9906,
nurl: “NURL_PIXEL”,
adm: “CREATIVE”,
adomain: [
“”
],
cid: “143354”,
crid: “46_10304614”,
dealid: “20135c3f564b7bd7dd138a480427a69f”,
w: 320,
h: 480,
ext: {
agency_name: “NAME”
}
}
],
seat: “6”
}
],
cur: “USD”
}
Footer Bid Response
{
id: “1617285225335329365_ad0f3240-92f1-11eb-9667-c36f23277c0b_client-banner”,
seatbid: [
{
bid: [
{
id: “b0f43c8b-d009-4cb2-adb5-1c2782400b35”,
impid: “opp_100”,
price: 0.51,
nurl: “NURL_PIXEL”,
burl: “BURL_PIXEL”,
adm: “CREATIVE_ADM”,
adomain: [
“”
],
crid: “123456789”,
w: 320,
h: 50
}
]
}
],
cur: “USD”
}