Connect TikTok Events API

How do you connect Perspection to the TikTok Events API?

Connecting Perspection to TikTok requires 2 credentials: the Pixel ID (pixel_code in the TikTok API) and an Access Token, both from TikTok Ads Manager under Tools > Events. Setup takes under 5 minutes, and Perspection validates the connection by sending a test ViewContent event to the TikTok API after saving.

Step-by-step connection setup

1. Open the Perspection dashboard -- Sign in at dashboard.perspection.app and select the workspace where TikTok tracking will be configured.

2. Navigate to Connectors > Destinations -- Click "Connectors" in the sidebar, then select "Destinations" from the submenu.

3. Select TikTok -- Locate the TikTok card (labeled "TikTok -- Events API") in the destination list. Click the card to expand the configuration form.

4. Obtain the Pixel ID from TikTok Ads Manager -- Open TikTok Ads Manager at ads.tiktok.com. Navigate to Tools > Events. Select the pixel associated with the advertising account. Copy the Pixel ID displayed on the pixel overview page.

5. Enter the Pixel ID -- Paste the Pixel ID into the "Pixel ID" field in the Perspection dashboard. The Pixel ID is a numeric string (e.g., C5TPJNOLCF77U9T0JG3G).

6. Generate an Access Token in TikTok Ads Manager -- In TikTok Ads Manager, navigate to Events Manager > select the pixel > Settings. Click "Generate Access Token." Copy the token immediately -- TikTok does not display the token again after generation.

7. Enter the Access Token -- Paste the Access Token into the "Access Token" field in Perspection. The field uses a password mask to protect the credential.

8. Save the destination -- Click "Save" to store the configuration. Perspection encrypts the access token at rest in the data plane database.

9. Test the connection -- Click "Test" to send a validation event. Perspection dispatches a test ViewContent event to the TikTok Events API and reports success or failure with latency in milliseconds.

10. Enable the destination -- Toggle the "Live" switch to start dispatching production events to TikTok.

Required and optional fields

Perspection stores destination credentials in the data plane database, encrypted and scoped to the workspace's tenant ID with row-level security.

What data does Perspection send to TikTok for each event?

Perspection sends 5 categories of data to TikTok for every event: event metadata (event name, ID, timestamp), user identifiers (SHA-256 hashed email and phone, external_id, ttp cookie, ttclid, IP, user agent), page context (URL, referrer), commerce properties (value, currency, content_type, contents array), and a Limited Data Use flag for GDPR/CCPA compliance.

Event payload structure

The TikTok connector transforms every Perspection event into the TikTok Events API v1.3 data format. The following table shows the complete field mapping:

Event Metadata

User Data

Page Data

Commerce Properties (for purchase, cart, and checkout events)

Event name mapping

Perspection automatically maps raw event names to TikTok standard event names. The connector strips any dl_ prefix (from Google Tag Manager DataLayer events) before mapping:

Internal events such as identify, session_start, page_hidden, perspection_consent_update, and GTM lifecycle events (gtm.dom, gtm.load, gtm.js) are automatically skipped and never dispatched to TikTok.

How does Perspection handle TikTok PII hashing and compliance?

TikTok requires SHA-256 hashing for all PII sent through the Events API. Perspection normalizes and hashes server-side: emails are lowercased, trimmed, and SHA-256 hashed; phone numbers are stripped to digits and hashed. The _ttp cookie and ttclid click identifier are sent unhashed for click attribution. Perspection applies a Limited Data Use flag for GDPR/CCPA compliance based on consent.

Hashing protocol

Perspection's base connector implements two hashing functions used by the TikTok connector:

1. Email hashing -- The hashEmail function converts the email to lowercase, removes leading and trailing whitespace, and produces a SHA-256 hex digest. Example: User@Example.com becomes the SHA-256 hash of user@example.com.

2. Phone hashing -- The hashPhone function strips all non-digit characters (spaces, dashes, parentheses, plus signs) and produces a SHA-256 hex digest of the numeric string. Example: +1 (555) 123-4567 becomes the SHA-256 hash of 15551234567.

If the Perspection SDK (v3.0+) has already pre-hashed user data on the client side, the connector uses the pre-hashed values directly from user_data.email_hash and user_data.phone_hash, avoiding double hashing.

