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
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 ${AUCTION_PRICE} macro, to indicate the clearing price of the winning bidder.

Available only for Banners ad unit

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”: {}

}

{

   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”

}

{

   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”

}