Instances API v4

Manage app mediation instances by retrieving, creating, updating, or deleting LevelPlay ad network instances programmatically via the Instances API v4.

読み終わるまでの所要時間 10 分

最終更新 1日前

重要

API versions 3 and below are deprecated as of March 2025. Update to the latest version to avoid disruptions.

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

Bearer API authentication

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
adFormat	Rewarded, interstitial, banner or native	interstitial
networkName	The ad network the instance belongs to	adColony
appConfig1 / appConfig2
instanceConfig1 / instanceConfig2	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": "",    "adUnit": "rewardedVideo",    "adFormat": "rewarded",    "networkName": "unityAds",    "appConfig1": "qtr",    "instanceConfig1": "trb",    "isBidder": true,    "groups": [101663],    "isLive": true  },  {    "instanceId": 1014428,    "instanceName": "Default",    "adUnit": "interstitial",    "adFormat": "interstitial",    "networkName": "unityAds",    "appConfig1": "qertb",    "instanceConfig1": "qtrb",    "isBidder": false,    "groups": [101664],    "isLive": true,    "rate": 25  },  {    "instanceId": 1845809,    "instanceName": "Default",    "adUnit": "rewardedVideo",    "adFormat": "rewarded",    "networkName": "adManager",    "appConfig1": "bqw",    "instanceConfig1": "qqr",    "isBidder": false,    "groups": [101663 ],    "isLive": true,    "rate": 4  }]

CREATE

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 by using 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.

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'
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	Example
instanceName	String	The newly created instance's name	✓ - For non-bidding instances	highestBidderinstance
networkName	String		✓	adColony
adFormat	String	Rewarded, interstitial, banner or native	✓	interstitial
isBidder	Boolean	Indicates if the instance is a bidder instance	✓	True / False
appConfig1	String		x	‘123' / ‘abc'
appConfig2	String		x	‘123' / ‘abc'
instanceConfig1	String		x	‘123' / ‘abc'
instanceConfig2	String		x	‘123' / ‘abc'
groups	Number Array	If not sent, regard as ‘all groups'. The recommended best practice is to 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 0.01-3000	x	5

Request Example


[  {      "instanceName": "newInstance",            "networkName": "unityAds",      "adUnit": "rewardedVideo",      "isBidder": true,      "appConfig1": "414n",      "instanceConfig1": "aaa1",      "instanceConfig2": "aaa1",      "groups": [12345],      "isLive": true  },  {      "instanceName": "newInstance_2",            "networkName": "unityAds",      "adFormat": "rewarded",      "isBidder": false,      "appConfig1": "414n",      "instanceConfig1": "bbb1",      "groups": [12345],      "isLive": true,      "rate": 5  }]

UPDATE

Use this API to update instances. Multiple instances can be updated with a single API call. To remove instance level rate, add the rate parameter with a '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	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		x	‘123' / ‘abc'
instanceConfig2	String		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 0.01-3000	x	100

Request Example


[  {      "instanceId": 122,      "instanceName": "newInstance",      "appConfig1": "414n",      "instanceConfig1": "aaa1",      "instanceConfig2": "aaa1",      "groups": [1],      "isLive": true,      "rate": 2  }]

DELETE

Use this API to delete an instance.

Default instances cannot be deleted.
Deleted instances cannot be restored.

Method

DELETE https://platform.ironsrc.com/levelPlay/network/instances/v4/

Requested 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	Example
ids	Array of number	Instance IDs as sent in the GET request	✓	1458, 5769

Request body example


{    "ids": [1458, 5769]}

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-402,            "errorMessage": "The instance name must be unique for the same ad format and network",            "params": {                "instanceName": "abc"            }        }    ],    "code": 400}

API v3 (previous version)

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

Bearer API authentication

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*
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

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.

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. To extend this limitation, contact support or contact your Account Manager.
To create bidder networks, contact support or contact your Account Manager.

CPM pricing

General

CPM Pricing allows you the control and flexibility to define expected CPM rates from the LevelPlay network. Read more here.
CPM pricing is available for specific accounts only. To activate CPM pricing, contact support or contact 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

Bearer API authentication

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
adUnit	String array	"rewardedVideo", "interstitial", "banner"
instanceName	String	the newly created instance's name
provider instance level config*	String

注

Provider instance level config is only mandatory on the creation of mediation a source instances. This parameter naming varies between mediation ad sources.

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

注

Ad source app level configs varies between mediation ad sources.

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

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.

Max number of update calls is limited to 6 per day.
In order to activate non-default instances you must first activate the default instance (instance ID=0).
Updating instance pricing will replace all pricing values on that same instance only.
To update bidder networks, contact support or reach out to your Account Manager.
To remove instance level rate, add the rate parameter with an empty string value (eg "")

Authentication Type

Bearer API authentication

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
adUnit	String array	"rewardedVideo", "interstitial", "banner"
instanceId	String	ID generated by ironSource platform on instance creation

Optional Parameters

Name	Type	Description
name	String	the 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
provider app level config*	String

注

Provider app and instance level configs naming varies between mediation ad sources.

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

Bearer API authentication

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"      }    ]  }}

Instances API v4

Rate limits

Authentication Type

GET

Description

Method

Request Parameters

Name

Type

Description

Example

Request Example URL

Response Parameters

Name

Description

Example

Response Example

CREATE

Method

Request Parameters

Name

Type

Description

Example

Request Example URL

Supported Parameters

Name

Type

Description

Mandatory

Example

Request Example

UPDATE

Method

Request Parameters

Name

Type

Description

Example

Request Example URL

Supported Parameters

Name

Type

Description

Mandatory

Example

Request Example

DELETE

Method

Requested Parameters

Name

Type

Description

Example

Request Example URL

Supported Parameters

Name

Type

Description

Mandatory

Example

Request body example

Success

Errors

Example

API v3 (previous version)

Get Instances

Description

Authentication Type

Method

Required Parameters

Name

Type

Description

Request Example URL

Response Parameters

Name

Description

JSON Example Response

Create Instances