TikTok Connector API - Narrative I/O Knowledge Base

The TikTok Connector API lets an unattended integration deliver audiences to TikTok Ads Manager and send offline conversion events to TikTok Events Manager. A person signs in once to create an API key and once to connect a profile to TikTok, and the integration works from the API key after that. Complete the prerequisites and set up API access on this page before you follow either guide.

Choose a guide

Audience delivery

Upload hashed identifiers and deliver them into a new TikTok audience, or into one that already exists.

Conversion events

Send offline conversion events, such as in-store purchases, to a TikTok Offline Event Set.

Prerequisites

What you need depends on the guide you follow:

Prerequisite	Audiences	Conversion events
API key	✓	✓
TikTok Connector installed	✓	✓
A profile connected to TikTok	✓	✓
An advertiser on the profile	✓
An Offline Event Set ID		✓

API key

Create the key under Settings → API Keys with read and write on datasets and connections, write on uploads, and read on installations. Add read and write on webhooks if you want delivery notifications. See API Keys for the procedure and the Permissions Reference for what each resource covers. Create it from a shared team account rather than a personal login, so the integration keeps working when someone changes roles.

TikTok Connector installed

The TikTok Connector is app 19. Find your installation of it:

curl -s https://api.narrative.io/installations \
  -H "Authorization: Bearer $NIO_API_TOKEN"
# find the record with "app_id": 19 and note its "id"

Record the installation ID. If no record has "app_id": 19, install the TikTok Connector from the Narrative Marketplace.

A profile connected to TikTok

A connector profile holds the TikTok for Business authorization that every delivery uses. The profile also decides which TikTok advertisers you can deliver to. Create the profile once, in the Narrative UI:

Open the connector

In Narrative, go to Installed Apps and select TikTok Connector.

Create a profile

In the Profiles tab, create a profile and give it a name.

Connect to TikTok

Choose Connect, sign in to TikTok for Business as someone with access to the advertisers you want to deliver to, select those advertisers, and approve the access request.

You can also start the sign-in from the API, once you have an installation token. Ask the connector for the profile’s TikTok authorization URL:

curl -s -X POST https://tiktok.narrativeconnectors.com/profiles/{profile_id}/connect \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"url": "https://business-api.tiktok.com/portal/auth?...",
#    "expires_at": "2025-01-02T12:00:00Z"}

Open the url in a browser before expires_at, which is 24 hours after the request. Sign in to TikTok for Business, select the advertisers, and approve. TikTok then sends the browser to the TikTok connector, which saves the authorization and returns an empty page. To confirm the profile is connected, list its advertisers. You connect a profile once. The profile can then deliver to every advertiser you selected, from any number of connections.

An Offline Event Set ID

Conversion events go to an Offline Event Set in TikTok Events Manager. Create one there for the advertiser that should receive the events, and copy its ID. Each event row you upload carries this ID.

Set up API access

The guides talk to two hosts, and each takes its own credential:

Host	Base URL	Credential	Handles
Narrative API	`https://api.narrative.io`	Your API key	Datasets, uploads, connections, webhooks
TikTok connector	`https://tiktok.narrativeconnectors.com`	An installation token	Profiles, advertisers, audiences, settings checks

Get an installation token

The TikTok connector authenticates requests with an installation token, which you get by exchanging your API key. Use the installation ID from TikTok Connector installed:

curl -s -X POST https://api.narrative.io/installations/{installation_id}/token \
  -H "Authorization: Bearer $NIO_API_TOKEN"
# → {"access_token": "<INSTALLATION_TOKEN>", "access_token_expires_in": 10799,
#    "refresh_token": "<REFRESH_TOKEN>", "refresh_token_expires_in": 86399}

Store access_token as $INSTALLATION_TOKEN. It lasts about three hours, so request a new one at the start of each run of your integration. Confirm that both hosts answer:

curl -s https://api.narrative.io/company-info/whoami \
  -H "Authorization: Bearer $NIO_API_TOKEN"
# → {"id": 1234}

curl -s https://tiktok.narrativeconnectors.com/profiles \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"records": [{"id": "<PROFILE_ID>", "name": "Example Brand", "status": "enabled", ...}]}

Send the API key to api.narrative.io and the installation token to tiktok.narrativeconnectors.com.

