VI | EN
Message us on Messenger
Developer resources

Create Smart Creative ads — TikTok Business API

Create Smart Creative ads · 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 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

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
adgroup_idbodystringYesAd 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_listbodyobject[]YesList of media information. Max size: 30.
title_listbodyobject[]NoList 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_listbodyobject[]NoCall-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_listbodyobject[]NoList of deeplinks. Length range: [0,1]. Note: Only one deeplink and corresponding deeplink_type can be submitted in each deeplink_list object.
display_name_listbodyobject[]NoDisplay names. Note: You can pass only one app_name or landing_page_name into each display_name_list object.
page_listbodyobject[]NoPage ID list.
card_listbodyobject[]NoCard ID list. Length range: [0,1].
landing_page_urlsbodyobject[]NoMultiple 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_materialbodyobjectNoCommon 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)

NameTypeSampleDescription
codenumberResponse code. For the complete list of response codes and descriptions, see Appendix - Return Codes.
messagestringResponse message. For details, see Appendix - Return Codes.
dataobjectReturned data.
advertiser_idstringAdvertiser ID.
adgroup_idstringAd group ID.
media_info_listobject[]List of media information.
material_idstringMaterial ID.
material_operation_statusstringThe status of the material. Enum values: `ENABLE` (the material can be used), `DISABLE`(the material cannot be used).
media_infoobjectMedia Information.
image_infoobject[]Image information.
web_uristringImage ID.
file_namestringImage name.
video_infoobjectVideo information.
video_idstringVideo ID.
file_namestringVideo name.
aigc_disclosure_typestringWhether 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_idstringThe ID of the TikTok post to be used as an ad (Spark Ad).
identity_idstringIdentity ID when you are using Spark Ads (`tiktok_item_id`).
identity_typestringIdentity type when you are using Spark Ads (`tiktok_item_id`). Enum values: `AUTH_CODE`, `TT_USER`. For details about identities, see Identities.
title_listobject[]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.
titlestringAd title (ad text).
call_to_action_listobject[]Call-to-action list.
call_to_actionstringCall-to-action text. For enum values, see Enumeration - Call-to-action.
deeplink_listobject[]List of deeplinks.
deeplinkstringThe specific location where you want your audience to go if they have your app installed.
deeplink_typestringThe 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_listobject[]Display names.
app_namestringApp name.
landing_page_namestringLanding page name.
page_listobject[]Page ID list.
page_idstringPage ID.
card_listobject[]Card ID list. Length range: [0,1].
card_idstringDisplay Card ID, Gift Code Sticker ID, Countdown Sticker ID, or Download Card ID.
landing_page_urlsobject[]Landing page URL list.
landing_page_urlstringLanding page URL.
common_materialobjectCommon material.
ad_namestringAd name.
call_to_action_idstringThe ID of the CTA portfolio that you want to use in your ads.
creative_authorizedbooleanWhether 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_urlstringPlayable material url.
fallback_typestringFallback 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_infoobjectTracking information.
impression_tracking_urlsstring[]Default Impression Tracking URL.
click_tracking_urlsstring[]Click Tracking URL.
tracking_pixel_idstringThe pixel ID that is tracked.
tracking_app_idstringThe ID of the application that is tracked.
tracking_offline_event_set_idsstring[]A list of Offline Event set IDs that are tracked.
identity_idstringIdentity ID when you are not using Spark Ads (`tiktok_item_id`).
identity_typestringIdentity type when you are not using Spark Ads (`tiktok_item_id`). The only supported value is `CUSTOMIZED_USER`.
is_smart_creativebooleanWhether Smart Creative is enabled for the ad group.
request_idstringThe 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

  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