Limited Data Use (LDU) compliance

The TikTok connector applies the limited_data_use flag based on two sources:

1. Consent enforcement service -- When Perspection's consent pipeline has evaluated user consent, the connector reads the sendable_to_ads, ad_storage, and ad_user_data consent signals and calculates the appropriate LDU flag via the consentEnforcementService.getTikTokLDU() function.

2. Default fallback -- When consent signals are not available, the connector defaults limited_data_use to true, ensuring privacy-compliant behavior until explicit consent is collected.

When limited_data_use is true, TikTok restricts the use of event data for audience building and ad optimization, ensuring compliance with GDPR, CCPA, and other privacy regulations.

How do you set up TikTok baseline comparison to measure conversion recovery?

Perspection's Baseline Pixel Code field enables side-by-side comparison between server-side and existing TikTok browser pixel tracking. Enter the existing TikTok Pixel Code in the optional "Baseline Pixel Code" field when configuring the TikTok destination. Perspection compares server-side conversion counts against TikTok's browser pixel numbers, surfacing a recovery value showing additional conversions Perspection captured that the browser pixel missed.

Setting up baseline comparison

1. Identify the existing TikTok Pixel Code -- Open TikTok Ads Manager > Tools > Events. Copy the Pixel ID of the browser pixel currently installed on the website.

2. Open the TikTok destination in Perspection -- Navigate to Connectors > Destinations and expand the TikTok card.

3. Enter the Baseline Pixel Code -- Paste the existing pixel code into the "Baseline Pixel Code" field (marked as Optional).

4. Save the configuration -- Click "Save." Perspection begins collecting comparison data immediately.

5. Review recovery metrics -- Open the Analytics section to view baseline comparison reports. The recovery value represents the delta between Perspection's server-side conversion count and the TikTok browser pixel's self-reported count.

What the recovery value measures

The recovery value quantifies conversions that Perspection's server-side dispatch captured but the TikTok browser pixel missed. Common sources of recovered conversions include:

• Ad-blocked sessions -- Visitors running ad blockers where the TikTok browser pixel never loaded.

• Cross-browser and cross-device purchases -- Users who clicked a TikTok ad on mobile but completed the purchase on desktop, where identity resolution links the sessions.

• Delayed conversions -- Purchases completed after the TikTok browser pixel's _ttp cookie expired (ITP caps at 7 days on Safari).

• JavaScript failure scenarios -- Checkout completions where the browser pixel failed to fire due to CSP restrictions, network errors, or race conditions with single-page application routing.

For detailed analysis of match quality across destinations, see Event Match Quality Scoring.

How do you verify TikTok events are being received correctly?

Perspection provides 3 verification methods for TikTok event delivery: the built-in connection test button (sends a test ViewContent event with latency reporting), TikTok's Test Events tool in Ads Manager (sandbox testing via Test Event Code), and the Perspection destination health dashboard (delivery success rates, error codes, latency percentiles). Use all three during initial setup to confirm end-to-end flow.

Method 1: Perspection connection test

1. Navigate to Connectors > Destinations -- Expand the TikTok destination card.

2. Click "Test" -- Perspection sends a test ViewContent event to the TikTok Events API using the configured Pixel ID and Access Token.

3. Review the result -- Perspection displays "Connection test successful!" with latency in milliseconds for a passing test, or an error message with the TikTok API error code for a failing test.

4. Quality coaching -- The test result includes an Event Match Quality score with recommendations for improving data quality. A minimal test event scores low because the test event contains no user identifiers; production events score higher.

Method 2: TikTok Test Events tool

1. Open TikTok Ads Manager -- Navigate to Tools > Events > select the pixel.

2. Click "Test Events" -- TikTok displays the Test Events tab where incoming test events appear in real time.

3. Copy the Test Event Code -- If TikTok displays a test event code, copy the code.

4. Enter the code in Perspection -- Paste the test event code into the "Test Event Code" field in the TikTok destination configuration on the Perspection dashboard. Note: the TikTok connector currently does not expose a separate test event code field in the UI, but the field is supported in the API payload as test_event_code.

5. Trigger test events -- Browse the website to generate page views, add-to-cart actions, or test purchases. Events sent with a test event code appear in TikTok's Test Events tab without affecting production reporting.

