> For the complete documentation index, see [llms.txt](https://help.branch.io/llms.txt).

# TikTok Web CAPI (New)

> Send web events from Branch to TikTok through the TikTok Events API (CAPI) to measure and optimize your TikTok campaigns.

## Overview

TikTok Web Conversions API (Web CAPI) enables Branch to forward web conversion events to TikTok's [Events API](https://business-api.tiktok.com/portal/docs?id=1771100865818625). When users interact with your TikTok ads, Branch captures the TikTok Click ID (`ttclid`), attributes the resulting web conversions, and forwards those events to TikTok. This connects ad clicks, attribution, and campaign optimization.

Branch has always attributed web conversions. With TikTok Web Conversions API enabled, Branch also shares that web conversion signal with TikTok:

- **Activate the web events you already track in Branch.** Branch forwards events captured by the Branch Web SDK or sent server-to-server (S2S) to TikTok. You don't need a separate server-side build or additional pixel instrumentation.
- **Optimize TikTok web campaigns on Branch-measured conversions.** Branch passes the `ttclid` captured from your Branch Ad Links, along with IP address, user agent, and optional hashed email and phone. TikTok uses these signals to match each conversion to the ad click. Its web optimization models can use matched events, so you can optimize toward the conversions you measure in Branch.
- **Consolidate how you send events.** Use Branch as a single source for web conversion events across ad partners instead of maintaining a separate TikTok-specific server integration alongside your Branch implementation.

For more information about integrating ad partners in general, visit our [Ad Partner Integration Guide](https://help.branch.io/marketer-hub/ad-partner-integration-guide-new.md).

> **Note: TikTok Web Conversions API vs. TikTok app attribution**
>
> You configure TikTok Web Conversions API on the same **TikTok For Business SAN** partner page as the [TikTok For Business self-attributing network (SAN) integration](https://help.branch.io/marketer-hub/enable-tiktok-for-business-san-new.md), but the two are independent. Web Conversions API sends web conversion signal *from* Branch *to* TikTok to support optimization and reporting. The SAN integration handles app attribution. Enabling Web Conversions API doesn't change how Branch attributes conversions or how Branch assigns TikTok SAN credit.

### Partner capabilities

| Capability | Details |
| --- | --- |
| Supported event sources | Branch Web SDK, Server-to-server (S2S) |
| Platforms | Web (iOS web, Android web, and desktop web) |
| Match signals | `ttclid`, IP address, user agent, hashed email, hashed phone |
| Event deduplication | Supported via `event_id` (mapped from `event_data.transaction_id`) |

## Before you begin

To set up TikTok Web Conversions API, you first need to:

- Enable Branch's Performance Product for your Branch account. Contact your Branch account manager or speak with our [Sales team](https://www.branch.io/contact-sales/).
- Enable the TikTok For Business SAN integration in Branch. See [Enable TikTok For Business SAN (New)](https://help.branch.io/marketer-hub/enable-tiktok-for-business-san-new.md).
- Implement the [Branch Web SDK](https://help.branch.io/developer-hub/web-sdk-overview.md) on your website with [event tracking](https://help.branch.io/developer-hub/track-branch-events.md) configured, or send web conversion events through [server-to-server (S2S)](https://help.branch.io/apidocs/events/overview.md) ingestion.
- Create a TikTok Pixel in [TikTok Events Manager](https://ads.tiktok.com/i18n/events_manager), and get admin or event-management permissions for that pixel in your TikTok Business Center.
- Place Branch Ad Links in your TikTok web campaigns. When a user selects your ad, TikTok automatically appends the TikTok Click ID (`ttclid`) to the landing page URL. If that landing page is a Branch Ad Link, Branch captures the `ttclid` and includes it in the events it forwards. TikTok uses the `ttclid` as its primary click-level matching signal. For more information, see [About TikTok Click ID](https://ads.tiktok.com/resources/help/article/tiktok-click-id).

## Enable TikTok Web Conversions API

To begin, navigate to **Configuration > Integrations** in Branch, select the **Ad partners** tab, and use the **Search partners** bar to find **TikTok For Business SAN**.

TikTok Web Conversions API requires a **Pixel ID** and an Events API access token from your TikTok Events Manager account. In Branch, you enter the access token in the **Conversion Key** field. Follow the steps below to retrieve these credentials and enable forwarding in Branch.

### Step 1: Retrieve your Pixel ID

1. Log in to [TikTok Ads Manager](https://ads.tiktok.com/).
2. Navigate to **Tools > Events** to open Events Manager.
3. Under **Web Events**, select **Manage**.
4. Select the pixel you want Branch to send events to.
5. Copy the **Pixel ID** that appears beneath the pixel name.

### Step 2: Generate an Events API access token

1. In TikTok Events Manager, select the pixel from Step 1.
2. Select the **Settings** tab.
3. Scroll to the **Events API** section.
4. Select **Generate Access Token**.
5. Copy the token and store it securely.

> **Note**
>
> If **Generate Access Token** is unavailable, your user may not have sufficient permissions for the pixel. Ask a TikTok Business Center admin to grant you access to the pixel or to generate the token for you.

### Step 3: Enter credentials in Branch

1. On the **TikTok For Business SAN** page in Branch, select **Partner settings**.
2. Under **Postback Credentials**, enter the Pixel ID from Step 1 in the **Pixel ID** field.
3. Enter the access token from Step 2 in the **Conversion Key** field.
4. Select **Save**.

Once saved, Branch begins forwarding eligible web conversion events to the TikTok Events API based on your configuration.

## Configure postbacks

Branch forwards web conversion events to the TikTok Events API based on your postback configuration. Branch sends only events from web platforms (iOS web, Android web, and desktop web), and maps them to TikTok's standard web event names as follows:

| TikTok event | Branch event |
| --- | --- |
| `Purchase` | `PURCHASE` |
| `AddToCart` | `ADD_TO_CART` |
| `ViewContent` | `VIEW_ITEM` |
| `InitiateCheckout` | `INITIATE_PURCHASE` |
| `AddPaymentInfo` | `ADD_PAYMENT_INFO` |
| `CompleteRegistration` | `COMPLETE_REGISTRATION` |
| `Search` | `SEARCH` |
| `AddToWishlist` | `ADD_TO_WISHLIST` |
| `Subscribe` | `SUBSCRIBE` |
| `StartTrial` | `START_TRIAL` |
| `Schedule` | `RESERVE` |
| `Lead` | `WEB_SESSION_START` |
| `{custom_event_name}` | `{custom_event_name}` |

> **Note**
>
> TikTok uses different standard event names for web and app. The names in the previous table are TikTok's web event names and apply only to TikTok Web Conversions API. App event mappings for the TikTok For Business SAN integration don't change.

> **Tip**
>
> TikTok optimizes web campaigns based on its standard events. Use the standard Branch events in the previous table wherever possible. Branch forwards custom events with their Branch event name, so they're best suited for reporting.

To forward all web conversion events Branch receives, not just events attributed to TikTok campaigns, turn on **Send all events** on the **Postback config** tab, and then select **Save Changes**. This gives TikTok the broadest possible signal for optimization and reporting.

To add a postback for another event, select **Add new postback** on the **Postback config** tab. For more details about customizing postbacks, see ["Configure postbacks"](https://help.branch.io/marketer-hub/ad-partner-integration-guide-new.md#configure-postbacks) in the general [Ad Partner Integration Guide](https://help.branch.io/marketer-hub/ad-partner-integration-guide-new.md).

## Deduplicate events with TikTok Pixel

If you also use the TikTok Pixel or send events to the TikTok Events API through other sources, the same conversion event may reach TikTok more than once. TikTok deduplicates these events using a shared `event_id`. If both events carry the same event name and `event_id`, TikTok counts them as a single conversion. For deduplication timing windows, see TikTok's [event deduplication guide](https://ads.tiktok.com/resources/help/article/event-deduplication).

Branch uses `transaction_id` as the `event_id` it sends to the TikTok Events API. To enable deduplication, pass the same `transaction_id` in your Branch Web SDK event as you do for the `event_id` in your TikTok Pixel event for the same conversion.

> **Caution: transaction_id required for deduplication with Pixel**
>
> TikTok requires an `event_id` on every event. If you don't provide a `transaction_id`, Branch sends its own unique Branch event ID as the `event_id` instead. This prevents duplicates from Branch itself, but it doesn't match the `event_id` your TikTok Pixel sends. TikTok can't deduplicate those events with Pixel, which may result in duplicate conversions in TikTok reporting.

## Verify your data

After you save your credentials and configure postbacks, verify that events flow correctly:

- **In [Liveview](https://help.branch.io/account-hub/liveview-new.md)**: Confirm that web conversion events from your site appear in real time. Filter for `Platform = Web` to isolate web events.
- **In TikTok Events Manager**: Navigate to your pixel and confirm that events forwarded by Branch appear under the **Overview** tab, with **Events API** as the connection method.
- **In TikTok Events Manager > Diagnostics**: Review any errors or warnings TikTok reports for events received from Branch, such as missing parameters or invalid values.

## Conversions API data mappings

Branch maps the following fields from web conversion events to the TikTok Events API payload:

| TikTok Events API field | Branch source field | Notes |
| --- | --- | --- |
| `event_source` | Hardcoded: `"web"` | Required by TikTok for all web events. |
| `event_source_id` | Pixel ID (Partner settings) | The pixel that receives the event. |
| `partner_name` | Hardcoded: `"Branch"` | Identifies Branch as the integration partner. |
| `event` | `name` | Mapped to TikTok standard web event names. See [Configure postbacks](#configure-postbacks). |
| `event_time` | `timestamp` | Unix timestamp in seconds. |
| `event_id` | `event_data.transaction_id` | Used for event deduplication. TikTok requires this field, so Branch falls back to its own event ID if `transaction_id` isn't present. |
| `user.ttclid` | `ttclid` (via Branch Ad Link) | Captured from the last attributed TikTok click. Omitted if `ttclid` isn't present. |
| `user.email` | `custom_data.em` | SHA-256 hashed by Branch before sending. Omitted if not present. |
| `user.phone` | `custom_data.ph` | SHA-256 hashed by Branch before sending. Omitted if not present. |
| `user.ip` | `user_data_ip` | Captured from the originating web request. |
| `user.user_agent` | `user_data_user_agent` | Captured from the originating web request. |
| `properties.value` | `revenue` | Included when present on the event. |
| `properties.currency` | `currency` | Included when present on the event. |
| `properties.contents` | `content_items[]` | Maps `$sku` (`content_id`), `$product_name` (`content_name`), `$quantity`, and `$price` from each content item. |
| `properties.content_ids` | `content_items[].$sku` | Array of `$sku` values extracted from content items. |
| `properties.content_type` | Hardcoded: `"product"` | Included only when the event has `content_items[]` or `revenue`. |
| `page.url` | `user_data_http_origin` | The origin of the page where the conversion occurred. |
| `page.referrer` | `user_data_http_referrer` | The referring URL, when available. |

## Pass email and phone for advanced matching

To improve match rates, pass the user's email address and phone number in the `em` and `ph` parameters. Branch hashes these values with SHA-256 before forwarding them to TikTok, so send them **unhashed**. Values that are already hashed result in a double hash that TikTok can't match.

Normalize the values before you send them:

- **Email:** Trim whitespace and convert to lowercase.
- **Phone:** Use E.164 format, including the country code (for example, `+14155550123`).

**Branch Web SDK:** Use [`setRequestMetaData`](https://help.branch.io/developer-hub/web-full-reference.md#setrequestmetadata) to set `em` and `ph` before you log the event. Once set, Branch attaches the values to subsequent Web SDK requests, including the events Branch forwards to TikTok.

```javascript
// Set once the user's email and phone are known (for example, after login or at checkout)
branch.setRequestMetaData('em', 'jane.doe@example.com');
branch.setRequestMetaData('ph', '+14155550123');

// Log the event after you set the metadata
branch.logEvent('PURCHASE', event_and_custom_data, content_items);
```

**Server-to-server (S2S):** Include `em` and `ph` in the `custom_data` object of your [event request](https://help.branch.io/apidocs/events/overview.md).

## Troubleshoot

Use the checks below to troubleshoot common issues with TikTok Web Conversions API.

### Events not appearing in TikTok Events Manager

If forwarded events don't appear in TikTok Events Manager, check the following:

- You entered your **Pixel ID** and **Conversion Key** (Events API access token) correctly in Branch. An invalid token causes TikTok to reject all events.
- You generated the access token for the same pixel you entered as the **Pixel ID**.
- Branch Liveview shows your web events, which means the Branch Web SDK or S2S is tracking them. Branch can only forward events it receives.
- **Send all events** is on in the **Postback config** tab, or your active postbacks include the specific events you expect.

### Low match rate

If TikTok reports a low match rate for forwarded events, check the following:

- Your TikTok campaigns use Branch Ad Links. Without Branch Ad Links, Branch can't capture the `ttclid`, so Events API events don't include it. TikTok uses the `ttclid` as its primary click-level matching signal.
- You pass normalized, unhashed email (`em`) and phone (`ph`) values by using `setRequestMetaData` in the Branch Web SDK or `custom_data` for S2S events. See [Pass email and phone for advanced matching](#pass-email-and-phone-for-advanced-matching). Along with IP address and user agent, these fields improve match quality when the `ttclid` is absent.

### Duplicate conversions in TikTok reporting

If you use both TikTok Pixel and Branch Web Conversions API and see higher-than-expected conversion counts in TikTok reporting, deduplication may not be working. Check the following:

- The `transaction_id` in your Branch Web SDK event matches the `event_id` in your TikTok Pixel event for the same conversion.
- Both the Pixel event and the Events API event use the same event name. TikTok requires both the event name and the event ID to match for deduplication.