VI | EN
Message us on Messenger
Developer resources

Create an asynchronous copy task for an Upgraded Smart+ Campaign — TikTok Business API

Create an asynchronous copy task for an Upgraded Smart+ Campaign · call it through Quantri360 with one API key for your own accounts / assets that you connected and authorized — 360 handles request signing and refreshing the authorization you granted.

Create an asynchronous copy task for an Upgraded Smart+ Campaign

POST/smart_plus/campaign/copy/task/create/Via 360: POST https://partner.quantri360.com/v1/tiktok_business/smart_plus/campaign/copy/task/create/
Write endpoint — changes data on TikTok Business. The key must be created with "Allow write API calls" ticked, otherwise you get 403 write_not_allowed. Every call is logged.
Description

Use this endpoint to create an asynchronous copy task for an Upgraded Smart+ Campaign.

You can only copy one campaign at a time. To learn about the detailed steps, see Copy an Upgraded Smart+ Campaign. After you create the task, use /smart_plus/campaign/copy/task/check/ to check the results.

> Note

> - Asynchronous Campaign Copy API is currently an allowlist-only feature. If you would like to access it, please contact your TikTok representative.

> - The rate limits for this endpoint are 1 query per second (QPS) and 30 queries per minute (QPM) per developer app. Global rate limits are not applicable to this endpoint.

Request

Endpoint

POST https://partner.quantri360.com/v1/tiktok_business/smart_plus/campaign/copy/task/create/

Authentication & shop

NameInTypeSampleDescription
AuthorizationheaderheaderBearer q360_live_ab12cd34_…Khóa API của brand (tạo ở mục API key). Bắt buộc với mọi request. Brand suy từ key — không truyền mã brand.
platform_shop_idquerystring7000000000000000001Tài sản TikTok Business đã kết nối — "Mã tài sản" ở trang Nền tảng hoặc GET /v1/platforms (tài khoản quảng cáo cho Marketing API, tài khoản TikTok cho Organic / Messaging). Có thể bỏ khi chỉ kết nối một tài sản.

Request parameters

NameInTypeRequiredSampleDescription
request_idbodystringYesRequest ID that supports idempotency to prevent you from sending the same request twice. If you retry requests with the same request ID multiple times within the 10-second cache time, then only one request will succeed. If a duplicate request with the expired request ID is received after the cache time, the server will treat it as a new request and process it accordingly. It is different from the request_id returned in the response parameters, which is used to uniquely identify an HTTP request. The value should be a string representation of a 64-bit integer. Example: "123456789".
campaign_idbodystringYesThe ID of an Upgraded Smart+ Campaign that you want to copy. To retrieve Upgraded Smart+ Campaigns within your ad account, use /smart_plus/campaign/get/. Note: - The source campaign must use one of these advertising objectives: APP_PROMOTION, LEAD_GENERATION, WEB_CONVERSIONS - The source campaign must not be deleted. - The source campaign must contain at least 1 undeleted ad group, which must contain at least 1 undeleted ad. - The source campaign must satisfy all per-level limits, and the total copied assets must also not exceed the global new campaign limits: - On the source campaign: you may have a maximum of 10 undeleted ad groups, each ad group may contain a maximum of 30 undeleted ads, and each individual ad may use a maximum of 50 creatives. - Separately, there are hard global caps that apply to the resulting new campaign: no more than 200 total ads may be copied over, and no more than 1,000 total creatives may be copied into the new campaign.
operation_statusbodystringNoThe status of the new campaign when created. Enum values: - ENABLE: The campaign is enabled when created. - DISABLE: The campaign is disabled when created. Default value: DISABLE. If you want to update the status of the campaign after creation, use /smart_plus/campaign/status/update/.
campaign_namebodystringNoThe name for the new campaign. Length limit: 512 characters. Emojis are not supported. Each word in Chinese or Japanese counts as two characters, while each letter in English counts as one character. If not specified, this field will default to "COPIED_{{name_of_the_source_campaign}}". For instance, if the source campaign is named "FIRST_CAMPAIGN" and this field is not specified, the name of the new campaign will be "COPIED_FIRST_CAMPAIGN".
budgetbodynumberNoThe budget for the new campaign or the budget limit for all ad groups under the new campaign. - When budget_optimize_on of the source campaign is true, this field represents the fixed budget or initial budget for the new campaign. - When budget_auto_adjust_strategy is UNSET, this field represents the fixed budget for the new campaign. - When budget_auto_adjust_strategy is AUTO_BUDGET_INCREASE, this field represents the initial budget for the new campaign. To retrieve the current campaign budget, use /smart_plus/campaign/get/ after the copy task is completed and check the returned current_budget. - When budget_optimize_on of the source campaign is false, this field represents the budget limit for all ad groups under the new campaign. - When budget_mode is BUDGET_MODE_DAY, this field represents the daily limit for all ad groups under the new campaign. - When budget_mode is BUDGET_MODE_TOTAL, this field represents the total limit for all ad groups under the new campaign. If not specified, this field will default to the budget of the source campaign or the budget limit for all ad groups under the source campaign.
schedule_typebodystringNo- Specify this field only when you want to set the same schedule for all ad groups in the new campaign. - If you want to use schedules of the source ad groups in the new campaign, leave this field unspecified. Schedule type for all new ad groups. Enum values: - SCHEDULE_START_END: Set start time and end time to run ad groups. You need to pass both schedule_start_time and schedule_end_time at the same time. - SCHEDULE_FROM_NOW: Set start time to run ad groups continuously. You need to pass schedule_start_time and the end time will be automatically set to 10 years later than the start time.
schedule_start_timebodystringNoRequired when schedule_type is passed. Schedule start time (UTC+0) for all new ad groups, in the format of YYYY-MM-DD HH:MM:SS. The start time can be up to 12 hours earlier than the current time, but cannot be later than 2028-01-01 00:00:00.
schedule_end_timebodystringNo- Required when schedule_type is SCHEDULE_START_END. - Not supported when schedule_type is SCHEDULE_FROM_NOW. Schedule end time (UTC+0) for all new ad groups, in the format of YYYY-MM-DD HH:MM:SS. The end time cannot be later than 2038-01-01 00:00:00.
daypartingbodystringNo- Specify this field only when you want to set the same ad delivery arrangement for all ad groups in the new campaign. - If you want to use the same ad delivery arrangements of the source ad groups in the new campaign, leave this field unspecified. Ad delivery arrangement, in the format of a string that consists of 48 x 7 characters. Each character is mapped to a 30-minute timeframe from Monday to Sunday. Each character can be set to either 0 or 1. 1 represents delivery in the 30-minute timeframe, and 0 stands for non-delivery in the 30-minute timeframe. The first character is mapped to 0:01-0:30 of Monday; The second character is mapped to 0:31-1:00 of Monday, and the last character represents 23:31-0:00 Sunday. Note: An all-1 value and when this field is not specified, are considered full-time delivery.
deep_copy_modebodystringNoThe copying mode determining how you create ad groups and ads (asset groups) in the new campaign. Enum values: - DEFAULT: The default copy mode. You copy all undeleted ad groups and ads from the source campaign to the new one. You can omit the adgroup_list field, as the API ignores it in this mode. - CUSTOM: The custom copy mode. You copy only the specified undeleted ad groups and ads from the source campaign to the new one. You also have options to customize specific ad group or ad settings to override the source configurations. - When using this mode, you need to provide the adgroup_list field simultaneously. You can copy a maximum of 20 ads per ad group, across a maximum of 30 ad groups. Default value: DEFAULT.
adgroup_listbodyobject[]No- When deep_copy_mode is set to DEFAULT or not passed, this field is ignored. - When deep_copy_mode is set to CUSTOM, this field is required. The customized settings for ad groups in the new campaign. Max size: 10.

