Ad Units API v1

Use this API to manage ad units on the LevelPlay dashboard. The API supports the following:

Create and update ad units
Managing ad units configurations

Requests are limited to 1 application per call.

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 ad units.

Method

GET https://platform.ironsrc.com/levelPlay/adUnits/v1/{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/adUnits/v1/142401ac1/

Response Parameters

Name	Description	Example
mediationAdUnitId	Unique ad unit ID generated by LevelPlay platform on ad unit creation	fgx25t56dq201bd2
mediationAdUnitName	The ad unit name	interstitial-1
adFormat	rewarded, interstitial, banner or native	interstitial
hasAbTest	Indicates if an A/B test is active (true for active, false otherwise)	false
isPaused	Indicates whether the ad unit is currently paused (true if paused, false if active)	false
reward	Represents a reward, the name and amount of the reward. Relevant only for rewarded ad format
These are the following reward fields in the ‘reward’ parameter
rewardItemName	Specifies the name of the reward item	Virtual Item
rewardAmount	Indicates the amount or value of the reward	1
settings	List of settings which belong to the ad unit
These are the following settings fields in the ‘settings’ array
testGroup	The settings test it is related to	A
cappingEnabled	Indicates if a cap or limit is enforced (true if enabled, false otherwise). Relevant only for rewarded and interstitial ad formats	true
cappingLimit	Specifies the maximum cap value for an ad unit	2
cappingInterval	Defines the time interval, ‘d’ (day) or ‘h’ (hour)	d
pacingEnabled	Indicates if pacing is active (true if enabled, false otherwise). Relevant only for rewarded and interstitial ad formats	false
pacingMinutes	Specifies the pacing interval in minutes	5.2
bannerRefreshRate	Sets the refresh rate for the banner in seconds. Relevant only for banner ad format	10

Response Example

[
    {
        "mediationAdUnitId": "fgx25t56dq201bd2",
        "mediationAdUnitName": "Banner",
        "adFormat": "banner",
        "hasAbTest": true,
        "isPaused": false,
        "settings": [
            {
                "testGroup": "A",
                "bannerRefreshRate": 15
            },
            {
                "testGroup": "B",
                "bannerRefreshRate": 20
            }
        ]
    },
    {
        "mediationAdUnitId": "8oe7wr90gbsbaj74",
        "mediationAdUnitName": "Interstitial",
        "adFormat": "interstitial",
        "hasAbTest": false,
        "isPaused": false,
        "settings": [
            {
                "testGroup": null,
                "cappingEnabled": false,
                "pacingEnabled": false
            }
        ]
    },
    {
        "mediationAdUnitId": "v5ipmsg9d4hiqp60",
        "mediationAdUnitName": "Native",
        "adFormat": "native",
        "hasAbTest": false,
        "isPaused": false,
        "settings": [
            {
                "testGroup": null
            }
        ]
    },
    {
        "mediationAdUnitId": "33o8iowbyf3vvof2",
        "mediationAdUnitName": "Rewarded",
        "adFormat": "rewarded",
        "hasAbTest": false,
        "isPaused": false,
        "reward": {
            "rewardItemName": "Virtual Item",
            "rewardAmount": 1
        },
        "settings": [
            {
                "testGroup": null,
                "cappingEnabled": true,
                "cappingLimit": 2,
                "cappingInterval": "d", 
                "pacingEnabled": true,
                "pacingMinutes": 5.2
            }
        ]
    }
]

CREATE

Description
Use this API to create mediation ad units. This API allows you to create multiple ad units with a single API call. The “settings” parameter allows you to define specific configurations for each ad unit.

Note:

This API allows you to create multiple ad units with a single API call
The Ad Unit ID value is reachable using GET call to this API

Method

POST https://platform.ironsrc.com/levelPlay/adUnits/v1/{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/adUnits/v1/142401ac1/

Supported Parameters

Name	Type	Description	Mandatory	Example
mediationAdUnitName	String	The newly created ad unit’s name Length should be in range 1 to 255	✓	Interstitial-1
adFormat	String	rewarded, interstitial, banner, native	✓	interstitial
reward	Object	Represents a reward, the name and amount of the reward. Relevant only for rewarded ad format Mandatory if ad format is rewarded	x
rewardItemName	String	Specifies the name of the reward item Length should be in range 1 to 32	✓	Virtual Item
rewardAmount	Number	Indicates the amount or value of the reward	✓	1
settings	Array	List of settings. If not specified, the default values will be set.	x
These are the following settings fields in the ‘settings’ array
testGroup	String	The AB test group it is related to. testGroup value should be ‘null’ or not sent in case there is no AB test	x	null
cappingEnabled	Boolean	Indicates if a cap or limit is enforced (true if enabled, false otherwise). Relevant only for rewarded and interstitial ad formats	x	true
cappingLimit	Number	Specifies the maximum cap value for the ad unit	x	5
cappingInterval	String	Defines the time interval, ‘d’ (day) or ‘h’ (hour)	x	d
pacingEnabled	Boolean	Indicates if pacing is active (true if enabled, false otherwise). Relevant only for rewarded and interstitial ad formats	x	true
pacingMinutes	Number	Specifies the pacing interval in minutes. float number maximum value is 1000	x	4.6
bannerRefreshRate	Number	Sets the refresh rate for the banner in seconds. Relevant only for banner ad format. Default value in case not being sent: 25 Possible values are 0,10,15,20,25,30,45,60,120 and 240	x	10

