Ad Units API v1

Configure and retrieve your mobile ad unit settings programmatically by using the Ad Units API v1 to streamline ad placement management.

Read time 15 minutes

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
GET

Description

Get the list of your application ad units. 

Method

GET https://platform.ironsrc.com/levelPlay/adUnits/v1/{appKey}

Request Parameters

NameTypeDescriptionExample
appKeyStringapplication key (as seen on the platform)142401ac1

Request Example URL

https://platform.ironsrc.com/levelPlay/adUnits/v1/142401ac1/

Response Parameters

NameDescriptionExample
mediationAdUnitIdUnique ad unit ID generated by LevelPlay platform on ad unit creationfgx25t56dq201bd2
mediationAdUnitNameThe ad unit nameinterstitial-1
adFormatrewarded, interstitial, banner or nativeinterstitial
hasAbTestIndicates if an A/B test is active (true for active, false otherwise)false
isPausedIndicates whether the ad unit is currently paused (true if paused, false if active)false
rewardRepresents 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
rewardItemNameSpecifies the name of the reward itemVirtual Item
rewardAmountIndicates the amount or value of the reward1
settingsList of settings which belong to the ad unit
These are the following settings fields in the ‘settings' array
testGroupThe settings test it is related toA
cappingEnabledIndicates if a cap or limit is enforced (true if enabled, false otherwise). Relevant only for rewarded and interstitial ad formatstrue
cappingLimitSpecifies the maximum cap value for an ad unit2
cappingIntervalDefines the time interval, 'd' (day) or 'h' (hour)d
pacingEnabledIndicates if pacing is active (true if enabled, false otherwise). Relevant only for rewarded and interstitial ad formatsfalse
pacingMinutesSpecifies the pacing interval in minutes5.2
bannerRefreshRateSets the refresh rate for the banner in seconds. Relevant only for banner ad format10

Response Example 

[code-snippet lang="jsonp"]

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

[/code-snippet]

CREATE
CREATE

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.

  • 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

NameTypeDescriptionExample
appKeyStringapplication key (as seen on the platform)142401ac1

Request Example URL

https://platform.ironsrc.com/levelPlay/adUnits/v1/142401ac1/

Supported Parameters

NameTypeDescriptionMandatoryExample
mediationAdUnitNameStringThe newly created ad unit's name Length should be in range 1 to 255✓Interstitial-1
adFormatStringrewarded, interstitial, banner, native✓interstitial
rewardObjectRepresents a reward, the name and amount of the reward. Relevant only for rewarded ad format Mandatory if ad format is rewardedx
rewardItemNameStringSpecifies the name of the reward item Length should be in range 1 to 32✓Virtual Item
rewardAmountNumberIndicates the amount or value of the reward✓1
settingsArrayList of settings. If not specified, the default values will be set.x
These are the following settings fields in the ‘settings' array
testGroupStringThe AB test group it is related to. testGroup value should be 'null' or not sent in case there is no AB testxnull
cappingEnabledBooleanIndicates if a cap or limit is enforced (true if enabled, false otherwise). Relevant only for rewarded and interstitial ad formatsxtrue
cappingLimitNumberSpecifies the maximum cap value for the ad unitx5
cappingIntervalStringDefines the time interval, 'd' (day) or 'h' (hour)xd
pacingEnabledBooleanIndicates if pacing is active (true if enabled, false otherwise). Relevant only for rewarded and interstitial ad formatsxtrue
pacingMinutesNumberSpecifies the pacing interval in minutes. float number maximum value is 1000x4.6
bannerRefreshRateNumberSets 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 240x10

Request Example 

[code-snippet lang="jsonp"]

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

[/code-snippet]

UPDATE
UPDATE

Description

Use this API to update mediation ad units setup

Multiple ad units can be updated with a single API call

Method

PUT https://platform.ironsrc.com/levelPlay/adUnits/v1/{appKey}

Request Parameters

NameTypeDescriptionExample
appKeyStringapplication key (as seen on the platform)142401ac1

Request Example URL

https://platform.ironsrc.com/levelPlay/adUnits/v1/142401ac1/

Supported Parameters

NameTypeDescriptionMandatoryExample
mediationAdunitIdStringad unit ID as sent in the GET request✓fgx25t56dq201bd2
mediationAdUnitNameStringThe newly created ad unit's name  Length should be in range 1 to 255xinterstitial-1
isPausedBooleanIndicates 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 unitxfalse
rewardObjectRepresents a reward, the name and amount of the reward. Relevant only for rewarded ad format Mandatory if ad format is rewardedx
rewardItemNameStringSpecifies the name of the reward item Length should be in range 1 to 32✓Virtual Item
rewardAmountNumberIndicates the amount or value of the reward✓1
settingsArrayList of settings. If not specified, the default values will be set.x
These are the following settings fields in the ‘settings' array
testGroupStringThe AB test group it is related to. null/"A"/"B"xnull
cappingEnabledBooleanIndicates if a cap or limit is enforced (true if enabled, false otherwise). Relevant only for rewarded and interstitial ad formatsxtrue
cappingLimitNumberSpecifies the maximum cap value for the ad unitx5
cappingIntervalStringDefines the time interval, 'd' (day) or 'h' (hour)xd
pacingEnabledBooleanIndicates if pacing is active (true if enabled, false otherwise). Relevant only for rewarded and interstitial ad formatsxtrue
pacingMinutesNumberSpecifies the pacing interval in minutes. float number maximum value is 1000x4.6
bannerRefreshRateNumberSets 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.x10

Request Example

[code-snippet lang="jsonp"]

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

[/code-snippet]

Success

A successful response will be sent with HTTP code 200.

Success
Success

A successful response will be sent with HTTP code 200.

Errors
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

[code-snippet lang="jsonp"]

{
    "errorsArray": [
        {
            "code": "ERR-4332",
            "errorMessage": "cappingInterval value must be either 'd' (days) or 'h' (hours)",
            "params": {
                "[0].settings[0].cappingInterval": "s"
            }
        }
    ],
    "code": 400
}

[/code-snippet]