Create Smart Creative ads
POST/ad/aco/create/Via 360: POST https://partner.quantri360.com/v1/tiktok_business/ad/aco/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 Smart Creative ads by uploading necessary ad creatives to the library. With this endpoint, you can upload multiple ad texts, titles, materials, and call-to-actions to the library. The platform automatically combines your ad creatives and prepares them for delivery. ad_id is not returned in the response. This is a totally new endpoint in v1.3.
> Note
> ACO ads are no longer supported in API. To ensure a smooth API integration, we recommend you migrate to Smart Creative ads.
Request
Endpoint
POST https://partner.quantri360.com/v1/tiktok_business/ad/aco/create/
Authentication & shop
| Name | In | Type | Sample | Description |
|---|---|---|---|---|
| Authorization | header | header | Bearer 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_id | query | string | 7000000000000000001 | Tà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
| Name | In | Type | Required | Sample | Description |
|---|---|---|---|---|---|
| adgroup_id | body | string | Yes | Ad group ID.
Note: The ID should be of the ad group that you will enable Smart Creative for, and creative_material_mode for the ad group must be SMART_CREATIVE. | |
| media_info_list | body | object[] | Yes | List of media information. Max size: 30. | |
| title_list | body | object[] | No | List of ad titles (also called ad texts). Ad titles are shown to your audience as part of your ad creative, to deliver the message you intend to communicate to them.
When you pass in tiktok_item_id, you don't need to pass in the objects image_info, video_info, and title_list. | |
| call_to_action_list | body | object[] | No | Call-to-action list.
Note:
- For TikTok ads, either this field or call_to_action_id must be specified. If both are specified, this field will be ignored.
- You can include at most three call-to-action texts (call_to_action) in each call_to_action_list object. | |
| deeplink_list | body | object[] | No | List of deeplinks. Length range: [0,1].
Note: Only one deeplink and corresponding deeplink_type can be submitted in each deeplink_list object. | |
| display_name_list | body | object[] | No | Display names.
Note: You can pass only one app_name or landing_page_name into each display_name_list object. | |
| page_list | body | object[] | No | Page ID list. | |
| card_list | body | object[] | No | Card ID list. Length range: [0,1]. | |
| landing_page_urls | body | object[] | No | Multiple landing page URLs.
You can pass only one landing_page_url into each landing_page_urls object.
Note: Once set, this field cannot be updated. | |
| common_material | body | object | No | Common material. |
Request examples
curl -s -X POST "https://partner.quantri360.com/v1/tiktok_business/ad/aco/create/" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"adgroup_id":"","media_info_list":[{"media_info":{}}],"title_list":[{}],"call_to_action_list":[{}],"deeplink_list":[{}],"display_name_list":[{}],"page_list":[{}],"card_list":[{}],"landing_page_urls":[{}],"common_material":{}}'
Python
import requests
KEY = "q360_live_..." # khóa API của brand
r = requests.post(
"https://partner.quantri360.com/v1/tiktok_business/ad/aco/create/",
params={},
json={
"adgroup_id": "",
"media_info_list": [
{
"media_info": {}
}
],
"title_list": [
{}
],
"call_to_action_list": [
{}
],
"deeplink_list": [
{}
],
"display_name_list": [
{}
],
"page_list": [
{}
],
"card_list": [
{}
],
"landing_page_urls": [
{}
],
"common_material": {}
},
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/ad/aco/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({"adgroup_id":"","media_info_list":[{"media_info":{}}],"title_list":[{}],"call_to_action_list":[{}],"deeplink_list":[{}],"display_name_list":[{}],"page_list":[{}],"card_list":[{}],"landing_page_urls":[{}],"common_material":{}}),
});
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/ad/aco/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, '{"adgroup_id":"","media_info_list":[{"media_info":{}}],"title_list":[{}],"call_to_action_list":[{}],"deeplink_list":[{}],"display_name_list":[{}],"page_list":[{}],"card_list":[{}],"landing_page_urls":[{}],"common_material":{}}');
$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)
| Name | Type | Sample | Description |
|---|---|---|---|
| code | number | Response code. For the complete list of response codes and descriptions, see Appendix - Return Codes. | |
| message | string | Response message. For details, see Appendix - Return Codes. | |
| data | object | Returned data. | |
| advertiser_id | string | Advertiser ID. | |
| adgroup_id | string | Ad group ID. | |
| media_info_list | object[] | List of media information. | |
| material_id | string | Material ID. | |
| material_operation_status | string | The status of the material. Enum values: `ENABLE` (the material can be used), `DISABLE`(the material cannot be used). | |
| media_info | object | Media Information. | |
| image_info | object[] | Image information. | |
| web_uri | string | Image ID. | |
| file_name | string | Image name. | |
| video_info | object | Video information. | |
| video_id | string | Video ID. | |
| file_name | string | Video name. | |
| aigc_disclosure_type | string | Whether to turn on the AIGC (Artificial Intelligence Generated Content) self-disclosure toggle to indicate the ad contains AI-generated content. After the toggle is turned on, your ad will carry an "Advertiser labeled as Al-generated" label when viewed in full. Enum values: - `SELF_DISCLOSURE`: To turn on the toggle to declare that the ad contains AI-generated content. - `NOT_DECLARED`: To not declare that the ad contains AI-generated content. | |
| tiktok_item_id | string | The ID of the TikTok post to be used as an ad (Spark Ad). | |
| identity_id | string | Identity ID when you are using Spark Ads (`tiktok_item_id`). | |
| identity_type | string | Identity type when you are using Spark Ads (`tiktok_item_id`). Enum values: `AUTH_CODE`, `TT_USER`. For details about identities, see Identities. | |
| title_list | object[] | List of ad titles (also called ad texts). Ad titles are shown to your audience as part of your ad creative, to deliver the message you intend to communicate to them. | |
| title | string | Ad title (ad text). | |
| call_to_action_list | object[] | Call-to-action list. | |
| call_to_action | string | Call-to-action text. For enum values, see Enumeration - Call-to-action. | |
| deeplink_list | object[] | List of deeplinks. | |
| deeplink | string | The specific location where you want your audience to go if they have your app installed. | |
| deeplink_type | string | The deeplink type. Allowed values differs based on campaign objectives. Allowed values: `NORMAL` (supported in Traffic, Conversion), `DEFERRED_DEEPLINK` (supported in App Install ). For an ad that will be included in an iOS 14 campaign, this field cannot be set to `DEFERRED_DEEPLINK`. | |
| display_name_list | object[] | Display names. | |
| app_name | string | App name. | |
| landing_page_name | string | Landing page name. | |
| page_list | object[] | Page ID list. | |
| page_id | string | Page ID. | |
| card_list | object[] | Card ID list. Length range: [0,1]. | |
| card_id | string | Display Card ID, Gift Code Sticker ID, Countdown Sticker ID, or Download Card ID. | |
| landing_page_urls | object[] | Landing page URL list. | |
| landing_page_url | string | Landing page URL. | |
| common_material | object | Common material. | |
| ad_name | string | Ad name. | |
| call_to_action_id | string | The ID of the CTA portfolio that you want to use in your ads. | |
| creative_authorized | boolean | Whether you grant displaying some of your ads in our TikTok for Business Creative Center. Only valid for non-US advertisers, the default value is `false`. Note: `creative_authorized` can only be used for video ads. | |
| playable_url | string | Playable material url. | |
| fallback_type | string | Fallback Type. If the audience do not have the app installed, you can have them fall back to install the app, or to view a specific web page. Allowed values: `APP_INSTALL `, `WEBSITE`, `UNSET`. Note: Not applicable for Deferred Deeplink. | |
| tracking_info | object | Tracking information. | |
| impression_tracking_urls | string[] | Default Impression Tracking URL. | |
| click_tracking_urls | string[] | Click Tracking URL. | |
| tracking_pixel_id | string | The pixel ID that is tracked. | |
| tracking_app_id | string | The ID of the application that is tracked. | |
| tracking_offline_event_set_ids | string[] | A list of Offline Event set IDs that are tracked. | |
| identity_id | string | Identity ID when you are not using Spark Ads (`tiktok_item_id`). | |
| identity_type | string | Identity type when you are not using Spark Ads (`tiktok_item_id`). The only supported value is `CUSTOMIZED_USER`. | |
| is_smart_creative | boolean | Whether Smart Creative is enabled for the ad group. | |
| request_id | string | The log id of a request, which uniquely identifies the request. |
Response sample
HTTPS/1.1 200 OK
{
"code": 0,
"message": "OK",
"request_id": "{{request_id}}",
"data": {
"title_list": [
{
"title": "{{title}}"
}
],
"common_material": {
"call_to_action_id": "{{call_to_action_id}}",
"identity_id": "{{identity_id}}",
"is_smart_creative": true,
"identity_type": "CUSTOMIZED_USER"
},
"landing_page_urls": [
{
"landing_page_url": "{{landing_page_url}}"
}
],
"adgroup_id": "{{adgroup_id}}",
"media_info_list": [
{
"media_info": {
"video_info": {
"video_id": "{{video_id}}"
},
"image_info": [
{
"web_uri": "{{web_uri}}"
}
]
}
}
],
"advertiser_id": "{{advertiser_id}}"
}
}
(/code);
Get started
- Sign up for Partner
- Enable a data type of the Ads (Marketing API) group on the platform page
- Create an API key (tick the TikTok Business channel)
- Call it as in the examples above