Placements API

Manage placement configurations within your AIR app by creating, retrieving, updating, or deleting ad placements using the Placements API.

Read time 5 minutes

Last updated 4 hours ago

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

For more information, refer to Placements.

Note

You must authenticate each API request by using Bearer API authentication.

Get method

Description

Provides placement setup information

Request

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

Default placement ad delivery cannot be toggled off. To enable capping/pacing, the amount field must be provided.

Request

Request URL example

https://dev-php-ssp5.supersonicads.com/partners/publisher/placements/v1?appKey=132deb27d

Request 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
}

Response

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

Placements API

Get method

Description

Request

Request URL example

Request parameters

Key

Type

Description

Value

Mandatory

Response

Response Parameters

Key

Type

Description

Mandatory

Response body example

Post method

Request

Request body parameters

Key

Type

Description

Mandatory

Request body example

Response

Response Parameters

Key

Type

Description

Value

Mandatory

Response body example

Put method

Request

Request URL example

Request body parameters

Key

Type

Description

Mandatory

Request body example

Response

Delete method

Request

Request body parameters

Key

Type

Description

Mandatory

Request body example

Response