TikTok Events API

Datafly Signal delivers web and app events to TikTok server-to-server via the Events API. This is the current TikTok blueprint with full vertical preset coverage; the older tiktok blueprint remains available for existing deployments.

This blueprint is currently in alpha. The TikTok Events API endpoint and payload schema are stable; the blueprint version marker reflects the rollout status of the preset set, not the underlying delivery.

Prerequisites

Before configuring TikTok Events API in Signal, you need:

A TikTok Ads Manager account with admin access
A TikTok Pixel (Web Event Source) created for your domain
An Events API access token for that Pixel

Get your TikTok credentials

Sign in to TikTok Ads Manager.
Go to Assets → Events → Web Events and select your Pixel (or click Connect data source → Web to create one).
The Pixel Code (e.g. C5ABCDEF1234GHIJ5678) is shown on the Pixel’s overview page.
Open the Set up Events API flow for that Pixel.
Click Generate access token. Copy the token immediately — it is shown only once.
(Optional) Open Test event to copy a test event code (e.g. TEST1234) for validation.

See TikTok’s Events API documentation for full setup details.

Configure the integration in Signal

In the Management UI, go to Integrations → Add Integration.
Select TikTok Events API from the catalogue.
Give the integration a name (for your reference).
Choose a preset:
- Retail — search, view, wishlist, cart, checkout, purchase, lead
- Travel — destination search, listing view/save, booking start/complete, lead
- B2B / SaaS — registration, lead, contact, trial, subscribe, application, content download
- Automotive — vehicle search/view/save, brochure, finance, test drive, dealer contact, service
Fill in the required fields:

Field	Required	Description
`pixel_code`	Yes	TikTok Pixel Code from Ads Manager.
`access_token`	Yes	Long-lived Events API access token.
`test_event_code`	No	Test event code for validation. Remove before production.

Choose which pipeline(s) this integration should run on.
Select consent categories (defaults to marketing).
Click Save.

Event mapping

Retail preset

Signal event	TikTok event
`page`	`Pageview`
`Products Searched`	`Search`
`Product Viewed`	`ViewContent`
`Product Added to Wishlist`	`AddToWishlist`
`Product Added`	`AddToCart`
`Checkout Started`	`InitiateCheckout`
`Payment Info Entered`	`AddPaymentInfo`
`Order Completed`	`Purchase`
`Lead Submitted`	`Lead`

Travel preset

Signal event	TikTok event
`page`	`Pageview`
`Destination Searched`	`Search`
`Listing Viewed`	`ViewContent`
`Listing Saved`	`AddToWishlist`
`Booking Started`	`InitiateCheckout`
`Payment Info Entered`	`AddPaymentInfo`
`Booking Completed`	`Purchase`
`Lead Submitted`	`Lead`

B2B / SaaS preset

Signal event	TikTok event
`page`	`Pageview`
`Signed Up`	`CompleteRegistration`
`Lead Submitted`	`Lead`
`Contact Requested`	`Contact`
`Trial Started`	`StartTrial`
`Subscription Started`	`Subscribe`
`Application Submitted`	`SubmitApplication`
`Content Downloaded`	`Download`

Automotive preset

Signal event	TikTok event
`page`	`Pageview`
`vehicle_searched`	`Search`
`vehicle_viewed` / `vehicle_compared`	`ViewContent`
`vehicle_saved`	`AddToWishlist`
`brochure_downloaded`	`Download`
`finance_quote_requested` / `trade_in_valued`	`SubmitForm`
`test_drive_booked`	`Lead`
`dealer_contacted`	`Contact`
`service_appointment_booked`	`Subscribe`

To customise, edit the integration’s Field Mappings in the Management UI.

Identity

Signal sends the following identity signals to TikTok, subject to consent and availability:

Capability	Field	Notes
Hashed email	`user.email`	SHA-256 (lowercase, trimmed)
Hashed phone	`user.phone_number`	SHA-256 (E.164)
External ID	`user.external_id`	`user_id` or anonymous identifier (hashed)
Click ID	`user.ttclid`	Captured from the `ttclid` URL parameter
Browser ID	`user.ttp`	First-party TikTok browser ID, self-generated if absent
Client IP	`user.ip`	Forwarded from the original request
User-Agent	`user.user_agent`	Forwarded from the original request

Hashing is performed by Signal before delivery.

This integration is gated on the marketing canonical consent category. Events without marketing consent are not delivered.

Verify it’s working

Paste a test event code from TikTok Ads Manager into the integration’s test_event_code field.
In the Management UI, go to Pipelines → your pipeline → Live Events.
Trigger a test event on your site.
The event appears in Signal’s live feed and in TikTok’s Test event tab within seconds.
Clear the test_event_code once validated.

Troubleshooting

Events aren’t appearing in TikTok.

Confirm the integration is enabled on the pipeline.
Confirm marketing consent is granted.
Check Live Events — if events aren’t reaching Signal, the issue is upstream.
If reaching Signal but not TikTok, inspect the delivery response — code: 40001 / 40100 indicate auth issues (regenerate the token).

Low match rate. Pass email, phone, and user_id via datafly.identify() so TikTok has more signals to match against.