Request Example

[
  {
    "mediationAdUnitName": "interstitial-1",
    "adFormat": "interstitial",
    "settings": [
      {
        "testGroup": null,
        "cappingEnabled": true,
        "cappingInterval": "d",
        "cappingLimit": 5,
        "pacingEnabled": true,
        "pacingMinutes": 4.6
      }
    ]
  },
  {
    "mediationAdUnitName": "banner-1",
    "adFormat": "banner",
    "settings": [
      {
        "bannerRefreshRate": 10
      }
    ]
  },
  {
    "mediationAdUnitName": "rewarded-1",
    "adFormat": "rewarded",
    "reward": {
      "rewardItemName": "Virtual Item",
      "rewardAmount": 1
    }
  }
]

UPDATE

Description

Use this API to update mediation ad units setup

Notes:

Multiple ad units can be updated with a single API call

Method

PUT https://platform.ironsrc.com/levelPlay/adUnits/v1/{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/adUnits/v1/142401ac1/

Supported Parameters

Name	Type	Description	Mandatory	Example
mediationAdunitId	String	ad unit ID as sent in the GET request	✓	fgx25t56dq201bd2
mediationAdUnitName	String	The newly created ad unit’s name Length should be in range 1 to 255	x	interstitial-1
isPaused	Boolean	Indicates whether the ad unit is currently paused (true if paused, false if active) Should be true to pause the ad unit, or false to unpause the ad unit	x	false
reward	Object	Represents a reward, the name and amount of the reward. Relevant only for rewarded ad format Mandatory if ad format is rewarded	x
rewardItemName	String	Specifies the name of the reward item Length should be in range 1 to 32	✓	Virtual Item
rewardAmount	Number	Indicates the amount or value of the reward	✓	1
settings	Array	List of settings. If not specified, the default values will be set.	x
These are the following settings fields in the ‘settings’ array
testGroup	String	The AB test group it is related to. null/”A”/”B”	x	null
cappingEnabled	Boolean	Indicates if a cap or limit is enforced (true if enabled, false otherwise). Relevant only for rewarded and interstitial ad formats	x	true
cappingLimit	Number	Specifies the maximum cap value for the ad unit	x	5
cappingInterval	String	Defines the time interval, ‘d’ (day) or ‘h’ (hour)	x	d
pacingEnabled	Boolean	Indicates if pacing is active (true if enabled, false otherwise). Relevant only for rewarded and interstitial ad formats	x	true
pacingMinutes	Number	Specifies the pacing interval in minutes. float number maximum value is 1000	x	4.6
bannerRefreshRate	Number	Sets the refresh rate for the banner in seconds. Relevant only for banner ad format. Default value in case not being sent: 25 Possible values are 0,10,15,20,25,30,45,60,120 and 240.	x	10

Request Example

[
  {
    "mediationAdUnitId": "fgx25t56dq201bd2",
    "mediationAdUnitName": "interstitial-1",
    "settings": [
      {
        "testGroup": null,
        "cappingEnabled": true,
        "cappingInterval": "d",
        "cappingLimit": 5,
        "pacingEnabled": false
      }
    ]
  },
  {
    "mediationAdUnitId": "agv25t56g6hj01bd2",
    "mediationAdUnitName": "banner-1",
    "settings": [
      {
        "testGroup": "A",
        "bannerRefreshRate": 30
      },
      {
        "testGroup": "B",
        "bannerRefreshRate": 10
      }
    ]
  },
  {
    "mediationAdUnitId": "qtr25t56dq201bd2",
    "reward": {
      "rewardItemName": "Virtual Item",
      "rewardAmount": 1
    }
  }
]

Success

A successful response will be sent with HTTP code 200.

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-4332",
            "errorMessage": "cappingInterval value must be either 'd' (days) or 'h' (hours)",
            "params": {
                "[0].settings[0].cappingInterval": "s"
            }
        }
    ],
    "code": 400
}