# TikTok Events API

[TikTok for Business](https://www.tiktok.com/business/en) is a global platform designed to give brands and marketers the solutions to be creative storytellers and meaningfully engage with the TikTok community.\
The TikTok Events API is a server-side integration that allows you to share website and app visitor events directly with TikTok using their [Events API for Web](https://business-api.tiktok.com/portal/docs?id=1771100865818625) and [Events API for App](https://business-api.tiktok.com/portal/docs?id=1771101111730178) version 2.0.

{% hint style="warning" %}
The [Events API for APP](https://business-api.tiktok.com/portal/docs?id=1771101111730178) support is currently under beta testing.
{% endhint %}

## Key features

The TikTok Events API destination provides the following key features:

* **Events structure**: our [Events reference](https://community.commandersact.com/platform-x/developers/tracking/events-reference) matches [TikTok's one](https://business-api.tiktok.com/portal/docs?rid=959icq5stjr\&id=1771100779668482), meaning that your data is properly bridged to the expected fields in an optimized way.
* **Prebuilt mappings**: data mapping for event-based destinations happens automatically, which simplifies user inputs.
* **Automatic hashing**: information is automatically hashed matching partner specifications.
* **Smart mapping**: data mapping can be readjusted using your datalayer defined fields.
* **Support for multi-item data**: information included in the [item](https://community.commandersact.com/platform-x/developers/tracking/events-reference#item) array is dispatched to TikTok.
* **Support for test event code**: real-time validation in your test environments with field <mark style="color:blue;">`test_event_code`</mark>.

## Destination setup

Before you get started with this destination, make sure you can access [TikTok Ads Manager](https://ads.tiktok.com).

{% hint style="warning" %}
TikTok custom events are available for reporting and audience creation purposes. Optimization is currently NOT supported.
{% endhint %}

### Configuration

<table><thead><tr><th width="359">Settings</th><th>Description</th></tr></thead><tbody><tr><td><code>Access Token</code></td><td><em><strong><code>Required</code></strong></em> for <a href="https://business-api.tiktok.com/portal/docs?id=1771100865818625">Web events</a>.<br>Your <a href="https://business-api.tiktok.com/portal/docs?id=1771101130925058">API Access Token</a> as provided by TikTok. More details are available by following this <a href="https://ads.tiktok.com/gateway/docs/index?identify_key=2b9b4278e47b275f36e7c39a4af4ba067d088e031d5f5fe45d381559ac89ba48&#x26;language=ENGLISH&#x26;doc_id=1727537566862337#item-link-How%20to%20generate%20an%20access%20token">LINK</a>.</td></tr><tr><td><code>Pixel Id</code></td><td><em><strong><code>Required</code></strong></em> for <a href="https://business-api.tiktok.com/portal/docs?id=1771100865818625">Web events</a>.<br>Your pixel identifier as provided by TikTok. More details are available by following this <a href="https://business-api.tiktok.com/portal/docs?id=1771101001228290#item-link-Q2%3A%20Where%20can%20I%20find%20the%20Pixel%20Code%3F">LINK</a>.</td></tr><tr><td><code>App Id</code></td><td><em><strong><code>Required</code></strong></em> for <a href="https://business-api.tiktok.com/portal/docs?id=1771101111730178">App events</a>.<br>Your app identifier as provided by TikTok. More details are available by following this <a href="https://business-api.tiktok.com/gateway/docs/index?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b&#x26;language=ENGLISH&#x26;doc_id=1771101111730178#item-link-Create%20an%20App%20in%20Events%20Manager%20and%20obtain%20an%20access%20token">LINK</a>.</td></tr><tr><td><code>Test Event Code</code></td><td>For <a href="https://business-api.tiktok.com/portal/docs?id=1771100865818625">Web events</a> only. This is used to test event tracking before deploying in production. This code can be found in the <a href="https://ads.tiktok.com/">TikTok Ads Manager</a> following <code>Assets</code> ➜ <code>Events</code> ➜ <code>Manage (Web Events)</code> ➜ Select your pixel ➜ <code>Test Events (Tab)</code> <strong>[1]</strong></td></tr><tr><td><code>Event Mapping</code></td><td>Change the standard mapping between TikTok's events and yours or add new mappings: custom events are also supported. More details on how you can set up custom TikTok web events are available following this <a href="https://business-api.tiktok.com/portal/docs?id=1740858531237890">LINK</a>.</td></tr><tr><td><code>TikTok "ViewContent" Event Mapping</code></td><td>Select <mark style="color:blue;"><code>page_view</code></mark>, <mark style="color:blue;"><code>view_item</code></mark> or both to send TikTok <mark style="color:blue;"><code>ViewContent</code></mark> event. See <a href="#quick-reference">Quick reference</a> for more details on event mapping.</td></tr><tr><td><code>Autodiscovery Event Source</code></td><td>Flag this option to set TikTok <code>event_source</code> based on the value provided in the "Smart Mapping" field <code>Experience Type</code> or in the standard property <code>context.app</code> . The "Smart Mapping" field <code>Event Source</code> has priority over this option.</td></tr><tr><td><code>Do Not Lower Case User Id</code></td><td>When flagged and the <code>User Id</code> (See <code>Smart Mapping</code> section) is provided in clear test, the user identifier is not forced to lower case before applying SHA256 hash algorithm.</td></tr></tbody></table>

{% hint style="info" %}

> **1.** The <mark style="color:blue;">`Test Event Code`</mark> can only be set in test environments as TikTok won't save data coming from live events where this code is included. More details are available following this [LINK](https://business-api.tiktok.com/portal/docs?id=1771100984456193).
> {% endhint %}

## Quick reference

{% hint style="info" %}
TikTok standard events are detailed in this [LINK](https://business-api.tiktok.com/portal/docs?id=1771101186666498).
{% endhint %}

| Commanders Act Events                                                                                                                   | TikTok Events                                                                                                        |
| --------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `achieve_level`                                                                                                                         | `AchieveLevel` **\[2]**                                                                                              |
| `add_payment_info`                                                                                                                      | `AddPaymentInfo`                                                                                                     |
| `add_to_cart`                                                                                                                           | `AddToCart`                                                                                                          |
| `add_to_wishlist`                                                                                                                       | `AddToWishlist`                                                                                                      |
| `application_approval`                                                                                                                  | `ApplicationApproval` **\[1]**                                                                                       |
| `begin_checkout`                                                                                                                        | `InitiateCheckout` **\[1]**                                                                                          |
| <p><code>click\_button</code></p><p><code>view\_content</code></p>                                                                      | `ViewContent`                                                                                                        |
| `complete_tutorial`                                                                                                                     | `CompleteTutorial` **\[2]**                                                                                          |
| `create_group`                                                                                                                          | `CreateGroup` **\[2]**                                                                                               |
| `create_role`                                                                                                                           | `CreateRole` **\[2]**                                                                                                |
| `customize_product`                                                                                                                     | `CustomizeProduct` **\[1]**                                                                                          |
| `purchase`                                                                                                                              | <p><code>CompletePayment</code> <strong>\[1]\[4]</strong><br><code>Checkout</code> <strong>\[2]</strong></p>         |
| `complete_payment`                                                                                                                      | <p><code>CompletePayment</code> <strong>\[1]\[4]</strong><br><code>Purchase</code> <strong>\[2]</strong></p>         |
| `contact`                                                                                                                               | `Contact` **\[1]**                                                                                                   |
| `download`                                                                                                                              | `Download` **\[1]**                                                                                                  |
| `find_location`                                                                                                                         | `FindLocation` **\[1]**                                                                                              |
| <p><code>submit\_form</code></p><p><code>generate\_lead</code></p>                                                                      | `Lead` **\[1]**                                                                                                      |
| `generate_lead`                                                                                                                         | `GenerateLead` **\[2]**                                                                                              |
| `in_app_ad_click`                                                                                                                       | `InAppADClick` **\[2]**                                                                                              |
| `in_app_ad_impr`                                                                                                                        | `InAppAdImpr` **\[2]**                                                                                               |
| `install_app`                                                                                                                           | `InstallApp` **\[2]**                                                                                                |
| `join_group`                                                                                                                            | `JoinGroup` **\[2]**                                                                                                 |
| `launch_app`                                                                                                                            | `LaunchAPP` **\[2]**                                                                                                 |
| `loan_application`                                                                                                                      | `LoanApplication` **\[2]**                                                                                           |
| `loan_approval`                                                                                                                         | `LoanApproval` **\[2]**                                                                                              |
| `loan_disbursal`                                                                                                                        | `LoanDisbursal` **\[2]**                                                                                             |
| `login`                                                                                                                                 | `Login` **\[2]**                                                                                                     |
| <p><code>view\_content</code></p><p><code>page\_view</code><strong>\[3]</strong></p><p><code>view\_item</code><strong>\[3]</strong></p> | `ViewContent`                                                                                                        |
| `rate`                                                                                                                                  | `Rate` **\[2]**                                                                                                      |
| `schedule`                                                                                                                              | `Schedule` **\[1]**                                                                                                  |
| `search`                                                                                                                                | `Search`                                                                                                             |
| `sign_up`                                                                                                                               | <p><code>CompleteRegistration</code> <strong>\[1]</strong></p><p><code>Registration</code> <strong>\[2]</strong></p> |
| `spend_credits`                                                                                                                         | `SpendCredits` **\[2]**                                                                                              |
| `start_trial`                                                                                                                           | `StartTrial`                                                                                                         |
| `submit_application`                                                                                                                    | `SubmitApplication` **\[1]**                                                                                         |
| `subscribe`                                                                                                                             | `Subscribe`                                                                                                          |
| `unlock_achievement`                                                                                                                    | `UnlockAchievement` **\[2]**                                                                                         |

{% hint style="info" %}

> **1.** For web events only. See <mark style="color:blue;">`event_source`</mark> in [Configuration](#configuration) for more details.\
> **2.** For app events only. See <mark style="color:blue;">`event_source`</mark> in [Configuration](#configuration) for more details.\
> **3.** Depending on your selection for <mark style="color:blue;">`TikTok "ViewContent" Event Mapping`</mark> . See [Configuration](#configuration) for more details.\
> **4.** With <mark style="color:blue;">`CompletePayment`</mark> events you can take advantage of TikTok [Value-Based Optimization for Web](https://ads.tiktok.com/help/article?aid=10008856) (VBO Web).
> {% endhint %}

## Field mappings

{% hint style="info" %}
Most properties can be remapped using our "Smart Mapping" feature.\
TikTok client-side pixel saves a unique identifier in cookie [**\_ttp**](https://business-api.tiktok.com/portal/docs?rid=4eezrhr6lg4\&id=1771100936446977)**,** which is used to match website visitor events with TikTok ads. This destination starts by getting this identifier from <mark style="color:blue;">`partners.tiktok.ttp`</mark> . If it's not present, it looks for the previously mentioned cookie [**\_ttp**](https://business-api.tiktok.com/portal/docs?rid=4eezrhr6lg4\&id=1771100936446977) and sets TikTok <mark style="color:blue;">`data.0.user.ttp`</mark> with the resulting value.\
The [Tiktok Click ID](https://business-api.tiktok.com/portal/docs?rid=4eezrhr6lg4\&id=1771100879787009) is a tracking parameter that is attached to your ad's landing page URLs. This destination checks if <mark style="color:blue;">`partners.tiktok.ttclid`</mark> is set with the ttclid value. If it's not present, it looks for cookie <mark style="color:blue;">ttclid</mark>. If none is found it tries by parsing the value from <mark style="color:blue;">`context.page.url`</mark> .
{% endhint %}

<table><thead><tr><th width="330.6685580062746">Commanders Act Properties</th><th>TikTok Properties</th></tr></thead><tbody><tr><td><code>partners.tiktok.event_source</code></td><td><code>event_source</code> <strong>[*][1]</strong></td></tr><tr><td><p><code>Pixel Id</code></p><p><code>App Id</code></p></td><td><code>event_source_id</code> <strong>[*]</strong></td></tr><tr><td><code>event_name</code></td><td><code>data.0.event</code> <strong>[*][2]</strong></td></tr><tr><td><code>context.event_timestamp</code></td><td><code>data.0.event_time</code> <strong>[*][3]</strong></td></tr><tr><td><code>id</code></td><td><code>data.0.event_id</code> <strong>[4]</strong></td></tr><tr><td><code>partners.tiktok.ttclid</code></td><td><code>data.0.user.ttclid</code> <strong>[5]</strong></td></tr><tr><td><code>user.id</code></td><td><code>data.0.user.external_id</code> <strong>[6]</strong></td></tr><tr><td><code>partners.tiktok.ttp</code></td><td><code>data.0.user.ttp</code> <strong>[7]</strong></td></tr><tr><td><code>context.page.url</code></td><td><code>data.0.page.url</code></td></tr><tr><td><code>context.page.referrer</code></td><td><code>data.0.page.referrer</code></td></tr><tr><td><code>context.device.advertising_id</code></td><td><code>data.0.user.idfa</code> <strong>[8]</strong></td></tr><tr><td><code>context.device.idfv</code></td><td><code>data.0.user.idfv</code> <strong>[8]</strong></td></tr><tr><td><code>context.device.att_status</code></td><td><code>data.0.user.att_status</code> <strong>[8][9]</strong></td></tr><tr><td><code>context.device.advertising_id</code></td><td><code>data.0.user.gaid</code> <strong>[10]</strong></td></tr><tr><td><code>context.app.namespace</code></td><td><code>data.0.app.app_id</code> <strong>[11]</strong></td></tr><tr><td><code>context.app.name</code></td><td><code>data.0.app.app_name</code></td></tr><tr><td><code>context.app.version</code></td><td><code>data.0.app.app_version</code></td></tr><tr><td><code>user.email</code></td><td><code>data.0.user.email</code> <strong>[6]</strong></td></tr><tr><td><code>user.phone</code></td><td><code>data.0.user.phone</code> <strong>[6][12]</strong></td></tr><tr><td><code>context.device.ip</code></td><td><code>data.0.user.ip</code></td></tr><tr><td><code>context.device.user_agent</code></td><td><code>data.0.user.user_agent</code></td></tr><tr><td><code>context.device.language</code></td><td><code>data.0.user.locale</code> <strong>[13]</strong></td></tr><tr><td><code>partners.tiktok.ldu</code></td><td><code>data.0.limited_data_use</code> <strong>[14]</strong></td></tr><tr><td><code>items.X.content_type</code></td><td><code>data.0.properties.contents.X.content_type</code> <strong>[15]</strong></td></tr><tr><td><code>items.X.id</code></td><td><p><code>data.0.properties.contents.X.content_id</code></p><p><code>data.0.properties.content_ids</code> <strong>[16]</strong></p></td></tr><tr><td><code>items.X.product.price</code></td><td><code>data.0.properties.contents.X.price</code></td></tr><tr><td><code>items.X.quantity</code></td><td><code>data.0.properties.contents.X.quantity</code></td></tr><tr><td><code>items.X.product.name</code></td><td><code>data.0.properties.contents.X.content_name</code></td></tr><tr><td><code>items.X.product.category_1</code></td><td><code>data.0.properties.contents.X.content_category</code></td></tr><tr><td><code>items.X.product.brand</code></td><td><code>data.0.properties.contents.X.brand</code></td></tr><tr><td><code>search_term</code></td><td><code>data.0.properties.search_string</code> <strong>[17]</strong></td></tr><tr><td><code>id</code></td><td><code>data.0.properties.order_id</code> <strong>[17]</strong></td></tr><tr><td><code>partners.tiktok.shop_id</code></td><td><code>data.0.properties.shop_id</code> <strong>[17]</strong></td></tr><tr><td><code>status</code></td><td><code>data.0.properties.status</code> <strong>[17]</strong></td></tr><tr><td><code>content_type</code></td><td><code>data.0.properties.content_type</code> <strong>[17]</strong></td></tr><tr><td><code>currency</code></td><td><code>data.0.properties.currency</code></td></tr><tr><td><code>event_name</code></td><td><code>data.0.properties.description</code></td></tr><tr><td><code>value</code></td><td><code>data.0.properties.value</code></td></tr><tr><td><code>items.length</code></td><td><code>data.0.properties.num_items</code></td></tr><tr><td><code>Test Event Code</code></td><td><code>test_event_code</code></td></tr></tbody></table>

{% hint style="info" %}

> **\*** Mandatory property.\
> **1.** Supported values: <mark style="color:blue;">`web`</mark> , <mark style="color:blue;">`app`</mark> , <mark style="color:blue;">`offline`</mark> , and <mark style="color:blue;">`crm`</mark> . When <mark style="color:blue;">`Autodiscovery Event Source`</mark> is flagged, if the "Smart Mapping" field `Experience Type` is set with a property holding the value `native app` or the object `context.app` has at least a property then this is set with `app` . The "Smart Mapping" `Event Source` has priority over the autodiscovery feature. Default value: `web` .\
> **2.** See [Quick reference](#quick-reference) for more details on event mapping.\
> **3.** If not provided, the current timestamp is used.\
> **4.** Required if you are sending web events from both TikTok browser pixel and this destination. Used in deduplication together with <mark style="color:blue;">`event_source_id`</mark> and <mark style="color:blue;">`data[0].event`</mark> . More details are available following this [LINK](https://ads.tiktok.com/marketing_api/docs?id=1771100965992450).\
> **5.** If not provided, the cookie <mark style="color:blue;">`ttclid`</mark> or <mark style="color:blue;">`context.page.url`</mark> is used.\
> **6.** If provided in clear text, it's automatically hashed with SHA-256.\
> **7.** If not provided, the cookie <mark style="color:blue;">`_ttp`</mark> is used.\
> **8.** Set when the "Smart Mapping" property <mark style="color:blue;">`Device Platform`</mark> or <mark style="color:blue;">`context.device.type`</mark> is set with `iOS` (case insensitive).\
> **9.** Supported values: <mark style="color:blue;">`AUTHORIZED`</mark> , <mark style="color:blue;">`DENIED`</mark> , <mark style="color:blue;">`NOT_DETERMINED`</mark> , <mark style="color:blue;">`RESTRICTED`</mark> and <mark style="color:blue;">`NOT_APPLICABLE`</mark>. More details are available following this [LINK](https://business-api.tiktok.com/gateway/docs/index?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b\&language=ENGLISH\&doc_id=1771101111730178#item-link-user%20parameters).\
> **10.** Set when the "Smart Mapping" property <mark style="color:blue;">`Device Platform`</mark> or <mark style="color:blue;">`context.device.type`</mark> is set with `Android` (case insensitive).\
> **11.** Required for app events.\
> **12.** Phone number in the [E.164 format](https://www.twilio.com/docs/glossary/what-e164).\
> **13.** See [BCP 47 language identifier](https://www.rfc-editor.org/rfc/bcp/bcp47.txt).\
> **14.** See [Events API 2.0 - Limited Data Use](https://ads.tiktok.com/marketing_api/docs?id=1771101204435970) for more details.\
> **15.** Supported values: <mark style="color:blue;">`product`</mark> and <mark style="color:blue;">`product_group`</mark> . Default: <mark style="color:blue;">`product`</mark> .\
> **16.** Required for Video Shopping Ads (VSA).\
> **17.** Set for web events.
> {% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.commandersact.com/features/destinations/destinations-catalog/tiktok/tiktok.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.