TikTok Conversions API Connector - Narrative I/O Knowledge Base

The TikTok Conversions API (CAPI) Connector sends conversion events from Narrative directly to TikTok’s Events API, enabling TikTok to attribute conversions back to ad campaigns and optimize delivery against real outcomes.

Overview

The connector routes conversion data — purchases, leads, registrations, and more — from any dataset in Narrative to a TikTok Offline Event Set. Events are matched against TikTok user accounts using hashed emails and phone numbers.

The connector currently supports offline events (e.g., in-store purchases, phone orders). Web, app, and CRM event sources are not yet supported.

Events are batched and delivered on a schedule you configure. PII fields are SHA-256 hashed before transmission in accordance with TikTok’s requirements. The Conversions API is a second interface of the same TikTok app that delivers custom audiences — one installed connector, one set of profiles and ad accounts, two delivery paths.

Guides

Sending Conversion Events to TikTok

Connect a dataset of conversion events

Setting Up API Access for TikTok

Prerequisites, API keys, and profiles for the API guides

Sending Conversion Events to TikTok via the API

Send conversion events with an API key

Prerequisites

A TikTok for Business account with access to the advertiser account you want to deliver events to.
An Offline Event Set created in TikTok Events Manager. Its ID is the event_set_id your dataset rows route to.
A Narrative dataset containing the conversion data you want to send.

The `tiktok_conversion_event` attribute

The tiktok_conversion_event attribute is Narrative’s standardized Rosetta Stone schema for conversion events sent to TikTok. When you map your dataset columns to this attribute, Narrative handles transformation, hashing, batching, and delivery to TikTok’s API.

Top-level fields

Narrative Field	TikTok Events API Field	Type	Required	Description
`event_set_id`	`event_source_id` (routing)	`string`	Yes	The TikTok Offline Event Set ID to deliver events to, from TikTok Events Manager. Each row routes to the event set it names.
`event_name`	`event`	`string` (enum)	Yes	The type of conversion event. See Event names.
`event_timestamp`	`event_time`	`timestamptz`	Yes	Timestamp when the event occurred. Events older than 90 days are skipped.
`event_id`	`event_id`	`string`	No	Unique string for deduplication. Optional for offline events but strongly recommended — use an order number or transaction ID.
`properties`	`properties`	`object`	No	Order and product information. See Properties fields.

Properties fields

Additional order and product data used by TikTok for attribution and reporting.

Narrative Field	Type	Description
`properties.value`	`double`	Monetary value of the conversion
`properties.currency`	`string`	ISO 4217 currency code (e.g., `USD`)
`properties.order_id`	`string`	Transaction or order ID
`properties.content_ids`	`string[]`	Product SKUs or content IDs
`properties.contents`	`object[]`	Array of product objects. Each requires `content_id` (string) and `quantity` (long). Optional: `content_name`, `content_category`, `brand` (strings), `price` (double)
`properties.content_type`	`string`	Type of the content IDs
`properties.num_items`	`long`	Number of items in the conversion
`properties.search_string`	`string`	Search query associated with the event
`properties.description`	`string`	Description of the event
`properties.shop_id`	`string`	TikTok Shop ID, if applicable

Supported user identifiers

In addition to the tiktok_conversion_event attribute, your dataset must include at least one of the following Rosetta Stone identifier attributes. TikTok matches offline events on hashed email and hashed phone number only — every event must carry at least one of the two, and any other identifier types in the dataset are not sent.

Identifier Attribute	Description
`sha256_hashed_email`	SHA-256 hashed email address
`hashed_email`	Hashed email address
`e164_phone_number`	Phone number in E.164 format
`telephone_number`	Phone number
`sha256_hashed_phone_number`	SHA-256 hashed phone number, sent unchanged
`narrative_id`	Narrative platform identity (resolves to matched emails and phone numbers)

Raw phone numbers are normalized to E.164 format and SHA-256 hashed by Narrative before transmission.

Reference

Event names

The event_name field accepts TikTok’s standard event names. Custom event names are not supported for offline events. Values are case-sensitive.

Value	Description
`AddPaymentInfo`	Payment information added
`AddToCart`	Item added to cart
`AddToWishlist`	Item added to wishlist
`ApplicationApproval`	Application approved
`CompleteRegistration`	Account created
`Contact`	Contact initiated
`CustomizeProduct`	Product customized
`Download`	Content downloaded
`FindLocation`	Store location looked up
`InitiateCheckout`	Checkout started
`Lead`	Lead submitted
`Purchase`	Purchase completed
`Schedule`	Appointment scheduled
`Search`	Search performed
`StartTrial`	Trial started
`SubmitApplication`	Application submitted
`Subscribe`	Subscription started
`ViewContent`	Content viewed

Deduplication

TikTok deduplicates events on the tuple (event_source_id, event_id, event_name). Narrative also tracks the event IDs already delivered to each event set and skips them on subsequent runs, so re-delivering a dataset does not double-count conversions. Provide a stable event_id (order number, transaction ID) to make both layers effective.

Event age limit

Events with an event_timestamp older than 90 days at delivery time are skipped and reported in the delivery’s skip count.

Batching

Events are delivered in batches of up to 1,000 per API call, grouped by event set.

API connection settings

A connection’s quick_settings pick the interface and set how the connection delivers. The fields depend on the interface.

Conversion events (`conversion_events`)

Field	What it does	Allowed values	Default
`historical_data_enabled`	Whether the connection also sends events already in the dataset	`true`, `false`	`false`

Each event names its event set in tiktok_conversion_event.event_set_id, so the connection has no advertiser or event set setting. The connection sends events up to 90 days old that carry an email address or a phone number.

Existing and new rows

A connection delivers every snapshot written to the dataset after the connection is created. The historical_data_enabled quick setting decides whether the connection also delivers data that was already in the dataset when you created it:

With historical_data_enabled set to true, the connection first delivers data already in the dataset, then keeps delivering new snapshots as they land.
With historical_data_enabled set to false, the connection delivers only snapshots written after it was created.

How far back the first delivery reaches depends on the connector, and each connector’s guide states it. For TikTok, historical_data_enabled delivers everything in the dataset when the connection is created. After that, each new snapshot is delivered as it lands. A conversion connection sends each event in each snapshot it delivers. Uploading the same events again in a new snapshot sends them again.

Data privacy

Narrative hashes all customer information fields (email, phone number) using SHA-256 before transmission. Raw PII is never sent to TikTok.

TikTok Connector

Deliver custom audiences to TikTok Ads Manager

Meta Conversions API Connector

Send conversion events to Meta

Data Activation Overview

Understand how connectors deliver data

Hashing PII

Prepare identifiers for delivery

Overview

Guides

Sending Conversion Events to TikTok

Setting Up API Access for TikTok

Sending Conversion Events to TikTok via the API

Prerequisites

The tiktok_conversion_event attribute

Top-level fields

Properties fields

Supported user identifiers

Reference

Event names

Deduplication

Event age limit

Batching

API connection settings

Conversion events (conversion_events)

Existing and new rows

Data privacy

Related content

TikTok Connector

Meta Conversions API Connector

Data Activation Overview

Hashing PII

The `tiktok_conversion_event` attribute

Conversion events (`conversion_events`)