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-2000 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-2000 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:

This API allows you to create multiple groups with a single API call.
The Group Id value is reachable using Get call to this API
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.	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-2000 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-2000 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:

Multiple groups can be updated with a single API call
To remove the groupRate/countryRate, simply add the field parameter with null value.
To remove the capping, simply add the field parameter with null value.
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-2000. 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-2000. 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:

The AllCountries group cannot be deleted.
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
}