Placements API
Manage placement configurations within your AIR app by creating, retrieving, updating, or deleting ad placements using the Placements API.
Read time 5 minutesLast updated 6 months ago
Use this API to manage your placements on the ad unit level in your LevelPlay account. This API will enable you to:
- Get your list of placements full details
- Create new placements, and define the placement ads delivery settings
- Update existing placements
- Delete (archive) placements
Note
You must authenticate each API request by using Bearer API authentication.
Get method
Description
Provides placement setup informationRequest
Request URL example
https://platform.ironsrc.com/partners/publisher/placements/v1/?appKey=\[REPLACE]Request parameters
Key | Type | Description | Value | Mandatory |
|---|---|---|---|---|
| appKey | string | Application unique identifier | v |
Response
Response Parameters
Key | Type | Description | Mandatory |
|---|---|---|---|
| adUnit | string | ad-unit name: rewardedVideo interstitial banner | v |
| name | string | placement unique name | v |
| id | integer | Placement unique identifier | v |
| adDelivery | integer | 1 if placement ad delivery is on, otherwise 0 | v |
| itemName | string | Reward name (max 30 chars) | v (rewardedVideo only) |
| rewardAmount | integer | Amount of items to gift for a single ad view (max 2000000000) | v (rewardedVideo only) |
| capping.enabled | integer | 1 to enable capping, otherwise 0 | |
| capping.limit | integer | Maximum number of ads delivered per capping interval (max 1000) | |
| capping.interval | string | capping interval: d - days h - hours | |
| pacing.enabled | integer | 1 to enable pacinhg, otherwise 0 | |
| pacing.minutes | float | Minimum gap in minutes between ad delivery (max 1000) |
Response body example
[ { "name": "Home_Screen", "id": 12, "adUnit": "rewardedVideo", "itemName": "Coins", "rewardAmount": 3, "adDelivery": 1, "capping": { "enabled": 1, "cappingLimit": 3, "cappingInterval": "h" }, "pacing": { "enabled": 1, "pacingMinutes": 12.5 }, "abVersion": "A" }]
Post method
Use this method to create new placements, include capping and pacing setup, in your application account Placements are created per ad unit types, each placement can be added per 1 ad unit only. The API support creation under the following ad units: Rewarded video- Interstitial
- Banner
- Placement name must be unique per ad unit type
- Multi placements creation in a single POST call is supported
- In response, you will receive a placementId. This parameter is not shown in the ironSource platform. You will need to use this parameter for PUT and DELETE methods
Request
Request body parameters
Key | Type | Description | Mandatory |
|---|---|---|---|
| appKey | string | Application key to create placements for | v |
| placements | array | List of placements to create | v |
| These are the following placement fields in the ‘placements' array | |||
| adUnit | string | ad-unit name: rewardedVideo interstitial banner | v |
| name | string | placement unique name | v |
| adDelivery | bolean | 1 if placement ad delivery is on, otherwise 0 (default 1) | |
| itemName | string | Reward name (max 30 chars) | v (rewardedVideo only) |
| rewardAmount | integer | Amount of items to gift for a single ad view (max 2000000000) | v (rewardedVideo only) |
| capping.enabled | integer | 1 to enable capping, otherwise 0 | |
| capping.limit | integer | Maximum number of ads delivered per capping interval (max 1000) | |
| capping.interval | string | capping interval: d - days h - hours | |
| pacing.enabled | integer | 1 to enable pacinhg, otherwise 0 | |
| pacing.minutes | float | Minimum gap in minutes between ad delivery (max 1000) |
Request body example
{ "appKey": "28cd2e39", "placements": [ { "adUnit": "rewardedVideo", // rewardedVideo / interstitial / banner "name": "Main_Menu", // unique placement name "itemName": "coin", // the rewarded item name "rewardAmount": 25, // amount of rewards to give per ad view "capping": { "enabled": 1, // 1 - enable capping, otherwise 0 (default: 1) "cappingLimit": 3, // limit of ads per cappingInterval "cappingInterval": "h" // interval type. "h"-hours, "d"-days (default: “d”) } }, { "adUnit": "banner", "name": "Custom_Pause", "pacing": { "enabled": 0, // 1 - enable pacing, otherwise 0 (default: 1) "pacingMinutes": 3, // pacing gap in minutes } } ]}
Response
A success response will have a newly created placement identifier. This parameter is not shown in the ironSource platform and you can retrieve it using the GET method. You will need to use the id when editing/deleting placements.Response Parameters
Key | Type | Description | Value | Mandatory |
|---|---|---|---|---|
| appKey | string | An application unique identifier | v | |
| adUnit | string | The name of the ad unit | rewardedVideo interstitial banner | v |
| name | string | The name of the placement | Up to 30 characters | v |
| id | string | The placement ID |
Response body example
{ "appKey": "28cd2e39", "placements": [ { "adUnit": "rewardedVideo", "id": 2, // unique id of your placement "name": "Main_Menu" }, { "adUnit": "banner", "id": 4, "name": "Custom_Pause" } ]}
Put method
Update existing placements, including capping and pacing in your applications The API supports the following ad units:- Rewarded video
- Interstitial
- Banner
Request
Request URL example
https://dev-php-ssp5.supersonicads.com/partners/publisher/placements/v1?appKey=132deb27dRequest body parameters
Key | Type | Description | Mandatory |
|---|---|---|---|
| appKey | string | Application key to update placements for | v |
| placements | array | List of placements to update | v |
| These are the following placement fields in the ‘placements' array | |||
| adUnit | string | ad-unit name: rewardedVideo interstitial banner | v |
| id | integer | placement unique id | v |
| adDelivery | integer | 1 if placement ad delivery is on, otherwise 0 | |
| itemName | string | Reward name (max 30 chars) | |
| rewardAmount | integer | Amount of items to gift for a single ad view (max 2000000000) | |
| capping.enabled | integer | 1 to enable capping, otherwise 0 | |
| capping.limit | integer | Maximum number of ads delivered per capping interval (max 1000) | |
| capping.interval | string | capping interval: d - days h - hours | |
| pacing.enabled | integer | 1 to enable pacinhg, otherwise 0 | |
| pacing.minutes | float | Minimum gap in minutes between ad delivery (max 1000) |
Request body example
{ "appKey": "28cd2e39", "placements": [ { "adUnit": "rewardedVideo", // rewardedVideo / interstitial / banner "id": 1, // unique placement id "rewardAmount": 25, // changing amount of rewards to give "adDelivery": 1, // toggling ad delivery, 1 - enables, otherwise 0 "capping": { "cappingInterval": "h" // updating capping interval to hours } }, { "adUnit": "interstitial", "id": 3, "pacing": { "enabled": 1, // 1 - enable pacing, otherwise 0 "pacingMinutes": 15, // pacing gap in minutes } } ]}
Response
In case the update was successful, HTTP code “200” will be responded with message “true”Delete method
Archive existing placements in your applications The API supports the following ad units:- Rewarded video
- Interstitial
- Banner
Note
Default placement cannot be archived
Request
Request body parameters
Key | Type | Description | Mandatory |
|---|---|---|---|
| appKey | string | Application key to archive the placement for | v |
| adUnit | string | ad-unit name: rewardedVideo interstitial banner | v |
| id | integer | placement unique id | v |
Request body example
{ "appKey": "28cd2e39", "adUnit": "rewardedVideo", // rewardedVideo / interstitial / banner "id": 1 // unique placement id}