# TikTok Ads

Freshpaint can send **Events** to your TikTok account for a specified `Pixel ID`. These server-side **Events** are sent via the [TikTok Events API](https://ads.tiktok.com/marketing_api/docs?id=1739583647070209). The **TikTok Events API** enables you to measure conversions by sending Freshpaint events directly to TikTok's servers.

## Destination Info

* Accepts [Track](https://documentation.freshpaint.io/developer/freshpaint-sdk-reference#track) calls
* Supports [HIPAA mode](https://documentation.freshpaint.io/hipaa-mode)
* Supports forwarding from the [Google Tag Manager Integration](/integrations/google-tag-manager-integration.md)
* Refer to this destination as **TikTok Ads** in the [Integrations object](https://documentation.freshpaint.io/reference/developer/freshpaint-sdk-reference#using-the-integrations-object)

  * If you've configured multiple Pixel IDs, you can choose a specific one by suffixing the Pixel ID, such as: **TikTok Ads::123456789.** 

  <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>When no suffix is specified, all configured Pixel IDs are selected for inclusion / exclusion.</p></div>
* Connection Modes:

<table><thead><tr><th> </th><th data-type="checkbox">Client-side</th><th data-type="checkbox">Server-side</th></tr></thead><tbody><tr><td><strong>Web</strong></td><td>false</td><td>true</td></tr><tr><td><strong>Mobile</strong></td><td>false</td><td>true</td></tr><tr><td><strong>Server</strong></td><td>false</td><td>true</td></tr></tbody></table>

## Getting Started

To set up the TikTok Ads integration, follow these steps:

* Go to the [TikTok Ads configuration page](https://app.freshpaint.io/destinations/apps/tiktok-ads) in Freshpaint and click "Configure" for Access Token & Pixel ID.
* In [TikTok Ads Manager -> Assets -> Web Events](https://ads.tiktok.com/i18n/events_manager/pixel?aadvid=7184581788730179586), find your `Pixel ID`, or create a new Pixel as described at [TikTok Events API: Get Started](https://ads.tiktok.com/marketing_api/docs?id=1739584855420929). Copy this value into your TikTok Ads configuration.

![img.png](/files/7tIoVAJL5QofypcDBQXe)

* Click on the Pixel you want to use and generate an `Access Token`. Copy this value into your TikTok Ads configuration.

![img.png](/files/woXYdpxxaMJMacpUsqcx)

## Events

### TikTok Event API: Web Event types

Each event sent to the **TikTok Event API** is categorized as a specific **TikTok Event**, derived from either the Freshpaint **Event Definition** name or a Destination **Transformation** (described further below).

Below are the **TikTok Events**, as defined in [TikTok Events API Reference](https://ads.tiktok.com/marketing_api/docs?id=1740858531237890), with the corresponding Freshpaint **Event Definition** names which automatically map to them:

| TikTok Event           | Mapped from Freshpaint Event Definition name                                                                                                               | Recommended TikTok properties-object fields                                                                                                                 |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AddToCart`            | <p>AddToCart<br>product added<br>added product<br></p>                                                                                                     | `value`, `currency`, `description`, `quantity`, `content_type` , `content_id`                                                                               |
| `AddToWishlist`        | AddToWishlist                                                                                                                                              |                                                                                                                                                             |
| `AddPaymentInfo`       | AddPaymentInfo                                                                                                                                             |                                                                                                                                                             |
| `ApplicationApproval`  | ApplicationApproval                                                                                                                                        |                                                                                                                                                             |
| `CustomizeProduct`     | CustomizeProduct                                                                                                                                           |                                                                                                                                                             |
| `Contact`              | Contact                                                                                                                                                    |                                                                                                                                                             |
| `CompleteRegistration` | CompleteRegistration                                                                                                                                       |                                                                                                                                                             |
| `Download`             | Download                                                                                                                                                   |                                                                                                                                                             |
| `FindLocation`         | FindLocation                                                                                                                                               |                                                                                                                                                             |
| `InitiateCheckout`     | <p>InitiateCheckout<br>checkout started<br>started checkout</p>                                                                                            |                                                                                                                                                             |
| `Lead`                 | <p>Lead (formerly SubmitForm)<br><br><em>Both event names are mapped to the TikTok Event</em> <code>Lead</code></p>                                        |                                                                                                                                                             |
| `Schedule`             | Schedule                                                                                                                                                   |                                                                                                                                                             |
| `Purchase`             | <p>Purchase (formerly CompletePayment) <br><br><em>Both event names are mapped to The TikTok Event</em> <code>Purchase</code></p>                          | <p><code>value</code>, <code>currency</code>, <code>description</code>,<br><code>content\_id</code>, <code>quantity</code>, <code>content\_type</code></p>  |
| `Search`               | <p>Search<br>products searched<br>searched products</p>                                                                                                    |                                                                                                                                                             |
| `StartTrial`           | StartTrial                                                                                                                                                 | `currency`, `value`                                                                                                                                         |
| `SubmitApplication`    | SubmitApplication                                                                                                                                          |                                                                                                                                                             |
| `Subscribe`            | Subscribe                                                                                                                                                  |                                                                                                                                                             |
| `ViewContent`          | <p>ViewContent<br>product list viewed<br>viewed product list<br>product category viewed<br>viewed product category<br>product viewed<br>viewed product</p> | <p><code>value</code>, <code>currency</code>, <code>description,</code><br><code>content\_id</code>, <code>quantity</code>, <code>content\_type</code> </p> |

Notes:

* **TikTok Events** are case-sensitive
* Any of the space-delimited names above are case-insensitive and may be alternatively delimited by an underscore or no separation. For example, "product added" can also be expressed as:
  * Product\_added
  * productAdded
* These non-TikTok-specific names can be useful when sending to multiple destinations, such as **Facebook Conversion API** and **TikTok Ads**, without requiring a Rename **Transformation** for one or both.

### Supported TikTok parameters

Several Freshpaint **Built-in Properties** are automatically sent to TikTok. To maximize the effectiveness of what is sent, you should define a number of Freshpaint **Custom Properties**, as described below.

Freshpaint **Custom Properties** include **Dynamic Properties** and **Data Layer Properties**, described at [Setting up Properties](https://documentation.freshpaint.io/readme/setting-up-properties), and **Transformation Constant Properties**, described in [Transformations](https://documentation.freshpaint.io/transformations).

#### User Traits

User traits you can define as **Custom Properties** to improve match rate are:

* `email`
* `phone_number`

Other ways you can optimize user match rate:

* Ensure Freshpaint [User Identification](https://documentation.freshpaint.io/readme/setting-up-identify) is being used in your application, so the `external_id` field gets sent (hashed from Freshpaint **Built-in Property** `distinct_id`).
* If you are already using the Pixel SDK with enabled cookie, capture the `ttp` property as described at [TikTok Click ID and Cookies section](https://ads.tiktok.com/marketing_api/docs?id=1739584860883969).

#### TikTok Field to Freshpaint Property Mapping Reference

Below is the full list of what Freshpaint sends to the **TikTok Events API** (beyond `Pixel ID` and `Access Token`).

In some cases, there are 1 or more alias properties for a field (e.g., for `value`, aliases are: `total`, `revenue`).

Fields mapped to Freshpaint **Custom Properties** are optional, but some are recommended:

* The User Traits properties described above are always recommended.
* See the Events Section above for recommended TikTok properties-object fields to be sent for specific **TikTok Events**.

See also the [TikTok Events API Reference](https://business-api.tiktok.com/portal/docs?id=1771101303285761).

### Event Properties

<table><thead><tr><th width="319.41015625">TikTok Events API field</th><th width="159.609375">Freshpaint Property</th><th width="90">Type</th><th width="107.1484375">Requirement</th><th>Description</th></tr></thead><tbody><tr><td><code>event_source</code></td><td></td><td>string</td><td>Required.</td><td>Specifies the type of events sent. Freshpaint currently only supports <code>web</code> events.</td></tr><tr><td><code>event_source_id</code></td><td><code>pixel_id</code></td><td>string</td><td>Required.</td><td>Source ID to measure events.</td></tr><tr><td><code>event</code></td><td>&#x3C; Freshpaint Event Definition name ></td><td>string</td><td>Required.</td><td>May be mapped via a transformation.</td></tr><tr><td><code>event_id</code></td><td>&#x3C; unique Freshpaint event id ></td><td>string</td><td>Required.</td><td>Unique identifier for the event.</td></tr><tr><td><code>event_time</code></td><td><code>time</code></td><td>string</td><td>Required.</td><td>Timestamp that the event took place.<br><br>Defaults to when Freshpaint processes the event if not provided.</td></tr></tbody></table>

### User Properties

To increase the accuracy of targeting and optimization models, it is highly recommended to include multiple types of matching data. You can use Advanced Matching, TikTok Click IDs (`ttclid`), and Cookies to attribute conversions.

<table><thead><tr><th width="244.89453125">Tiktok Events API Field</th><th>Freshpaint Property</th><th>Type</th><th>Requirement</th><th>Description</th></tr></thead><tbody><tr><td><code>ttclid</code></td><td><code>$ttclid</code></td><td>string</td><td></td><td>TikTok Click ID, a data connection parameter appended to a landing page URL whenever a user clicks on an ad on TikTok.</td></tr><tr><td><code>email</code></td><td><code>email</code></td><td>string</td><td></td><td>The email address of the customer.<br><br>Note: Freshpaint will hash this value, do not send Freshpaint pre-hashed email values.</td></tr><tr><td><code>phone</code></td><td><code>phone_number</code> or <code>phone</code>  </td><td>string</td><td></td><td><p>The phone number of the customer. </p><p></p><p>Note: Freshpaint will hash this value, do not send Freshpaint pre-hashed email values.</p></td></tr><tr><td><code>external_id</code></td><td><code>distinct_id</code></td><td>string</td><td></td><td>External ID, a unique identifier on the advertiser's side, such as loyalty membership IDs, user IDs, and external cookie IDs.<br><br>Note: Freshpaint will hash this value, do not send Freshpaint pre-hashed email values.</td></tr><tr><td><code>ttp</code></td><td><code>ttp</code></td><td>string</td><td></td><td>Cookie ID.</td></tr><tr><td><code>ip</code></td><td><code>$ip</code> or <code>ip_address</code></td><td>string</td><td></td><td>Non-hashed <strong>public IP</strong> address of the user's device.</td></tr><tr><td><code>user_agent</code></td><td><code>$user_agent</code> or <code>user_agent</code></td><td>string</td><td></td><td>Non-hashed user agent from the user’s device.</td></tr><tr><td><code>locale</code></td><td><code>locale</code></td><td>string</td><td></td><td>The BCP 47 language identifier.<br>For reference, refer to <a href="https://www.rfc-editor.org/rfc/bcp/bcp47.txt">the IETF BCP 47 standardized code</a>.</td></tr></tbody></table>

### Properties Parameters

<table><thead><tr><th width="214.59765625">Tiktok Events API Field</th><th>Freshpaint Parameter</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><code>content_ids</code></td><td><code>products</code> or <code>contents</code></td><td>string[]</td><td>Required for Video Shopping Ads</td><td>Unique ID or array of multiple IDs of the products or content.</td></tr><tr><td><code>content_type</code></td><td><code>content_type</code></td><td>string</td><td>Required for Video Shopping Ads</td><td>The type of content in the event.<br>Enum values: <code>product</code>, <code>product_group</code>.</td></tr><tr><td><code>currency</code></td><td><code>currency</code></td><td>string</td><td>Recommended for revenue related events</td><td>The ISO 4217 currency code.<br>Examples: <code>EUR</code>, <code>USD</code>, <code>JPY</code>.</td></tr><tr><td><code>value</code></td><td></td><td>float</td><td>Recommended for revenue related events</td><td>Value of the order or items sold.</td></tr><tr><td><code>num_items</code></td><td><code>quantity</code></td><td>integer</td><td></td><td>The quantity of items.</td></tr><tr><td><code>search_string</code></td><td></td><td>string</td><td></td><td>The user-entered string for search.</td></tr><tr><td><code>description</code></td><td><code>description</code> or <code>name</code></td><td>string</td><td></td><td>Description of the item or page.</td></tr><tr><td><code>order_id</code></td><td></td><td>string</td><td></td><td>Order ID.</td></tr><tr><td><code>shop_id</code></td><td></td><td>string</td><td></td><td>Shop ID.</td></tr></tbody></table>

### Ad Contents Properties

| Tiktok Events API Field | Freshpaint Parameter                                    | Type   | Required                        | Description                          |
| ----------------------- | ------------------------------------------------------- | ------ | ------------------------------- | ------------------------------------ |
| `price`                 | `price`                                                 | float  |                                 | The price of the item.               |
| `content_id`            | `content_id`, `product_id`, `productID`, `id`, or `sku` | string | Required for Video Shopping Ads | Unique ID of the product or content. |
| `content_category`      | `content_category`                                      | string |                                 | Category of the page or product.     |
| `content_name`          | `content_name`                                          | string |                                 | Name of the page or product.         |
| `brand`                 | `brand`                                                 | string |                                 | Brand name of the product item.      |

### Page Properties

| Tiktok Events API Field | Freshpaint Parameter   | Type   | Required | Description                               |
| ----------------------- | ---------------------- | ------ | -------- | ----------------------------------------- |
| `url`                   | `$current_url`or `url` | string | Required | The browser URL where the event happened. |
| `referrer`              | `$referrer`            | string |          | The referrer URL.                         |

## Sending the same events from TikTok Pixel and TikTok Events API

If you are already using **TikTok Pixel**, sending the same events from both the browser and the server can improve the accuracy of browser events by providing redundancy. Events that previously would have been lost (e.g. due to the **TikTok Pixel** being blocked or network errors) can still be captured using the **TikTok Events API** via the Freshpaint **TikTok Ads** integration.

However, the event\_id used by TikTok Pixel to deduplicate events is generated differently than that used by the Freshpaint TikTok Ads destination, so if you gather the same events with both TikTok Pixel and Freshpaint, they are likely to not be deduplicated by TikTok, and you may get diagnostic warning messages related to this. To minimize the chance of duplication, ensure the **TikTok Event** is set properly and the recommended match fields described above are included. For further details see [TikTok Event Deduplication](https://ads.tiktok.com/help/article?aid=10012410\&redirected=1).

## Transformations

Freshpaint [Transformations](https://documentation.freshpaint.io/transformations) allow you to customize how Freshpaint **Events** map to **TikTok Events**:

* Map any Freshpaint **Event Definition** name to a **TikTok Event**
* Rename Freshpaint **Custom Properties** mapped to supported TikTok property-object fields
* Rename any Freshpaint Property mapped to a supported **TikTok Field**
* Define a **Constant Property** when a **Custom Property** is not available
* Suppress a Freshpaint Property from being sent to TikTok

To create a TikTok Ads **Transformation**, go to [Transformations](https://app.freshpaint.io/transformations) or the [TikTok Ads configuration page](https://app.freshpaint.io/destinations/advertising/tiktok-ads) in Freshpaint and click "Event Transformations".

### Map any Freshpaint Event Definition name to a TikTok Event

{% hint style="info" %}
To optimize for conversions, use Transformations to match Freshpaint events to [TikTok Standard Events](https://business-api.tiktok.com/portal/docs?id=1741601162187777).
{% endhint %}

*Select Standard Event*

In the example below, the Event Definition named "TikTok event" is mapped to a TikTok `Search` Event:

![img.png](/files/u4nk2PZASf7dz4irlezj)

![img.png](/files/Pd6s64Z7Zy8yphS5jqXf)

## Rename Freshpaint Custom properties mapped to supported TikTok Property Object fields

*Select Standard Event*

In this example, the "order\_total" Freshpaint **Custom Property** is renamed to the mapped `value` name.

![img.png](/files/TxBsAJxYpl4lnfL4iUpJ)

![img.png](/files/mFBqC2DlM5ht1DF7IgQF)

## Rename any Freshpaint Property mapped to a supported TikTok Field

*Select Modify Data*

Here, the "phone\_nbr" Freshpaint **Custom Property** is renamed to the mapped `phone_number` name.

![img.png](/files/Fsd2ksiaiknPUhOqBxyK)

![img.png](/files/AW7cFPSKMpsxhg3yYc7R)

## Define a Constant Property when a Custom Property is not available

*Select Modify Data*

In this case, there is no Freshpaint **Custom Property** `currency` defined, so we set a Transformation **Constant Property**:

![img.png](/files/ScvTERJ984zwqQUrS0Oy)

![img.png](/files/rcI8MJcPA959CTij0aKX)

## Suppress a Freshpaint Property from being sent to TikTok

*Select Modify Data*

Finally, we might want to ensure that no search information is sent, so we suppress the Freshpaint **Custom Property** `query` if it's present:

![img.png](/files/fvvdJP12mHDQbeEKJb3W)

![img.png](/files/lQQnPDsU3LbESsJkx1SV)

## Using the GTM Integration

If using the [Google Tag Manager (GTM) Integration](/integrations/google-tag-manager-integration.md), you should define the `event name` and any other properties on the tag.

If you're using multiple TikTok instances, you can specify the Instance Pixel ID as well, as shown below:

<figure><img src="/files/Lc7yxT2XhGYtFEAZEq0T" alt=""><figcaption></figcaption></figure>


---

# 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://documentation.freshpaint.io/integrations/destinations/direct-response-ads/tiktok-ads.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.