Request examples

curl -s -X POST "https://partner.quantri360.com/v1/tiktok_business/smart_plus/campaign/copy/task/create/" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"request_id":"","campaign_id":"","adgroup_list":[{}]}'
Python
import requests

KEY = "q360_live_..."  # khóa API của brand
r = requests.post(
    "https://partner.quantri360.com/v1/tiktok_business/smart_plus/campaign/copy/task/create/",
    params={},
    json={
        "request_id": "",
        "campaign_id": "",
        "adgroup_list": [
            {}
        ]
    },
    headers={"Authorization": f"Bearer {KEY}"},
    timeout=60,
)
print(r.status_code)
print(r.json())
Node.js
const KEY = 'q360_live_...'; // khóa API của brand
const url = new URL('https://partner.quantri360.com/v1/tiktok_business/smart_plus/campaign/copy/task/create/');
for (const [k, v] of Object.entries({})) url.searchParams.set(k, typeof v === 'object' ? JSON.stringify(v) : String(v));
const r = await fetch(url, {
  method: 'POST',
  headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({"request_id":"","campaign_id":"","adgroup_list":[{}]}),
});
console.log(r.status, await r.json());
PHP
<?php
$key = 'q360_live_...'; // khóa API của brand
$url = 'https://partner.quantri360.com/v1/tiktok_business/smart_plus/campaign/copy/task/create/' . '?' . http_build_query([]);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $key, 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"request_id":"","campaign_id":"","adgroup_list":[{}]}');
$res = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status, "\n", $res;

Response

Response fields (as returned by TikTok Business)

NameTypeSampleDescription
codenumberResponse code. For the complete list of response codes and descriptions, see Appendix - Return Codes.
messagestringResponse message. For details, see Appendix - Return Codes.
request_idstringThe log ID of the request, which uniquely identifies a request.
dataobjectReturned data.
task_idstringID of the asynchronous campaign copy task. To check the results of the task, use /smart_plus/campaign/copy/task/check/.
adgroup_error_listobject[]The errors encountered during the process of copying specific ad groups.
adgroup_idstringThe ID of the ad group that fails to be copied.
error_messagestringThe error encountered during the process of copying the ad group (`adgroup_id`).

Response sample

HTTPS/1.1 200 OK
{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": {
        "task_id": "{{task_id}}"
    }
}

Get started

  1. Sign up for Partner
  2. Enable a data type of the Ads (Marketing API) group on the platform page
  3. Create an API key (tick the TikTok Business channel)
  4. Call it as in the examples above