TikTok Events API

Datafly Signal delivers events to TikTok server-to-server using the TikTok Events API. This enables accurate conversion tracking and audience optimisation without relying on the TikTok Pixel client-side script.

Prerequisites

Before configuring TikTok Events API in Signal, you need a TikTok for Business account, a Pixel, and an access token.

Step 1: Create a TikTok for Business Account

Go to ads.tiktok.com and click Sign Up.
Enter your business details and verify your email.
Complete the account setup wizard.

Step 2: Create a TikTok Pixel

In TikTok Ads Manager, go to Assets > Events > Web Events.
Click Set Up Web Events.
Select TikTok Pixel and click Next.
Choose Events API as the connection method (for server-side delivery).
Name your Pixel (e.g. “My Website Pixel”).
Click Create Pixel.
Note the Pixel Code (format: CXXXXXXXXXXXXXXXXX) — you’ll need this for Signal.

Step 3: Generate an Access Token

On the Pixel setup page, click Settings (or go to Events > your Pixel > Settings).
Under Events API, click Generate Access Token.
Copy the token immediately — it will only be shown once.

⚠️

Store this token securely. If you lose it, you can generate a new one from the same Settings page, but the old token will be revoked.

Step 4: Configure Events API Permissions

Ensure your TikTok Ads Manager user has Admin or Events Manager permissions.
If using a Business Center account, make sure the user has access to the ad account containing the Pixel.

API Endpoint

POST https://business-api.tiktok.com/open_api/v1.3/event/track/

Events are sent as JSON with authentication via the Access-Token request header.

Configuration

Field	Required	Description
`pixel_code`	Yes	Your TikTok Pixel code (e.g. `CXXXXXXXXXXXXXXXXX`). Found in TikTok Ads Manager > Events > Web Events.
`access_token`	Yes	Events API access token. Generate in TikTok Ads Manager > Events > Settings > Generate Access Token.

Management UI Setup

Go to Integrations > Add Integration > TikTok Events API.
Enter your pixel_code and access_token.
Select consent categories (typically advertising).
Click Save.

Management API Setup

curl -X POST http://localhost:8084/v1/admin/integrations \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "src_abc123",
    "vendor": "tiktok",
    "name": "TikTok Events API",
    "enabled": true,
    "config": {
      "pixel_code": "CXXXXXXXXXXXXXXXXX",
      "access_token": "your_access_token"
    },
    "consent_categories": ["advertising"]
  }'

Identity Signals

Signal	Field	Description
`ttp`	`user.ttp`	TikTok browser ID. Datafly Signal self-generates this as a UUID and stores it as a first-party cookie (`_ttp`).
`ttclid`	`user.ttclid`	TikTok click ID. Automatically extracted from the `ttclid` URL parameter when a user clicks a TikTok ad.
`external_id`	`user.external_id`	Set to the hashed Datafly `anonymous_id`.
`ip`	`user.ip`	Visitor’s IP address, forwarded from the original request.
`user_agent`	`user.user_agent`	Visitor’s User-Agent string, forwarded from the original request.

User-Provided Signals (Hashed)

When user data is available via _df.identify(), the following fields are SHA-256 hashed before sending to TikTok:

Signal	Hashing	Description
`email`	SHA-256, lowercase, trimmed	User’s email address
`phone`	SHA-256, E.164 format	User’s phone number (e.g. `+15551234567`)

All PII hashing is performed server-side by the Delivery Worker. Raw PII never leaves your infrastructure.

Event Mapping

Datafly Event	TikTok Event	Notes
`page` (page view)	`PageView`	Sent for every page view
`Product Added`	`AddToCart`	Includes content parameters
`Order Completed` / `Product Purchased`	`CompletePayment`	Requires `value`, `currency`
`Checkout Started`	`InitiateCheckout`	Includes `value`, `currency`
`Product Viewed`	`ViewContent`	Includes content parameters
`Products Searched`	`Search`	Includes `query` parameter
`Product Added to Wishlist`	`AddToWishlist`	Includes content parameters
`Signed Up`	`CompleteRegistration`	User registration
`Lead Generated`	`SubmitForm`	Lead form submission
Custom events	Passed through	Sent as custom event name

Example: Purchase Event

Datafly.js call:

_df.track("Order Completed", {
  order_id: "ORD-001",
  total: 129.99,
  currency: "USD",
  products: [
    { product_id: "SKU-A", name: "Widget", price: 49.99, quantity: 2 },
    { product_id: "SKU-B", name: "Gadget", price: 30.01, quantity: 1 }
  ]
});

TikTok Events API payload sent by Datafly:

{
  "pixel_code": "CXXXXXXXXXXXXXXXXX",
  "event": "CompletePayment",
  "event_id": "evt_abc123def456",
  "timestamp": "2026-01-29T14:30:00Z",
  "context": {
    "page": {
      "url": "https://example.com/checkout/confirmation",
      "referrer": "https://example.com/checkout"
    },
    "ip": "203.0.113.50",
    "user_agent": "Mozilla/5.0 ..."
  },
  "user": {
    "ttp": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "ttclid": "E.C.P.abc123def456",
    "external_id": "a1b2c3d4e5f6..."
  },
  "properties": {
    "currency": "USD",
    "value": 129.99,
    "order_id": "ORD-001",
    "contents": [
      {
        "content_id": "SKU-A",
        "content_name": "Widget",
        "content_type": "product",
        "price": 49.99,
        "quantity": 2
      },
      {
        "content_id": "SKU-B",
        "content_name": "Gadget",
        "content_type": "product",
        "price": 30.01,
        "quantity": 1
      }
    ]
  }
}

Example: Page View

{
  "pixel_code": "CXXXXXXXXXXXXXXXXX",
  "event": "PageView",
  "event_id": "evt_789ghi012jkl",
  "timestamp": "2026-01-29T14:29:00Z",
  "context": {
    "page": {
      "url": "https://example.com/products/widgets",
      "referrer": "https://www.tiktok.com/"
    },
    "ip": "203.0.113.50",
    "user_agent": "Mozilla/5.0 ..."
  },
  "user": {
    "ttp": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "ttclid": "E.C.P.abc123def456"
  }
}

Content Parameters

For e-commerce events, TikTok expects detailed content information:

Parameter	Type	Description
`content_id`	string	Product SKU or identifier
`content_type`	string	Type of content (`product` or `product_group`)
`content_name`	string	Product name
`value`	number	Total monetary value of the event
`currency`	string	ISO 4217 currency code (e.g. `USD`, `EUR`)
`price`	number	Unit price of the item
`quantity`	integer	Number of items

⚠️

The currency and value fields are required for CompletePayment events. Without them, TikTok cannot attribute revenue to your conversions.

API Response

A successful response from TikTok:

{
  "code": 0,
  "message": "OK",
  "request_id": "2026012914300012345678901234567890"
}

An error response:

{
  "code": 40001,
  "message": "Invalid access token",
  "request_id": "2026012914300012345678901234567891"
}

Common error codes:

Code	Meaning
`0`	Success
`40001`	Invalid access token
`40002`	Invalid pixel code
`40003`	Invalid event
`40100`	Rate limit exceeded

Rate Limits

Setting	Default
`rate_limit_rps`	100
`rate_limit_burst`	200

TikTok’s Events API allows up to 500 events per batch request. Datafly Signal batches events automatically when throughput is high.

Google Ads Conversions Pinterest CAPI