Skip to main content

TikTok Marketing

This connector captures data from TikTok marketing campaigns and ads into Flow collections via the TikTok API for Business. It supports production as well as sandbox accounts.

It is available for use in the Flow web application. For local development or open-source workflows, provides the latest version of the connector as a Docker image. You can also follow the link in your browser to see past image versions.

This connector is based on an open-source connector from a third party, with modifications for performance in the Flow system. You can find their documentation here, but keep in mind that the two versions may be significantly different.

Supported data resources

The following data resources are supported:

Ad GroupsXX
Ads Reports HourlyXX
Ads Reports DailyXX
Ads Reports LifetimeXX
Advertisers Reports HourlyX
Advertisers Reports DailyX
Advertisers Reports LifetimeX
Ad Groups Reports HourlyXX
Ad Groups Reports DailyXX
Ad Groups Reports LifetimeXX
Campaigns Reports HourlyXX
Campaigns Reports DailyXX
Campaigns Reports LifetimeXX
Advertisers Audience Reports HourlyX
Advertisers Audience Reports DailyX
Advertisers Audience Reports LifetimeX
Ad Group Audience Reports HourlyXX
Ad Group Audience Reports DailyXX
Ads Audience Reports HourlyXX
Ads Audience Reports DailyXX
Campaigns Audience Reports By Country HourlyXX
Campaigns Audience Reports By Country DailyXX

By default, each resource is mapped to a Flow collection through a separate binding.


Prerequisites differ depending on whether you have a production or sandbox TikTok for Business account, and on whether you'll use the Flow web app or the flowctl CLI.

OAuth authentication in the web app (production accounts)

If you have a TikTok marketing account in production and will use the Flow web app, you'll be able to quickly log in using OAuth.

You'll need:

Sandbox access token authentication in the web app or CLI

If you're working in a Sandbox TikTok for Business account, you'll authenticate with an access token in both the web app and CLI.

You'll need:


You configure connectors either in the Flow web app, or by directly editing the catalog specification file. See connectors to learn more about using connectors. The values and specification sample below provide configuration details specific to the TikTok Marketing source connector.



The properties in the table below reflect the manual authentication method for Sandbox accounts. If you're using a production account, you'll use OAuth2 to authenticate in the Flow web app, so many of these properties aren't required.

/credentialsAuthentication MethodAuthentication methodobjectRequired
/credentials/auth_typeAuthentication typeSet to sandbox_access_token to manually authenticate a Sandbox.stringRequired
/credentials/advertiser_idAdvertiser IDThe Advertiser ID generated for the developer's Sandbox application.string
/credentials/access_tokenAccess TokenThe long-term authorized access token.string
/end_dateEnd DateThe date until which you'd like to replicate data for all incremental streams, in the format YYYY-MM-DD. All data generated between start_date and this date will be replicated. Not setting this option will result in always syncing the data till the current date.string
/report_granularityReport Aggregation GranularityThe granularity used for aggregating performance data in reports. Choose DAY, LIFETIME, or HOUR.string
/start_dateStart DateReplication Start DateThe Start Date in format: YYYY-MM-DD. Any data before this date will not be replicated. If this parameter is not set, all data will be replicated.string


/streamStreamTikTok resource from which a collection is captured.stringRequired
/syncModeSync ModeConnection method.stringRequired


This sample specification reflects the access token method for Sandbox accounts.

auth_type: sandbox_access_token
access_token: {secret}
advertiser_id: {secret}
end_date: 2022-01-01
report_granularity: DAY
start_date: 2020-01-01
- resource:
stream: campaigns
syncMode: incremental
target: ${PREFIX}/campaigns

Report aggregation

Many of the resources this connector supports are reports. Data in these reports is aggregated into rows based on the granularity you select in the configuration.

You can choose hourly, daily, or lifetime granularity. For example, if you choose daily granularity, the report will contain one row for each day.