Developer resources

Get all audiences — TikTok Business API

Get all audiences · 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

Get all audiences

GET/dmp/custom_audience/list/Via 360: GET https://partner.quantri360.com/v1/tiktok_business/dmp/custom_audience/list/

Description

Use this endpoint to get all audiences. The returned list is paginated with a maximum paging size of 100. For each audience, information like ID, name, type, creation time, expiration time will be returned in the response. This endpoint returns both owned and shared audiences. You can use is_creator to check whether this advertiser is the owner of this audience.

To get more details about an audience, such as current status and modification record, use /dmp/custom_audience/get/ instead.

Request

Endpoint

GET https://partner.quantri360.com/v1/tiktok_business/dmp/custom_audience/list/

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_ids	query	string[]	No	A list of Audience IDs. Length range is [1, 100].
page	query	number	No	Current page number. Default value: `1`. Value range: ≥ 1.
page_size	query	number	No	Page size. Defaults is `10`. Value range: 1-100.

Request examples

curl -s "https://partner.quantri360.com/v1/tiktok_business/dmp/custom_audience/list/" \
  -H "Authorization: Bearer $KEY"

Python

import requests

KEY = "q360_live_..."  # khóa API của brand
r = requests.get(
    "https://partner.quantri360.com/v1/tiktok_business/dmp/custom_audience/list/",
    params={},
    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/list/');
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: 'GET',
  headers: { Authorization: `Bearer ${KEY}` },
});
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/list/' . '?' . http_build_query([]);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $key]);
$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, see Appendix-Return Codes.
message	string	Return message, see Appendix-Return Codes.
data	object	Returned data.
list	object[]	A list of Audience.
shared	boolean	Whether this audience is shared with others. Enum values: `True`, `False`.
is_creator	boolean	Whether this advertiser is the owner of the audience. Enum values: `true`, `false`. You can use `shared` and `is_creator` to check audience ownership and shared status. The rules are as follows: 1. `shared` = `true` and `is_creator` = `true`: The advertiser is the owner and the audience is shared to others. 2. `shared` = `true` and `is_creator` = `false`: The advertiser is NOT the owner and the audience is shared by others. 3. `shared` = `false` and `is_creator` = `true`: The advertiser is the owner and the audience has not been shared to others.
audience_id	string	Audience ID.
cover_num	number	Coverage, or number of matched users on TikTok.
create_time	string	Time when the audience was created. GMT time.
is_valid	boolean	Audience availability. An audience becomes available after it has been processed. An audience becomes invalid after it is expired.
is_expiring	boolean	Whether an audience is expiring. When an audience is expiring, it will expire in less than 60 days.
expired_time	string	Time when the audience expires, in the format of "YYYY-MM-DD HH:MM:SS".
name	string	Audience name.
audience_type	string	Audience type. Enum values: - `Customer File Audience` (Customer File Audience). - `Engagement Audience` (Engagement Audience). - `App Activity Audience` (App Activity Audience). - `Website Audience` (Website Traffic Audience). - `Lookalike Audience` (Lookalike Audience). - `Lead Generation `(Lead Generation Audience) - `Rule Business Account` (Business Account Audience) - `Rule ad shop` (Shop Activity Audience) - `Partner` (Partner Audience) - `Challenge` (Challenge Audience) - `Preferred Population` (Premium Audience)Note: Currently, Partner Audience, Challenge Audience and Premium Audience cannot be created through the API.
calculate_type	string	Encryption type, only applies to customer file audience. For enum values, see Enumeration - Encryption Type.
page_info	object	Pagination information.
page	number	Current page number.
page_size	number	Paging size.
total_number	number	Total number of results.
total_page	number	Total pages of results.
request_id	string	The log ID of a request, which uniquely identifies the request.

Response sample

HTTPS/1.1 200 OK
{
HTTPS/1.1 200 OK
{
    "code": 0,
    "message": "OK",
    "request_id": "123",
    "data": {
        "page_info": {
            "page_size": 10,
            "total_number": 1,
            "page": 1,
            "total_page": 1
        },
        "list": [
            {
                "cover_num": 6489086,
                "is_valid": false,
                "calculate_type": null,
                "is_creator": false,
                "audience_id": "123",
                "name": "CUSTOM_AUDIENCE_NAME",
                "is_expiring": false,
                "create_time": "2022-05-26 22:12:12",
                "audience_type": "Lookalike Audience",
                "expired_time": "2023-09-08 02:34:20",
                "shared": true
            }
        ]
    }
}
(/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