VI | EN
Message us on Messenger
Developer resources

Create a Saved Audience — TikTok Business API

Create a Saved Audience · 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 a Saved Audience

POST/dmp/saved_audience/create/Via 360: POST https://partner.quantri360.com/v1/tiktok_business/dmp/saved_audience/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 a Saved Audience. An advertiser account can have up to 400 Saved Audiences.

Request

Endpoint

POST https://partner.quantri360.com/v1/tiktok_business/dmp/saved_audience/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
saved_audience_namebodystringYesSaved Audience name. Character limit is 512 and cannot contain emoji.
location_idsbodystring[]YesIDs of the locations that you want to target. To get the available locations and corresponding IDs, use the /tool/region/ or /tool/targeting/search/ endpoint. Note: - Overlapping targeted locations are not supported. For instance, you cannot target the U.S. and the state of California at the same time.
genderbodystringNoGender that you want to target. Enum values: GENDER_FEMALE,GENDER_MALE,GENDER_UNLIMITED
age_groupsbodystring[]NoAge groups you want to target. For enum values, see Enumeration - Targeting Age Group.
languagesbodystring[]NoCodes of the languages that you want to target. You can get language codes via /tool/language/, and if you don't want to limit the languages you target, assign an empty value to this field or do not pass in this field.
audience_idsbodystring[]NoList of audience IDs. You can get audience IDs via the /dmp/custom_audience/list/ endpoint.
excluded_audience_idsbodystring[]NoList of audience IDs to be excluded. You can get audience IDs via the /dmp/custom_audience/list/ endpoint.
interest_category_idsbodystring[]NoInterest classification. You can use /tool/target_recommend_tags/ to get a list of recommended interest categories based on your targeting regions and your industries, or use /tool/interest_category/ endpoint to get the complete list of interest categories. If the interest is specified, users who do not meet the interest target will be excluded during delivery. Do not specify if you wish to target everyone.
interest_keyword_idsbodystring[]NoIDs of interest keywords that you want to use to target audience. You can use /tool/interest_keyword/recommend/ to get recommended interest keywords.
actionsbodyobject[]NoA list of action category objects.
operating_systemsbodystring[]NoDevice operating systems that you want to target. Enum values: ANDROID, IOS. Only one value is allowed.
min_android_versionbodystringNoMinimum device Android version. For enum values, see Enumeration - Minimum Android Version.
min_ios_versionbodystringNoMinimum iOS version. For enum values, see Enumeration - Minimum iOS Version.
device_model_idsbodystring[]NoIDs of the device models that you want to target. Use /tool/device_model/ to get the complete list of device model IDs and their statuses, and only active devices (is_active = true in the response of /tool/device_model/) can be used to create ads. Note: Device model (device_model_ids) and device price (device_price_ranges) cannot be set at the same time.
network_typesbodystring[]NoDevice connection types that you want to target. Default: unlimited. For enum values, see Enumeration - Connection Type.
carrier_idsbodystring[]NoCarriers that you want to target. Use /tool/carrier/ endpoint to get a list of carriers. A carrier is valid only when the in_use field for the carrier is true. The carriers must be consistent with the location(s) that you want to target.
device_price_rangesbodynumber[]NoTargeting device price range. 10000 means 1000+. The numbers must be in multiples of 50. Important: The upper limit you set will be added by 50 and the resulting new number will be used as the actual upper limit for device targeting. The actual upper limit is shown in the ad group settings in TikTok Ads Manager. If you set and get the price range of [0, 250], it actually means [0, 300].

Request examples

curl -s -X POST "https://partner.quantri360.com/v1/tiktok_business/dmp/saved_audience/create/" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"saved_audience_name":"","location_ids":[],"actions":[{}]}'
Python
import requests

KEY = "q360_live_..."  # khóa API của brand
r = requests.post(
    "https://partner.quantri360.com/v1/tiktok_business/dmp/saved_audience/create/",
    params={},
    json={
        "saved_audience_name": "",
        "location_ids": [],
        "actions": [
            {}
        ]
    },
    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/saved_audience/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({"saved_audience_name":"","location_ids":[],"actions":[{}]}),
});
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/saved_audience/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, '{"saved_audience_name":"","location_ids":[],"actions":[{}]}');
$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
codenumberReturn code. For the complete list of response codes and descriptions, see Return codes.
messagestringResponse message. For details, see Return codes.
request_idstringThe log ID of a request, which uniquely identifies the request.
dataobjectReturned data.
saved_audience_idstringSaved Audience ID.

Response sample

{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": {
        "saved_audience_id": "{{saved_audience_id}}"
    }
}

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