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`)
`tntId`	`string`	No	The attribution handle from the pixel. A resolved session fills `user.ttclid`, `user.ttp`, `user.ip`, `user.user_agent` and any missing UTM fields
`utmSource`	`string`	No	UTM source parameter (e.g. `tiktok`) — stored for attribution reporting, and also decides delivery when it names a different paid platform. See When we withhold a conversion
`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[]`)

tntId is not one of these — it is a top-level field, sent once per request rather than per event.

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"
        }
      }
    ],
    "tntId": "9f2b7c1e-4d3a-4f8b-9c2e-1a5d7e0b4c63",
    "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 every event in a request is deduplicated, submissionId is null and duplicate is true. In a non-test request containing both duplicate and new events, Flex queues the new events and tracks the skipped events on the returned submission. See duplicate submissions and resends for the event-ID policy.

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`	Every conversion reached a final outcome and none was rejected. Usually means all were delivered — but a withheld conversion also finishes here, so compare `counts.success` with `expectedCount` if you need delivery confirmed
`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

Withheld Conversions

A conversion is withheld when its attribution says another paid channel served the click — a utmSource naming a different platform, with no TikTok click ID beside it. Uploading it would train TikTok's bidding on traffic TikTok never sent, so we hold it back instead. The full rules, and the utm_source values that count as a claim, are in When we withhold a conversion from a platform.

The check is per request, not per data[] entry. utmSource is a top-level field, so it applies to the whole request, and the click-ID side is evaluated across every entry: the request is withheld only when no data[] entry carries a user.ttclid. A single entry with one submits the entire request — including the entries that have no ttclid of their own. Split events into separate requests if you need them judged independently.

This is not an error. A withheld pair appears in counts.withheld, is excluded from counts.success, and never counts as failed — failed means the platform rejected it. A submission whose only non-delivered pairs were withheld finishes as complete, so compare counts.success with expectedCount if you need delivery confirmed.

{
  "expectedCount": 2,
  "counts": {
    "success": 1,
    "failed": 0,
    "withheld": 1
  },
  "withheld": [
    {
      "reason": "cross_channel",
      "claimedPlatform": "google",
      "count": 1
    }
  ],
  "status": "complete"
}

Both counts.withheld and the withheld array are present only when something was withheld, so a submission with nothing withheld returns exactly the shape it always has. Each entry carries reason (always cross_channel today), claimedPlatform (google, meta, bing, tiktok, linkedin, reddit or openai) and count; the entries sum to counts.withheld. Nothing is discarded — the payload is kept, so a withheld conversion can still be delivered later if your tagging or the rules change. Re-sending the same payload will be withheld again; send the TikTok click ID alongside utmSource and the click ID wins.

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
Send tntId when your backend has it — the attribution handle recovers the click ID and UTMs captured on the visitor's original ad click, which is often the only thing that attributes an offline conversion at all

Authentication​

Submitting a Conversion​

Endpoint​

Request Body Schema​

Event Fields (data[])​

User Fields (data[].user)​

Properties Fields (data[].properties)​

Example Request​

Example Response​

Checking Submission Status​

Endpoint​

Example Request​

Example Response​

Status Values​

Withheld Conversions​

Inspecting Failed Conversions In Your Batch​

Best Practices​

Authentication

Submitting a Conversion

Endpoint

Request Body Schema

Event Fields (`data[]`)

User Fields (`data[].user`)

Properties Fields (`data[].properties`)

Example Request

Example Response

Checking Submission Status

Endpoint

Example Request

Example Response

Status Values

Withheld Conversions

Inspecting Failed Conversions In Your Batch

Best Practices