Instance API v4
Use the Instance API to manage instances on the LevelPlay dashboard. This API version supports the following:
- Support for CRUD
- Changing ad networks’ application-level configurations
- Adding or removing instances from waterfall groups (Supporting active AB test applications)
Requests are limited to 1 application per call.
Rate limits
The API returns a 429 HTTP status code if a request exceeds 4000 requests in a time period of 30 minutes.
Authentication Type
GET
Description
Get a list of all the application instances, bidding and non bidding.
Method
GET https://platform.ironsrc.com/levelPlay/network/instances/v4/
Request Parameters
Name | Type | Description | Example |
appKey | String | application key (as seen on the platform) | 142401ac1 |
Request Example URL
https://platform.ironsrc.com/levelPlay/network/instances/v4/142401ac1/
Response Parameters
Name | Description | Example |
instanceId | Unique instance ID | 1072562 |
instanceName | The instance name | Rewarded50 |
adUnit | The ad unit type per instance (rewardedVideo, interstitial, or banner) | banner |
networkName | The ad network the instance belongs to | adColony |
appConfig1 / appConfig2 | For ad source app level configs naming convention refer to this section | |
instanceConfig1 / instanceConfig2 | For ad source naming conventions refer to this article. This should be sent for each config field | |
isBidder | the instance a bidder instance (true or false) | true |
groups | An array of group ids, as sent in the LevelPlay Groups API | [2515, 6226] |
isLive | Instance status can be active or inactive | ‘false’ |
rate | Instance level rate (if defined) | 15 |
Response Example
[
{
"instanceId": 1072562,
"instanceName": "Default",
"adUnit": "rewardedVideo",
"networkName": "adColony",
"appConfig1": "qtr",
"instanceConfig1": "trb",
"isBidder": true,
"groups": [
101663
],
"isLive": true,
"rate": 10
},
{
"instanceId": 1014428,
"instanceName": "Default",
"adUnit": "interstitial",
"networkName": "unity",
"appConfig1": "qertb",
"instanceConfig1": "qtrb",
"isBidder": false,
"groups": [
101663
],
"isLive": true,
"rate": 25
},
{
"instanceId": 1845809,
"instanceName": "Default",
"adUnit": "rewardedVideo",
"networkName": "adManager",
"appConfig1": "bqw",
"instanceConfig1": "qqr",
"isBidder": false,
"groups": [
101663
],
"isLive": true,
"rate": 4
}
]
CREATE
Description
Use this API to create instances for mediated ad sources. This API allows you to create multiple instances with a single API call. Keep in mind that when creating instances via the API, you are limited to the number of instances the platform allows.
Use the “groups” parameter to determine each waterfall group to include/exclude instance. The “groups” ID value is reachable using the Mediation API.
Note:
- Instances created without a ‘status’ parameter set will be automatically set as ‘active’
- Instances created for apps that are not live at the store will be automatically set as ‘inactive’
- To create instances for mediated ad networks, refer to this article for naming convention.
- Application configuration must have the same value for instances with the same ad network
- For custom network instance creation, ‘networkKey’ parameter is required, this can be found on the network documentation
Method
POST https://platform.ironsrc.com/levelPlay/network/instances/v4/
Request Parameters
Name | Type | Description | Example |
appKey | String | application key (as seen on the platform) | 142401ac1 |
Request Example URL
https://platform.ironsrc.com/levelPlay/network/instances/v4/142401ac1/
Supported Parameters
Name | Type | Description | Mandatory Parameter | Example |
instanceName | String | the newly created instance’s name | ✓ – For non-bidding instances | highestBidderinstance |
networkName | String | for ad source naming convention refer to this section | ✓ | adColony |
adUnit | String | “rewardedVideo”, “interstitial”, “banner” | ✓ | rewardedVideo / interstitial / banner |
isBidder | Boolean | Indicates if the instance is a bidder instance. | ✓ | True / False |
appConfig1 | String | ad source application level configs naming convention, refer to this section | x | ‘123’ / ‘abc’ |
appConfig2 | String | ad source application level configs naming convention, refer to this section | x | ‘123’ / ‘abc’ |
instanceConfig1 | String | For ad source instance level configs naming convention, refer to this section | x | ‘123’ / ‘abc’ |
instanceConfig2 | String | For ad source instance level configs naming convention, refer to this section | x | ‘123’ / ‘abc’ |
groups | Number Array | If not sent, regard as ‘all groups’. Notice: you should send groupIds for both ‘A’ & ‘B’ groups if you’re in the midst of an A/B test. | x | [12525] |
isLive | Boolean | Making the instance active or inactive. If not sent regard as active | x | True / False |
rate | Number | Between 1-2000 | x | 5 |
Request Example
[
{
"instanceName": "newInstance",
"networkName": "adColony",
"adUnit": "rewardedVideo",
"isBidder": true,
"appConfig1": "414n",
"instanceConfig1": "aaa1",
"instanceConfig2": "aaa1",
"groups": [12345],
"isLive": true,
"rate": 2
}
]
UPDATE
Description
Use this API to update instances. Multiple instances can be updated with a single API call.
Note:
To remove instance level rate, simply add the rate parameter with ‘null’ value.
Method
PUT https://platform.ironsrc.com/levelPlay/network/instances/v4/
Request Parameters
Name | Type | Description | Example |
appKey | String | application key (as seen on the platform) | 142401ac1 |
Request Example URL
https://platform.ironsrc.com/levelPlay/network/instances/v4/142401ac1/
Supported Parameters
Name | Type | Description | Mandatory Parameter | Example |
instanceId | Number | Instance Id as sent in the GET request | ✓ | |
instanceName | String | the newly created instance’s name | x | highestBidderinstance |
appConfig1 | String | x | ‘123’ / ‘abc’ | |
appConfig2 | String | x | ‘123’ / ‘abc’ | |
instanceConfig1 | String | for ad source instance level configs naming convention refer to this section | x | ‘123’ / ‘abc’ |
instanceConfig2 | String | for ad source instance level configs naming convention refer to this section | x | ‘123’ / ‘abc’ |
groups | Number Array | If not sent, regarded as ‘all groups’ | x | [12525] |
isLive | Boolean | Active or inactive. If not sent regard as active | x | true |
rate | Number | Between 1-2000 | x | 100 |
Request Example
[
{
"instanceId": 122,
"instanceName": "newInstance",
"appConfig1": "414n",
"instanceConfig1": "aaa1",
"instanceConfig2": "aaa1",
"groups": [1],
"isLive": true,
"rate": 2
}
]
DELETE
Description
Use this API to delete an instance.
Notes:
- Default instances cannot be deleted.
- Deleted instances cannot be restored.
Method
DELETE https://platform.ironsrc.com/levelPlay/network/instances/v4/
Request Parameters
Name | Type | Description | Example |
appKey | String | application key (as seen on the platform) | 142401ac1 |
Request Example URL
https://platform.ironsrc.com/levelPlay/network/instances/v4/142401ac1/
Supported Parameters
Name | Type | Description |
instanceId | Number | ID generated by ironSource platform on instance creation |
Request body example
[
{
"instanceId": 58
},
{
"instanceId": 59
},
]
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.
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 void. Each error has a code which is explained in the table below.
Example:
API v3 (previous version)
Note: Instance API v3 does not support apps during a live A/B test
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
Method
GET platform.ironsrc.com/partners/publisher/instances/v3?
Required Parameters
Name | Type | Description |
appKey | String | application Key (as seen on our platform) |
Request Example URL
https://platform.ironsrc.com/partners/publisher/instances/v3?appKey=aa2209b1d
Response Parameters
Name | Description |
appKey | application key (as seen on our platform) |
appName | the application name |
appStatus | the application status |
platform | platform can be iOS or android |
bundleId | the native app store bundle id |
creationDate | the date the app was added to ironSource platform |
id | unique instance ID generated by ironSource platform on instance creation |
provider instance level config* | for ad source instance level configs naming convention refer to this article |
name | the instance name |
status | instance status can be active or inactive |
rate | instance level rate (if defined) |
pricing | pricing as set on the platform for ironSource network |
abVersion | A/B test version (optional values are: “A”, “B”, “N/A”) |
JSON Example Response
{ "appKey": "aa2209b1d", "appName": "My Test App", "appStatus": "active", "platform": "Android", "bundleId": "com.test.app", "creationDate": "N/A", "adUnits": { "rewardedVideo": { "activeNetworks": [ "ironSource", "AdColony" ], "activeBidderNetworks": [ "" ], "networkInstances": { "ironSource": [ { "id": 0, "name": "Default", "status": "active", "pricing": [ { "eCPM": "10.5", "Countries": [ "FR", "UK" ] } ], "abVersion": "N/A" } ], "AdColony": [ { "id": 0, "zoneId": "zone_ID_US_High", "name": "US_high", "status": "active", "rate": 87, "abVersion": "N/A" }, { "id": 2851429, "zoneId": "zone_ID_US_Low", "name": "US_Low", "status": "active", "rate": 12, "abVersion": "N/A" } ] }, "networkBidderInstances": [] }, "offerWall": { "activeNetworks": [ "ironSource" ] }, "interstitial": { "activeNetworks": [], "activeBidderNetworks": [], "networkInstances": { "ironSource": [ { "id": 0, "name": "Default", "status": "inactive", "pricing": [ { "eCPM": "8.5", "Countries": [ "FR", "UK" ] } ], "abVersion": "N/A" } ] }, "networkBidderInstances": [] }, "banner": { "activeNetworks": [], "networkInstances": { "ironSource": [ { "id": 0, "name": "Default", "status": "inactive", "abVersion": "N/A" } ] } } } }
Create Instances
Description
Use this API to create instances for both ironSource network and mediated ad sources. This API allows you to create multiple instances with a single API call.
Notes:
- Instances created without a ‘status’ parameter set will be automatically set as ‘active’
- Instances created for apps that are not live at the store will be automatically set as ‘inactive’
- For Mediation users – each newly created instance will be included in all of the app’s mediation groups.
- Each app is limited up to 10 instances per ad unit. In order to extend this limitation Contact Us or reach out to your Account Manager.
- To create instances for mediated ad sources, please refer to this article for naming convention.
- To create bidder networks 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 on 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 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
Method
POST platform.ironsrc.com/partners/publisher/instances/v3?
Required Parameters
Name | Type | Description |
appKey | String | application Key (as seen on our platform) |
provider | String array | for ad source naming convention refer to this article |
adUnit | String array | “rewardedVideo”, “interstitial”, “banner” |
instanceName | String | the newly created instance’s name |
provider instance level config* | String | for ad source instance level configs naming convention refer to this article |
Optional Parameters
Name | Type | Description |
status | String | instance status can be ‘active’ or ‘inactive’ |
pricing | String array | determine the eCPM to be delivered by ironSource network |
rate | Double | instance level rate (if defined) |
provider app level configs* | String | for ad source app level configs naming convention refer to this article |
Request Example URL
https://platform.ironsrc.com/partners/publisher/instances/v3?
Request Example Body
{
"appKey": "d11a21a5",
"configurations": {
"ironSource": {
"interstitial": [
{
"instanceName": "low_interstitial",
"status": "active",
"pricing": [
{
"country": [
"FR",
"DE"
],
"eCPM": 3
}
],
"pricingType": "eCPM"
},
{
"instanceName": "high_interstitial",
"status": "active",
"pricing": [
{
"country": [
"IL",
"US"
],
"eCPM": 20
}
]
}
]
},
"adColony": {
"rewardedVideo": [
{
"instanceName": "adcolony_rv",
"status": "active",
"zoneId": 102030,
"rate": 10
}
]
}
}
}
JSON Example Response
{
"rewardedVideo": {
"AdColony": [
{
"id": 6701121,
"zoneId": "102030",
"name": "adcolony_rv",
"status": "active",
"rate": 10,
"abVersion": "N/A"
}
]
},
"interstitial": {
"ironSource": [
{
"id": 0,
"name": "Default",
"status": "active",
"abVersion": "N/A"
},
{
"id": 6701117,
"name": "low_interstitial",
"status": "active",
"abVersion": "N/A",
"pricing": [
{
"eCPM": 3,
"Countries": [
"FR",
"DE"
]
}
]
},
{
"id": 6701119,
"name": "high_interstitial",
"status": "active",
"abVersion": "N/A",
"pricing": [
{
"eCPM": 20,
"Countries": [
"IL",
"US"
]
}
]
}
],
"ironSourceBidding": [
{
"id": 2948695,
"name": "",
"status": "inactive",
"abVersion": "N/A"
}
]
}
}
Update Instances
Description
Use this API to update instance name, status and pricing for ironSource network and mediation ad sources (pricing is only available for ironSource network). Multiple instances can be updated with a single API call.
Notes:
- 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 pricing values on that same instance only.
- To update mediation ad source instances please refer to this article for naming convention.
- To update bidder networks Contact Us or reach out to your Account Manager.
- To remove instance level rate simply add the rate parameter with an empty string value (eg “”)
Authentication Type
Method
PUT platform.ironsrc.com/partners/publisher/instances/v3?
Required Parameters
Name | Type | Description |
appKey | String | Application Key (as seen on our platform) |
provider | String array | For ad source naming convention refer to this article |
adUnit | String array | “rewardedVideo”, “interstitial”, “banner” |
instanceId | String | 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’ |
rate | Double | instance level rate (if defined) |
provider instance level config* | String | for ad source instance level configs naming convention refer to this article |
provider app level config* | String | for ad source app level configs naming convention refer to this article |
Request Example URL
https://platform.ironsrc.com/partners/publisher/instances/v3?
Request Body Example
{ "appKey": "6bc83099", "configurations": { "ironSourceBidding": { "rewardedVideo": [ { "instanceId": 327, "status": "inactive" } ] } } }
JSON Response Example
{ "rewardedVideo": { "ironSource": [ { "id": 0, "name": "Default", "status": "inactive", "abVersion": "N/A" } ], "AdColony": [ { "id": 0, "name": "default", "status": "active", "abVersion": "N/A" }, { "id": 326, "name": "lw", "status": "inactive", "rate":"2", "abVersion": "N/A" } ], "ironSourceBidding": [ { "id": 327, "name": "-", "status": "inactive", "abVersion": "N/A" } ] }, "interstitial": { "ironSource": [ { "id": 0, "name": "Default", "status": "active", "abVersion": "N/A" } ] }, "banner": { "ironSource": [ { "id": 0, "name": "Default", "status": "inactive", "abVersion": "N/A" } ] } }
Delete Instance
Description
Use this API to delete an instance.
General notes:
- 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
Method
DELETE platform.ironsrc.com/partners/publisher/instances/v3?
Required Parameters
Name | Type | Description |
appKey | String | application Key (as seen on our platform) |
instanceId | String | ID generated by ironSource platform on instance creation |
Request Example URL
http://platform.ironsrc.com/partners/publisher/instances/v3?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" } ] } }