TikTok Events API

Web conversions for TikTok ads, matched on hashed email, phone, external id and ttclid.

Verified against the TikTok Business API portal (Events API 2.0) on 2026-09-03: Setup guide for Web, Parameters, Responses and error handling, Supported events, Event deduplication.

Prerequisites

A TikTok Ads Manager account with a pixel created in Events Manager.
A TikTok for Business developer app with the Events API scope, approved for your ad account.

What to collect

Value	Where to find it	Stored as
Pixel code	Events Manager → Web Events → your pixel → Settings. A string like `CXXXXXXXXXXXXXXXXXXX`. Sent as `event_source_id`.	Config
Access token	TikTok for Business developer portal → your app → Authorized accounts, or Events Manager → Settings → Generate access token for the pixel.	Vault
Test event code (optional)	Events Manager → your pixel → Test Event tab.	Config
Event source	`web` in almost every case; `offline` and `crm` exist for other pipelines.	Config
Limited data use	Turn on to mark events as subject to CCPA limited data use.	Config

What SaaS Pro Max sends

POST https://business-api.tiktok.com/open_api/v1.3/event/track/
Access-Token: <access token>
Content-Type: application/json

{
  "event_source": "web",
  "event_source_id": "CXXXXXXXXXXXXXXXXXXX",
  "data": [{
    "event": "Purchase",
    "event_time": 1786…,
    "event_id": "<the SaaS Pro Max event id>",
    "user": {
      "email": "<sha256 of the lowercased, trimmed email>",
      "phone": "<sha256 of the E.164 number, leading + included>",
      "external_id": "<sha256 of the distinct id>",
      "ttclid": "…", "ttp": "…",
      "user_agent": "…", "locale": "en-US",
      "city": "sanfrancisco", "state": "ca", "country": "us"
    },
    "page": { "url": "https://example.com/checkout", "referrer": "…" },
    "properties": {
      "value": 49, "currency": "USD",
      "contents": [{ "content_id": "SKU-1", "quantity": 2, "price": 20 }],
      "content_type": "product", "num_items": 2, "order_id": "…"
    }
  }]
}

Three details that are easy to get wrong, and that this adapter gets right:

The phone keeps its +. TikTok hashes +12133734253; Meta hashes 12133734253. The same number produces different digests for the two platforms, deliberately.
city, state and country are plain text, not hashed. Meta requires all three hashed. Sending TikTok a hashed city degrades matching or trips error 40002.
There is no partner_name field in Events API 2.0. It existed in 1.0 and is not sent.

Hashed: email, phone, external_id, first_name, last_name, zip_code. Not hashed: ttclid, ttp, ip, user_agent, locale, city, state, country.

user.ip is not sent: SaaS Pro Max hashes IPs at ingest and never stores them.

Standard web event names

Case-sensitive. Spell them exactly:

AddPaymentInfo, AddToCart, AddToWishlist, ApplicationApproval, CompleteRegistration, Contact, CustomizeProduct, Download, FindLocation, InitiateCheckout, Lead, Purchase, Schedule, Search, StartTrial, SubmitApplication, Subscribe, ViewContent.

Names from the legacy pixel vocabulary do not exist in Events API 2.0 for web. Map them across:

Old name	Use instead
`CompletePayment`	`Purchase`
`PlaceAnOrder`	`InitiateCheckout` or `Purchase`, depending on your semantics
`SubmitForm`	`Lead`
`ClickButton`, `Pageview`	Drop, or send as a custom event

A name outside the list is accepted as a custom event: it supports reporting and audiences, but not optimisation.

Verifying

Set a test event code on the destination.
Open Events Manager → your pixel → Test Event.
Press Send test event in SaaS Pro Max.
The event appears in the Test Event tab, marked as coming from the Events API.
Remove the test event code before relying on the numbers.

A successful call answers HTTP 200 with {"code": 0, "message": "OK", "request_id": "…", "data": {}}. SaaS Pro Max treats code: 0 as the only success signal — TikTok also answers 4xx/5xx for failures, so neither the HTTP status nor the body code alone is sufficient.

Deduplication with the pixel

The key is (event_source_id, event, event_id) within 48 hours; a duplicate that arrives within 5 minutes has its data merged into the first copy rather than being discarded, which is useful when the server event carries an email the browser event did not.

Send the SaaS Pro Max event id as the pixel's event_id.

Note that TikTok's cookie-based fallback deduplication only applies when event_id is absent. Pick one strategy; event_id is the recommended one.

Limitations

No ip, and no user_agent unless a server SDK supplies $user_agent.
One event per request (TikTok accepts up to 1,000).
Only throttling (40100) and 5xx responses are retried. 40002 — an invalid payload, including an unhashed value where a hash is required — is recorded as failed immediately.
quantity inside contents is accepted and appears in every official example, but is not in the documented parameter table. It is sent; do not depend on it being validated.