vendor/tiktok-events-api · vendor documented

TikTok Events API timestamp is ISO 8601

Server-to-server track and batch on business-api.tiktok.com. pixel_code is the Pixel ID. event is the conversion name. timestamp is ISO 8601; an epoch number is stamped as the arrival time instead.

context.user.email, phone_number, and external_id are SHA-256 hex. context.ip and context.user_agent are sent unhashed. Same split as Meta: hash identifiers, not the request metadata.

timestamp is ISO 8601, not epoch

An epoch number is accepted and then ignored in favor of arrival time. Backfills look like they happened just now.

Rule: vendor.tiktok-events-api.body.timestamp.invalid

What this pack matches

Hosts: business-api.tiktok.com
Paths: …/pixel/track…, …/pixel/batch…
Vendor docs: ads.tiktok.com/marketing_api/docs?id=1739584855420929

Rules

Codes are stable. A finding in CI, MCP, or the playground lands on the same id.

Field	Required	What it checks	Rule ids	Source
`pixel_code`	required	It is the Pixel ID from Events Manager. TikTok documents it as required on both the single-event track call and the batch call. Fix: Set `pixel_code` to the Pixel ID shown in Events Manager.	`vendor.tiktok-events-api.body.pixel_code.missing` `vendor.tiktok-events-api.body.pixel_code.empty`	docs
`batch`	optional	The batch endpoint posts events under `batch`. The track endpoint posts a single event at the root instead.		docs
`event`	required	It is the conversion event name. TikTok documents it as required on every track payload. Fix: Set `event` to a documented web event name, such as `CompletePayment` or `ViewContent`.	`vendor.tiktok-events-api.body.event.missing` `vendor.tiktok-events-api.body.event.empty`	docs
`event_id`	optional	It identifies the event for deduplication against the browser pixel. TikTok documents it as required when the same conversion is sent from both. Fix: Send the same `event_id` the Pixel fired, so the pair collapses to one conversion.	`vendor.tiktok-events-api.body.event_id.empty`	docs
`timestamp`	optional	TikTok documents the event time as an ISO 8601 timestamp. An epoch number is not that format, and TikTok then stamps the event with the time it arrived. Fix: Send an ISO 8601 timestamp, such as `2026-07-26T06:00:00Z`.	`vendor.tiktok-events-api.body.timestamp.empty` `vendor.tiktok-events-api.body.timestamp.invalid`	docs
`context.ip`	optional	It is the visitor's public IP address, sent unhashed. Fix: Send the browser's public IP, not a SHA-256 digest and not your server's address.	`vendor.tiktok-events-api.body.context.ip.empty`	docs
`context.user_agent`	optional	It is the visitor's user agent, sent unhashed. Fix: Send the browser's user agent string, not a digest.	`vendor.tiktok-events-api.body.context.user_agent.empty`	docs
`context.user.email`	optional	Email must be SHA-256 hashed on the client side before it is sent. Fix: Trim and lowercase the address, hash it with SHA-256, and send the hex digest.	`vendor.tiktok-events-api.body.context.user.email.empty` `vendor.tiktok-events-api.body.context.user.email.invalid`	docs
`context.user.phone_number`	optional	Phone must be SHA-256 hashed on the client side before it is sent. Fix: Normalize the number, hash it with SHA-256, and send the hex digest.	`vendor.tiktok-events-api.body.context.user.phone_number.empty` `vendor.tiktok-events-api.body.context.user.phone_number.invalid`	docs
`context.user.external_id`	optional	Advertiser-side identifiers must be SHA-256 hashed on the client side. Fix: Hash the identifier with SHA-256 and send the hex digest.	`vendor.tiktok-events-api.body.context.user.external_id.empty` `vendor.tiktok-events-api.body.context.user.external_id.invalid`	docs
`properties.currency`	optional	It is an ISO 4217 currency code. Fix: Use the three-letter code, such as `USD`.	`vendor.tiktok-events-api.body.properties.currency.empty` `vendor.tiktok-events-api.body.properties.currency.invalid`	docs
`properties.value`	optional	It is the total value of the order or items, not the unit price.		docs
`body.unhashed_email`	required	A field carries what looks like a raw email address. TikTok requires customer email to be SHA-256 hashed on the client side. Fix: Trim the address, lowercase it, hash it with SHA-256, and send the hex digest.	`vendor.tiktok-events-api.body.unhashed_email`	docs
`body.hashed_plaintext_field`	required	This field looks like a SHA-256 digest, but TikTok documents `context.ip` and `context.user_agent` as unhashed. Fix: Send the raw IP address or user agent. Hashing it makes the event unmatchable.	`vendor.tiktok-events-api.body.hashed_plaintext_field`	docs

Validate a payload

pixellint validate json @payload.json --rulepack vendor/tiktok-events-api

Or paste it into the playground. Same engine, in the browser, nothing sent anywhere.

cargo install pixellint · npm install pixellint