> ## Documentation Index
> Fetch the complete documentation index at: https://docs.narrative.io/llms.txt
> Use this file to discover all available pages before exploring further.

# TikTok Conversions API Connector

> Send offline conversion events to TikTok for ad attribution and campaign optimization

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.

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

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](/reference/connectors/tiktok) — one installed connector, one set of profiles and ad accounts, two delivery paths.

## 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.

## Sending conversion events

Delivering conversion events to TikTok involves three steps: creating a connector profile, preparing your dataset, and adding a connection.

### Step 1: Create a connector profile

If you already deliver audiences through the TikTok Connector, you can reuse your existing profile and skip this step.

<Steps>
  <Step title="Navigate to the connector">
    In Narrative, go to **Installed Apps** and select **TikTok Connector**.
  </Step>

  <Step title="Authenticate with TikTok">
    Click **Connect** and authorize Narrative to access your TikTok for Business account.
  </Step>

  <Step title="Select your Ad Account">
    Choose the advertiser account that owns the Offline Event Set you want to deliver events to.
  </Step>
</Steps>

### Step 2: Create your dataset

Your dataset must be mapped to the [`tiktok_conversion_event`](https://app.narrative.io/platform/rosetta-stone/attributes/tiktok_conversion_event) Rosetta Stone attribute. The recommended approach is to map your source data to this attribute and then materialize it using Data Studio or NQL.

<Note>
  The connector requires your dataset to include `tiktok_conversion_event` **and** at least one [supported user identifier](#supported-user-identifiers) for user matching. Any dataset that contains the required attributes in the correct schema is eligible for delivery.
</Note>

See the [attribute schema](#the-tiktok_conversion_event-attribute) below for the full list of event fields, and [Supported user identifiers](#supported-user-identifiers) for the identity attributes your dataset must include.

### Step 3: Add a connection

<Steps>
  <Step title="Open your connector profile">
    Navigate to the TikTok connector profile you created in Step 1.
  </Step>

  <Step title="Add a new connection">
    Click **Add Connection** and select **Deliver Conversion Events** as the connection type.
  </Step>

  <Step title="Configure delivery options">
    * **Deliver all data** — Toggle on to deliver all data currently in the dataset. If off, only new data written after the connection is created will be delivered.
  </Step>

  <Step title="Connect">
    Click **Connect** to activate. Events will begin delivering on the next scheduled run.
  </Step>
</Steps>

## The `tiktok_conversion_event` attribute

The [`tiktok_conversion_event`](https://app.narrative.io/platform/rosetta-stone/attributes/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-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).                                                    |

### 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                                                               |
| `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.

***

## Data privacy

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

***

## Related content

<CardGroup cols={2}>
  <Card title="TikTok Connector" icon="tiktok" href="/reference/connectors/tiktok">
    Deliver custom audiences to TikTok Ads Manager
  </Card>

  <Card title="Meta Conversions API Connector" icon="meta" href="/reference/connectors/meta-conversions-api">
    Send conversion events to Meta
  </Card>

  <Card title="Data Activation Overview" icon="bullseye-arrow" href="/concepts/data-activation/overview">
    Understand how connectors deliver data
  </Card>

  <Card title="Hashing PII" icon="hashtag" href="/guides/ingestion/hashing-pii">
    Prepare identifiers for delivery
  </Card>
</CardGroup>