Mediation Management API
Use this API to manage all group and waterfall configurations you have set on ironSource’s dashboard.
Before you start make sure you go over our API introduction article.
Note: Mediation Management API does not support apps during a live A/B test
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/v1?
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/v1?appKey=813df9s5
Response Parameters
| Name | Description |
| 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 | targeted segments (if defined) |
| groupCountries | targeted countries (country codes) |
| adSourcePriority | waterfall setup |
| providerName | ad source provider name (e.g Facebook, ironSource) |
| instanceName | instance name as defined on the platform |
| instanceId | either auto-generated by ironSource network or input manually for other networks |
JSON Example Response
{
"appKey": "a123y419",
"appName": "ironsource App",
"appStatus": "active",
"platform": "Android",
"bundleId": "com.ironsource.app",
"adUnits": {
"rewardedVideo": [
{
"groupName": "US_High",
"groupId": 275212,
"groupPosition": 1,
"groupSegments": [
{
"id": "6112",
"name": "age_Over_16"
}
],
"groupAbVersion": "N/A",
"groupCountries": [
"US"
],
"adSourcePriority": {
"bidders": [
{
"providerName": "AdColony",
"instanceId": 1636704
},
{
"providerName": "ironSource",
"instanceId": 1646701
}
],
"auto": [
{
"providerName": "AdColony",
"instanceName": "Default",
"instanceId": 0
},
{
"providerName": "ironSource",
"instanceName": "Default",
"instanceId": 0
}
]
}
},
{
"groupName": "All Countries",
"groupId": 275310,
"groupPosition": 2,
"groupSegments": [],
"groupAbVersion": "N/A",
"groupCountries": [
"*"
],
"adSourcePriority": {
"bidders": [
{
"providerName": "AdColony",
"instanceId": 1636704
},
{
"providerName": "ironSource",
"instanceId": 1646701
}
],
"auto": [
{
"providerName": "AdColony",
"instanceName": "Default",
"instanceId": 0
},
{
"providerName": "ironSource",
"instanceName": "Default",
"instanceId": 0
}
]
},
"isAllCountries": true
}
],
"interstitial": [
{
"groupName": "All Countries",
"groupId": 275111,
"groupPosition": 1,
"groupSegments": [],
"groupAbVersion": "N/A",
"groupCountries": [
"*"
],
"adSourcePriority": {
"bidders": [
{
"providerName": "AdColony",
"instanceId": 1699706
}
],
"auto": [
{
"providerName": "ironSource",
"instanceName": "is_IS_Bidder",
"instanceId": 163302
},
{
"providerName": "AdColony",
"instanceName": "Default",
"instanceId": 0
},
{
"providerName": "ironSource",
"instanceName": "Default",
"instanceId": 0
}
]
},
"isAllCountries": true
}
]
}
}
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 will be placed within the waterfall’s “auto optimization” section of the newly created group.
- If ‘adSourcePriority’ is included in the call, and “manualHigh” and “manualLow” parameters are set, the instances will be placed based on their order in the call itself.
- If ‘groupPosition’ is missing in the call, the newly created group will be placed on top of the existing groups.
Authentication Type
Method
POST https://platform.ironsrc.com/partners/publisher/mediation/management/v1?
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 targeted 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 targeted segments (ID) |
|
adSourcePriority |
String array | the newly created group’s waterfall setup. Can include 3 sections: ‘manualHigh’, ‘auto’, ‘manualLow’, ‘bidders’ |
Request Example URL
https://platform.ironsrc.com/partners/publisher/mediation/management/v1?appKey=8a5513f5
Request Body Example
{
"appKey": "8a5513f5",
"adUnit": "rewardedVideo",
"groupCountries": [
"JP"
],
"groupName": "Japan_High",
"adSourcePriority": {
"bidders": [
{
"providerName": "AdColony",
"instanceId": 1626704
},
{
"providerName": "ironSource",
"instanceId": 1626701
}
],
"manualHigh": [
{
"providerName": "ironSource",
"instanceName": "Default",
"instanceId": 0
}
],
"auto": [
{
"providerName": "AdColony",
"instanceName": "Default",
"instanceId": 0
}
]
}
}
JSON Example Response
{
"appKey": "8a5513f5",
"adUnits": {
"rewardedVideo": [
{
"groupName": "Japan_High",
"groupId": 275903,
"groupPosition": 1,
"groupSegments": [],
"groupAbVersion": "N/A",
"groupCountries": [
"JP"
],
"adSourcePriority": {
"bidders": [
{
"providerName": "AdColony",
"instanceId": 1626704
},
{
"providerName": "ironSource",
"instanceId": 1626701
}
],
"manualHigh": [
{
"providerName": "ironSource",
"instanceName": "Default",
"instanceId": 0
}
],
"auto": [
{
"providerName": "AdColony",
"instanceName": "Default",
"instanceId": 0
}
]
}
},
{
"groupName": "US_High",
"groupId": 275112,
"groupPosition": 2,
"groupSegments": [
{
"id": "6112",
"name": "age_Over_16"
}
],
"groupAbVersion": "N/A",
"groupCountries": [
"US"
],
"adSourcePriority": {
"bidders": [
{
"providerName": "AdColony",
"instanceId": 1626704
},
{
"providerName": "ironSource",
"instanceId": 1626701
}
],
"auto": [
{
"providerName": "AdColony",
"instanceName": "Default",
"instanceId": 0
},
{
"providerName": "ironSource",
"instanceName": "Default",
"instanceId": 0
}
]
}
},
{
"groupName": "All Countries",
"groupId": 275110,
"groupPosition": 3,
"groupSegments": [],
"groupAbVersion": "N/A",
"groupCountries": [
"*"
],
"adSourcePriority": {
"bidders": [
{
"providerName": "AdColony",
"instanceId": 1626704
},
{
"providerName": "ironSource",
"instanceId": 1626701
}
],
"auto": [
{
"providerName": "AdColony",
"instanceName": "Default",
"instanceId": 0
},
{
"providerName": "ironSource",
"instanceName": "Default",
"instanceId": 0
}
]
},
"isAllCountries": true
}
],
"interstitial": [
{
"groupName": "All Countries",
"groupId": 275111,
"groupPosition": 1,
"groupSegments": [],
"groupAbVersion": "N/A",
"groupCountries": [
"*"
],
"adSourcePriority": {
"bidders": [
{
"providerName": "AdColony",
"instanceId": 1626706
}
],
"auto": [
{
"providerName": "ironSource",
"instanceName": "is_IS_Bidder",
"instanceId": 1626702
},
{
"providerName": "AdColony",
"instanceName": "Default",
"instanceId": 0
},
{
"providerName": "ironSource",
"instanceName": "Default",
"instanceId": 0
}
]
},
"isAllCountries": true
}
]
}
}
Update Mediation Groups
Description
Use this API to update the mediation group’s name, position, targeted countries, targeted segments and waterfall setup.
General notes:
- Supports updating of only one mediation group per call.
- If ‘adSourcePriority’ is included in the call, and “manualHigh” and “manualLow” parameters are set, the instances will be placed based on their order in the call itself.
- Any optional parameter that is not included in the call (‘groupName’, ‘groupPosition’, ‘groupSegments’, ‘groupCountries’ or ‘adSourcePriority’) will not impact the group’s existing setup.
- Any optional parameter that is included in the call (‘groupName’, ‘groupPosition’, ‘groupSegments’, ‘groupCountries’ or ‘adSourcePriority’) will replace the group’s existing setup.
Authentication Type
Method
PUT https://platform.ironsrc.com/partners/publisher/mediation/management/v1?
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 newly targeted segments |
| groupCountries | String array | the desired group’s newly targeted 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 | String array | the desired group’s newly waterfall setup. Can include 3 sections: ‘manualHigh’, ‘auto’, ‘manualLow’, ‘bidders’ |
Request Example URL
https://platform.ironsrc.com/partners/publisher/mediation/management/v1?appKey=8a2cbac5
Request Body Example
{
"appKey": "8a2cbac5",
"groupId": "275903",
"groupName": "Japan_High",
"groupPosition": "1",
"countries": [
"JP"
],
"adSourcePriority": {
"bidders": [
{
"providerName": "AdColony",
"instanceId": 1626704
},
{
"providerName": "ironSource",
"instanceId": 1626701
}
],
"manualHigh": [
{
"providerName": "ironSource",
"instanceName": "Default",
"instanceId": 0
}
],
"auto": [
{
"providerName": "AdColony",
"instanceName": "Default",
"instanceId": 0
}
]
}
}
JSON Example Response
{
"appKey": "8a2cbac5",
"adUnits": {
"rewardedVideo": [
{
"groupName": "Japan_High",
"groupId": 275903,
"groupPosition": 1,
"groupSegments": [],
"groupAbVersion": "N/A",
"groupCountries": [
"JP"
],
"adSourcePriority": {
"bidders": [
{
"providerName": "AdColony",
"instanceId": 1626704
},
{
"providerName": "ironSource",
"instanceId": 1626701
}
],
"manualHigh": [
{
"providerName": "ironSource",
"instanceName": "Default",
"instanceId": 0
}
],
"auto": [
{
"providerName": "AdColony",
"instanceName": "Default",
"instanceId": 0
}
]
}
},
{
"groupName": "US_High",
"groupId": 275112,
"groupPosition": 2,
"groupSegments": [
{
"id": "6112",
"name": "age_Over_16"
}
],
"groupAbVersion": "N/A",
"groupCountries": [
"US"
],
"adSourcePriority": {
"bidders": [
{
"providerName": "AdColony",
"instanceId": 1626704
},
{
"providerName": "ironSource",
"instanceId": 1626701
}
],
"auto": [
{
"providerName": "AdColony",
"instanceName": "Default",
"instanceId": 0
},
{
"providerName": "ironSource",
"instanceName": "Default",
"instanceId": 0
}
]
}
},
{
"groupName": "All Countries",
"groupId": 275110,
"groupPosition": 3,
"groupSegments": [],
"groupAbVersion": "N/A",
"groupCountries": [
"*"
],
"adSourcePriority": {
"bidders": [
{
"providerName": "AdColony",
"instanceId": 1626704
},
{
"providerName": "ironSource",
"instanceId": 1626701
}
],
"auto": [
{
"providerName": "AdColony",
"instanceName": "Default",
"instanceId": 0
},
{
"providerName": "ironSource",
"instanceName": "Default",
"instanceId": 0
}
]
},
"isAllCountries": true
}
],
"interstitial": [
{
"groupName": "All Countries",
"groupId": 275111,
"groupPosition": 1,
"groupSegments": [],
"groupAbVersion": "N/A",
"groupCountries": [
"*"
],
"adSourcePriority": {
"bidders": [
{
"providerName": "AdColony",
"instanceId": 1626706
}
],
"auto": [
{
"providerName": "ironSource",
"instanceName": "is_IS_Bidder",
"instanceId": 1626702
},
{
"providerName": "AdColony",
"instanceName": "Default",
"instanceId": 0
},
{
"providerName": "ironSource",
"instanceName": "Default",
"instanceId": 0
}
]
},
"isAllCountries": true
}
]
}
}
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/v1?
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/v1?groupId=182641&appKey=8a2edd51
JSON Example Response
{
"appKey": "8a2edd51",
"adUnits": {
"rewardedVideo": [
{
"groupName": "Tier 1",
"groupId": 182951,
"groupPosition": 1,
"groupSegments": [],
"groupCountries": [
"AU",
"CN",
"DE",
"GB",
"US"
],
"adSourcePriority": {
"auto": [
{
"providerName": "AdColony",
"instanceName": "Default",
"instanceId": 0
},
{
"providerName": "ironSource",
"instanceName": "Default",
"instanceId": 0
}
]
}
},
{
"groupName": "All Countries",
"groupId": 182637,
"groupPosition": 2,
"groupSegments": [],
"groupCountries": [
"*"
],
"adSourcePriority": {
"auto": [
{
"providerName": "AdColony",
"instanceName": "Default",
"instanceId": 0
},
{
"providerName": "ironSource",
"instanceName": "Default",
"instanceId": 0
}
]
},
"isAllCountries": true
}
],
"interstitial": [
{
"groupName": "All Countries",
"groupId": 182638,
"groupPosition": 1,
"groupSegments": [],
"groupCountries": [
"*"
],
"adSourcePriority": {
"auto": [
{
"providerName": "ironSource",
"instanceName": "Default",
"instanceId": 0
}
]
},
"isAllCountries": true
}
],
"banner": [
{
"groupName": "All Countries",
"groupId": 182639,
"groupPosition": 1,
"groupSegments": [],
"groupCountries": [
"*"
],
"adSourcePriority": {
"auto": [
{
"providerName": "ironSource",
"instanceName": "Default",
"instanceId": 0
}
]
},
"isAllCountries": true
}
]
}
}