Groups API v3

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

  • Managing mediation groups setup
  • Managing WaterFalls 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/v3/

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/v3/142401ac1/

Response Parameters

Name Description Example
id Unique group ID generated by Levelplay platform on group creation 2432228
name The group name SpeakingEnglish
adUnit rewardedVideo, interstitial, banner or native banner
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 adColony
isBidder true for bidder instances, otherwise false. false
tierPosition The tier position which the instance belongs to. For non-bidding instances only.  2
capping Number of maximum ads delivered per day. Should be in the range of 0-10 4
groupRate Used to prioritize the instance in your waterfall. Should be in the range 0.01-1000 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-1000 Read more. 9

Response Example 

[
  {
	 "id": 12673,
   "adUnit": "rewardedVideo",
   "abTest" "A",
 	 "name": "newGroup",      
   "countries": ['FR', 'US'],
	 "position": 1,
   "segments": [],
	 "floorPrice": 0.3,
	 "instances": [
{
   "id": 3681,
   "name": "Default",
   "networkName": "ironSource"
},
{
   "id": 2,
   "name": "Default"
   "isBidder": false,
   "tierPosition": 2,
   "networkName": "AdColony",
   "groupRate": 5,
   "capping": 1,
   "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/v3/

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/v3/142401ac1/

Supported Parameters

Name Type Description Mandatory Parameter Default      value Example
name String

The newly created group’s name 

Length should be in range 1 to 32.

Tier 1
adUnit String “rewardedVideo”, “interstitial”, “banner” native
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 “A” 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.

x Include All Countries  US, GB
segments Array of String An array of segments names  x under30, femaleOnly
instances Array List of instances to update x
These are the following instance fields in the ‘instances’ array
id Number Instance ID as sent in LevelPlay Instances API 124526
tierPosition Number The position tier which the instance belongs to. 2 2
capping Number Number of max ads delivered. Should be in range 0-10. x 2
groupRate Number Used only to prioritize the instance in your waterfall. Should be in the range 0.01-1000 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-1000 Read more. 2.4

Request Example 

[
  {
 	 "name": "new group",      
   "adUnit": "rewardedVideo",
	 "countries": ["FR", "US"],
	 "position": 1,
      "segments": [nonPaying],
	 "abTest": "B",
	 "floorPrice?": 0.3,
	 "instances?": [
{
  "id": 7983541,
  "tierPosition?": 2,
  "groupRate": 2,
  "capping": 4,
  "countriesRate": [{
	"countryCode": "FR",
	"rate": 1
   }]
},
{
	"id": 4896357,
 },
{
  "id": 62624583,
  "tierPosition": 1,
  "countriesRat": [{
	"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 remove the capping, simply add the field parameter with null value.
  4. To update an array field, include all values (new and existing).

Method

PUT https://platform.ironsrc.com/levelPlay/groups/v3/

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/v3/142401ac1/

Supported Parameters

Name Type Description Mandatory Parameter Default      value Example
id Number Group ID as sent in the GET request
name 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.

x AllCountries  US, GB
segments Array of String An array of segment names  x under30, femaleOnly
instances Array List of instances to update x All instances are configed to the app
These are the following instance fields in the ‘instances’ array
id Number Instance ID as sent in LevelPlay Instances API 123658
tierPosition Number

The position which the instance belongs to.

1 / 2 / 3

x 2 2
capping Number Number of  max ads delivered. Should be in range 0-10 x 2
groupRate Number Used only to prioritize the instance in your waterfall. Should be in the range 0.01-1000. 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-1000. Read more. 2.5

Request Example

[
  {
	 "id": 123,
 	 "name": "new group",      
   "countries": ['FR', 'US'],
	 "position": 1,
      "segments": [],
	 "floorPrice": 0.3,
	 "instances": [
{
  "id": 1  "tierPosition?": 1,
  "groupRate": null,
  "capping": null,
  "countriesRate: [{
	"countryCode": "FR"
	"rate": 1
   }]
},
{
  "id": 2
  "tierPosition": 1,
  "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/v3/

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/v3/142401ac1/

Supported Parameters

Name Type Description Mandatory Parameter Default      value 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].name": ""
            }
        },
        {
            "code": ERR-311,
            "errorMessage": "Group position value is not valid",
            "params": {
                "[0].position": ""
            }
        }
    ],
    "code": 400
}