TikTok is a global social networking service that focuses on short-form videos and reports having 1 Billion active monthly users around the globe. You can use TikTok's Marketing API to target customers by creating custom segments.

Treasure Data's TikTok Integration allows you to send job results from Treasure Data directly to TikTok Marketing using custom audiences.

What can you do with this Integration?

  • Send Audience segments to TikTok in order to build the best-fit campaign for retargeting our existing customers, as well as attracting more look-alike audiences.
  • Stop targeting when end-users explicitly give the opt-out consent.


Requirements and Limitations

  • The maximum file size to be uploaded is 50MB per file and 500 files per audience which means we only could support uploading a maximum of 50MB * 500 files = 25000 MB ~ 25GB (the actual size due to restriction in plugin make it around 20GB )
  • After the creation of an audience, the audience will be accessible in 1 hour
  • Maximum 400 custom audiences

  • Data before hashing needs to be in all uppercase or lowercase

  • A minimum audience size of 1,000 is required to target Custom Audiences in an ad group

Creating Your Own TikTok Marketing API Developer Account and Application

You'll need to create your own Tiktok Marketing API Developer Account before you can begin creating applications. Learn more about how to Register as a Developer and what you need to do to Create a Developer Application for TikTok.

1. From the TikTok Marketing API homepage, select the Register button on the top right.
2. Type in your login credentials and confirm your password.
3. Select Send Code.
4. Next, you will receive an SMS with a passcode. Type the code into the Verification Code field and select Sign Up. 
If you do not receive a passcode select the Send Code button again. 
5.  After correctly entering the Verification Code, you are redirected to the login screen, where you can use your new credentials. 
6. Slide the bar to line up with the displayed image to complete the verification steps. 
7. You are now logged into the TikTok Marketing API homepage. 
8. Select Become a Developer from the top-right menu.
9. A new screen appears. Type in your login information and choose Direct Advertiser in the field What best describes you or your company. Select Send Code to verify your email and phone.
10. Select Next.
11.  Type on your information, including Company Name, Company Website, etc. Then, select Next. 
12.  Navigate to the Create Application pane. Then, type in your application name and description.
13. Type your local IP address in the Callback Address. You may need to certain permission, such as those in the following example. 
14. Select Submit.

15. You are redirected to the My Apps page, where you can view the status of your application. Application approval may take 2 or 3 business days. 

Obtain your App ID and Secret and get your Access Token

You must have your App ID and Secret before you can get your TikTok Access Token. 

1. From the TikTok Marketing API homepage, select Log In in the top right.
2. Select the My Apps to view your application.
3. Select the app name you want.

4. On the new screen, you can view your basic information, including the App ID and Secret.
5. Note this information for later.
6. Select Copy to retain the Secret on your clipboard.
7. On current application's screen, scroll down to Authorized URL.
8. Copy the Authorized URL, paste it into an open web browser, and press Enter. You will be prompted to log in to your TikTok Ads Account, then a new screen appears and select Confirm.

9. You will be redirected to a non-existent webpage. Copy the URL in the webpage and get the auth_code value.
For example, your URL may look like this:

10. Using your preferred API request tool, such as POSTMAN, you can send a request to https://business-api.tiktok.com/open_api/v1.2/oauth2/access_token/ with a request body as shown in the following example. 
    "app_id" : "{your_app_id}",
    "auth_code" : "{auth_code_in_above_step}",
    "secret" : "{your_app_secret}"

11. Next, select Send.

12. Alternatively, you may use cURL with the following command
$ curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.2/oauth2/access_token/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "app_id" : "{your_app_id}",
    "auth_code" : "{auth_code_in_above_step}",
    "secret" : "{your_app_secret}"

13. After you receive the response with the access_token and advertiser_ids like in the following example, you are ready to integrate with TikTok.
    "message": "OK",
    "code": 0,
    "data": {
        "access_token": "********************",
        "scope": [
        "advertiser_ids": [
    "request_id": "11111"

Use the TD Console to Create Your Connection

Create a New Connection

In Treasure Data, you must create and configure the data connection prior to running your query. As part of the data connection, you provide authentication to access the integration.

1. Open TD Console.
2. Navigate to Integrations Hub Catalog.
3. Search for and select TikTok.

4. Select Create Authentication.
5. Type the access token to authenticate.

6. Type a name for your connection.
7. Select Continue.

Define your Query

Your query will need to have the id column.

  1. Complete the instructions in Creating a Destination Integration.
  2. Navigate to Data Workbench > Queries.

  3. Select a query for which you would like to export data.

  4. Run the query to validate the result set.

  5. Select Export Results.

  6. Select an existing integration authentication.
  7. Define any additional Export Results details. In your export integration content review the integration parameters.
    For example, your Export Results screen might be different, or you might not have additional details to fill out:
  8. Select Done.

  9. Run your query.

  10. Validate that your data moved to the destination you specified.

Integration Parameters for TikTok 

ParameterTypesSample ValueDescription
access_token StringxxxxAccess Token
api_versionStringv1.2API version on TikTok. Do not changes this values unless you're required to change from Treasure Data
use_sandboxbooleanfalseFlag to indicate that you are trying to push segment to sandbox environment of TikTok
advertiser_idString12345678901234567890Your advertiser's id on TikTok
audience_nameStringTest AudienceAudience’s name



Audience's Action (REMOVE, REPLACE, ADD)

Example Query

FROM my_table

Example TD CLI

td query -d my_database -r '{ "accessToken": "__SAVED__", "useSandbox": true, "advertiserId": "12345678901234567890", "apiVersion": "v1.2", "audienceAction": "REPLACE", "audienceName": "test", "encryptionType": "FIRST_NORMAL" }' "select id FROM my_table" -T presto

  • No labels