TikTok Events API

Datafly Signal delivers events to TikTok server-to-server using the TikTok Events API, replacing the client-side TikTok Pixel.

Why route TikTok through Datafly Signal

• Conversions survive ad blockers and tracking prevention. A browser tag served from an advertising domain is blocked outright for part of your traffic, and Safari’s ITP shortens the cookies it can set. Signal sends the event from your own server, so the conversions TikTok optimises against are not filtered by the browser.
• Email, phone number and user id are hashed before leaving your infrastructure. Signal normalises (trim and lowercase) and applies SHA-256 inside your own deployment, so TikTok receives match keys rather than raw personal data.
• Client IP and user agent are carried in the payload. Both are taken from the original visitor request rather than your server, which is what TikTok needs to attribute the event to the right session.
• Click identifiers are captured and replayed. Signal stores ttclid first-party at collection time and attaches them to the conversion later, so attribution survives even when the original landing cookie has expired.
• Delivery is batched, rate-limited, and retried. Signal buffers to Kafka, respects the TikTok rate limit, and retries on 429 or transient failure rather than dropping the event.
• Presets for Retail, Travel, Automotive and Media. The mapping starts from a working configuration for your vertical instead of a blank field map.
• One consent decision governs every destination. TikTok is gated by the same consent state as the rest of your stack, so a withdrawal applies everywhere at once.
• No vendor tag on the page. Removing it removes its page weight and its independent access to your visitors.

Prerequisites

Before configuring TikTok in Signal, you need:

• A TikTok for Business / TikTok Ads Manager account with admin or Events Manager permissions
• A TikTok Pixel (Web Event Source)
• An Events API access token for that Pixel

Get your TikTok credentials

1. Sign in to TikTok Ads Manager.
2. Go to Assets → Events → Web Events and select your Pixel (or click Set up Web Events to create one).
3. The Pixel Code (e.g. CXXXXXXXXXXXXXXXXX) is shown on the Pixel overview page.
4. Open the Pixel’s Settings → Events API and click Generate access token. Copy the token immediately.

See TikTok’s Events API documentation for full details.

Configure the integration in Signal

1. In the Management UI, go to Integrations → Add Integration.
2. Select TikTok from the catalogue.
3. Give the integration a name (for your reference).
4. Choose a preset (Retail, Travel, Automotive, Media or Insurance).
5. Fill in the required fields:

6. Choose which pipeline(s) this integration should run on.
7. Select consent categories (defaults to marketing).
8. Click Save.

Presets and event mapping

contents (TikTok’s shape: content_id, content_name, content_category, brand, price, quantity) comes from your items[] (canonical), else the legacy products[], else a single flat item_id / product_id (automotive: then the legacy vehicle_id), with content_type product. search_string and query are search_term, else the legacy query; order_id is transaction_id, else order_id; value is value (the total including tax and shipping, as the event specs define it), else the legacy revenue. CompletePayment is sent only with a currency.

The request’s event_source is web unless you set event_source on the integration (app, offline, crm); app events are reported as web for now (#1581). Every request is batched in data[] with event_source_id (your pixel code).

Retail preset (ecommerce)

Full retail funnel for the TikTok Events API: Pageview, Search (search_string and query), ViewContent, AddToWishlist, AddToCart, InitiateCheckout, AddPaymentInfo, CompletePayment (currency required, order ID) and Lead. contents (content_id, content_name, content_category, brand, price, quantity) come from items[], else the legacy products[], else a flat item. Email and phone are normalised SHA-256 hashes, the user ID a SHA-256 hash.

Travel preset (travel)

Travel funnel for the TikTok Events API: searches, listing views and saves, booking start, payment and completed booking (CompletePayment), leads; contents from items[].

Automotive preset (automotive)

Vehicle marketing funnel for the TikTok Events API: Search, ViewContent, AddToWishlist, Download, SubmitForm, Lead, Contact and Subscribe; contents from items[] or the flat item_id.

Media preset (media)

Media and subscription funnel for the TikTok Events API: content views, subscriptions, leads and registrations.

Insurance preset (insurance)

Insurance funnel per the insurance event spec’s TikTok mapping: quote requests and leads as SubmitForm, policy views as ViewContent, checkout and payment, policy purchase and renewal as CompletePayment (policy number as order_id, currency required), the quote journey as custom events. Email and phone are sent only as normalised SHA-256 hashes; contents come from items[].

Example: purchase

A Retail purchase from a known visitor, as Signal sends it to POST https://business-api.tiktok.com/open_api/v1.3/event/track/:

{
  "data": [
    {
      "event": "CompletePayment",
      "event_id": "evt-spec-0001",
      "event_time": 1790155800,
      "page": {
        "referrer": "https://www.google.com/",
        "url": "https://shop.example.co.uk/checkout?gclid=g-123"
      },
      "properties": {
        "content_type": "product",
        "contents": [
          {
            "brand": "BMW",
            "content_category": "SUV",
            "content_id": "STK-7421",
            "content_name": "BMW X3 xDrive30e",
            "price": 49995,
            "quantity": 1
          }
        ],
        "currency": "GBP",
        "event_source": "web",
        "order_id": "ORD-10042",
        "value": 49995
      },
      "user": {
        "email": "86e0b9e56c17cc4d12387e1949b85053fbe73bc3ce5a1188713a9d300cc6133d",
        "external_id": "40ba61f5c6b64e4f3f389c4b7a244f2b176115cbf452d1d81cf9bf70ebdf739d",
        "ip": "203.0.113.7",
        "locale": "en-GB",
        "phone_number": "a8acc3a90a7b4e4dc65e93db9240ed26523050ef754d63b75b5161de76781436",
        "ttclid": "tt-123",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 Version/18.0 Safari/605.1.15"
      }
    }
  ],
  "event_source": "web"
}

Identity

Signal sends these identity signals to TikTok, subject to consent and availability:

TikTok only matches on email and phone, so they are never sent in plain text. See Personal data by integration.

Consent

This integration is gated on the marketing canonical consent category. Events without marketing consent are not delivered.

Verify it’s working

1. Paste a test event code from TikTok Ads Manager into the integration’s test_event_code field.
2. In the Management UI, open Pipelines → your pipeline → Live Events and trigger a test event.
3. The event appears in Signal’s live feed and in TikTok’s Test event tab within seconds.
4. Clear the test_event_code once validated.

Troubleshooting

Events aren’t appearing in TikTok.

1. Confirm the integration is enabled on the pipeline.
2. Confirm marketing consent is granted.
3. Inspect the delivery response — code: 40001 / 40100 indicate auth issues (regenerate the token).

code: 40002. The pixel code is invalid — verify the value in TikTok Ads Manager.

See also

• TikTok Events API documentation
• Consent
• Identity