ironSource Ads Instances API

Use this API to manage your instances for the ironSource Ads network on external mediations.

The API supports the following: Get, Create, Update and Delete

Requests are limited to 1 application per call.

Note: Bidding instances are supported on GET method only

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
appKey	String	application 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 Ads	2432228
instanceName	The instance name	isAndroid_RV
adUnit	rewardedVideo, interstitial, banner, or native	banner
isLive	Boolean value if the instance is live or not	true
isBidder	the instance a bidder instance (true or false)	true
isOptimized	Optional – Boolean value if the instance has optimized pricing	false
isInTestMode	Campaigns are delivering to your app but not generating revenue	false
globalPricing	Optional – the value of the global CPM pricing	1.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-2.	US
eCPM	The eCPM value for the specific country	100

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.

Note:

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	String	application 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	String	The newly created instance name, Length should be between 1 to 32 characters.	✓	–	instance 1
adUnit	String	“rewardedVideo”, “interstitial”, “banner”	✓	–	rewardedVideo
isLive	Boolean	Indicates if the instance is live or not	✓	–	true
isOptimized	Boolean	Indicates whether the instance is optimized or not	X	true	false
globalPricing	Number	Setting a global CPM value for the instance	x	–	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	Number	The 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

Note:

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	String	application 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	Number	instance ID as sent in the GET request	✓	–	12345
adUnit	String	rewardedVideo/interstitial/banner	✓	–	banner
instanceName	String	The newly updated instance name Length should be in range 1 to 32.	x	–	updatedInstance
isLive	Boolean	Indication rather the instance is live or not	x	–	true
isOptimized	Boolean	Indication rather the instance pricing is optimized	x	–	true
globalPricing	Number	updating global CPM value for the instance, send null to reset	x	–	10
countriesPricing	Array	List 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	Number	The 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.

Notes:

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	String	application 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	Number	Instance 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
}