TikTok Conversions

This guide covers how to submit conversions to TikTok through the TNT Growth API.

Authentication

All requests require an x-api-key header with your client-specific API key provided by TNT Growth.

-H "x-api-key: YOUR_API_KEY"

Submitting a Conversion

Endpoint

POST /api/tiktok/events/add

Request Body Schema

Field	Type	Required	Description
event_source	string	No	Event source — defaults to web
event_source_id	string	No	Your TikTok Pixel ID (provided during onboarding)
data	array	Yes	Array of event objects (see below)
ingestionSource	string	No	Origin of the event (e.g. pixel, conversion-api)
utmSource	string	No	UTM source parameter (e.g. tiktok) — stored for attribution reporting
utmMedium	string	No	UTM medium parameter (e.g. cpc) — stored for attribution reporting
utmCampaign	string	No	UTM campaign name — stored for attribution reporting
utmTerm	string	No	UTM search keyword — stored for attribution reporting
utmContent	string	No	UTM content parameter (ad/creative variant) — stored for attribution reporting

Event Fields (data[])

Field	Type	Required	Description
event	string	No	Event name (e.g. Purchase, AddToCart)
event_time	string|number	Yes	Unix timestamp (seconds) or ISO string of the event
event_id	string	No	Unique ID for deduplication (recommended)
user	object	Yes	Customer identifiers for matching (see below)
properties	object	No	Conversion details like value and contents (see below)
page	object	No	Page context — { url, referrer }

User Fields (data[].user)

Include as many identifiers as possible to improve match quality.

Field	Type	Description
email	string	Customer email address
phone	string	Customer phone number
external_id	string	Your internal customer ID
ttclid	string	TikTok click ID captured from the ad click
ttp	string	TikTok tracking parameter (_ttp cookie)
ip	string	IP address of the customer
user_agent	string	Browser user agent string

Properties Fields (data[].properties)

Field	Type	Description
value	number	Monetary value of the conversion
currency	string	Currency code (e.g. USD)
content_type	string	Content type (e.g. product, product_group)
contents	array	Array of { content_id, content_name } objects

Example Request

curl -X POST https://flex.tntgrowth.io/api/tiktok/events/add \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "event_source": "web",
    "event_source_id": "C8FORM3BC77U1ABCDEFG",
    "data": [
      {
        "event": "Purchase",
        "event_time": 1778043599,
        "event_id": "order-12345",
        "user": {
          "email": "customer@example.com",
          "phone": "+15551234567",
          "ttclid": "E.C.P.AbCdEfG"
        },
        "properties": {
          "value": 150,
          "currency": "USD",
          "content_type": "product",
          "contents": [
            { "content_id": "SKU-001", "content_name": "Treatment Plan" }
          ]
        },
        "page": {
          "url": "https://example.com/thank-you"
        }
      }
    ],
    "utmSource": "tiktok",
    "utmMedium": "paid-social",
    "utmCampaign": "awareness-q2",
    "utmTerm": "treatment options",
    "utmContent": "in-feed-video-variant-b"
  }'

Example Response

{
  "message": "Conversion Queued for TikTok! Pixel ID: C8FORM3BC77U1ABCDEFG",
  "data": {
    "submissionId": "8f3c2d10-7e6b-4a51-9d8c-3b2e1f0a9b8c",
    "duplicate": false
  }
}

When a conversion is dedup-skipped (the same event was submitted within the last 24 hours), submissionId is null and duplicate is true.

Checking Submission Status

After submitting a conversion, use the submission ID to check processing status.

Endpoint

GET /api/conversions/submissions/:submissionId

Example Request

curl https://flex.tntgrowth.io/api/conversions/submissions/8f3c2d10-7e6b-4a51-9d8c-3b2e1f0a9b8c \
  -H "x-api-key: YOUR_API_KEY"

Example Response

{
  "id": "8f3c2d10-7e6b-4a51-9d8c-3b2e1f0a9b8c",
  "source": "TIKTOK",
  "externalAccountId": "C8FORM3BC77U1ABCDEFG",
  "expectedCount": 1,
  "createdAt": "2026-05-11T12:00:00.000Z",
  "scheduledFor": null,
  "counts": {
    "success": 1,
    "failed": 0
  },
  "status": "complete"
}

Status Values

Status	Description
pending	Conversion is queued and waiting to be processed
pending_delivery	Submission is scheduled for future delivery. Currently only emitted by Google Ads ingest paths; TikTok submissions never enter this state.
complete	Conversion processed successfully
complete_with_errors	Processing finished but some conversions failed — use GET /api/conversions/tiktok/failed?submissionId=<id> to fetch the actual error messages
stalled	Processing has not progressed — contact support

The scheduledFor field is always null for TikTok submissions and is included only for schema parity with Google Ads, which uses it for deferred delivery.

Inspecting Failed Conversions In Your Batch

When a submission ends with complete_with_errors, the submission status endpoint surfaces only the count of failed rows. Fetch the actual error messages with:

GET /api/conversions/tiktok/failed?submissionId=<submissionId>

The response payload mirrors the Google Ads failed-conversion shape — see Google Ads → Inspecting Failed Conversions In Your Batch.

Best Practices

• Include event_id for deduplication — if the same event is sent twice with the same event_id, TikTok will deduplicate it
• Send user with as many identifiers as possible to maximize match rates
• Include ttclid when available — TikTok click IDs provide the strongest attribution signal
• Use accurate timestamps — event_time should reflect when the event actually occurred
• Poll with a delay — wait 30-60 seconds after submission before checking status