VI | EN
Message us on Messenger
Developer resources

Get customized TikTok posts — TikTok Business API

Get customized TikTok posts · 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.

Get customized TikTok posts

POST/gmv_max/creation/custom_anchor_video_list/get/Via 360: POST https://partner.quantri360.com/v1/tiktok_business/gmv_max/creation/custom_anchor_video_list/get/
Description

Use this endpoint to retrieve a list of shop-level and campaign-level customized TikTok posts created from an ad account for a specific TikTok Shop.

Shop-level customized TikTok posts are generated by directly linking your TikTok videos to a product at the TikTok Shop level. If the linked product is part of an active campaign, the video linked to that product will be automatically added to that campaign. In contrast, campaign-level customized TikTok posts are generated by linking your TikTok videos to a product during the Product GMV Max Campaign creation process and are exclusive to the campaign.

Request

Endpoint

POST https://partner.quantri360.com/v1/tiktok_business/gmv_max/creation/custom_anchor_video_list/get/

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
store_idbodystringYesThe ID of a TikTok Shop. To obtain a TikTok Shop that is available for GMV Max Campaigns, use /gmv_max/store/list/ and confirm that the returned is_gmv_max_available is true.
store_authorized_bc_idbodystringYesThe ID of the Business Center that is authorized to access the TikTok Shop (store_id). To obtain the ID, check the store_authorized_bc_id for the store_id returned from /gmv_max/store/list/.
creative_sourcebodystringYesCreative source type. Enum value: - CUSTOMIZED: customized post.
spu_id_listbodystring[]NoA list of Product SPU (standard product unit) IDs to filter the results by. To obtain the list of SPU IDs for products within a TikTok Shop, use /store/product/get/. Set ad_creation_eligible to GMV_MAX and select item_group_id values where status is AVAILABLE and gmv_max_ads_status is UNOCCUPIED.
sort_fieldbodystringNoThe sorting field. Enum values: - GMV: GMV. - POST_TIME: Post time. - VIDEO_VIEWS: Video views. - VIDEO_LIKES: Video likes. - CLICK_THROUGH_RATE: Click-through Rate (CTR). - PRODUCT_CLICKS: Product clicks. Default value: GMV.
sort_typebodystringNoThe sorting order. Enum values: - ASC: ascending. - DESC: descending.
keywordbodystringNoA search keyword to filter posts (videos). You can specify a post ID or caption. - To search by post caption (text), provide a text string. This search type supports multiple-language searches and fuzzy matches. Example: summer. - To search by post ID (item_id), provide a numeric string with at least 19 characters. This search type supports exact matches. Example: 1234567891234567891.
need_auth_code_videobodybooleanNoWhether to include posts associated with AUTH_CODE identities in the results. Supported values: true, false. Default value: false. Note: If need_auth_code_video is false or not passed and identity_list is not specified, you will retrieve an empty post list.
identity_listbodyobject[]NoA list of TT_USER, BC_AUTH_TT, or TTS_TT identities to filter the results by. To obtain a list of identities available for Product GMV Max Campaigns, use /gmv_max/identity/get/ and select identities with product_gmv_max_available as true. Max size: 20. Note: If need_auth_code_video is false or not passed and identity_list is not specified, you will retrieve an empty post list.
campaign_idbodystringNoThe ID of a Product GMV Max Campaign to filter the returns by. You can use this field to filter campaign-level customized posts. If this field is not specified, the results will only include shop-level customized posts. To retrieve existing Product GMV Max Campaigns within your ad account, use /gmv_max/campaign/get/ and set filtering to {"gmv_max_promotion_types":["PRODUCT_GMV_MAX"]}.
pagebodynumberNoCurrent page number. Value range: ≥ 1. Default value: 1.
page_sizebodynumberNoPage size. Value range: 1-50. Default value:10.

Request examples

curl -s -X POST "https://partner.quantri360.com/v1/tiktok_business/gmv_max/creation/custom_anchor_video_list/get/" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"store_id":"","store_authorized_bc_id":"","creative_source":"","identity_list":[{}]}'
Python
import requests

