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.

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

Bearer API authentication

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": "813df9s5",
  "appName": "My App",
  "appStatus": "active",
  "platform": "iOS",
  "bundleId": "com.my.app",
  "adUnits": {
    "banner": [
      {
        "groupName": "US",
        "groupId": 185919,
        "groupPosition": 1,
        "groupSegments": [],
        "groupCountries": [
          "US"
        ],
        "adSourcePriority": {
          "auto": [
            {
              "providerName": "Facebook",
              "instanceName": "Banner_HighCPM",
              "instanceId": 1054777
            },
            {
              "providerName": "Facebook",
              "instanceName": "Banner_AnyPrice",
              "instanceId": 0
            },
            {
              "providerName": "AppLovin",
              "instanceName": "Default",
              "instanceId": 0
            }
          ]
        }
      },
      {
        "groupName": "All Countries",
        "groupId": 119625,
        "groupPosition": 2,
        "groupSegments": [],
        "groupCountries": [
          "*"
        ],
        "adSourcePriority": {
          "manualHigh": [
            {
              "providerName": "Facebook",
              "instanceName": "Banner_HighCPM",
              "instanceId": 1054777
            }
          ],
          "auto": [
            {
              "providerName": "AppLovin",
              "instanceName": "Default",
              "instanceId": 0
            },
            {
              "providerName": "Facebook",
              "instanceName": "Banner_AnyPrice",
              "instanceId": 0
            }
          ]
        },
        "isAllCountries": true
      }
    ],
    "interstitial": [
      {
        "groupName": "US",
        "groupId": 185917,
        "groupPosition": 1,
        "groupSegments": [],
        "groupCountries": [
          "US"
        ],
        "adSourcePriority": {
          "manualHigh": [
            {
              "providerName": "ironSource",
              "instanceName": "Default",
              "instanceId": 0
            }
          ],
          "auto": [
            {
              "providerName": "Facebook",
              "instanceName": "FB_Interstitial_HighCPM",
              "instanceId": 1054773
            },
            {
              "providerName": "Facebook",
              "instanceName": "FB_Interstitial_AnyPrice",
              "instanceId": 0
            }
          ]
        }
      },
      {
        "groupName": "All Countries",
        "groupId": 119627,
        "groupPosition": 2,
        "groupSegments": [],
        "groupCountries": [
          "*"
        ],
        "adSourcePriority": {
          "auto": [
            {
              "providerName": "Facebook",
              "instanceName": "FB_Interstitial_HighCPM",
              "instanceId": 1054773
            },
            {
              "providerName": "Facebook",
              "instanceName": "FB_Interstitial_AnyPrice",
              "instanceId": 0
            },
            {
              "providerName": "ironSource",
              "instanceName": "Default",
              "instanceId": 0
            }
          ]
        },
        "isAllCountries": true
      }
    ],
    "rewardedVideo": [
      {
        "groupName": "United States Ad Whales",
        "groupId": 2617,
        "groupPosition": 1,
        "groupSegments": [
          {
            "id": "3205",
            "name": "US Ad Whales"
          }
        ],
        "groupCountries": [
          "US"
        ],
        "adSourcePriority": {
          "manualHigh": [
            {
              "providerName": "ironSource",
              "instanceName": "Default",
              "instanceId": 0
            },
            {
              "providerName": "AppLovin",
              "instanceName": "Default",
              "instanceId": 0
            },
            {
              "providerName": "Facebook",
              "instanceName": "FB_RV_HighCPM",
              "instanceId": 0
            }
          ],
          "auto": [
            {
              "providerName": "Facebook",
              "instanceName": "FB_RV_AnyPrice",
              "instanceId": 1054769
            },
            {
              "providerName": "UnityAds",
              "instanceName": "Default",
              "instanceId": 0
            }
          ]
        }
      },
      {
        "groupName": "US",
        "groupId": 185913,
        "groupPosition": 2,
        "groupSegments": [],
        "groupCountries": [
          "US"
        ],
        "adSourcePriority": {
          "auto": [
            {
              "providerName": "Facebook",
              "instanceName": "FB_RV_AnyPrice",
              "instanceId": 1054769
            },
            {
              "providerName": "Facebook",
              "instanceName": "FB_RV_HighCPM",
              "instanceId": 0
            },
            {
              "providerName": "AppLovin",
              "instanceName": "Default",
              "instanceId": 0
            },
            {
              "providerName": "UnityAds",
              "instanceName": "Default",
              "instanceId": 0
            },
            {
              "providerName": "ironSource",
              "instanceName": "Default",
              "instanceId": 0
            }
          ]
        }
      },
      {
        "groupName": "Turkey",
        "groupId": 2613,
        "groupPosition": 3,
        "groupSegments": [],
        "groupCountries": [
          "TR"
        ],
        "adSourcePriority": {
          "manualHigh": [
            {
              "providerName": "Facebook",
              "instanceName": "FB_RV_HighCPM",
              "instanceId": 0
            }
          ],
          "auto": [
            {
              "providerName": "Facebook",
              "instanceName": "FB_RV_AnyPrice",
              "instanceId": 1054769
            },
            {
              "providerName": "ironSource",
              "instanceName": "Default",
              "instanceId": 0
            },
            {
              "providerName": "AppLovin",
              "instanceName": "Default",
              "instanceId": 0
            },
            {
              "providerName": "UnityAds",
              "instanceName": "Default",
              "instanceId": 0
            }
          ]
        }
      },
      {
        "groupName": "Tier 1",
        "groupId": 2577,
        "groupPosition": 4,
        "groupSegments": [],
        "groupCountries": [
          "AU",
          "CN",
          "DE",
          "GB"
        ],
        "adSourcePriority": {
          "manualHigh": [
            {
              "providerName": "AppLovin",
              "instanceName": "Default",
              "instanceId": 0
            }
          ],
          "auto": [
            {
              "providerName": "Facebook",
              "instanceName": "FB_RV_HighCPM",
              "instanceId": 0
            },
            {
              "providerName": "ironSource",
              "instanceName": "Default",
              "instanceId": 0
            },
            {
              "providerName": "UnityAds",
              "instanceName": "Default",
              "instanceId": 0
            },
            {
              "providerName": "Facebook",
              "instanceName": "FB_RV_AnyPrice",
              "instanceId": 1054769
            }
          ]
        }
      },
      {
        "groupName": "All Countries",
        "groupId": 2557,
        "groupPosition": 5,
        "groupSegments": [],
        "groupCountries": [
          "*"
        ],
        "adSourcePriority": {
          "auto": [
            {
              "providerName": "Facebook",
              "instanceName": "FB_RV_AnyPrice",
              "instanceId": 1054769
            },
            {
              "providerName": "Facebook",
              "instanceName": "FB_RV_HighCPM",
              "instanceId": 0
            },
            {
              "providerName": "AppLovin",
              "instanceName": "Default",
              "instanceId": 0
            },
            {
              "providerName": "UnityAds",
              "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:

  1. Supports creation of only one mediation group per call.
  2. 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.
  3. 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.
  4. If ‘groupPosition’ is missing in the call, the newly created group will be placed on top of the existing groups.

Authentication Type

Bearer API authentication

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’


Request Example URL

https://platform.ironsrc.com/partners/publisher/mediation/management/v1?appKey=8a5513f5

Request Body Example 

{
    "appKey": "881ffb4d",
    "adUnit": "rewardedVideo",
    "groupCountries": [
        "US"
    ],
    "groupName": "US_high",
    "groupSegments": [
        3641
    ],
    "adSourcePriority": {
        "manualHigh": [
            {
                "providerName": "ironSource",
                "instanceId": 0
            }
        ],
        "auto": [
            {
                "providerName": "Facebook",
                "instanceId": 0
            }
        ],
        "manualLow": [
            {
                "providerName": "Chartboost",
                "instanceId": 0
            }
        ]
    }
}

JSON Example Response

{
  "appKey": "881ffb4d",
  "adUnits": {
    "rewardedVideo": [
      {
        "groupName": "US_high",
        "groupId": 197721,
        "groupPosition": 1,
        "groupSegments": [
          {
            "id": "3641",
            "name": "under_18"
          }
        ],
        "groupCountries": [
          "US"
        ],
        "adSourcePriority": {
          "manualHigh": [
            {
              "providerName": "ironSource",
              "instanceName": "Default",
              "instanceId": 0
            }
          ],
          "auto": [
            {
              "providerName": "Facebook",
              "instanceName": "Default",
              "instanceId": 0
            }
          ],
          "manualLow": [
            {
              "providerName": "Chartboost",
              "instanceName": "Default",
              "instanceId": 0
            }
          ]
        }
      },
      {
        "groupName": "All Countries",
        "groupId": 174959,
        "groupPosition": 2,
        "groupSegments": [],
        "groupCountries": [
          "*"
        ],
        "adSourcePriority": {
          "auto": [
            {
              "providerName": "Facebook",
              "instanceName": "Default",
              "instanceId": 0
            },
            {
              "providerName": "Chartboost",
              "instanceName": "Default",
              "instanceId": 0
            },
            {
              "providerName": "ironSource",
              "instanceName": "Default",
              "instanceId": 0
            }
          ]
        },
        "isAllCountries": true
      }
    ],
    "interstitial": [
      {
        "groupName": "All Countries",
        "groupId": 174961,
        "groupPosition": 1,
        "groupSegments": [],
        "groupCountries": [
          "*"
        ],
        "adSourcePriority": {
          "auto": [
            {
              "providerName": "Chartboost",
              "instanceName": "Default",
              "instanceId": 0
            },
            {
              "providerName": "ironSource",
              "instanceName": "Default",
              "instanceId": 0
            }
          ]
        },
        "isAllCountries": true
      }
    ],
    "banner": [
      {
        "groupName": "All Countries",
        "groupId": 194639,
        "groupPosition": 1,
        "groupSegments": [],
        "groupCountries": [
          "*"
        ],
        "adSourcePriority": {
          "auto": [
            {
              "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:

  1. Supports updating of only one mediation group per call.
  2. 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.
  3. Any optional parameter that is not included in the call (‘groupName’, ‘groupPosition’, ‘groupSegments’, ‘groupCountries’ or ‘adSourcePriority’) will not impact the group’s existing setup.
  4. Any optional parameter that is included in the call (‘groupName’, ‘groupPosition’, ‘groupSegments’, ‘groupCountries’ or ‘adSourcePriority’) will replace the group’s existing setup.

Authentication Type

Bearer API authentication

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’


Request Example URL

https://platform.ironsrc.com/partners/publisher/mediation/management/v1?appKey=8a2cbac5

Request Body Example 

{
    "appKey": "881ffb4d",
    "groupId": "197721",
    "groupName": "Israel_high",
    "groupPosition": "1",
    "countries": [
        "IL"
    ],
    "segments": [
        "3641"
    ],
    "adSourcePriority": {
        "manualHigh": [
            {
                "providerName": "Facebook",
                "instanceId": "0"
            }
        ],
        "auto": [
            {
                "providerName": "Chartboost",
                "instanceId": "0",
                "instanceCapping": 3
            }
        ],
        "manualLow": [
            {
                "providerName": "ironsource",
                "instanceId": "0"
            }
        ]
    }
}

JSON Example Response

 

{
  "appKey": "881ffb4d",
  "adUnits": {
    "rewardedVideo": [
      {
        "groupName": "Israel_high",
        "groupId": 197721,
        "groupPosition": 1,
        "groupSegments": [
          {
            "id": "3641",
            "name": "under_18"
          }
        ],
        "groupCountries": [
          "IL"
        ],
        "adSourcePriority": {
          "manualHigh": [
            {
              "providerName": "Facebook",
              "instanceName": "Default",
              "instanceId": 0
            }
          ],
          "auto": [
            {
              "providerName": "Chartboost",
              "instanceName": "Default",
              "instanceId": 0,
              "capping": {
                "value": 3,
                "interval": "session"
              }
            }
          ],
          "manualLow": [
            {
              "providerName": "ironSource",
              "instanceName": "Default",
              "instanceId": 0
            }
          ]
        }
      },
      {
        "groupName": "All Countries",
        "groupId": 174959,
        "groupPosition": 2,
        "groupSegments": [],
        "groupCountries": [
          "*"
        ],
        "adSourcePriority": {
          "auto": [
            {
              "providerName": "Facebook",
              "instanceName": "Default",
              "instanceId": 0
            },
            {
              "providerName": "Chartboost",
              "instanceName": "Default",
              "instanceId": 0
            },
            {
              "providerName": "ironSource",
              "instanceName": "Default",
              "instanceId": 0
            }
          ]
        },
        "isAllCountries": true
      }
    ],
    "interstitial": [
      {
        "groupName": "All Countries",
        "groupId": 174961,
        "groupPosition": 1,
        "groupSegments": [],
        "groupCountries": [
          "*"
        ],
        "adSourcePriority": {
          "auto": [
            {
              "providerName": "Chartboost",
              "instanceName": "Default",
              "instanceId": 0
            },
            {
              "providerName": "ironSource",
              "instanceName": "Default",
              "instanceId": 0
            }
          ]
        },
        "isAllCountries": true
      }
    ],
    "banner": [
      {
        "groupName": "All Countries",
        "groupId": 194639,
        "groupPosition": 1,
        "groupSegments": [],
        "groupCountries": [
          "*"
        ],
        "adSourcePriority": {
          "auto": [
            {
              "providerName": "ironSource",
              "instanceName": "Default",
              "instanceId": 0
            }
          ]
        },
        "isAllCountries": true
      }
    ]
  }
}

Delete Mediation Group

Description
Use this API to delete a mediation group

General notes:

  1. Can delete one mediation group per call.
  2. ‘All Countries’ default group cannot be deleted.
  3. Deleted mediation groups cannot be restored.
  4. Response includes all of the app’s mediation groups excluding the deleted ones.

Authentication Type

Bearer API authentication

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