Developer resources

Create a Custom Conversion — TikTok Business API

Create a Custom Conversion · 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 a Custom Conversion

POST/custom_conversion/create/Via 360: POST https://partner.quantri360.com/v1/tiktok_business/custom_conversion/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 Custom Conversion for a Pixel or an App.

> Note

> - You can create a maximum of 1,000 Custom Conversions within an ad account.

> - For a Pixel or an App, you can create a maximum of 100 Custom Conversions.

Request

Endpoint

POST https://partner.quantri360.com/v1/tiktok_business/custom_conversion/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
name	body	string	Yes	The name of the Custom Conversion. The name must start with a letter and can include letters, numbers, spaces, underscores, or hyphens. Length limit: 50 characters and cannot contain emoji. Note: - Do not specify the name of a standard event. - Duplicate names for Custom Conversion within an ad account are not allowed.
description	body	string	No	The description of the Custom Conversion. Length limit: 500 characters and cannot contain emoji.
event_source_type	body	string	Yes	Event source type. Enum values: - `PIXEL`: Pixel. - `APP`: App.
event_source_id	body	string	Yes	Event source ID. - When `event_source_type` is `PIXEL`, specify a Pixel ID. - To obtain IDs of Pixels within your ad account, use /pixel/list/ and check the returned `pixel_id`. - When `event_source_type` is `APP`, specify the app platform ID of a Self Attribution Network (SAN) App. - This app can only be used with the TikTok App Events SDK. The SDK creates a direct first-party connection from your app to TikTok, reducing signal loss and providing more accurate measurement. Learn how to install the SDK. - To obtain app platform IDs of SAN Apps within your ad account, use /app/list/. Confirm that the returned `self_attribution_enabled` for the App is `true` and check the returned `app_platform_id`.
optimization_event	body	string	No	- Required in any of the following scenarios: - When `event_source_type` is `PIXEL`. - When `event_source_type` is `APP` and you are creating a custom conversion using a standard event. - When `event_source_type` is `APP` and you are creating a custom conversion using a Custom Event, and the app is allowlisted for mapping Custom Events to Standard Events. - Not supported when the following conditions are all met: - `event_source_type` is `APP`. - You are creating a custom conversion using a Custom Event. - The app is not allowlisted for mapping Custom Events to Standard Events. The Standard Event to associate with the Custom Conversion. For enum values, see List of values for `optimization_event`. Note: Mapping Custom Events to Standard Events while creating custom conversions using an app event source and a custom event is currently an allowlist-only feature. If you would like to access it, please contact your TikTok representative.
custom_event_type	body	string	No	Valid only when the Custom Event has been configured for the App or Pixel (`event_source_id`). The Custom Event to associate with the Custom Conversion. When you specify a Custom Event for the Custom Conversion, you need to specify the Standard Event to map the event to through `optimization_event` simultaneously. Custom Events are actions that TikTok partners can define themselves beyond the predefined Standard Events list. To learn more about Custom Events, see About Custom Events in TikTok Ads Manager. To obtain the Custom Events that are configured for a Pixel, use /pixel/list/ and check the returned `custom_event_type`. Note: When creating custom conversions using an app event source and a custom event, ensure that postbacks of the specified App Custom Event (`custom_event_type`) have been received before this custom conversion can be created. Otherwise, an error will occur.
rules	body	object[]	Yes	Details of the conversion rules for the Custom Conversion. Only actions that meet these conditions will count as Custom Conversions. Size range: 1-10.

Request examples

curl -s -X POST "https://partner.quantri360.com/v1/tiktok_business/custom_conversion/create/" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"","event_source_type":"","event_source_id":"","rules":[{"parameter":"","operator":"","values":[]}]}'

Python

import requests

KEY = "q360_live_..."  # khóa API của brand
r = requests.post(
    "https://partner.quantri360.com/v1/tiktok_business/custom_conversion/create/",
    params={},
    json={
        "name": "",
        "event_source_type": "",
        "event_source_id": "",
        "rules": [
            {
                "parameter": "",
                "operator": "",
                "values": []
            }
        ]
    },
    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/custom_conversion/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({"name":"","event_source_type":"","event_source_id":"","rules":[{"parameter":"","operator":"","values":[]}]}),
});
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/custom_conversion/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, '{"name":"","event_source_type":"","event_source_id":"","rules":[{"parameter":"","operator":"","values":[]}]}');
$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 Code.
message	string	Response message. For details, see Appendix - Return Codes.
request_id	string	The log ID of a request, which uniquely identifies the request.
data	object	Returned data.
custom_conversion_id	string	The ID of the Custom Conversion.

Response sample

HTTPS/1.1 200 OK
{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": {
        "custom_conversion_id": "{{custom_conversion_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