TikTok Events API
Send server-side conversion events to TikTok for attribution and ad optimization via the Events API. Server-side events improve measurement accuracy by bypassing browser ad blockers and cookie restrictions.
Prerequisites
- A TikTok Business Center account
- A TikTok Pixel set up in TikTok Events Manager
- Your Pixel Code
- Access to the TikTok Marketing API
Authentication
TikTok Events API uses OAuth 2.0 via TikTok Business Center.
- Click Connect with OAuth in Zeotap
- Sign in with your TikTok Business account
- Authorize the requested permissions
OAuth grants event.create scope for sending conversion events.
Configuration
| Field | Type | Required | Description |
|---|---|---|---|
| Pixel Code | Text | Yes | Your TikTok Pixel code for receiving conversion events. Example: ABCDEFG123 |
| Event Source | Select | Yes | Where the conversion events originate. Options: web, app. Default: web |
Supported Operations
Sync Modes
| Mode | Supported |
|---|---|
| Insert | Yes |
| Update | — |
| Upsert | — |
| Mirror | — |
Audience Sync Modes
| Mode | Supported |
|---|---|
| Add | Yes |
| Remove | — |
| Mirror | — |
| Upsert | — |
Features
| Feature | Supported |
|---|---|
| Field Mapping | Yes |
| Schema Introspection | No |
Required Mapping Fields
| Field | Description |
|---|---|
event_name | Conversion event name (e.g., CompletePayment, AddToCart, ViewContent) |
email or hashed_email | User email for PII matching. Provide either a raw email (auto-hashed by Zeotap) or a pre-hashed SHA256 email |
Default Destination Fields
Event
| Field | Description |
|---|---|
event_name | The conversion event name |
event_time | Unix timestamp of the event |
User Data (raw)
These fields are automatically normalized and hashed with SHA256 before being sent to TikTok.
| Field | Description |
|---|---|
email | User email address |
phone | Phone number with country code |
User Data (pre-hashed)
These fields are passed through to TikTok without additional hashing. Values must be lowercase SHA256 hex strings.
| Field | Description |
|---|---|
hashed_email | SHA256-hashed email address |
hashed_phone | SHA256-hashed phone number |
Additional Fields
| Field | Description |
|---|---|
external_id | Your unique identifier for the user |
value | Monetary value of the event |
currency | ISO 4217 currency code (e.g., USD, EUR) |
content_id | Product or content identifier |
content_type | Category of content |
Supported Event Types
TikTok recognizes the following standard conversion events:
CompletePaymentAddToCartViewContentCompleteRegistrationInitiateCheckoutAddPaymentInfoPlaceAnOrderSubscribeSubmitFormContactDownloadSearch
Custom event names are also supported.
How It Works
Zeotap reads rows from your model query and applies field mapping to transform your data into TikTok’s Events API format.
PII hashing: Raw user data fields (email, phone) are automatically normalized and hashed with SHA256 per TikTok’s requirements. Pre-hashed fields (hashed_email, hashed_phone) are passed through without re-hashing.
Batching: Events are batched up to 50 per API call to the TikTok Events API endpoint. For syncs with more than 50 events, Zeotap automatically splits them into multiple API calls.
Event source: The event_source value from your configuration is applied to every event in the sync.
Rate Limits
- 50 events per API call — Zeotap automatically batches events to stay within this limit
- TikTok Marketing API rate limits apply based on your app’s usage tier
Troubleshooting
Invalid Pixel Code
Verify your Pixel Code in TikTok Events Manager. Navigate to Assets > Events > Web Events and locate the Pixel code in your Pixel settings.
Events not appearing in Events Manager
Check that your event_source matches the actual event origin. Events may take a few minutes to appear in TikTok Events Manager. Verify that the Pixel is active and not paused.
Authentication failed
TikTok OAuth tokens may expire. Reconnect your TikTok account in Zeotap to refresh the credentials.
Missing event data
Each event requires at minimum an event_name and at least one user data field for matching (e.g., email or hashed_email). Verify your field mapping includes these required fields.