Documentation

Support

ironSource Ads

Monetization

User Acquisition

Get started as a DSP partner

ironSource Ads

ironSource Ads Instances API

Manage and configure your ironSource ad instances programmatically using the Instances API for greater flexibility and automation.
Read time 5 minutesLast updated 4 hours ago
Use this API to manage your instances for the ironSource Ads network on external mediations. The API supports the following actions: Get, Create, Update, and Delete. Requests are limited to one application per call.

Rate limits

The API returns a 429 HTTP status code if a request exceeds 8000 requests in a time period of 30 minutes.

Maintenance mode

If the API is under maintenance, it will return 503 HTTP status code with an error message.

Authentication type

Bearer API authentication

GET

Description

Get a list of your application's ironSource traditional instances.

Method

GET 
https://platform.ironsrc.com/ads/instances/v1

Request parameters

Name

Type

Description

Example

appKeyStringapplication key (as seen on the platform)142401ac1

Request example URL

https://platform.ironsrc.com/ads/instances/v1/142401ac1/

Response parameters

Name

Description

Example

instanceId
Unique instance ID generated by ironSource Ads2432228
instanceName
The instance nameisAndroid RV
adUnit
rewardedVideo, interstitial, banner, or nativebanner
isLive
Boolean value if the instance is live or nottrue
isBidder
the instance a bidder instance (true or false)true
isOptimized
Optional - Boolean value if the instance has optimized pricingfalse
isInTestMode
Campaigns are delivering to your app but not generating revenuefalse
globalPricing
Optional - the value of the global CPM pricing1.3
countriesPricing
Optional - list of countries and their eCPM value (see below)
These are the following countries pricing fields in the 
countriesPricing
array
country
Country code which is defined by a 2 letter country code, as per ISO 3166-1 Alpha-2US
eCPM
The eCPM value for the specific country100

Response example

[
  {
    	"instanceId": 0,
    	"instanceName": "Default",
    	"adUnit": "rewardedVideo",
    	"isLive": false,
    	"isOptimized": true,
    	"isInTestMode": false
  },
  {
    	"instanceId": 123456
    	"instanceName": "instance1",
    	"adUnit": "rewardedVideo",
    	"isLive": true,
    	"isOptimized": false,
      "isInTestMode": false,
    	
    	"globalPricing": 10,
    	"countriesPricing": [
	{
		"country": "US",
		"eCPM": 20
	},
	{
		"country": "CN",
		"eCPM": 20
	},	{
		"country": "AU",
		"eCPM": 30
	}
]
  }
]

CREATE

Description

Use this API to create traditional ironSource instances You can create multiple instances with a single API call.
  • This API allows you to create multiple instances with a single API call.
  • The instance Id value is reachable using Get call to this API

Method

POST 
https://platform.ironsrc.com/ads/instances/v1

Request parameters

Name

Type

Description

Example

appKey
Stringapplication key (as seen on the platform)142401ac1

Request example URL

https://platform.ironsrc.com/ads/instances/v1/142401ac1/

Supported parameters

Name

Type

Description

Mandatory parameter

Default value

Example

instanceName
StringThe newly created instance name, Length should be between  1 to 32 characters.✓-instance 1
adUnit
String“rewardedVideo”, “interstitial”, “banner”✓-rewardedVideo
isLive
BooleanIndicates if the instance is live or not✓-true
isOptimized
BooleanIndicates whether the instance is optimized or notXtruefalse
globalPricing
NumberSetting a global CPM value for the instancex-15
countriesPricing
Array An array of countries and their CPM value (see below)x-
These are the following countries pricing fields in the ‘countriesPricing’ array
country
String
Country code. which is defined by a 2 letter country code  as per ISO 3166-1 Alpha-2.
✓-AU
eCPM
NumberThe eCPM value for the related country✓-2.4

Request example

[
  {
    	"instanceName": "instance1",
    	"adUnit": "rewardedVideo",
    	"isLive": false
  },
  {
    	"instanceName": "instance2",
    	"adUnit": "interstitial",
    	"isLive": true,
    	"isOptimized": false,
    	"globalPricing": 10,
    	"countriesPricing": [
	{
		"country": "US",
		"eCPM": 20
	},
	{
		"country": "CN",
		"eCPM": 20
	},	{
		"country": "AU",
		"eCPM": 30
	}
]
  }
]

Success

A successful response will be sent with HTTP code 200.

UPDATE

Description

Use this API to update ironSource instances
  • Multiple instances can be updated with a single API call
  • To remove the globalPricing, simply enter 
    null
    into the field parameter To remove the countriesPricing, simply add the field parameter with 
    empty array
    value.

Method

PUT 
https://platform.ironsrc.com/ads/instances/v1

Request parameters

Name

Type

Description

Example

appKey
Stringapplication key (as seen on the platform)142401ac1

Request example URL

https://platform.ironsrc.com/ads/instances/v1/142401ac1/

Supported parameters

Name

Type

Description

Mandatory parameter

Default value

Example

instanceId
Numberinstance ID as sent in the GET request✓-12345
adUnit
StringrewardedVideo/interstitial/banner✓-banner
instanceName
StringThe newly updated instance name. Length should be in range 1 to 32.x-updatedInstance
isLive
BooleanIndication rather the instance is live or notx-true
isOptimized
BooleanIndication rather the instance pricing is optimizedx-true
globalPricing
Numberupdating global CPM value for the instance, send null to resetx-10
countriesPricing
ArrayList of countries pricing to update - send empty array to reset (see below)x-
These are the following countries pricing fields in the 
countriesPricing
array
country
string
Country code which is defined by a 2 letter country code  as per ISO 3166-1 Alpha-2.
✓-AU
eCPM
NumberThe eCPM value for the related country✓-2.5

Request example

[
  {
	"instanceId": 0,
    	"adUnit": "rewardedVideo",
    	"instanceName": "instance1_update",
    	"isLive": true
  },
  {
	"instanceId": 12345
    	"instanceName": "instance2_update",
    	"adUnit": "interstitial",
    	"isLive": false,
    	"globalPricing": 100,
    	"countriesPricing": []
  }
]

Success

A successful response will be sent with HTTP code 200.

DELETE

Description

Use this API to delete ironSource instances.
  • Multiple instances can be deleted with a single API call
  • The default instances cannot be deleted
  • Deleted instances cannot be restored

Method

DELETE 
https://platform.ironsrc.com/ads/instances/v1

Request parameters

Name

Type

Description

Example

appKey
Stringapplication key (as seen on the platform)142401ac1

Request example URL

https://platform.ironsrc.com/ads/instances/v1/142401ac1/

Supported parameters

Name

Type

Description

Mandatory parameter

Default value

Example

instanceId
NumberInstance IDs as sent in the GET request✓-12473

Request body example

[
  {
      "instanceId": 1458
  },
  {
      "instanceId": 123654
  },
]

Success

A successful response will be sent with HTTP code 200.

Errors

If one of the instances sent in the request is failing, an error array will be sent with HTTP code 400 and will cause the whole request to be rejected. Each error will be followed with an error message.

Example

{
    "errorsArray": [
        {
            "code": "ERR-3201",
            "errorMessage": "Instance name is required",
            "params": {
                "[0].instancename": ""
            }
        },
        {
            "code": "ERR-3328",
            "errorMessage": "countriesPricing country is invalid",
            "params": {
                "[0].countriesPricing[0].country": ""
            }
        }
    ],
    "code": 400
}