Contact usContact us

Groups API v4

Important! API versions 3 and below will be deprecated by the end of March 2025. Please ensure you update to the latest version to avoid disruptions.

Use this API to manage mediation groups on the LevelPlay dashboard. The API supports the following:

  • Managing mediation groups setup
  • Managing Waterfall per mediation group

Requests are limited to 1 application per call.

Note: You can find the previous version of the API here

Rate limits

The API returns a 429 HTTP status code if a request exceeds 4000 requests in a time period of 30 minutes.

Authentication Type

Bearer API authentication

GET

Description

Get the list of your application groups. 

Method

GET https://platform.ironsrc.com/levelPlay/groups/v4/{appKey}

Request Parameters

Name Type Description Example
appKey String application key (as seen on the platform) 142401ac1

Request Example URL

https://platform.ironsrc.com/levelPlay/groups/v4/142401ac1/

Response Parameters

Name Description Example
groupId Unique group ID generated by LevelPlay platform on group creation 2432228
groupName The group name SpeakingEnglish
mediationAdUnitId ID of the ad unit to which the group belongs fgx25t56dq201bd2
mediationAdUnitName Name of the ad unit to which the group belongs interstitial-1
adFormat rewarded, interstitial, banner or native interstitial
abTest The group test it is related to A
position The position of group in the list 1
floorPrice The minimum bid per impression, expressed as CPM  1.3
countries List of country codes which belong to the group US, GB
segments List of segments names which belong to the group under30, femaleOnly
instances  List of instances which belong to the group
These are the following instance fields in the ‘instances’ array
id Instance ID as sent in LevelPlay Instances API 128395
name The instance name Rewarded50
networkName The ad network the instance belongs to unityAds
isBidder true for bidder instances, otherwise false false
groupRate Used to prioritize the instance in your waterfall. Should be in the range 0.01-3000 Read more 11.9
countriesRate List of countries rates which Different from the group level rate
These are the following countryRate fields in the ‘countriesRate’ array
countryCode Country code which is defined by a 2 letter country code as per ISO 3166-1 Alpha-2 GB
rate Used to prioritize the instance in your waterfall and for reporting. Should be in the range 0.01-3000 Read more 9

Response Example 

[
  {
    "groupId": 12673,
    "groupName": "newGroup",
    "mediationAdUnitId": "fgx25t56dq201bd2",
    "mediationAdUnitName": "interstitial-1",
    "adFormat": "interstitial",
    "abTest": "A",
    "countries": ["FR","US"],
    "position": 1,
    "segments": [],
    "floorPrice": 0.3,
    "instances": [
      {
        "id": 3681,
        "name": "",
        "networkName": "ironSource",
        "isBidder": true
      },
      {
        "id": 2,
        "name": "Default",
        "isBidder": false,
        "networkName": "unityAds",
        "groupRate": 5,
        "countriesRate": [
          {
            "countryCode": "FR",
            "rate": 1
          }
        ]
      }
    ]
  }
]

CREATE

Description
Use this API to create mediation groups. This API allows you to create multiple groups with a single API call. Use the “instances” parameter to determine each instance to include/exclude in a group. The instance ID value is reachable using the Instances API.

Note:

  1. This API allows you to create multiple groups with a single API call.
  2. The Group Id value is reachable using Get call to this API
  3. The instance ID value is reachable using the Instances API.

Method

POST https://platform.ironsrc.com/levelPlay/groups/v4/{appKey}

Request Parameters

Name Type Description Example
appKey String application key (as seen on the platform) 142401ac1

Request Example URL

https://platform.ironsrc.com/levelPlay/groups/v4/142401ac1/

Supported Parameters

Name Type Description Mandatory Example
groupName String The newly created group’s name 
Length should be in range 1 to 32.		 ✓ Tier 1
adFormat String rewarded, interstitial, banner, native ✓ interstitial
mediationAdUnitId String ID of the ad unit to which the group belongs
Mandatory if multiple ad units exist for the ad format		 x fgx25t56dq201bd2
position Number The position of group in the list of groups
Should be between 1 to maximum groups at the list (except allCountries group)		 ✓ 2
abTest String The AB test group it is related to.
“A”, “B” 		 x B
floorPrice Number The minimum bid per impression, expressed as a CPM x 15
countries Array of String An array of country codes 
which is defined by a 2 letter country code as per ISO 3166-1 Alpha-2. If not specified, the default will include allCountries		 x US, GB
segments Array of String An array of segments names  x under30, femaleOnly
instances Array List of instances to update. If not specified, the default will include all instances configured to the ad format x
These are the following instance fields in the ‘instances’ array
id Number Instance ID as sent in LevelPlay Instances API ✓ 124526
groupRate Number Used only to prioritize the instance in your waterfall. Should be in the range 0.01-3000
Read more		 x 0.6
countriesRate Array List of country rate to update x
These are the following countryRate fields in the ‘countriesRate’ array
countryCode String country code. which is defined by a 2 letter country code as per ISO 3166-1 Alpha-2 ✓ AU
rate Number Used only to prioritize the instance in your waterfall. Should be in the range 0.01-3000
Read more		 ✓ 2.4