API keys contain characters that shells mangle. Read the key from a file or an environment variable rather than pasting it inline.

Find your profile

GET /profiles lists every TikTok profile in your company. To read one:

curl -s https://tiktok.narrativeconnectors.com/profiles/{profile_id} \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"id": "<PROFILE_ID>", "created_at": "2025-01-01T12:00:00Z",
#    "company_id": 1234, "name": "Example Brand", "status": "enabled",
#    "updated_at": "2025-01-01T12:00:00Z"}

Use a profile whose status is enabled. Record its id.

List your advertisers

Advertisers are the TikTok advertiser accounts the profile can deliver to, which are the ones selected when the profile was connected:

curl -s https://tiktok.narrativeconnectors.com/profiles/{profile_id}/advertisers \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"records": [{"id": "<ADVERTISER_ID>", "name": "Example Advertiser"},
#                {"id": "<ADVERTISER_ID>", "name": "Example Outlet Advertiser"}]}

Record the id of the advertiser you deliver to.

List the audiences in an advertiser

curl -s "https://tiktok.narrativeconnectors.com/profiles/{profile_id}/advertisers/{advertiser_id}/audiences?page=1&page_size=100" \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"records": [{"id": "<AUDIENCE_ID>", "name": "Spring Buyers"},
#                {"id": "<AUDIENCE_ID>", "name": "Newsletter Subscribers"}],
#    "page_info": {"page": 1, "page_size": 100, "total_number": 2, "total_page": 1}}

Each record is an audience in that advertiser, with its TikTok audience ID and name. When total_page is more than 1, request the next page. The audience delivery guide uses this list to find audience IDs.

What the connection does

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

Audiences (`audience_first_party`)

One interface covers new and existing audiences. Set create_new_for, existing_audiences, or both.

Field	What it does	Allowed values	Default
`create_new_for`	The advertisers to create a new audience in	A non-empty list of advertiser IDs	None
`existing_audiences`	The existing audiences to add members to, grouped by advertiser	An object that maps each advertiser ID to a non-empty list of audience IDs in that advertiser	None
`audience_name`	The name of each audience the connection creates	Any string	`Connection <connection ID> Audience`
`historical_data_enabled`	Whether the connection also delivers data already in the dataset	`true`, `false`	`false`

An advertiser can appear in create_new_for or in existing_audiences, not in both. The connector creates new audiences on the connection’s first delivery and reuses them for every delivery after that.

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. An audience connection adds members and never removes them. When you overwrite the dataset, the connection adds the rows in the new snapshot, and members missing from it stay in the audience. A conversion connection sends each event in each snapshot it delivers. Uploading the same events again in a new snapshot sends them again.

Delivery notifications

The TikTok Connector reports each delivery as an app webhook event. Subscribe a webhook to app 19 to receive them:

curl -s -X POST https://api.narrative.io/webhooks \
  -H "Authorization: Bearer $NIO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "webhook_subscription_app",
    "app_id": 19,
    "url": "https://your-host.example/hooks/narrative",
    "name": "tiktok-deliveries"
  }'
# → {"id": "<WEBHOOK_ID>", "app_id": 19, "name": "tiktok-deliveries",
#    "secret": "<WEBHOOK_SECRET>", "status": "active",
#    "url": "https://your-host.example/hooks/narrative", ...}

Keep the secret to verify each delivery. The connector sends these events:

Event	Sent when
`audience.delivery.completed`	A delivery to a TikTok audience finishes
`audience.delivery.failed`	A delivery to a TikTok audience fails
`audience.delivery.quota_exceeded`	A delivery to a TikTok audience stops at TikTok’s daily quota. The connector sends this event instead of `audience.delivery.failed`
`conversion.delivery.completed`	A delivery of conversion events finishes
`conversion.delivery.failed`	A delivery of conversion events fails
`conversion.delivery.quota_exceeded`	A delivery of conversion events stops at TikTok’s daily quota. The connector sends this event instead of `conversion.delivery.failed`

Read a subscription with GET /webhooks/{webhook_id}. To stop the notifications, delete the subscription with DELETE /webhooks/{webhook_id}. See App subscription for the subscription fields and Verifying deliveries for checking the secret.