ironSource Exchange OpenRTB 2.5 specs

Follow the OpenRTB 2.5 specifications to connect your DSP or ad platform with the ironSource Exchange for programmatic ad buying.

Read time 11 minutes

Last updated 4 hours ago

The following article specifies the objects and parameters that are supported by ironSource Exchange, ensure that 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 (for example, 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 (for example, 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 (for example, 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 when 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.header bidding`	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 (for example, "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 (for example, 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

Examples of bid requests and 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"
}

ironSource Exchange OpenRTB 2.5 specs

Bid request

Request object

Parameter

Type

Always passed

Description

Impression object

Parameter

Type

Always passed

Description

Video object

Parameter

Type

Always passed

Description

Banner object

Parameter

Type

Always passed

Description

Format object

Parameter

Type

Always passed

Description

App object

Parameter

Type

Always passed

Description

Device object

Parameter

Type

Always passed

Description

User object

Parameter

Type

Always passed

Description

Source object

Parameter

Type

Always passed

Description

Regs object

Parameter

Type

Always passed

Description

Geo object

Parameter

Type

Always passed

Description

Bid response

Bid response object

Parameter

Type

Requirement

Description

Seat bid object

Parameter

Type

Requirement

Description

Bid object

Parameter

Type

Requirement

Description

No bid response

Value

Description

Examples of bid requests and responses

Video bid request

Display bid request

Footer bid request