[UPDATED] TikTok For Business Data Connector

Setting Up TikTok for Business


Updates [November 2021]:

  • Additional metrics from TikTok for Business can be pulled by creating conversion events (see instructions below).


Quick Details

Data Connector Technology API (TikTok marketing API v. 1.2)
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.

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_datetime
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 (Taken from the [app_download_url])
Standardized Bid Type standardized_bid_strategy optimize_goal
Timezone adn_timezone timezone
Text creative_text ad_text

Network Clicks

adn_clicks click_cnt
Network Impressions adn_impressions show_cnt
Network Installs adn_installs convert_cnt
Original Cost adn_original_cost stat_cost
Original Currency adn_original_currency currency
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)

In addition to the metrics that Singular pulls from TikTok for Business by default, you can pull any TikTok for Business metric (see list) 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.


Was this article helpful?