TikTok Events API
Overview
Section titled “Overview”The TikTok Events API creates a direct connection between TikTok and your marketing data, and lets you decide what is shared. Sending those events is what allows TikTok to measure ad performance, optimize delivery and build audiences.
This connector covers the website case. Events are sent from your server rather than the visitor’s browser, so a conversion still reaches TikTok when an ad blocker, a cookie restriction or a dropped page load would otherwise have lost it.
It complements the TikTok pixel rather than replacing it. If the conversion happened away from the browser, use TikTok Offline Events API instead.
Supported sources
Section titled “Supported sources”Prerequisites
Section titled “Prerequisites”Before connecting TikTok Events API, make sure you have:
- An active TikTok Ads account.
- A subdomain set up for first-party cookies. Web events depend on it, so it has to be in place before anything is reported.
- Server-side API permissions, if you plan to connect manually.
- Either TikTok single sign-on access, or a Pixel ID and Access Token.
- A Datahash Studio account with the target project selected.
- A website source connected in the same project. Events reach TikTok through the source, so this destination on its own sends nothing.
Authentication
Section titled “Authentication”In Studio, open Destinations, find TikTok, and click the Events API tile. You can connect in two ways.
Single sign-on
Section titled “Single sign-on”- Click Continue with TikTok and sign in with your TikTok for Business credentials.
- Grant the requested permissions and confirm.
- Select the Advertiser ID and the associated Event Set ID that events should be written to.
- Click Finish.
Manual setup
Section titled “Manual setup”- Enter your Pixel ID and Access Token.
- Click Validate Credentials, then Finish.
| Field | What it is | Where to find it |
|---|---|---|
| Pixel ID | The identifier of the TikTok asset events are written to. Called an Event Set on the single sign-on screen. | TikTok Ads Manager, Tools, Events, Web Events, then Manage. |
| Access Token | A credential authorizing Datahash to send events on your behalf. | The same screen, then Settings, then Events API, then Generate Access Token. |
TikTok calls the same asset an Event Set on the single sign-on screen and a Pixel on the manual screen. They refer to the same thing.
Configuration
Section titled “Configuration”The advertiser and event set you chose during authentication are where events are written. Signals writes to one event set per instance.
The events themselves come from the connected source. Event names, the identifiers used for matching and the deduplication key are all set by the source mapping, not here.
There is no event mapping on this connector. TikTok accepts the event names your source sends.
Manage instance
Section titled “Manage instance”To change the instance, open it from Manage Instances, use the menu in the top right and choose Edit, update the fields and click Finish. Cancel keeps the previous configuration running, so updates apply only after you finish.
Deduplication
Section titled “Deduplication”Deduplication happens on the basis of the event ID. Where the same conversion is reported by both the browser pixel and the server, the same event ID has to travel on both, or TikTok counts it twice.
The event ID is set by the source mapping, not here.
Data & identifiers
Section titled “Data & identifiers”Send identifiers already hashed where you can. Plain text also works: they are normalized and SHA-256 hashed before they reach TikTok.
Required
Section titled “Required”| Field | When it is required |
|---|---|
| Event time | Always. UNIX timestamp. |
| Event name | Always. Must match the browser pixel event name, or deduplication will not work. |
| Page URL | Always on web events. TikTok rejects a web event without it. |
| Event ID | Always where the pixel reports the same conversion. It is the deduplication key. |
| Email address | At least one of email or phone on every event. |
| Phone number | At least one of email or phone on every event. |
| Currency | Purchase events only. The three-letter currency code. |
| Value | Purchase events only. |
Recommended
Section titled “Recommended”All of these raise the share of conversions TikTok can match to a person who saw your ads. Name and location fields are not among them on this connector, so contact data does most of the work.
| Field | Format |
|---|---|
| TikTok click ID | Captured when a visitor arrives from a TikTok ad. The strongest single signal on a web event. |
| TikTok cookie ID | The first-party cookie value TikTok writes on your subdomain. |
| IP address | Passed through as captured. |
| User agent | The full browser user agent string, unmodified. |
| External ID | An identifier of your own, hashed. Useful where the same person returns across sessions. |
| Page referrer URL | The page the visitor arrived from. |
Consent parameters
Section titled “Consent parameters”TikTok exposes an Opt-in for Limited Data Usage control on the authentication screen. Select Yes to enable the restriction on how TikTok uses the data, which TikTok cites as relevant to United States state privacy laws in California, Virginia, Colorado, Connecticut and Utah. Select No to disable it. The default is No.
This applies to the whole instance rather than to individual events, so decide it deliberately rather than leaving the default.
Best practices
Section titled “Best practices”- Send the same event ID from the browser and the server for any conversion reported on both paths. This is the single thing that prevents double counting.
- Decide the Limited Data Usage setting deliberately rather than accepting the default.
- Send email and phone together.
- Confirm the subdomain is in place and resolving before judging whether events are arriving.
- Rotate the access token before it expires if you connected manually, and revalidate afterwards.
Troubleshooting & FAQ
Section titled “Troubleshooting & FAQ”Validate Credentials fails. Re-check the Pixel ID and confirm the token was generated for that asset and has server-side API access.
No events appearing in Events Manager. Confirm a website source is connected in the same project, that the subdomain is resolving, and that the tag is published in your tag manager.
Conversions counted twice. The browser and server events are not sharing an event ID, or the event names differ. See Deduplication.
Low match rates. Add phone numbers where you only have email. Name and location will not help on this connector.
I cannot tell which asset to select. Event Set and Pixel are the same thing on TikTok. Pick the one you created for web events.
Delivery stopped. The access token may have expired or been revoked. Generate a new one and revalidate.