Add/Delete audience segment mappings
POST/segment/mapping/Via 360: POST https://partner.quantri360.com/v1/tiktok_business/segment/mapping/
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 add mappings to audience segments, or delete existing mappings from audience segments. The mapping can be single ID mapping (one audience ID per user or device) or multiple ID mapping (multiple audience IDs per user or device ).
Please see Customer File API vs Streaming API - Important Notes for Streaming API to learn about the notes about Multiple Advertisers Associated with a Business Account, and Guidelines for identifier normalization to learn about how to normalize your identifiers.
>Note
We review applications on an ongoing basis.
>Note
- Rate limits:
- 10 audience IDs in one request.
- 5,000 QPS per advertiser account per app.
- 1 billion IDs (user or device IDs) per day per advertiser account.
- Streaming API specific rate limit is 10,000 QPS (Basic), 20,000 QPS (Advanced), 30,000 QPS (Premium), 50,000 QPS (Ultimate).
- Payload size limit is 1,000 IDs per request.
- SLA: Upon making the API call, you'll immediately receive a success/error response. In case of success, our system will process the IDs asynchronously, for which the SLA is 48 hours.
Request
Endpoint
POST https://partner.quantri360.com/v1/tiktok_business/segment/mapping/
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 | Sample | Description |
|---|---|---|---|---|---|
| advertiser_ids | body | string[] | Yes | A list of advertiser IDs to make segment mappings, or delete existing segment mappings. All advertiser IDs must belong to the same business account. | |
| action | body | string | No | Type of action to be performed.
Enum values:
- add: To add UIDs to an audience or a group of audiences.
- delete: To remove UIDs from an audience or a group of audiences. Default value: add.
Note: UID refers to
- hashed Device ID ( id_type= IDFA_MD5, AAID_MD5, IDFA_SHA256, or AAID_SHA256).
- External user ID such as hashed email or hashed phone (id_type=EMAIL_SHA256,PHONE_SHA256) | |
| id_schema | body | string[] | Yes | ID Types to be used for populating the audiences.
Allowed values:
- IDFA_MD5: MD5 hash of an iOS IDFA.
- AAID_MD5: MD5 hash of an Android AAID/GAID.
- IDFA_SHA256: SHA256 iOS IDFA.
- AAID_SHA256: SHA256 Android AAID/GAID.
- EMAIL_SHA256: SHA256 hash of email ID.
- PHONE_SHA256: SHA256 hash of a phone number in E.164 form, e.g. +1231234567.
Note:
- Duplicate ID Types are not allowed.
- The ID Types can be provided in any order, and you can pass in the allowed values in lower case. | |
| batch_data | body | object[][] | Yes | batch_data contains one or more of the following items as an array in JSON format. The field is used to add or delete multiple ID mapping (multiple audience IDs per user or device ). |
Request examples
curl -s -X POST "https://partner.quantri360.com/v1/tiktok_business/segment/mapping/" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"advertiser_ids":[],"id_schema":[],"batch_data":[{}]}'
Python
import requests
KEY = "q360_live_..." # khóa API của brand
r = requests.post(
"https://partner.quantri360.com/v1/tiktok_business/segment/mapping/",
params={},
json={
"advertiser_ids": [],
"id_schema": [],
"batch_data": [
{}
]
},
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/mapping/');
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({"advertiser_ids":[],"id_schema":[],"batch_data":[{}]}),
});
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/mapping/' . '?' . 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, '{"advertiser_ids":[],"id_schema":[],"batch_data":[{}]}');
$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 | Sample | 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 message. | |
| data | object | Returned data. | |
| 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": "XXXXXXXXXX",
"data": {}
}
(/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