Developer resources

Create/Delete an audience segment — TikTok Business API

Create/Delete an audience segment · 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.

Open in the API index TikTok Business platform page

Create/Delete an audience segment

POST/segment/audience/Via 360: POST https://partner.quantri360.com/v1/tiktok_business/segment/audience/

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 or delete an audience segment.

Please see About Streaming API - Important Notes for Streaming API to learn about the notes about Multiple Advertisers Associated with a Business Account and Mixed Segments with IDFA/AAID, and Guidelines for identifier normalization to learn about how to normalize your identifiers.

>Note

We review applications on an ongoing basis.

> Note

The rate limit is 1 QPS per advertiser account.
You can create up to a maximum of 400 audience segments for an advertiser account. Existing audiences need to be deleted prior to new audience creation if the advertiser account reaches this limit. This limit is at advertiser level.

Request

Endpoint

POST https://partner.quantri360.com/v1/tiktok_business/segment/audience/

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	Description
action	body	string	Yes	Type of action to be performed. Enum values: - `create`: To create an audience segment. You will also need to include `custom_audience_name` in the request. - `delete`: To delete an audience segment. You will also need to include `delete_audience_id` in the request. If no value is specified, the default value is `create`.
custom_audience_name	body	string	No	Custom audience name of audience to be created. Please note that names over 70 characters will be truncated to 67 characters with "..." appended. This field is required when the value of `action` is `create`.
delete_audience_id	body	string	No	Audience ID to be deleted. This field is required when the value of `action` is `delete`.

Request examples

curl -s -X POST "https://partner.quantri360.com/v1/tiktok_business/segment/audience/" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":""}'

Python

import requests

KEY = "q360_live_..."  # khóa API của brand
r = requests.post(
    "https://partner.quantri360.com/v1/tiktok_business/segment/audience/",
    params={},
    json={
        "action": ""
    },
    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/segment/audience/');
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({"action":""}),
});
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/segment/audience/' . '?' . 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, '{"action":""}');
$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	Description
code	number	Return code. For the complete list of response codes and descriptions, see Appendix-Return Codes.
message	string	Return message. For details, see Appendix-Return Codes.
data	object	Returned data.
audience_id	string	Audience ID. You will use this field when creating audience mappings.
request_id	string	The log id of a request, which uniquely identifies the request.

Response sample

HTTPS/1.1 200 OK
{
    "code": 200,
    "message": "OK",
    "request_id":"XXXXXXXXXXXXXX",
    "data": {
        "audience_id": 100008357
    }
}
(/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