Create a split test
POST/split_test/create/Via 360: POST https://partner.quantri360.com/v1/tiktok_business/split_test/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 split test group.
Before you start, see here to find out the prerequisites of creating a split test and here to find out how to create a split test.
Currently, we support split test at ad group level and campaign level. For ad group level split test, the total budget will be evenly distributed to each group. For campaign level split test, the budget will follow the existing budget amount set for each campaign.
Request
Endpoint
POST https://partner.quantri360.com/v1/tiktok_business/split_test/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 | Sample | Description |
|---|---|---|---|---|---|
| split_test_level | body | string | No | Split test level.
Enum values:
- ADGROUP(Ad group level split test.)
- CAMPAIGN(Campaign level split test.)Default value: ADGROUP.
Note:
- Campaign-level split tests are currently an allowlist-only feature. If you would like to access it, please contact your TikTok representative.
- Comparing two ad groups from different campaigns in a split test is currently an allowlist-only feature. If you would like to access it, please contact your TikTok representative. The campaigns can have different advertising objectives. | |
| object_ids | body | string[] | No | adgroup_ids bound to this split-test.
- For ad group level split test, input either this field or cells.
- For campaign level split test, input cells instead of this field. | |
| cells | body | object[] | No | Required when split_test_level is set to CAMPAIGN.
List of cells in split test. The length must be 2. | |
| test_variable | body | string | No | Split test variable. It will NOT affect your test results.
Enum values:
- BIDDING_OPTIMIZATION: Set different optimization values for bidding & optimization fields to compare how optimization methods impact your ad performance.
- TARGTING: Set different targeting values at the ad group level for comparing how effective your ad groups are at reaching different audiences or demographics.
- CREATIVE: Set different creatives to compare how different creatives impact your ad performance.
- CUSTOM: Set multiple variables to compare how these variables impact your ad performance. This enum value is only available for campaign level split test.Default value:
- For ad group level split test, the default value is BIDDING_OPTIMIZATION.
- For campaign level split test, the default value is CUSTOM.
Note: The test_variable cannot be updated once specified. | |
| key_metric | body | string | No | The key metric you want to monitor.
Enum values:
- UNSET: Unset.
- CONVERT_RATE: CVR (Conversion rate).
- CLICK_THROUGH_RATE: Click through rate (CTR).
- COST_PER_SHOW: Cost per mille (CPM).
- COST_PER_CONVERT: Cost per conversion.
- COST_PER_REACH: Cost per reach.
- COST_PER_CLICK: Cost per click.
- COST_PER_FOCUSED_VIEW: Cost per focused view.
- FOCUSED_VIEW_RATE: Focused view rate.
- COMPLETE_PAYMENT_ROAS: Complete Payment ROAS.
- COST_PER_LANDING_PAGE_VIEW: Cost per landing page view.
- LANDING_PAGE_VIEW_RATE: Landing page view rate.
- CLICK(deprecated): Click.
- REACH(deprecated): Reach.
- SHOW(deprecated): Impression.
- CONVERT(deprecated): Conversion.
- COST(deprecated): Cost.
See Super Split Test - Supported optimization goals to find out the key metrics supported under different optimization goals.
If no value is specified for this field, the following default values will be used:
- For ad group level split test, if both ad groups use REACH optimization goal, the default key metric will be COST_PER_REACH. Otherwise, the default key metric will be COST_PER_SHOW.
- For campaign level split test, the default key metric is UNSET. | |
| budget | body | float | No | - Required when split_test_level is set to ADGROUP.
- Do not specify this field when split_test_level is set to CAMPAIGN. Otherwise, an error will occur.
The total split test budget.
- For ad group level split test, the budget will be distributed to each group evenly. This budget specified here will overwrite the existing budgets in the two ad groups. If you want to change the total budget after the test has started, we recommend you update the budgets in the two ad groups to the same value.
- For campaign level split test, the budget will follow the existing budget amount set for each campaign. | |
| start_time | body | string | Yes | The start time of this split test, in the format of YYYY-MM-DD HH:MM:SS (UTC+0). Example: 2022-01-01 00:00:00. Note: - The time of campaign level split test can only be set to hour level. Thus, any MM and SS input will default to 00. - The start time set for campaign level split test will not overwrite the start time of campaigns and ad groups in this test. | |
| end_time | body | string | Yes | The end time of this split test, in the format of YYYY-MM-DD HH:MM:SS (UTC+0). Example: 2022-01-01 00:00:00. Note: - The time of campaign level split test can only be set to hour level. Thus, any MM and SS input will default to 00. - The end time set for campaign level split test will not overwrite the end time of campaigns and ad groups in this test. |
Request examples
curl -s -X POST "https://partner.quantri360.com/v1/tiktok_business/split_test/create/" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"cells":[{}],"start_time":"","end_time":""}'
Python
import requests
KEY = "q360_live_..." # khóa API của brand
r = requests.post(
"https://partner.quantri360.com/v1/tiktok_business/split_test/create/",
params={},
json={
"cells": [
{}
],
"start_time": "",
"end_time": ""
},
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/split_test/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({"cells":[{}],"start_time":"","end_time":""}),
});
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/split_test/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, '{"cells":[{}],"start_time":"","end_time":""}');
$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 | 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. | |
| split_test_group_id | string | Split test group ID. | |
| request_id | string | The log id of a request, which uniquely identifies the request. |
Response sample
{
"code": 0,
"message": "OK",
"request_id": "{{request_id}}",
"data": {
"split_test_group_id": "{{split_test_group_id}}"
}
}
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