Instance API

  • Use this API to manage instances on the ironSource dashboard.Before you start make sure you go over our API introduction article.

    Note: Instance API 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/v2?

    Required Parameters

    Name Type Description
    appKey String application Key (as seen on our platform)

    Request Example URL

    https://platform.ironsrc.com/partners/publisher/instances/v2?appKey=aa2209b1d

    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
    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.mytestapp",
        "creationDate": "N/A",
        "adUnits": {
            "rewardedVideo": {
                "activeNetworks": [
                    "ironSource",
                    "AdColony",
                    "TapJoy",
                    "Mintegral"
                ],
                "activeBidderNetworks": [
                    "ironSourceBidding",
                    "adColonyBidding",
                    "TapJoyBidding",
                    ""
                ],
                "networkInstances": {
                    "ironSource": [
                        {
                            "id": 0,
                            "name": "Default",
                            "status": "active",
                            "abVersion": "N/A"
                        },
                        {
                            "id": 1954810,
                            "name": "New",
                            "status": "active",
                            "abVersion": "N/A",
                            "pricing": [
                                {
                                    "eCPM": 20,
                                    "Countries": [
                                        "*"
                                    ]
                                },
                                {
                                    "eCPM": 15,
                                    "Countries": [
                                        "AU"
                                    ]
                                }
                            ]
                        }
                    ],
                    "AdColony": [
                        {
                            "id": 0,
                            "name": "Default",
                            "status": "active",
                            "abVersion": "N/A"
                        }
                    ]
                },
                "networkBidderInstances": {
                    "ironSourceBidding": [
                        {
                            "id": 1954801,
                            "name": "",
                            "status": "active",
                            "abVersion": "N/A"
                        }
                    ],
                    "adColonyBidding": [
                        {
                            "id": 1954802,
                            "name": "",
                            "status": "active",
                            "abVersion": "N/A"
                        }
                    ],
                    "TapJoyBidding": [
                        {
                            "id": 1954804,
                            "name": "",
                            "status": "active",
                            "abVersion": "N/A"
                        }
                    ],
                    "": [
                        {
                            "id": 1954805,
                            "name": "",
                            "status": "active",
                            "abVersion": "N/A"
                        }
                    ]
                }
            },
            "offerWall": {
                "activeNetworks": [
                    "ironSource"
                ]
            },
            "interstitial": {
                "activeNetworks": [
                    "ironSource",
                    "AdColony",
                    "Mintegral"
                ],
                "activeBidderNetworks": [
                    "adColonyBidding",
                    "",
                    "ironSourceBidding"
                ],
                "networkInstances": {
                    "ironSource": [
                        {
                            "id": 0,
                            "name": "Default",
                            "status": "active",
                            "abVersion": "N/A"
                        }
                    ],
                    "AdColony": [
                        {
                            "id": 0,
                            "name": "Default",
                            "status": "active",
                            "abVersion": "N/A"
                        }
                    ]
                },
                "networkBidderInstances": {
                    "adColonyBidding": [
                        {
                            "id": 1954803,
                            "name": "",
                            "status": "active",
                            "abVersion": "N/A"
                        }
                    ],
                    "": [
                        {
                            "id": 1954806,
                            "name": "",
                            "status": "active",
                            "abVersion": "N/A"
                        }
                    ],
                    "ironSourceBidding": [
                        {
                            "id": 1954807,
                            "name": "",
                            "status": "active",
                            "abVersion": "N/A"
                        }
                    ]
                }
            },
            "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:

    1. Instances created without a ‘status’ parameter set will be automatically set as ‘active’
    2. Instances created for live that are not live at the store will be automatically set as ‘inactive’
    3. For Mediation users – each newly created instance will be included in all of the app’s mediation groups.
    4. 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.
    5. To create instances for mediated ad sources, please refer to this article for naming convention.
    6. To create bidder networks Contact Us or reach out to your Account Manager.

    CPM pricing:

    General –

    1. CPM Pricing allows you the control and flexibility to define expected CPM rates from ironSource’s network.  Read more here.
    2. CPM pricing is available for specific accounts only, to activate CPM pricing Contact Us or reach out to your Account Manager.
    3. For best practices on using instances with pricing go to our Best Practices article.

    Notes –

    1. In order to set global pricing for an instance, populate the instance’s country field with asterisk character ‘*’.
    2. Instances created without pricing and countries without defined pricing will be set to use optimized pricing.
    3. 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/v2?

    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

    Note: provider instance level config is only mandatory on the creation of mediation a source instances. This parameter naming varies between mediation ad sources. For naming convention go to this article.


    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
    provider app level configs* String for ad source app level configs naming convention refer to this article

    Note: ad source app level configs varies between mediation ad sources. For naming convention go to this article

    Request Example URL

    https://platform.ironsrc.com/partners/publisher/instances/v2?

    Request Example Body

    {
      "appKey": "9bc83099",
      "configurations": {
        "ironSourceBidding": {
          "rewardedVideo": [
            {
              "status": "active"
            }
          ]
        },
        "adColony": {
          "appConfig": {
            "appID": "fk34sf"
          },
          "rewardedVideo": [
            {
              "instanceName": "default",
              "status": "active",
              "zoneId": 123
            },
            {
              "instanceName": "low",
              "status": "inactive",
              "zoneId": 1234
            }
          ]
        }
      }
    }

    JSON Example Response

    {
      "rewardedVideo": {
        "ironSource": [
          {
            "id": 0,
            "name": "Default",
            "status": "inactive",
            "abVersion": "N/A"
          }
        ],
        "AdColony": [
          {
            "id": 0,
            "name": "default",
            "status": "active",
            "abVersion": "N/A"
          },
          {
            "id": 326,
            "name": "low",
            "status": "inactive",
            "abVersion": "N/A"
          }
        ],
        "ironSourceBidding": [
          {
            "id": 327,
            "name": "-",
            "status": "active",
            "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"
          }
        ]
      }
    }

    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:

    1. Max number of update calls is limited to 6 per day.
    2. In order to activate ironSource’s non default instances you must first activate ironSource’s default instance (instance ID=0).
    3. Updating instance pricing will replace all pricing values on that same instance only.
    4. To update mediation ad source instances please refer to this article for naming convention.
    5. To update bidder networks Contact Us or reach out to your Account Manager.

    Authentication Type

    Bearer API authentication

    Method

    PUT platform.ironsrc.com/partners/publisher/instances/v2?

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

    Note: provider app and instance level configs naming varies between mediation ad sources. For naming convention go to this article.

    Request Example URL

    https://platform.ironsrc.com/partners/publisher/instances/v2?

    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": "low",
            "status": "inactive",
            "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:

    1. Can delete one instance per call.
    2. Default instance cannot be deleted.
    3. Deleted instance cannot be restored.
    4. 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/v2?

    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/v2?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"
          }
        ]
      }
    }

    API Versions