Connecting TikTok Events API

Overview

The TikTok Events API allows you to send server-side conversion events directly from DealOracle to TikTok. This is particularly valuable for lead generation advertisers because it enables you to report downstream outcomes (qualified leads, appointments, closed deals) back to TikTok's algorithm.

Why Use TikTok Events API?

• Bypass browser limitations — Server-side tracking is not affected by ad blockers, ITP, or cookie restrictions.
• Improved signal quality — Send hashed first-party data (email, phone) for better user matching.
• Optimize for real outcomes — Tell TikTok which leads actually converted, so the algorithm can find more people like them.
• Full-funnel visibility — Track the entire journey from ad click to closed deal.

Key benefit for lead gen: Most advertisers only optimize for form fills. With DealOracle + TikTok Events API, you can optimize for qualified leads or closed deals — dramatically improving your return on ad spend.

Prerequisites

Before connecting TikTok Events API, you'll need:

• TikTok for Business account — Sign up or log in at ads.tiktok.com.
• A TikTok pixel created — Go to Assets → Events → Web Events → Create Pixel. Choose "Events API" as the connection method.
• Events API access token — After creating your pixel, generate an access token in the pixel settings. Copy this token — you'll need it during setup.

How to Generate Your Access Token

1. Go to TikTok Ads Manager → Assets → Events
2. Click on your pixel
3. Go to Settings
4. Under "Events API", click Generate Access Token
5. Copy the token and store it securely

Important: Access tokens do not expire, but you can regenerate them at any time. Regenerating a token invalidates the old one.

Connection Steps

Follow these steps to connect TikTok Events API to DealOracle:

Step 1: Navigate to Integrations

From your DealOracle dashboard, go to Settings → Integrations → TikTok.

Step 2: Enter Your Pixel ID and Access Token

Enter the following information:

• Pixel ID — Found in TikTok Ads Manager → Assets → Events → your pixel's details page
• Access Token — The token you generated in the prerequisites step

Step 3: Select Events to Track

Choose which DealOracle disposition changes should trigger events to TikTok. You can select from:

• New lead captured
• Lead qualified
• Appointment booked
• Appointment attended
• Deal closed (won)
• Deal closed (lost)

Step 4: Map Events and Test

Map each selected disposition to a TikTok event (see Event Mapping below), then click Test Connection to send a test event.

Tip: After sending a test event, check TikTok Events Manager → Test Events to confirm receipt. Events typically appear within 1–2 minutes.

Event Mapping & Testing

Disposition to TikTok Event Mapping

DealOracle Disposition	TikTok Event	Description
New Lead	SubmitForm	A new lead has been submitted
Qualified	Contact	Lead has been qualified
Appointment Set	Subscribe	An appointment or call has been scheduled
Appointment Shown	ViewContent	Prospect attended the meeting
Closed Won	CompletePayment	Deal successfully closed
Closed Lost	Custom: ClosedLost	Deal was lost (useful for exclusions)

Custom Events

TikTok supports custom events via the Events API. If the standard events don't fit your funnel, you can define custom event names in DealOracle. Custom events can be used for:

• Creating custom audiences in TikTok
• Setting up custom conversion rules
• Reporting on non-standard funnel stages

Event Parameters

DealOracle sends the following data with each event:

• event — The event name
• event_time — Unix timestamp of the disposition change
• user — Hashed email, hashed phone number, external ID
• properties — Lead value, currency, content category
• page — Referrer URL and landing page URL (if available)

Verifying Events in TikTok

To confirm events are being received:

1. Go to TikTok Ads Manager → Assets → Events
2. Click on your pixel
3. Open the Test Events tab
4. Look for events labeled "Server" in the source column
5. Verify the event name and parameters match your expectations

Troubleshooting

• "Invalid access token" — Regenerate your access token in TikTok pixel settings and update it in DealOracle.
• "Pixel ID not found" — Double-check the pixel ID in TikTok Ads Manager. Make sure you're using the pixel ID, not the ad account ID.
• Events not appearing — Ensure the pixel is set to "Events API" mode (not "Manual" or "Partner"). Check the DealOracle event log for error details.
• Low match rate — Send both email and phone number for each lead to improve TikTok's ability to match events to ad clicks.

Need help? Contact DealOracle support at [email protected] or use the in-app chat.