KEY = "q360_live_..."  # khóa API của brand
r = requests.post(
    "https://partner.quantri360.com/v1/tiktok_business/gmv_max/creation/custom_anchor_video_list/get/",
    params={},
    json={
        "store_id": "",
        "store_authorized_bc_id": "",
        "creative_source": "",
        "identity_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/gmv_max/creation/custom_anchor_video_list/get/');
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({"store_id":"","store_authorized_bc_id":"","creative_source":"","identity_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/gmv_max/creation/custom_anchor_video_list/get/' . '?' . 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, '{"store_id":"","store_authorized_bc_id":"","creative_source":"","identity_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.
item_listobject[]A list of TikTok videos (posts) available for Product GMV Max campaigns using the specified TikTok Shop.
item_idstringThe ID of the TikTok post.
textstringThe caption of the TikTok post.
spu_id_liststring[]The list of Product SPU IDs that the TikTok post is associated with. Note: This field is not included in the response for videos with no product anchor link.
can_change_anchorbooleanWhether you can change the product anchor link in this video. Supported values: - `true`: You can add a product anchor link to create a customized post. - `false`: You cannot use the video to create a customized post. Note: If `can_change_anchor` is `false`, you cannot pass the video to `custom_anchor_video_list` or `item_list` in /campaign/gmv_max/create/ or /campaign/gmv_max/update/ to create customized posts.
identity_infoobjectInformation about the identity associated with the TikTok post.
identity_idstringIdentity ID.
identity_typestringIdentity type. Enum values: - `AUTH_CODE`: Authorized User. This type of identity is created when you use the authorization code to access a TikTok account or a TikTok post. - `TT_USER`: TikTok User. This type of identity is created when you bind your TikTok For Business account with your TikTok Business Account, or when you bind your TikTok For Business account with your regular TikTok account and then upgrade the account to Business Account. - `BC_AUTH_TT`: TikTok Account User in Business Center. This type of identity is created when you add a TikTok account to your Business Center, and the TikTok account owner approves your request. - `TTS_TT`: TikTok Account User for TikTok Shop. This type of identity is created when you set an official TikTok account for the TikTok Shop.
identity_authorized_bc_idstringReturned only when `identity_type` is `BC_AUTH_TT`. The ID of the Business Center that a TikTok Account User in Business Center identity is associated with.
identity_authorized_shop_idstringReturned for some `BC_AUTH_TT` identities. The ID of the TikTok Shop that the TikTok Account User in Business Center identity is associated with.
store_idstringReturned only when `identity_type` is `TTS_TT`. The ID of the TikTok Shop that a TikTok Account User for TikTok Shop identity is associated with.
profile_imagestringTemporary profile image URL for the TikTok account that is associated with the identity. Validity period: around 48 hours. The expiration time is included in the URL after the `x-expires` parameter, in the format of an Epoch/Unix timestamp in seconds. Once the URL expires, you need to call /gmv_max/video/get/ to obtain a new URL.
display_namestringThe display name of the TikTok account that is associated with the identity.
video_infoobjectDetails of the video in the post.
video_idstringThe ID of the video.
video_cover_urlstringTemporary URL for the video cover. Validity period: around 24 hours. The expiration time is included in the URL after the `x-expires` parameter, in the format of an Epoch/Unix timestamp in seconds. Once the URL expires, you need to call /gmv_max/video/get/ to obtain a new URL.
preview_urlstringTemporary preview URL for the video. Validity period: six hours. Once the URL expires, you need to call /gmv_max/video/get/ to obtain a new URL.
heightnumberThe height of the video in pixels. Example: 1920.
widthnumberThe width of the video in pixels. Example: 1080.
bit_ratenumberThe bit rate of the video in bps. Example: 8500323.
durationnumberThe duration of the video in seconds. Example: 3.669.
sizenumberThe size of the video in bytes. Example: 3898461.
signaturestringThe MD5 of the video. Example: `ab1cd2345e678fghi91jkl23b456m7no`.
formatstringThe format of the video. Example: `mp4`.
definitionstringThe definition of the video. Example: `1080p`.
fpsnumberThe frames per second (FPS) of the video. Example: 27.
page_infoobjectPagination information.
pagenumberCurrent page number.
page_sizenumberPage size.
total_numbernumberTotal number of results.
total_pagenumberTotal pages of results.

Response sample

{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": {
        "item_list": [
            {
                "can_change_anchor": true,
                "identity_info": {
                    "avatar_url": "{{avatar_url}}",
                    "display_name": "{{display_name}}",
                    "identity_authorized_bc_id": "{{identity_authorized_bc_id}}",
                    "identity_id": "{{identity_id}}",
                    "identity_type": "BC_AUTH_TT"
                },
                "item_id": "{{item_id}}",
                "text": "{{text}}",
                "video_info": {
                    "bit_rate": {{bit_rate}},
                    "definition": "720p",
                    "duration": {{duration}},
                    "format": "mp4",
                    "fps": {{fps}},
                    "height": {{height}},
                    "preview_url": "{{preview_url}}",
                    "signature": "{{signature}}",
                    "size": {{size}},
                    "video_cover_url": "{{video_cover_url}}",
                    "video_id": "{{video_id}}",
                    "width": {{width}}
                }
            },
            {
                "can_change_anchor": true,
                "identity_info": {
                    "avatar_url": "{{avatar_url}}",
                    "display_name": "{{display_name}}",
                    "identity_id": "{{identity_id}}",
                    "identity_type": "TT_USER"
                },
                "item_id": "{{item_id}}",
                "text": "{{text}}",
                "video_info": {
                    "bit_rate": {{bit_rate}},
                    "definition": "720p",
                    "duration": {{duration}},
                    "format": "mp4",
                    "fps": {{fps}},
                    "height": {{height}},
                    "preview_url": "{{preview_url}}",
                    "signature": "{{signature}}",
                    "size": {{size}},
                    "video_cover_url": "{{video_cover_url}}",
                    "video_id": "{{video_id}}",
                    "width": {{width}}
                }
            }
        ],
        "page_info": {
            "page": 1,
            "page_size": 20,
            "total_number": 2,
            "total_page": 1
        }
    }
}

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