TikTok Ads

Reporting API

Psst... Dessert Data connects all your marketing data into a neatly organized database. You can use the same query to pull spend for Bing, TikTok, or Google.

Don't worry about APIs changes or database uptime. We handle all that for you.

GET STARTED FREE

Overview

TikTok provides an easy Ads Reporting API for accessing your performance and spend data. Like other advertisers, the effort is spent getting approved for a developer token.

TikTok provides a developer sandbox for safe development

The steps are:

Create and setup a TikTok Ads developer account
Identify your advertiser ID
Generate an OAuth access token
Query the reporting API

Creating the TikTok Ads Developer Account

I won't go into detail here as this guide is more about the technical implementation. TikTok has a thorough manual review process.

You will need to provide information about your business use case, including your website and company location.

Generate an OAuth access token

Once you have a developer account, you can generate a standard OAuth access token.

Find your App ID

You'll need your app ID found on your TikTok business account dashboard. TikTok App ID

Authenticate your account

Plug your app id into the following URL and open it in your browser:

https://business-api.tiktok.com/portal/auth?app_id={{ your app id}}&state=your_custom_params&redirect_uri=http%3A%2F%2Flocalhost%3A3000

You will be redirected to a broken localhost URL, but the URL will contain the authorization code.http://localhost:3000/?auth_code={{ ignore this code }}&code={{ copy this code }}&state=your_custom_params

Generate an Access Token

Post to the access_token endpoint


POST https://business-api.tiktok.com/open_api/v1.3/oauth2/access_token/
Content-Type:application/json

{
    "secret": "{{$dotenv TIKTOK_SECRET}}", 
    "app_id": "{{$dotenv TIKTOK_APP_ID}}", 
    "auth_code": "{{ code copied from redirect URL }}"
}

Save the Access Token

The access token returned does not expire. So make sure to store it somewhere secure.


{
  "code": 0,
  "message": "OK",
  "request_id": "202309171942383471EF9E07779EA8057D",
  "data": {
    "access_token": "{{ save your access token }}",
    "advertiser_ids": [
      "{{ also note your advertiser ID }}"
    ],
    "scope": [
      4
    ]
  }
}

Identify your advertiser ID

You will need your advertiser ID to query the reporting API. If you didn't note this during the OAuth flow, you can find it by logging into your TikTok Ads account and expanding the Accounts drop down near the top right corner. TikTok Advertiser ID

Query the reporting API

TikTok provides thorough documentation thorough documentation for their reporting API.

For example if you want to pull September's daily impressions and spend by campaign, you could make the following query


GET https://business-api.tiktok.com/open_api/v1.3/report/integrated/get/ HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Access-Token: {{ your access token }}

metrics=["spend", "impressions"]
&data_level=AUCTION_CAMPAIGN
&end_date=2023-09-30
&page_size=10
&start_date=2023-09-01
&advertiser_id={{ YOUR ADVERTISER ID }}
&service_type=AUCTION
&report_type=BASIC
&page=1
&dimensions=["campaign_id", "stat_time_day"]

The response


{
  "code": 0,
  "message": "OK",
  "request_id": "202309241836164B1BB5FF1A45D79D5D4B",
  "data": {
    "list": [
      {
        "metrics": {
          "impressions": "635",
          "spend": "5.00"
        },
        "dimensions": {
          "stat_time_day": "2023-09-15 00:00:00",
          "campaign_id": "1774149501261857"
        }
      },
      {
        "metrics": {
          "impressions": "1004",
          "spend": "5.00"
        },
        "dimensions": {
          "stat_time_day": "2023-09-16 00:00:00",
          "campaign_id": "1774149501261857"
        }
      },
      ...
    ],
    "page_info": {
      "total_number": 3,
      "page": 1,
      "total_page": 1,
      "page_size": 3
    }
  }
}