Placement API

1. Batch Create And Update Placements

1.1 Request URL

https://openapi.toponad.com/v1/deal_placement

1.2 Request method

POST

1.3 Request params

params	type	required	notes
count	Int	Y	Quantity of created placements
app_id	String	Y	APP ID of created placements
placements.placement_name	String	Y	Placement name. max length 30
placements.placement_id	String	N	Placement id (Incoming when modified)
placements.adformat	String	Y	Native,banner,rewarded_video,interstitial,splash
placements.template	Int	N	Configurations for native ads: 0: standard 1: Native Banner 2: Native Splash
placements.template.cdt	Int	N	Template is Native Splash: countdown time, default 5s
placements.template.ski_swt	Int	N	Template is Native Splash: it can skipped or not, it could be skipped by default. 0: No 1: Yes
placements.template.aut_swt	Int	N	Template is Native Splash: it can be auto closed or not, it could be auto closed by default. 0: No 1: Yes
placements.template.auto_refresh_time	Int	N	Template is Native Banner: it can be auto refreshed or not, it could not be auto refreshed by default -1: no auto refresh 0-n: auto refresh time (s)
remark	String	N	Remarks information
status (field deprecated.)	Int	N	Placement's status
placements.share_pl_id	String	N	Bind shared placement ID. No update if omitted; pass empty string "" to unbind.

1.4 Return data

fields	type	required	notes
app_id	String	Y	App ID
placement_name	String	Y	Placement name
placement_id	String	Y	Placement ID
adformat	String	Y	Native, banner, rewarded video, interstitial, splash
placements.template	Int	N	Configurations for native ads: 0: standard 1: Native Banner 2: Native Splash
placements.template.cdt	Int	N	Template is Native Splash: countdown time, default 5s
placements.template.ski_swt	Int	N	Template is Native Splash: it can skipped or not, it could be skipped by default. 0: No 1: Yes
placements.template.aut_swt	Int	N	Template is Native Splash: it can be auto closed or not, it could be auto closed by default. 0: No 1: Yes
placements.template.auto_refresh_time	Int	N	Template is Native Banner: it can be auto refreshed or not, it could not be auto refreshed by default -1 no auto refresh 0-n auto refresh time (s)
remark	String	N	Remarks information
status	Int	N	Placement's status

1.5 Sample

Request sample:

{
    "count": 1,
    "app_id": "a5c41a9ed1679c",
    "placements": [
        {
            "placement_name": "6",
            "adformat": "native",
            "remark": "remark",
            "template":2,
            "template_extra":{
                "cdt":55,
                "ski_swt":1,
                "aut_swt":1
            }

        }

    ]
}

Return sample:

[
    {
        "app_name": "test1",
        "app_id": "a5c41a9ed1679c",
        "platform": 2,
        "placement_id": "b1bv57tielnlts",
        "placement_name": "6",
        "adformat": "native",
        "remark": "remark",
        "template": 2,
        "template_extra": {
            "cdt": 55,
            "ski_swt": 1,
            "aut_swt": 1
        }
    }
]

2. Get Placement List

2.1 Request URL

https://openapi.toponad.com/v1/placements

2.2 Request method

POST

2.3 Request params

params	type	required	notes
app_ids	Array[String]	N	eg: ["abc", "acc"]
placement_ids	Array[String]	N	eg: ["abc", "acc"]
type	Int	N	1 = Regular Placement, 2 = Shared Placement; return all if not passed
start	Int	N	Default 0 (Not required when both app and ad slot are specified)
limit	Int	N	Default 100 (Not required when both app and ad slot are specified)

2.4 Return data

fields	type	required	notes
app_id	String	Y	App ID
app_name	String	Y	App name
platform	Int	Y	1 or 2 (1: android,2: IOS)
placement_id	String	N	-
placement_name	String	N	-
adformat	String	N	-
placements.template	Int	N	Configurations for native ads: 0: standard 1: Native Banner 2: Native Splash
placements.template.cdt	Int	N	Template is Native Splash: countdown time, default 5s
placements.template.ski_swt	Int	N	Template is Native Splash: it can skipped or not, it could be skipped by default. 0: No 1: Yes
placements.template.aut_swt	Int	N	Template is Native Splash: it can be auto closed or not, it could be auto closed by default. 0: No 1: Yes
placements.template.auto_refresh_time	Int	N	Template is Native Banner: it can be auto refreshed or not, it could not be auto refreshed by default -1 no auto refresh 0-n auto refresh time (s)
remark	String	N	Remarks information
status	Int	N	Placement's status
type	Int	N	1: Regular placement, 2: Shared placement
share_pl_sw	Int	N	Shared Placement Access Status: 1=On, 2=Off
share_pl_id	String	N	Bound shared placement ID. If this parameter is not passed, no update will be performed. Pass an empty string `""` to unbind.
share_pl_name	String	N	Name of the shared placement bound to regular placement
app_version	String	N	Shared placement application version

