Instances API v4

• Support for CRUD
• Changing ad networks' application-level configurations
• Adding or removing instances from waterfall groups (Supporting active AB test applications)

Rate limits

Authentication Type

GET

Description

Method

Request Parameters

Request Example URL

Response Parameters

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

• 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

Request Parameters

Request Example URL

Supported Parameters

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

Method

Request Parameters

Request Example URL

Supported Parameters

Request Example

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

DELETE

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

Method

Requested Parameters

Request Example URL

Supported Parameters

Request body example

{
    "ids": [1458, 5769]
}

Success

Errors

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)

Get Instances

Description

Authentication Type

Method

Required Parameters

Request Example URL

Response Parameters

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

• 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

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 support or contact your Account Manager.
3. For best practices on using instances with pricing go to our Best Practices article.

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

Method

Required Parameters

Optional Parameters

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

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

Method

Required Parameters

Optional Parameters

Request Example URL

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

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

Method

Required Parameters

Request Example URL

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