Mediation Management
Use this API to receive all group and waterfall configurations you have set on ironSource’s dashboard.
Before you start make sure you go over our API introduction article.
Get Mediation Groups
Description
Use this API to retrieve a list of each of your application’s groups and their waterfall configurations. The response will include the following: group name, group ID, group segment, group countries, group position, group waterfall, and more.
Authentication Type
Method
GET https://platform.ironsrc.com/partners/publisher/mediation/management/v2?
Required Parameters
| Name | Type | Description |
| appKey | String | application Key (as seen on our platform) |
Request Example URL
https://platform.ironsrc.com/partners/publisher/mediation/management/v2?appKey=813df9s5
Response Parameters
| Name | Description |
| appKey | application Key (as seen on our platform) |
| appName | the application name |
| appStatus | app status can be active or inactive |
| platform | iOS or Android |
| bundleId | the native app store bundle_id |
| adUnits | includes the active ad sources per ad unit |
| groupName | name as defined on the platform |
| groupId | the mediation group’s ID |
| groupPosition | the group’s hierarchy vs. other groups |
| groupSegments | segments included (if defined) |
| groupCountries | countries included (country codes) |
| adSourcePriority | waterfall setup |
| providerName | ad source provider name (e.g Meta Audience Network, ironSource) |
| tierType | tier optimization type (‘bidding’, ‘manual’, ‘sortByCpm’, ‘optimized’) |
| rate | group level CPM override (if defined) |
| instanceName | instance name as defined on the platform |
| instanceId | either auto-generated by ironSource network or input manually for other networks |
| capping | limit the number of ads displayed per user per session (if defined) |
JSON Example Response
{
"appKey": "ae4e3rrd31",
"appName": "ironSource app",
"appStatus": "active",
"platform": "iOS",
"bundleId": "com.irosSource.app",
"adUnits": {
"rewardedVideo": [
{
"groupName": "English speaking",
"groupId": 800961,
"groupPosition": 1,
"groupSegments": [],
"groupAbVersion": "N/A",
"groupCountries": [
"AU",
"CA",
"GB",
"US"
],
"adSourcePriority": {
"bidding": {
"tierType": "bidding",
"instances": [
{
"providerName": "ironSource",
"instanceId": 193944,
"capping": {
"value": 1,
"interval": "session"
}
},
{
"providerName": "AdColony",
"instanceId": 1228046
},
{
"providerName": "Mintegral",
"instanceId": 1238050
},
{
"providerName": "TapJoy",
"instanceId": 1555052
}
]
},
"tier1": {
"tierType": "manual",
"instances": [
{
"instanceName": "Default",
"providerName": "ironSource",
"instanceId": 0
},
{
"instanceName": "Default",
"providerName": "AdColony",
"instanceId": 0
}
]
},
"tier2": {
"tierType": "sortByCpm",
"instances": [
{
"instanceName": "high",
"providerName": "ironSource",
"instanceId": 1338066,
"rate": 13
},
{
"instanceName": "Default",
"providerName": "Pangle",
"instanceId": 0,
"rate": 11
},
{
"instanceName": "Default",
"providerName": "AppLovin",
"instanceId": 0
}
]
},
"tier3": {
"tierType": "sortByCpm",
"instances": [
{
"instanceName": "Default",
"providerName": "AdMob",
"instanceId": 0,
"rate": 7
}
]
},
"backfill": {
"tierType": "backfill",
"instances": [
{
"instanceName": "Default Backfill",
"providerName": "ironSourceBackfill",
"instanceId": 1958067
}
]
}
}
},
{
"groupName": "US",
"groupId": 822760,
"groupPosition": 2,
"groupSegments": [],
"groupAbVersion": "N/A",
"groupCountries": [
"US"
],
"adSourcePriority": {
"bidding": {
"tierType": "bidding",
"instances": [
{
"providerName": "ironSource",
"instanceId": 193944
}
]
},
"tier1": {
"tierType": "manual",
"instances": [
{
"instanceName": "Default",
"providerName": "ironSource",
"instanceId": 0
},
{
"instanceName": "high",
"providerName": "ironSource",
"instanceId": 1958066
}
]
},
"tier2": {
"tierType": "sortByCpm",
"instances": [
{
"instanceName": "Default",
"providerName": "AdColony",
"instanceId": 0
},
{
"instanceName": "Default",
"providerName": "AppLovin",
"instanceId": 0
},
{
"instanceName": "Default",
"providerName": "Pangle",
"instanceId": 0
}
]
},
"tier3": {
"tierType": "sortByCpm",
"instances": [
{
"instanceName": "Default",
"providerName": "AdMob",
"instanceId": 0
}
]
},
"backfill": {
"tierType": "backfill",
"instances": [
{
"instanceName": "Default Backfill",
"providerName": "ironSourceBackfill",
"instanceId": 1958067
}
]
}
}
},
{
"groupName": "All Countries",
"groupId": 8004757,
"groupPosition": 3,
"groupSegments": [],
"groupAbVersion": "N/A",
"groupCountries": [
"*"
],
"adSourcePriority": {
"bidding": {
"tierType": "bidding",
"instances": [
{
"providerName": "ironSource",
"instanceId": 193944
}
]
},
"tier1": {
"tierType": "manual",
"instances": [
{
"instanceName": "Default",
"providerName": "ironSource",
"instanceId": 0
},
{
"instanceName": "high",
"providerName": "ironSource",
"instanceId": 1958066
}
]
},
"tier2": {
"tierType": "sortByCpm",
"instances": [
{
"instanceName": "Default",
"providerName": "Pangle",
"instanceId": 0,
"rate": 10
},
{
"instanceName": "Default",
"providerName": "AdMob",
"instanceId": 0,
"rate": 9
}
]
},
"backfill": {
"tierType": "backfill",
"instances": [
{
"instanceName": "Default Backfill",
"providerName": "ironSourceBackfill",
"instanceId": 1958067
}
]
}
}
}
],
"interstitial": [
{
"groupName": "English speaking",
"groupId": 8010763,
"groupPosition": 1,
"groupSegments": [],
"groupAbVersion": "N/A",
"groupCountries": [
"AU",
"CA",
"GB",
"US"
],
"adSourcePriority": []
},
{
"groupName": "US",
"groupId": 802762,
"groupPosition": 2,
"groupSegments": [],
"groupAbVersion": "N/A",
"groupCountries": [
"US"
],
"adSourcePriority": []
},
{
"groupName": "All Countries",
"groupId": 802758,
"groupPosition": 3,
"groupSegments": [],
"groupAbVersion": "N/A",
"groupCountries": [
"*"
],
"adSourcePriority": []
}
],
"banner": [
{
"groupName": "All Countries",
"groupId": 802759,
"groupPosition": 1,
"groupSegments": [],
"groupAbVersion": "N/A",
"groupCountries": [
"*"
],
"adSourcePriority": []
}
]
}
}
Create Mediation Groups
Description
Use this API to create mediation groups and define each groups waterfall setup.
General notes:
- Supports creation of only one mediation group per call.
- If ‘adSourcePriority’ is missing in the call, all networks that are active in the app and ad unit will be placed within the waterfall’s ‘tier 2’ section of the newly created group on ‘sortByCPM tierType.
- If ‘tierType’ is missing in the call – ‘tier 1’, ‘tier 2’ and ‘tier 3’ default type will be ‘sortByCPM’
- Bidding sources will be automatically set to tierType: ‘bidding’
- If ‘groupPosition’ is missing in the call, the newly created group will be placed on top of the existing groups.
- If ‘adSourcePriority’ is included in the call, and “manual” tier type is set, the instances will be placed based on their order in the call itself.
Authentication Type
Method
POST https://platform.ironsrc.com/partners/publisher/mediation/management/v2?
Required Parameters
| Name | Type | Description |
| appKey | String | application Key (as seen on our platform) |
| adUnit | String | “rewardedVideo”, “interstitial”, “banner” |
| groupName | String | the newly created group’s name |
| groupCountries |
String array | the newly created group’s included countries, countries are defined by a 2 letter country code, as per ISO 3166-1 Alpha-2. To include all countries simple add asterisk (*) |
Optional Parameters
| Name | Type | Description |
| groupPosition | Integer |
the newly created group’s hierarchy vs. existing groups |
| groupSegments | String array | the newly created group’s included segments (ID) |
| adSourcePriority | Object | the newly created group’s waterfall setup. |
| tierType | String | tier optimization type (‘bidding’, ‘manual’, ‘sortByCpm’, ‘optimized’) |
| rate | Floating point | group level CPM override (values range is 0.01-1000) |
| capping | Integer | limit the number of ads displayed per user per session (values range is 1-10) |
Request Example URL
https://platform.ironsrc.com/partners/publisher/mediation/management/v2?appKey=ab1234
Request Body Example
{
"appKey": "ab1234",
"adUnit": "rewardedVideo",
"groupCountries": [
"JP"
],
"groupName": "Japan_High",
"adSourcePriority": {
"bidding": {
"instances": [
{
"providerName": "AdColony",
"instanceId": 12345
}
]
},
"tier1": {
"tierType": "sortByCpm",
"instances": [
{
"providerName": "AppLovin",
"instanceId": 0,
"rate": 2.5
},
{
"tagId": 1234,
"rate": 1
}
]
},
"tier2": {
"tierType": "optimized",
"instances": [
{
"providerName": "TapJoy",
"instanceId": 0
}
]
},
"tier3": {
"tierType": "manual",
"instances": [
{
"providerName": "TapJoy",
"instanceId": 54321
}
]
}
}
}
JSON Example Response
{
"appKey": "ab1234",
"adUnits": {
"rewardedVideo": [
{
"groupName": "Japan_High",
"groupId": 100100,
"groupPosition": 2,
"groupSegments": [],
"groupAbVersion": "N/A",
"groupCountries": [
"JP"
],
"adSourcePriority": {
"bidding": {
"tierType": "bidding",
"instances": [
{
"providerName": "AdColony",
"instanceId": 12345
}
]
},
"tier1": {
"tierType": "manual",
"instances": [
{
"instanceName": "Default",
"providerName": "AppLovin",
"instanceId": 0
},
{
"tagName": "My Tag",
"tagId": 1234
}
]
},
"tier2": {
"tierType": "optimized",
"instances": [
{
"instanceName": "Default",
"providerName": "TapJoy",
"instanceId": 0
}
]
},
"tier3": {
"tierType": "sortByCpm",
"instances": [
{
"instanceName": "My Instance",
"providerName": "TapJoy",
"instanceId": 54321
}
]
}
}
},
{
"groupName": "All Countries",
"groupId": 100099,
"groupPosition": 2,
"groupSegments": [],
"groupAbVersion": "N/A",
"groupCountries": [
"*"
],
"adSourcePriority": []
}
],
"interstitial": [
{
"groupName": "All Countries",
"groupId": 100098,
"groupPosition": 1,
"groupSegments": [],
"groupAbVersion": "N/A",
"groupCountries": [
"*"
],
"adSourcePriority": []
}
],
"banner": [
{
"groupName": "All Countries",
"groupId": 102293,
"groupPosition": 1,
"groupSegments": [],
"groupAbVersion": "N/A",
"groupCountries": [
"*"
],
"adSourcePriority": []
}
]
}
}
Update Mediation Groups
Description
Use this API to update the mediation group’s name, position, included countries, included segments and waterfall setup.
General notes:
- Supports updating of only one mediation group per call.
- Any optional parameter that is not included in the call (‘groupName’, ‘groupPosition’, ‘groupSegments’, ‘groupCountries’, ‘adSourcePriority’, ‘capping’, ‘tierType’ or ‘rate’) will not impact the group’s existing setup.
- Any optional parameter that is included in the call (‘groupName’, ‘groupPosition’, ‘groupSegments’, ‘groupCountries’, ‘adSourcePriority’, ‘capping’, ‘tierType’ or ‘rate’) will replace the group’s existing setup.
- If ‘adSourcePriority’ is included in the call, and “manual” tier type is set, the instances will be placed based on their order in the call itself.
Authentication Type
Method
PUT https://platform.ironsrc.com/partners/publisher/mediation/management/v2?
Required Parameters
| Name | Type | Description |
| appKey | String | application Key (as seen on our platform) |
| groupId | Integer | unique group ID |
Optional Parameters
| Name | Type | Description |
| groupName | String | the desired group’s new name |
| groupPosition | Integer | the desired group’s new position |
| groupSegments | String array | the desired group’s new segments |
| groupCountries | String array | the desired group’s newly included countries. countries are defined by a 2 letter country code, as per ISO 3166-1 Alpha-2. To include all countries simple add asterisk (*) |
| adSourcePriority | Object | the updated group’s new waterfall setup |
| tierType | String | tier optimization type (, ‘manual’, ‘sortByCpm’, ‘optimized’) |
| rate | Floating point | group level CPM override (values range is 0.01-1000) |
| capping | Integer | limit the number of ads displayed per user per session (values range is 1-10) |
Request Example URL
https://platform.ironsrc.com/partners/publisher/mediation/management/v2?appKey=ab1234
Request Body Example
{
"appKey": "ab1234",
"groupId": "100100",
"groupName": "Asia_High",
"groupPosition": "1",
"countries": [
"JP",
"CN"
],
"adSourcePriority": {
"bidding": {
"instances": [
{
"providerName": "TapJoy",
"instanceId": 212121,
"capping": {
"value": 1,
"interval": "session"
}
}
]
},
"tier1": {
"instances": [
{
"providerName": "TapJoy",
"instanceId": 0
}
]
},
"tier2": {
"tierType": "sortByCpm",
"instances": [
{
"providerName": "AppLovin",
"instanceId": 0
}
]
},
"tier3": {
"instances": [
{
"providerName": "TapJoy",
"instanceId": 54321
},
{
"tagId": 1234,
"rate": 1
}
]
}
}
}
JSON Example Response
{
"appKey": "ab1234",
"adUnits": {
"rewardedVideo": [
{
"groupName": "Asia_High",
"groupId": 100100,
"groupPosition": 1,
"groupSegments": [],
"groupAbVersion": "N/A",
"groupCountries": [
"JP",
"CN"
],
"adSourcePriority": {
"bidding": {
"tierType": "bidding",
"instances": [
{
"providerName": "TapJoy",
"instanceId": 212121,
"capping": {
"value": 1,
"interval": "session"
}
}
]
},
"tier1": {
"tierType": "manual",
"instances": [
{
"instanceName": "Default",
"providerName": "AppLovin",
"instanceId": 0
}
]
},
"tier2": {
"tierType": "sortByCpm",
"instances": [
{
"instanceName": "Default",
"providerName": "TapJoy",
"instanceId": 0
}
]
},
"tier3": {
"tierType": "sortByCpm",
"instances": [
{
"instanceName": "My Instance",
"providerName": "TapJoy",
"instanceId": 54321
},
{
"tagName": "My Tag",
"tagId": 1234
}
]
}
}
},
{
"groupName": "All Countries",
"groupId": 100099,
"groupPosition": 2,
"groupSegments": [],
"groupAbVersion": "N/A",
"groupCountries": [
"*"
],
"adSourcePriority": []
}
],
"interstitial": [
{
"groupName": "All Countries",
"groupId": 100098,
"groupPosition": 1,
"groupSegments": [],
"groupAbVersion": "N/A",
"groupCountries": [
"*"
],
"adSourcePriority": []
}
],
"banner": [
{
"groupName": "All Countries",
"groupId": 102293,
"groupPosition": 1,
"groupSegments": [],
"groupAbVersion": "N/A",
"groupCountries": [
"*"
],
"adSourcePriority": []
}
]
}
}
Delete Mediation Group
Description
Use this API to delete a mediation group
General notes:
- Can delete one mediation group per call.
- ‘All Countries’ default group cannot be deleted.
- Deleted mediation groups cannot be restored.
- Response includes all of the app’s mediation groups excluding the deleted ones.
Authentication Type
Method
DELETE https://platform.ironsrc.com/partners/publisher/mediation/management/v2?
Required Parameters
| Name | Type | Description |
| appKey | String | application Key (as seen on our platform) |
| groupId | Integer | unique group ID |
Request Example URL
https://platform.ironsrc.supersonicads.com/partners/publisher/mediation/management/v2?groupId=182641&appKey=ab1234
JSON Example Response
{
"appKey": "ab1234",
"adUnits": {
"rewardedVideo": [
{
"groupName": "Japan_High",
"groupId": 100100,
"groupPosition": 2,
"groupSegments": [],
"groupAbVersion": "N/A",
"groupCountries": [
"JP"
],
"adSourcePriority": {
"bidding": {
"tierType": "bidding",
"instances": [
{
"providerName": "AdColony",
"instanceId": 12345
}
]
},
"tier1": {
"tierType": "manual",
"instances": [
{
"instanceName": "Default",
"providerName": "AppLovin",
"instanceId": 0
},
{
"tagName": "My Tag",
"tagId": 1234
}
]
},
"tier2": {
"tierType": "optimized",
"instances": [
{
"instanceName": "Default",
"providerName": "TapJoy",
"instanceId": 0
}
]
},
"tier3": {
"tierType": "sortByCpm",
"instances": [
{
"instanceName": "My Instance",
"providerName": "TapJoy",
"instanceId": 54321
}
]
}
}
},
{
"groupName": "All Countries",
"groupId": 100099,
"groupPosition": 2,
"groupSegments": [],
"groupAbVersion": "N/A",
"groupCountries": [
"*"
],
"adSourcePriority": []
}
],
"interstitial": [
{
"groupName": "All Countries",
"groupId": 100098,
"groupPosition": 1,
"groupSegments": [],
"groupAbVersion": "N/A",
"groupCountries": [
"*"
],
"adSourcePriority": []
}
],
"banner": [
{
"groupName": "All Countries",
"groupId": 102293,
"groupPosition": 1,
"groupSegments": [],
"groupAbVersion": "N/A",
"groupCountries": [
"*"
],
"adSourcePriority": []
}
]
}
}