ironSource Ads Instances API

Manage and configure your ironSource ad instances programmatically using the Instances API for greater flexibility and automation.

Read time 10 minutes

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
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
Maintenance mode

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

Authentication type
Authentication type

Bearer API authentication

GET
GET

Description
Description

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

Method
Method

GET

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

Request parameters
Request parameters

NameTypeDescriptionExample
appKeyStringapplication key (as seen on the platform)142401ac1

Request example URL
Request example URL

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

Response parameters
Response parameters

NameDescriptionExample
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
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
CREATE

Description
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
Method

POST

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

Request parameters
Request parameters

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

Request example URL
Request example URL

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

Supported parameters
Supported parameters

NameTypeDescriptionMandatory parameterDefault valueExample
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
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
Success

A successful response will be sent with HTTP code 200.

UPDATE
UPDATE

Description
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
Method

PUT

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

Request parameters
Request parameters

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

Request example URL
Request example URL

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

Supported parameters
Supported parameters

NameTypeDescriptionMandatory parameterDefault valueExample
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
Request example

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

Success
Success

A successful response will be sent with HTTP code 200.

DELETE
DELETE

Description
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
Method

DELETE

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

Request parameters
Request parameters

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

Request example URL
Request example URL

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

Supported parameters
Supported parameters

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

Request body example
Request body example

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

Success
Success

A successful response will be sent with HTTP code 200.

Errors
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
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
}