Back to BlogTikTok Events API

Complete Guide to TikTok Events API Setup (2026)

Step-by-step guide to implementing TikTok Events API for server-side conversion tracking. Includes access token setup, ttclid capture, event payload format, and testing.

Complete Guide to TikTok Events API Setup (2026)
Table of contents

Why TikTok Events API?

TikTok Events API is TikTok's server-side tracking solution, similar to Facebook's Conversions API. It allows you to send conversion data directly from your server to TikTok, bypassing browser-based limitations.

Benefits

  • Better data accuracy with server-side tracking
  • Improved ad performance through optimized signals
  • Reduced impact from iOS 14+ and ad blockers
  • More reliable attribution for offline conversions

Prerequisites

Before setting up TikTok Events API, you'll need:

  • TikTok Ads Manager account
  • TikTok Pixel installed on your website
  • Access token from TikTok for Events API
  • A way to send server-side events (DealOracle or custom code)

Step 1: Get Your Access Token

  1. Log into TikTok Ads Manager
  2. Go to Assets → Events
  3. Select your pixel
  4. Click "Settings" → "Events API"
  5. Generate an access token
  6. Copy and save the token securely

Step 2: Capture the TikTok Click ID (ttclid)

When users click your TikTok ads, they arrive with a ttclid parameter. Capture this in a hidden form field:

ttclid-capture.html
<input type="hidden" name="ttclid" id="ttclid" />
<script>
  const params = new URLSearchParams(window.location.search);
  document.getElementById('ttclid').value = params.get('ttclid') || '';
</script>

Step 3: Configure Events in TikTok

Set up the events you want to track:

  • ViewContent - When someone views a page
  • SubmitForm - When someone submits a form
  • Contact - Phone call or message
  • CompleteRegistration - Account signup
  • CompletePayment - Purchase completed

Step 4: Connect with DealOracle

  1. In DealOracle, go to Integrations → TikTok
  2. Click "Connect with TikTok"
  3. Enter your pixel ID and access token
  4. Select which events to send
  5. Save and test the connection

Event Payload Structure

Here's what a TikTok Events API request looks like:

tiktok-event-payload.json
{
  "pixel_code": "YOUR_PIXEL_ID",
  "event": "SubmitForm",
  "event_id": "unique_event_id_123",
  "timestamp": "2026-01-25T10:30:00Z",
  "context": {
    "user_agent": "Mozilla/5.0...",
    "ip": "203.0.113.195"
  },
  "user": {
    "email": "sha256_hashed_email",
    "phone": "sha256_hashed_phone",
    "ttclid": "E.C.P..."
  },
  "properties": {
    "contents": [{
      "content_type": "product",
      "content_id": "lead_form"
    }]
  }
}

Testing Your Integration

Use TikTok's Test Event Tool

  1. Go to Events Manager → Your Pixel → Test Events
  2. Send a test event from DealOracle
  3. Verify the event appears in the test tool
  4. Check the match quality indicators

Verify in Events Overview

After 24-48 hours, check your Events Overview to see:

  • Event count and trends
  • Match quality score
  • Data discrepancies

Best Practices

1. Send Both Pixel and API Events

For redundancy, use both TikTok Pixel (browser-side) and Events API (server-side). Use the same event_id for deduplication.

2. Include User Agent and IP

TikTok uses these for additional matching. DealOracle captures these automatically.

3. Hash PII Correctly

All personally identifiable information must be SHA-256 hashed before sending. Format emails and phones consistently.

4. Send Events Promptly

Events sent within an hour of occurrence have the best match rates.

Troubleshooting

Events Not Appearing?

  • Verify your access token is valid
  • Check the pixel ID matches
  • Ensure event names match TikTok's standard events

Low Match Quality?

  • Capture ttclid on all landing pages
  • Send more user data (email + phone)
  • Include user agent and IP address

Conclusion

TikTok Events API is essential for advertisers serious about TikTok marketing. With DealOracle, setup takes minutes, not days, and you'll see improved match quality immediately.

Want the managed version of everything above? See how DealOracle sends TikTok Events API conversions straight from your CRM, with click ID capture, SHA-256 hashing and deduplication handled for you.

Kevin Salas

Kevin Salas

CMO - Chief Marketing Officer

We build DealOracle to help marketers recover conversion signal lost to iOS 14, ad blockers, and privacy changes, so you can optimize with real data.

Ready to improve your tracking?

Get started with DealOracle and recover 95% of your conversion data.