6. Verify event parameters -- In TikTok's Test Events view, confirm that event names (e.g., PlaceAnOrder, AddToCart), user parameters (hashed email, hashed phone), and commerce properties (value, currency, contents) match expected values.

7. Remove the test event code -- After verification, clear the test event code field in Perspection and save. Production events will no longer be tagged as test events.

Method 3: Perspection destination health monitoring

1. Open the Pipeline section -- Navigate to the Pipeline page in the Perspection dashboard.

2. Review dispatch status -- Perspection displays real-time delivery metrics per destination, including success rate, error rate, average latency, and most recent error messages.

3. Check for common errors -- The most frequent TikTok API errors include:

   • 40001 -- Invalid access token (regenerate the token in TikTok Ads Manager).

   • 40002 -- Invalid pixel code (verify the Pixel ID matches the value in TikTok Ads Manager).

   • 40100 -- Rate limit exceeded (Perspection automatically tracks the 1,000 requests per minute limit and backs off).

   • 50000 -- TikTok internal server error (Perspection retries automatically with exponential backoff up to 3 attempts).

For detailed guidance on monitoring destination health across all connected platforms, see Destination Health Monitoring.

How does Perspection score TikTok event match quality?

Perspection calculates a real-time Event Match Quality score for every TikTok dispatch across 5 weighted factors: email (30%), phone (25%), external ID (20%), browser data (15%), and event data (10%). Maximum score is 100. Events below 70 for browser sources or below 50 for offline conversions trigger quality coaching recommendations in the Perspection logs.

Quality score breakdown

Quality thresholds

• Browser events: 70 minimum -- Standard events from the Perspection browser SDK should score 70 or higher because the SDK captures user agent, IP address, and the TikTok _ttp cookie automatically.

• Offline conversions: 50 minimum -- Events from CSV uploads, Shopee COD confirmations, or Lazada COD confirmations score lower because offline sources lack browser context (no user agent, no IP, no _ttp cookie). The 50 threshold requires at least a hashed email or hashed phone for TikTok to match the conversion.

• Excellent: 85+ -- Events with hashed email, hashed phone, external ID, full browser data, and commerce properties achieve scores above 85, enabling optimal TikTok attribution and audience building.

Improving event match quality

1. Capture email at checkout -- Ensure the checkout form collects email before the purchase event fires. Perspection's identity resolution pipeline automatically associates the email with the user's event stream.

2. Preserve the TikTok _ttp cookie -- Deploy Perspection's first-party domain tracking to set the _ttp cookie under the website's own domain, extending the cookie lifetime beyond ITP restrictions.

3. Pass product details in e-commerce events -- Include items or line_items arrays with product_id, name, quantity, and price in purchase and add-to-cart event properties.

4. Include phone numbers when available -- Phone number hashing adds 2.5 points to the weighted quality score, significantly improving TikTok's ability to match conversions to ad clicks.

For a comprehensive guide to optimizing match quality across all advertising platforms, see Event Match Quality Scoring.

Methodology

All TikTok Events API configuration steps and event mapping tables in this guide were verified against the Perspection production dashboard and live TikTok Events Manager as of February 2026.

"TikTok's Events API attribution model weights the _ttp cookie and ttclid click identifier more heavily than hashed email or phone for real-time ad optimization. However, the hashed identifiers become critical for offline conversions and cross-device attribution where click cookies are unavailable. Perspection's quality scoring reflects this reality -- browser data quality is weighted at 15%, but for offline conversions, that 15% is effectively unreachable, which is why the offline threshold drops to 50 from 70. The practical takeaway: invest in first-party domain tracking to preserve the _ttp cookie across Safari and Firefox, and ensure email capture happens before the purchase event fires." -- Perspection Engineering Team

Sources & References

1. TikTok Events API -- Getting Started, https://business-api.tiktok.com/portal/docs?id=1741601162187777

2. TikTok Events API -- Parameters, https://business-api.tiktok.com/portal/docs?id=1741601162187777

3. TikTok for Business -- Conversion Tracking Best Practices, https://ads.tiktok.com/help/article/conversion-events

4. Perspection Product Guide -- Event Match Quality, /library/event-match-quality-guide

5. Perspection Product Guide -- Destination Health, /library/destination-health-failed-events-guide