TikTok For Business Data Connector


Quick Details

Data Connector Technology API (TikTok marketing API v. 1.3)
Data Breakdown (segmentation) Your data is broken down by the following dimensions:
  • Platform (default)
  • Country
  • Placement
  • DMA
Important: To use a breakdown other than Platform, contact Singular support. Due to TikTok's API limitations, we cannot pull data from multiple breakdowns at the campaign level.

If you don't use the country breakdown, single-targeted campaigns will display country values, but a multi-targeted campaign will be "N/A" unless we can estimate it based on attribution data. Estimated data may not be identical to TikTok. See "How is cost calculated per country?"
How far back we pull data 7 days
Time zone UTC by default
Is data available on the creative (ad) level? Yes
Does Singular show your creative assets? Yes

Data Mapping

Tip: For more information about any field in Singular reporting, see the Metrics and Dimensions Glossary. Additionally, you can see TikTok's campaign feature mapping to their reporting API fields here.

Field in Singular UI Field in Singular API Field in TikTok API
Account ID adn_account_id (Taken from [advertiser/info])
Account Name adn_account_name advertiser_name
App app app_name
App Site ID app_site_id (Taken from the [app_download_url])
Bid Type bid_type bid_type
Campaign Objective campaign_objective objective_type
Campaign Status campaign_status opt_status
Campaign URL adn_campaign_url landing_page_url
Country country_field location
Date date_field stat_time_day
DMA ID dma_id_field dma.id
DMA Name dma_name_field dma.name
Network Campaign ID adn_campaign_id campaign_id
Network Campaign Name adn_campaign_name campaign_name
Network Creative ID adn_creative_id ad_id
Network Creative Name adn_creative_name ad_name
Network Sub Campaign ID adn_sub_campaign_id adgroup_id
Network Sub Campaign Name adn_sub_campaign_name adgroup_name
Original Bid Amount original_bid_amount bid
Original Bid Currency original_metadata_currency currency
Platform platform
  • platform
  • app_type (If platform is empty)
  • operating_system (If both are empty)
Public Id site_public_id mobile_app_id
Standardized Bid Type standardized_bid_strategy optimize_goal
Timezone adn_timezone timezone
Text creative_text ad_text
Age age age
Gender gender gender
Average Frequency frequency frequency
Comments comments comments
Likes likes likes
Network Clicks adn_clicks clicks
Network Impressions adn_impressions impressions
Network Installs adn_installs


(backup option: app_installs)

Original Cost adn_original_cost stat_cost
Original Currency adn_original_currency currency
Page Follows
page_follows follows
reach reach
shares shares
Video Views video_views total_play
Video Views - 25% video_views_25pct play_first_quartile
Video Views - 50% video_views_50pct play_midpoint
Video Views - 75% video_views_75pct play_third_quartile
Completed Video Views completed_video_views play_over

Setup Instructions

Setup Steps

To set up the TikTok for Business data connector:

  1. In your Singular account, go to Settings > Data Connectors.


  2. Click Add New Connector and start typing "TikTok". Select "TikTok Ads" from the list that appears.


  3. In the configuration window that opens, click Sign In with TikTok and log into your TikTok For Business account.


  4. The TikTok platform asks if you want to grant Singular permissions to access TikTok data. Check the Agree to the Platform Service Agreement checkbox and click Confirm.


  5. After you grant the permissions, the configuration window in Singular indicates that you are connected. You can close the window.
  6. TikTok now appears in the list of data connectors. The data connector status is "Pending" while Singular performs the first data pull. Once the first data pull is completed, the status will change to "Active".


  7. After the data connector has successfully pulled data into Singular, you can start running reports that include TikTok data. For more information see the Reports FAQ, Singular API Reference, or Singular Data Destinations FAQ.

    Sample report:


Additional Metrics (Conversion Events)

Singular pulls metrics from the TikTok for Business metrics list.  By default, regular events are pulled from the "in-app events metrics" section and SKAdNetwork events from the "Supported SKAN Metrics" section of the list. In addition to these, you can pull any metric by creating a conversion event in Singular.

To create a conversion event:

  1. In Singular, go to Settings > Events. If you have both Custom Events and Conversion Events tabs, select Conversion Events.
  2. Click New Event.
  3. In the TikTok Ads dropdown, select the desired metric.

    The next day, when Singular pulls daily data for your account, it will pull completions as well.

  4. After the new event is populated with some data, run a report in the Reports page, and choose the conversion event you created from Events dropdown.