Adsource API (v3)

1. Get Adsource list

1.1 Request URL

https://api.toponad.net/v3/units/list

1.2 Request method

GET

1.3 Request params

params	type	required	notes
app_ids	Array[String]	N	App ID list
placement_ids	Array[String]	N	Placement ID list
network_ids	Array[Int]	N	Network ID list
start	Int	N	Default value: 0 (cannot be used with the above parameters)
limit	Int	N	Default value: 1000, and the maximum is 1000 at a time (cannot be used with the above parameters)

1.4 Return data

params	type	required	notes
total	Int	Y	Total number of item returned
items	Array[Ojbect]	Y	Adsource list
items.id	Int	Y	Adsource ID
items.name	String	Y	Adsource name
items.app_id	String	Y	App ID in the developer backend
items.placement_id	String	Y	Placement ID in the developer backend
items.network_id	Int	Y	Network ID in the developer backend
items.nw_firm_id	Int	Y	Network Firm ID

1.5 Sample

Request sample:

curl --location --request GET 'https://api.toponad.net/v3/units/list?app_ids=a63f5cced466da&placement_ids=b1ehgn65hup6v0,b640ae1464e7e9&network_ids=4779,4780&start=0&limit=200 ' \
--header 'X-Up-Key: 877f8ae9c6e9ca82c0===b5fff594c373axxx' \
--header 'X-Up-Signature: CE12B506DBCD868C2C6F09E08C139CBC' \
--header 'X-Up-Timestamp: 1626056011000' \
--header 'Content-Type: application/json' \
--data-raw ''

Return sample:

{
    "total": 10,
    "items": [
        {
            "app_id": "a6392a1c24510e",
            "placement_id": "b6392a1d36f73f",
            "network_id": 5117,
            "id": 2279787,
            "name": "ADX",
            "nw_firm_id":15
        },
        {
            "app_id": "a6392a1c24510e",
            "placement_id": "b6392a1d59c06f",
            "network_id": 5117,
            "id": 2279797,
            "name": "ADX",
             "nw_firm_id":15
        }
    ]
}

2. Get Adsource Detail

2.1 Request URL

https://api.toponad.net/v3/units

2.2 Request method

GET

2.3 Request params

params	type	required	notes
ids	Array[Int]	Y	Adsource ID list, maximum number of IDs is 100, and the minimum is 1.

2.4 Return data

params	type	required	notes
-	Array[Object]	Y	Adsource info list
-.id	Int	Y	Adsource ID
-.name	String	Y	Adsource name
-.network_id	Int	Y	Network ID in the developer backend
-.placement_id	String	Y	Placement ID in the developer backend
-.type	Int	Y	Ad Source types: 2: Regular Ad Source 4: ADX Ad Source 10: Fallback Ad Source 12: Client-side bidding Ad Source 13: Server-side bidding Ad Source
-.mix_format	Int	Y	Mixed Ad Type, note: only certain platforms have this attribute, enumeration description:  -1 or same as ad slot format value: non-mixed type  0: Mixed Native Type  1: Mixed Rewarded-Video Type  2: Mixed Banner Type  3: Mixed Interstitial Type  4: Mixed Splash Type
-.adsource_token	Object	Y	Ad Source configuration parameters, third-party ad platforms, or custom-associated third-party platforms. For details, see the “Detailed parameters of network” specification attribute column <adsource_token>. When customizing ad platforms, the json object format must be met. This attribute does not currently support adx ad sources (related to traffic grouping).
-.auto_unit_sw	Int	Y	Auto Ad Source switch, available on certain platforms only: 1: ON 2: OFF
_.nw_firm_id	Int	Y	Network Firm ID

2.5 Sample

Request sample：

curl --location --request GET 'https://api.toponad.net/v3/units?ids=417018,374133' \
--header 'X-Up-Key: 877f8ae9c6e9ca82c0===b5fff594c373axxx' \
--header 'X-Up-Signature: CE12B506DBCD868C2C6F09E08C139CBC' \
--header 'X-Up-Timestamp: 1626056011000' \
--header 'Content-Type: application/json' \
--data-raw ''

Return sample:

[
    {
        "id": 374133,
        "placement_id": "b6049c640e6ad1",
        "network_id": 4779,
        "name": "CSJ_rv_3",
        "type": 2,
        "mix_format": -1,
        "adsource_token": {
            "app_id": "5343323",
            "personalized_template": "1",
            "slot_id": "4566363563"
        },
        "auto_unit_sw": 2,
         "nw_firm_id":15
    },
    {
        "id": 417018,
        "placement_id": "b6049c640e6ad1",
        "network_id": 4779,
        "name": "CSJ_rv_6",
        "type": 2,
        "mix_format": -1,
        "adsource_token": {
            "app_id": "5343323",
            "personalized_template": "0",
            "slot_id": "324ewrwe"
        },
        "auto_unit_sw": 2,
         "nw_firm_id":15
    }
]

3. Create Adsources

Note: After successfully creating an ad source, it will be unbound and disabled by default (because these attributes are related to segments, i.e., they will be different in different segments). You need to call the ad source management API2 or API5 of Aggregation Management again to bind and enable it in the specified segment as needed.

3.1 Request URL

https://api.toponad.net/v3/units

