Placements API

Use this API to manage your placements on the ad unit level in your ironSource 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 

You can read more about placements here

Get method

Description

Provides placement setup information

Request

Request URL example

https://platform.ironsrc.com/partners/publisher/placements/v1/?appKey=[REPLACE]

Request parameters

Response:

Response Parameters

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

notes:

• 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 URL example

https://platform.ironsrc.com.com/partners/publisher/placements/v1

Request body parameters

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

Note

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

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

Notes:

• Default placement ad delivery cannot be toggled off
• In order to enable capping/pacing, the amount field must be provided

Request

Request URL example

https://platform.ironsrc.com.com/partners/publisher/placements/v1

Request body parameters

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 URL example

https://platform.ironsrc.com.com/partners/publisher/placements/v1

Request body parameters

Request body example

{
    "appKey": "28cd2e39",
    "adUnit": "rewardedVideo", // rewardedVideo / interstitial / banner
    "id": 1 // unique placement id
}

Response

In case the update was successful, HTTP code “200” will be responded with message “true”