VI | EN
Message us on Messenger
Developer resources

Create an asynchronous copy task for a Manual Campaign — TikTok Business API

Create an asynchronous copy task for a Manual 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 a Manual Campaign

POST/campaign/copy/task/create/Via 360: POST https://partner.quantri360.com/v1/tiktok_business/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 a Manual Campaign.

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

To copy an Upgraded Smart+ Campaign, use /smart_plus/campaign/copy/task/create/ instead.

>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/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
campaign_idbodystringYesThe ID of the campaign that you want to copy. Note: - You cannot copy existing GMV Max Campaigns with customized TikTok posts. To check whether the campaign contains customized TikTok posts, use /campaign/gmv_max/info/ and check whether the returned custom_anchor_video_list is []. - You cannot copy iOS Dedicated Campaigns with Apps that have not activated the SAN module on your MMP. To ensure that TikTok SAN integration is enabled for your App, see How to transition to SAN for existing apps and How to integrate to SAN for new apps. - Starting September 30, 2024, you will no longer be able to copy campaigns that contain Playable Ads delivered to TikTok placement. - Only campaigns with the supported advertising objectives (REACH, TRAFFIC, VIDEO_VIEWS, ENGAGEMENT, APP_PROMOTION, LEAD_GENERATION, WEB_CONVERSIONS) can be copied. - Ad groups belonging to an ENGAGEMENT campaign and with a promotion_type of LIVE_SHOPPING cannot be copied. - Ad groups belonging to an ENGAGEMENT campaign and with an optimization_goal of PAGE_VISIT cannot be copied. - Smart+ Campaigns and Upgraded Smart+ Campaigns are not supported. If you want to copy an Upgraded Smart+ Campaign, use /smart_plus/campaign/copy/task/create/ instead. - The campaign to be copied must have at least one undeleted ad group with at least one undeleted ad. - The campaign to be copied should not exceed a limit of 20 undeleted ad groups, with a maximum of 50 undeleted ads per ad group. - You cannot copy Automated Creative Optimization (ACO) ad groups in the campaign, but you can copy Smart Creative ad groups. - If you copy a campaign that contains ad groups bound to a split test, only the ad groups will be copied. Split test groups associated with those ad groups will not be created.
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".
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 /campaign/status/update/.
virtual_objective_typebodystringNoThe new objective type. Enum value: SALES. Use this field to create a campaign with the Sales objective, the combined objective for Website Conversions and Product Sales objectives. Learn more about the Sales objective.
sales_destinationbodystringNoRequired and valid only when virtual_objective_type is specified. Sales destination, the destination where you want to drive your sales. Enum values: - TIKTOK_SHOP: TikTok Shop. Drive sales on your TikTok Shop. - WEBSITE: Website. Drive sales on your website. - APP: App. Drive sales on your app (product catalog required).
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_original_campaign}}". For instance, if the original campaign is named "FIRST_CAMPAIGN" and this field is not specified, the name of the new campaign will be "COPIED_FIRST_CAMPAIGN".
is_advanced_dedicated_campaignbodybooleanNoWhether to enable the Advanced Dedicated Campaign setting for the new campaign. Advanced Dedicated Campaigns leverage advanced delivery models that benefit from real-time signals. To learn about how to create such campaigns, see Create Advanced Dedicated Campaigns. Enum values: true, false. If this field is not passed, the new campaign will inherit the same Advanced Dedicated Campaign setting as the original campaign. Note: Once set, this field cannot be updated.
budgetbodynumberNoThe budget for the new campaign. If not specified, this field will default to the budget of the original campaign. To learn about the minimum budget and how to set budget modes, see Budget. To obtain the daily budget value range for a currency, see Currency-Daily budget value range.
rta_idbodystringNoRealtime API (RTA) ID, the RTA strategy identifier. To obtain the list of RTA IDs associated with your ad account, contact your TikTok representative. To learn about the prerequisites for and the steps of enabling RTA for your ads, see Realtime API. Note: Enabling RTA for your ads is currently an allowlist-only feature. If you would like to access it, please contact your TikTok representative. You will need to complete the onboarding process to be able to receive and respond to RTA requests sent to your system first.
po_numberbodystringNoPO (purchase order) number. PO numbers are useful for invoice tracking and reconciliation. Learn more about PO numbers on monthly invoices.
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 set schedules separately for each ad group in the new campaign, you can pass the schedule_type within the object array adgroup_list instead. 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".
deep_copy_modebodystringNoThe copying mode, which determines how ad groups and ads are created in the new campaign. Enum values: - DEFAULT: Default copy mode. This mode copies all undeleted ad groups and ads from the original campaign to the new campaign. The field adgroup_list will be ignored. - CUSTOM: Custom copy mode. This mode only copies the specified undeleted ad groups and ads from the original campaign to the new campaign. - In this mode, you need to provide the field adgroup_list simultaneously. The maximum number of ads that can be copied is 50 ads per ad group, with a maximum of 20 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: 20.

Request examples

curl -s -X POST "https://partner.quantri360.com/v1/tiktok_business/campaign/copy/task/create/" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"campaign_id":"","request_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/campaign/copy/task/create/",
    params={},
    json={
        "campaign_id": "",
        "request_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/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({"campaign_id":"","request_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/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, '{"campaign_id":"","request_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 /campaign/copy/task/check/. If errors occur (`adgroup_error_list` is not empty), task ID will not be generated, and the value of this field will be an empty string (`""`).
adgroup_error_listobject[]The errors encountered during the process of copying specific ad groups. If no errors occur, the value of this field will be an empty list (`[]`).
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}}",
        "adgroup_error_list": []
    }
}

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