Request Example 

[
  {
    "groupName": "new group",
    "adFormat": "rewarded",
    "mediationAdUnitId": "fgx25t56dq201bd2",
    "countries": ["FR","US"],
    "position": 1,
    "segments": ["nonPaying"],
    "abTest": "B",
    "floorPrice": 0.3,
    "instances": [
      {
        "id": 7983541,
        "groupRate": 2,
        "countriesRate": [
          {
            "countryCode": "FR",
            "rate": 1
          }
        ]
      },
      {
        "id": 4896357
      },
      {
        "id": 62624583,
        "countriesRate": [
          {
            "countryCode": "US",
            "rate": 5.3
          }
        ]
      }
    ]
  }
]

UPDATE

Description

Use this API to update mediation groups setup configuration and waterfalls

Notes:

  1. Multiple groups can be updated with a single API call
  2. To remove the groupRate/countryRate, simply add the field parameter with null value.
  3. To update an array field, include all values (new and existing).

Method

PUT https://platform.ironsrc.com/levelPlay/groups/v4/{appKey}

Request Parameters

Name Type Description Example
appKey String application key (as seen on the platform) 142401ac1

Request Example URL

https://platform.ironsrc.com/levelPlay/groups/v4/142401ac1/

Supported Parameters

Name Type Description Mandatory Example
groupId Number Group ID as sent in the GET request ✓ 12673
groupName String The newly created group’s name 
Length should be in range 1 to 32		 x Speaking English
position Number The position of group in the list of groups
Should be between 1 to maximum groups at the list (except allCountries group)		 x 2
floorPrice Number The minimum bid per impression, expressed as CPM x 15
countries Array of String An array of country codes 
which is defined by a 2 letter country code as per ISO 3166-1 Alpha-2. If not specified, the default will include allCountries		 x US, GB
segments Array of String An array of segment names  x under30, femaleOnly
instances Array List of instances to update. If not specified, the default will include all instances configured to the ad format x
These are the following instance fields in the ‘instances’ array
id Number Instance ID as sent in LevelPlay Instances API ✓ 123658
groupRate Number Used only to prioritize the instance in your waterfall. Should be in the range 0.01-3000. Read more x 0.6
countriesRate Array List of countryRate to update x
These are the following countryRate fields in the ‘countriesRate’ array
countryCode string Country code which is defined by a 2 letter country code  as per ISO 3166-1 Alpha-2 ✓ AU
rate Number Used only to prioritize the instance in your waterfall. Should be in the range 0.01-3000. Read more ✓ 2.5

Request Example

[
  {
    "groupId": 123,
    "groupName": "new group",
    "countries": ["FR","US"],
    "position": 1,
    "segments": [],
    "floorPrice": 0.3,
    "instances": [
      {
        "id": 1,
        "groupRate": null,
        "countriesRate": [
          {
            "countryCode": "FR",
            "rate": 1
          }
        ]
      },
      {
        "id": 2,
        "countriesRate": [
          {
            "countryCode": "FR",
            "rate": 1.4
          }
        ]
      }
    ]
  }
]

Success

A successful response will be sent with HTTP code 200.

DELETE

Description

Use this API to delete an instance.

Notes:

  1. The AllCountries group cannot be deleted.
  2. Deleted groups cannot be restored.

Method

DELETE https://platform.ironsrc.com/levelPlay/groups/v4/{appKey}

Request Parameters

Name Type Description Example
appKey String application key (as seen on the platform) 142401ac1

Request Example URL

https://platform.ironsrc.com/levelPlay/groups/v4/142401ac1/

Supported Parameters

Name Type Description Mandatory Example
ids Array of number Group IDs as sent in the GET request ✓ 12473, 47238

Request body example

{
    "ids": [1458, 5769]
}

Success

A successful response will be sent with HTTP code 200.

Errors

If one of the groups sent in the request is failing, an error array will be sent with HTTP code 400 and will cause the whole request to be rejected.

Each error will be followed with an error message.

Example

{
    "errorsArray": [
        {
            "code": ERR-208,
            "errorMessage": "Group name value is required",
            "params": {
                "[0].groupName": ""
            }
        },
        {
            "code": ERR-311,
            "errorMessage": "Group position value is not valid",
            "params": {
                "[0].position": ""
            }
        }
    ],
    "code": 400
}