Overview

TikTok Web Conversions API (Web CAPI) enables Branch to forward web conversion events to TikTok's Events API. 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.

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, 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.
• Enable the TikTok For Business SAN integration in Branch. See Enable TikTok For Business SAN (New).
• Implement the Branch Web SDK on your website with event tracking configured, or send web conversion events through server-to-server (S2S) ingestion.
• Create a TikTok Pixel in TikTok 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.

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.
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" in the general Ad Partner Integration Guide.

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.

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: 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.
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 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.

// 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.

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. 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.