3.2 Request method

POST

3.3 Request params

params	type	required	notes
placement_id	String	Y	Placement ID in the developer backend
items	Array[Object]	Y	Adsource list
items.name	String	Y	Adsource name
items.network_id	Int	Y	Network ID in the developer backend
items.type	Int	Y	Ad Source types: 2: Regular Ad Source 10: Fallback Ad Source 12: Client-side bidding Ad Source 13: Server-side bidding Ad Source
items.mix_format	Int	Y	Mixed Ad Type, note: only certain platforms have this attribute, enumeration description:  -1: non-mixed type  0: Mixed Native Type  1: Mixed Rewarded-Video Type  2: Mixed Banner Type  3: Mixed Interstitial Type  4: Mixed Splash Type
items.adsource_token	Object	Y	Ad Source configuration parameters, third-party ad platforms, or custom-associated third-party platforms. For details, see the “Detailed parameters of network” specification attribute column <adsource_token>. When customizing ad platforms, the json object format must be met. This attribute does not currently support adx ad sources (related to traffic grouping).

3.4 Return data

params	type	required	notes
items	Array[Object]	Y	The list of successfully created adsource information, index positions, and request parameters items index positions correspond one-to-one.
items.id	Int	Y	Adsource ID
errs	Array[Object]	N	Error application information list, note: 1. If the list is empty, the operation is successful. 2. If the list is not empty, the list indicates which apps failed verification, and all apps (including those that passed verification) failed.
errs.index	Int	Y	The index position of the error item in the request parameter items, starting from 0.
errs.code	Int	Y	Error code
errs.msg	String	Y	Error message

3.5 Sample

Request sample:

curl --location --request POST 'https://api.toponad.net/v3/units' \
--header 'X-Up-Key: 877f8ae9c6e9ca82c0==5b5fff594c373axxx' \
--header 'X-Up-Signature: CE12B506DBCD868C2C6F09E08C139CBC' \
--header 'X-Up-Timestamp: 1626161553000' \
--header 'Content-Type: application/json' \
--data-raw '{
    "placement_id": "b64993cxxxx",
    "items": [
        {
            "network_id": 4778,
            "name": "xcj_admob_openapi1",
            "adsource_token": {
                "unit_id":"123456790000",
                "orientation":"1"
            },
            "mix_format":-1,
            "type": 2
        }
    ] 
}'

Return sample:

{
    "errs": [
        {
            "index": 0,
            "code": 4000,
            "msg": "the unit type is invalid"
        }
    ]
}

4. Update Adsources

4.1 Request URL

https://api.toponad.net/v3/units

4.2 Request method

PUT

4.3 Request params

params	type	required	notes
placement_id	String	Y	Placement ID in the developer backend
items	Array[Object]	Y	Adsource list
items.id	Int	Y	Adsource ID
items.name	String	Y	Adsource name
items.adsource_token	Object	Y	Ad Source configuration parameters, third-party ad platforms, or custom-associated third-party platforms. For details, see the “Detailed parameters of network” specification attribute column <adsource_token>. When customizing ad platforms, the json object format must be met. This attribute does not currently support adx ad sources (related to traffic grouping).

4.4 Return data

params	type	required	notes
items	Array[Object]	N	Error application information list, note: 1. If the list is empty, the operation is successful. 2. If the list is not empty, the list indicates which apps failed verification, and all apps (including those that passed verification) failed.
items.index	Int	Y	The index position of the error item in the request parameter items, starting from 0.
items.err_code	Int	Y	Error code
items.err_msg	String	Y	Error message

4.5 Sample

Request sample:

curl --location --request PUT 'https://api.toponad.net/v3/units' \
--header 'X-Up-Key: 877f8ae9c6e9ca82c0==5b5fff594c373axxx' \
--header 'X-Up-Signature: CE12B506DBCD868C2C6F09E08C139CBC' \
--header 'X-Up-Timestamp: 1626161553000' \
--header 'Content-Type: application/json' \
--data-raw '{
    "placement_id": "b64993cxxxx",
    "items": [
        {
            "id": 4778,
            "name": "xcj_admob_openapi1",
            "adsource_token": {
                "unit_id":"123456790000",
                "orientation":"1"
            }
        }
    ]
}'

Return sample:

{

}

5. Delete Adsources

Note: Currently still v1, awaiting upgrade to v3.

5.1 Request URL

https://api.toponad.net/v1/del_units

5.2 Request method

POST

5.3 Request params

params	type	required	notes
adsource_ids	Array[Int]	Y	Adsource ID list, maximum limit of 10. The Adsource ID list can be obtained after creating an ad source via [Api3].

5.4 Return data

params	type	required	notes
msg	String	Y	Result description, “suc” means deletion successful

5.5 Sample

Request sample:

curl --location --request PUT 'https://api.toponad.net/v1/del_units' \
--header 'X-Up-Key: 877f8ae9c6e9ca82c0==5b5fff594c373axxx' \
--header 'X-Up-Signature: CE12B506DBCD868C2C6F09E08C139CBC' \
--header 'X-Up-Timestamp: 1626161553000' \
--header 'Content-Type: application/json' \
--data-raw '{
    "adsource_ids":[19683]
}'

Return sample:

{
    "msg": "suc"
}