2.5 Sample

Request sample:

{
    "placement_ids":["b5bc9bc2951216"]
}

Return sample:

[
    {
        "app_name": "topontest",
        "app_id": "a5bc9921f7fdb4",
        "platform": 2,
        "placement_id": "b5bc9bc2951216",
        "placement_name": "topontest_rewardvideo",
        "adformat": "rewarded_video"
    }
]

3. Batch Delete Placemens

3.1 Request URL

https://openapi.toponad.com/v1/del_placements (The API is deprecated.)

3.2 Request method

POST

3.3 Request params

params	type	required	notes
placement_ids	Array[String]	Y	eg: ["abc", "acc"]

3.4 Return data

fields	type	required	notes
msg	String	N	-

3.5 Sample

Request sample:

{
    "placement_ids":["b5bc9bc2951216"]
}

Return sample:

{
    "msg": "suc"
}

4. Batch Enable / Disable Placements

4.1 Request URL

https://openapi.toponad.com/v3/placements/status

4.2 Request Method

PUT

4.3 Request Parameters

表格

Field	Type	Required	Remarks
ids	Array[String]	Y	List of placement IDs, maximum 100 items. Example: `["34343943uucce33"]`
status	Int	Y	Operation status enum:`1`: Disable`3`: Enable

4.4 Response Parameters

表格

Field	Type	Required	Remarks
items	Array[Object]	N	List of invalid placement information. Notes:1. Empty list means the operation succeeded.2. Non‑empty list indicates which placements failed validation. All placements (including validated ones) will fail the operation.
items.id	String	Y	Placement ID
items.err_code	Int	Y	Error code
items.err_msg	String	Y	Error message. Partial description as below:`"the unit is not yet bind to the segment"`: The passed parameters contain ad units not bound to any segment during enable/disable operation

4.5 Sample

Request Sample:

curl --location --request PUT 'https://openapi.toponad.com/v3/placements/status' \
--header 'X-Up-Key: 877f8ae9c6e9ca82c0675b5fff594c373axxx' \
--header 'X-Up-Signature: CE12B506DBCD868C2C6F09E08C139CBC' \
--header 'X-Up-Timestamp: 1626161553000' \
--header 'Content-Type: application/json' \
--data-raw '{
    "ids": ["34343943uucce33"],
    "status": 1
}'

Response Sample:

{}

5. Create Shared Placement

Note: This feature is currently under whitelist control. To enable it, please contact your TopOn account manager.

5.1 Request URL

https://openapi.toponad.com/v3/shared_placement

5.2 Request Method

POST

5.3 Request Parameters

Field	Type	Required	Remarks
app_id	string	Y	Application ID
name	string	Y	Name of shared placement, 1‑100 characters
adformat	string	Y	Ad format: `native`, `rewarded_video`, `banner`, `interstitial`, `splash`
placement_ids	string[]	Y	List of regular placement IDs to be bound. Minimum 1 item, maximum 99 items.
unbind_others_on_share	bool	N	false: Incremental sync; true: Full sync & unbind (default). Under full sync mode, regular ad placements not included in placement_ids will be unbound.
remark	string	N	Remarks
app_version	string	N	Application version

5.4 Response Parameters

表格

Field	Type	Remarks
placement_id	string	ID of the newly‑created shared placement
placement_name	string	Name of the shared placement
app_id	string	Application ID
adformat	string	Ad format
type	int	Fixed value: `2` (stands for shared placement)
remark	string	Remarks
app_version	string	Application version
bound_placements	array	Binding result list
bound_placements[].placement_id	string	Regular placement ID
bound_placements[].status	string	`success` / `fail`
bound_placements[].err_msg	string	Reason for failure

5.5 Sample

Request Sample:

curl --location --request PUT 'https://openapi.toponad.com/v3/shared_placement' \
--header 'X-Up-Key: 877f8ae9c6e9ca82c0675b5fff594c373axxx' \
--header 'X-Up-Signature: CE12B506DBCD868C2C6F09E08C139CBC' \
--header 'X-Up-Timestamp: 1626161553000' \
--header 'Content-Type: application/json' \
--data-raw '{
  "app_id": "a5f2d0807c75e3",
  "name": "share_pool_1",
  "adformat": "banner",
  "placement_ids": ["b1hle3r3hbgqpe"],
  "remark": "共享池1",
  "app_version": ""
}'

Return Sample：

{
  "placement_id": "b1hle3r3vpjint",
  "placement_name": "share_pool_1",
  "app_id": "a5f2d0807c75e3",
  "adformat": "banner",
  "type": 2,
  "remark": "共享池1",
  "bound_placements": [
    { "placement_id": "b1hle3r3hbgqpe", "status": "success" }
  ]
}

Last modified: 2026-09-23Powered by

Outline