Developer resources

Create an audience by rule — TikTok Business API

Create an audience by rule · 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 an audience by rule

POST/dmp/custom_audience/rule/create/Via 360: POST https://partner.quantri360.com/v1/tiktok_business/dmp/custom_audience/rule/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 audience by rules.

To create an audience, you need to specify a set of inclusion rules and optionally a set of exclusion rules.

>Note

Newly created audiences require at most 48 hours to be analyzed and processed before they become active.
Use /dmp/custom_audience/get/ to check the current status of an audience. Only 'available' (is_valid = true) audiences can be operated on. Upon expiration, the audience will become 'Unavailable' (is_valid =false), and get detached from any active campaign.
If a campaign has no targeting settings other than audience targeting, it will be paused.

Comparing v1.2 and v1.3

The following table outlines the differences between v1.2 and v1.3 endpoints.

 |Changes{30%}|v1.2{35%}|v1.3{35%}|
|---|---|---|
|Endpoint path|/v1.2/dmp/custom_audience/rule/create/|/v1.3/dmp/custom_audience/rule/create/|
|Request parameter data type |`advertiser_id`: number
`is_auto_refresh`: number|`advertiser_id`: string
`is_auto_refresh`: boolean|
|New request parameters| / |`retention_in_days`
`identity_id`
`identity_type`
`identity_authorized_bc_id`
`parameter_filters` (including all parameters within the object array)|
|Response parameter data type |`custom_audience_id`: number|`custom_audience_id`: string|

Request

Endpoint

POST https://partner.quantri360.com/v1/tiktok_business/dmp/custom_audience/rule/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	Description
custom_audience_name	body	string	Yes	Audience name. Length limit: 128 characters.
audience_type	body	string	Yes	Audience type. Enum values: - `ENGAGEMENT`: Engagement Audience (with asset type as ad groups). - `ENGAGEMENT_ORGANIC_VIDEO`: Organic Engagement Audience (with asset type as public video). - `ENGAGEMENT_LIVE_VIDEO`: Live Engagement Audience (with asset type as live video). - `APP`: App Activity Audience. - `PIXEL`: Website Traffic Audience. - `LEAD_GENERATION`: Lead Generation Audience. - `BUSINESS_ACCOUNT`: Business Account Audience. - `TIKTOK_SHOP`: Shop Activity Audience. - `OFFLINE`: Offline Activity Audience.
audience_sub_type	body	string	No	Audience sub type, indicating the type of ads that the audience can be used. Enum values: - `NORMAL`: Audience for non-Reach & Frequency ads. - `REACH_FREQUENCY`: Audience for Reach & Frequency ads. It can only be used in Reach & Frequency ads. Default value: `NORMAL`.
retention_in_days	body	integer	No	Number of days to retain the audience. Value range: 1-365. Note: - If this field is passed, the expiration date will be the specified number of retention days from the date when the audience was created. Any operations to the audience CANNOT reset the expiration date. - If this field is not passed, the expiration date will be 365 days from the last time the audience was applied to an active ad group or modified. Applying the audience to an active ad group or modifying the audience will reset the expiration date. To learn about the actions that will reset the expiration date, refer to the Help Center article Audience Expiration Policy.
is_auto_refresh	body	boolean	No	Whether to turn on the audience auto-refresh function. Supported values: `true`, `false`. Default value: `true`. If you enable this feature, your audience will automatically refresh to include the latest user data according to the lookback window you set. If you disable this feature, your audience will not automatically refresh.
identity_id	body	string	No	Required when `audience_type` is `ENGAGEMENT_LIVE_VIDEO` or `ENGAGEMENT_ORGANIC_VIDEO`. Identity ID.
identity_type	body	string	No	Required when `audience_type` is `ENGAGEMENT_LIVE_VIDEO` or `ENGAGEMENT_ORGANIC_VIDEO`. Identity type. Enum values: `TT_USER`, `BC_AUTH_TT`
identity_authorized_bc_id	body	string	No	Required when `identity_type` is `BC_AUTH_TT`. ID of the Business Center that a TikTok Account User in Business Center identity is associated with.
rule_spec	body	object	Yes	Rule of the audience.

Request examples

curl -s -X POST "https://partner.quantri360.com/v1/tiktok_business/dmp/custom_audience/rule/create/" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"custom_audience_name":"","audience_type":"","rule_spec":{"inclusion_rule_set":{"operator":"","rules":[{"retention_days":0,"filter_set":{"operator":"","filters":[{"field":"","operator":"","value":""}]}}]}}}'

Python

import requests

KEY = "q360_live_..."  # khóa API của brand
r = requests.post(
    "https://partner.quantri360.com/v1/tiktok_business/dmp/custom_audience/rule/create/",
    params={},
    json={
        "custom_audience_name": "",
        "audience_type": "",
        "rule_spec": {
            "inclusion_rule_set": {
                "operator": "",
                "rules": [
                    {
                        "retention_days": 0,
                        "filter_set": {
                            "operator": "",
                            "filters": [
                                {
                                    "field": "",
                                    "operator": "",
                                    "value": ""
                                }
                            ]
                        }
                    }
                ]
            }
        }
    },
    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/dmp/custom_audience/rule/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({"custom_audience_name":"","audience_type":"","rule_spec":{"inclusion_rule_set":{"operator":"","rules":[{"retention_days":0,"filter_set":{"operator":"","filters":[{"field":"","operator":"","value":""}]}}]}}}),
});
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/dmp/custom_audience/rule/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, '{"custom_audience_name":"","audience_type":"","rule_spec":{"inclusion_rule_set":{"operator":"","rules":[{"retention_days":0,"filter_set":{"operator":"","filters":[{"field":"","operator":"","value":""}]}}]}}}');
$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	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.
custom_audience_id	string	Custom audience ID.
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": {
        "custom_audience_id": "{{custom_audience_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