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

Bearer API authentication

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:

  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 and ad unit will be placed within the waterfall’s ‘tier 2’ section of the newly created group on ‘sortByCPM tierType.
  3. If ‘tierType’ is missing in the call – ‘tier 1’, ‘tier 2’ and ‘tier 3’ default type will be ‘sortByCPM’
  4. Bidding sources will be automatically set to tierType: ‘bidding’
  5. If ‘groupPosition’ is missing in the call, the newly created group will be placed on top of the existing groups.
  6. 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

Bearer API authentication

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:

  1. Supports updating of only one mediation group per call.
  2. 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.
  3. 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.
  4. 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

Bearer API authentication

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:

  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/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": []
      }
    ]
  }
}