Instance
Use this API to get, set, update and delete instances on ironSource’s dashboard.
Before you start make sure you go over our API introduction article.
Get Instances
Description
Use this API to retrieve a list of all of your application’s instances. The response will include all information from the Applications List API, as well as the following: instance name, instance ID, status, and pricing if relevant (pricing is only available for ironSource network instances)
Authentication Type
Bearer API authentication
Method
GET platform.ironsrc.com/partners/publisher/instances/v1?
Required Parameters
Name | Type | Description |
appKey | String | Application Key (as seen on our platform) |
Request Example URL
https://platform.ironsrc.com/partners/publisher/instances/v1?appKey=6e9e4c111
Response Parameters
Name | Description |
ID | unique instance ID generated by ironSource platform on instance creation |
name | instance name |
status | instance status can be active or inactive |
pricing | pricing as set on the platform |
JSON Example Response
{
"appKey": "6e9e4c111",
"adUnits": {
"rewardedVideo": {
"ironSourceNetworkStatus": "active",
"activeNetworks": [
"ironSource"
],
"networkInstances": {
"ironSource": [
{
"id": 0,
"name": "Default",
"status": "active"
},
{
"id": 12345,
"name": "secondRVInstance",
"status": "active"
},
{
"id": 45678,
"name": "thirdRVInstance",
"status": "inactive"
}
]
}
},
"offerWall": {
"ironSourceNetworkStatus": "test",
"activeNetworks": [
"ironSource"
]
},
"interstitial": {
"ironSourceNetworkStatus": "active",
"activeNetworks": [
"ironSource"
],
"networkInstances": {
"ironSource": [
{
"id": 0,
"name": "Default",
"status": "active"
},
{
"id": 23456,
"name": "secondISInstance",
"status": "active",
"pricing": [
{
"eCPM": "0.01",
"Countries": [
"FR",
"UK"
]
}
]
}
]
}
},
"banner": {
"ironSourceNetworkStatus": "active",
"activeNetworks": [
"ironSource"
],
"networkInstances": {
"ironSource": [
{
"id": 0,
"name": "Default",
"status": "active"
}
]
}
}
}
}
Create Instances
Description
Use this API to create ironSource’s instances. This API allows you to create multiple instances with a single API call.
Notes:
- To use the Create instance API Contact Us or reach out to your Account Manager
- Instances created without a ‘status’ parameter set will be automatically set according to the default instance’s status.
- For Mediation users – each newly created instance will be included in all of the app’s mediation groups.
- An app is limited up to 3 instances per ad unit. In order to extend this limitation Contact Us or reach out to your Account Manager.
CPM pricing:
General –
- CPM Pricing allows you the control and flexibility to define expected CPM rates from ironSource’s network. Read more here.
- CPM pricing is available for specific accounts only, to activate CPM pricing Contact Us or reach out to your Account Manager.
- For best practices of using instances with pricing go to our Best Practices article.
Notes –
- In order to set global pricing for an instance, populate the instance’s country field with asterisk character ‘*’.
- Instances created without pricing and specific countries without defined pricing will be set to use optimized pricing.
- Countries are defined based on 2 letter country code, as per ISO 3166-1 Alpha-2.
Authentication Type
Bearer API authentication
Method
POST platform.ironsrc.com/partners/publisher/instances/v1?
Required Parameters
Name | Type | Description |
appKey | String | Application Key (as seen on our platform) |
provider | String | at the moment only ‘ironSource’ is enabled |
adUnit | String | “rewardedVideo”, “interstitial”, “banner” |
instanceName | String | The newly created instance’s name |
Optional Parameters
Name | Type | Description |
status | String | instance status can be ‘active’ or ‘inactive’ |
pricing | String | determine the eCPM to be delivered by ironSource network |
Request Example URL
https://platform.ironsrc.com/partners/publisher/instances/v1?
Request Example Body
{ "appKey": "6e9e4c11", "configurations": { "ironSource": { "rewardedVideo": [ { "instanceName": "thirdRVInstance", "status": "active", "pricing": "optimized" } ] } } }
JSON Example Response
{ "rewardedVideo": { "ironSource": [ { "id": 0, "name": "Default", "status": "active" }, { "id": 12345, "name": "secondRVInstance", "status": "active" }, { "id": 45678, "name": "thirdRVInstance", "status": "inactive" } ] }, "interstitial": { "ironSource": [ { "id": 0, "name": "Default", "status": "active" }, { "id": 23456, "name": "secondISInstance", "status": "active", "pricing": [ { "eCPM": "2.5", "Countries": [ "FR", "UK" ] } ] } ] }, "banner": { "ironSource": [ { "id": 0, "name": "Default", "status": "inactive" } ] } }
Update Instances
Description
Use this API to update ironSource’s instance name, status and pricing. Multiple instances can be updated with a single API call.
Notes:
- To use the Update instance API Contact Us or reach out to your Account Manager
- Max number of update calls is limited to 6 per day.
- In order to activate ironSource’s non default instances you must first activate ironSource’s default instance (instance ID=0)
- Updating instance pricing will replace all of the instance’s old pricing set.
Authentication Type
Bearer API authentication
Method
PUT platform.ironsrc.com/partners/publisher/instances/v1?
Required Parameters
Name | Type | Description |
appKey | String | Application Key (as seen on our platform) |
provider | String | at the moment only ‘ironSource’ is enabled |
adUnit | String | “rewardedVideo”, “interstitial”, “banner” |
instanceId | String | Unique ID generated by ironSource platform on instance creation |
Optional Parameters
Name | Type | Description |
name | String | The desired instance’s name |
pricing | String | determine the eCPM to be delivered by ironSource network |
status | String | instance status can be ‘active’ or ‘inactive’ |
Request Example URL
https://platform.ironsrc.com/partners/publisher/instances/v1?
Request Body Example
{ "appKey": "6e9e4c11", "configurations": { "ironSource": { "rewardedVideo": [ { "instanceId": 45678, "status": "active", "pricing": [ { "eCPM": "0.01", "Countries": [ "FR", "UK" ] } ] } ] } } }
JSON Response Example
{ "rewardedVideo": { "ironSource": [ { "id": 0, "name": "Default", "status": "active" }, { "id": 12345, "name": "secondRVInstance", "status": "active" }, { "id": 45678, "name": "thirdRVInstance", "status": "inactive", "pricing": [ { "eCPM": "0.01", "Countries": [ "FR", "UK" ] } ] } ] }, "interstitial": { "ironSource": [ { "id": 0, "name": "Default", "status": "active" }, { "id": 23456, "name": "secondISInstance", "status": "active", "pricing": [ { "eCPM": "0.01", "Countries": [ "FR", "UK" ] } ] } ] }, "banner": { "ironSource": [ { "id": 0, "name": "Default", "status": "inactive" } ] } }
Delete Instance
Description
Use this API to delete an instance.
General notes:
- To use the Delete instance API Contact Us or reach out to your Account Manager
- Can delete one instance per call.
- Default instance cannot be deleted.
- Deleted instance cannot be restored.
- Response includes all of the app’s instances excluding the deleted ones.
Authentication Type
Bearer API authentication
Method
DELETE platform.ironsrc.com/partners/publisher/instances/v1?
Required Parameters
Name | Type | Description |
appKey | String | Application Key (as seen on our platform) |
instanceId | String | Unique ID generated by ironSource platform on instance creation |
Request Example URL
http://platform.ironsrc.com/partners/publisher/instances/v1?appKey=6e9e4c11&instanceId=12345
JSON Response Example
{ "rewardedVideo": { "ironSource": [ { "id": 0, "name": "Default", "status": "active" }, { "id": 45678, "name": "thirdRVInstance", "status": "inactive" } ] }, "interstitial": { "ironSource": [ { "id": 0, "name": "Default", "status": "active" }, { "id": 23456, "name": "secondISInstance", "status": "active", "pricing": [ { "eCPM": "0.01", "Countries": [ "FR", "UK" ] } ] } ] }, "banner": { "ironSource": [ { "id": 0, "name": "Default", "status": "inactive" } ] } }