TikTok Ads API Tutorial - Reporting and Ad Management |

Get access to the TikTok Ads API. Examine your account, report on your campaigns and learn how to duplicate your best-performing ad - all programmatically.

In this TikTok Ads API tutorial, you will learn how to

Get access to the TikTok Ads API
Examine your account, campaigns, ad groups, and ads
Report on your ads
Find your best-performing ad (by spend)

This tutorial targets marketers working with TikTok Ads who are comfortable in a somewhat technical environment. The goal is to get you to play around with your TikTok ad account and build a solid foundation of transferable learnings that you can use to come up with your use cases. For more information, please visit the official documentation.

If you want to work with the TikTok Ads API but do NOT want to go through technical documentation or handle authentication yourself, check out Kitchn.io.

Get access to the TikTok Ads API

TikTok makes it more cumbersome than Facebook to get access to its Ads API. It also does not provide an interactive API explorer-like Facebook’s Graph API Explorer.

That means you will have to register as a developer, create an app and then complete the authorization procedure to get an access token that we can use for all API calls.

Despite the tedious process, the Getting Started part of the TikTok Ads API documentation is pretty good, so definitely make sure to check it out.

Register as a developer

To access the TikTok Ads API, you’ll first have to get a TikTok For Business account. Register as a developer here.

https://ads.tiktok.com/marketing_api/homepage

If you don’t have a TikTok account, you must create one.

After creating the account or logging in, click on Become a Developer on the top right.

Then, enter your information and details about your company and briefly describe how you plan to use the API, e.g., “To programmatically pull reports for my TikTok ad accounts and manage my campaigns, ad groups, and ads.”.

Create an app and get approved

Next, create a new app by clicking My Apps and Create New. As you can see, I previously already created an app, so your screen might look slightly different.

https://ads.tiktok.com/marketing_api/apps/

You will be asked to enter a name and some brief description that you can copy from above. Also:

Advertiser redirect URL: This is the place where TikTok will send Advertisers after connecting their ad account to your app. Feel free to enter your homepage.
Scope of permission: API access is broken up via different scopes to protect advertisers from accidentally sharing crucial information with a third-party app. We will need Ads Management and Reporting. Additionally, if you want to upload new creatives, add Creative Management.

TikTok Ads API Scope of permission

Next, hit Confirm. Your app will now be reviewed and approved if all goes well.

This usually takes 2-3 days.

So...

See ya!

The author’s demo app got approved after two days.

After getting approved

And...

...

... welcome back!

Now that your app is confirmed, it’s time to generate that access token so we can finally make our first API call.

Head over to your app detail page:

The App detail view contains your app id, secret and

Copy the Advertiser authorization URL and enter it into a new tab. Then, share access to your ad accounts with your app by ticking all boxes.

Permission Management for the Demo App

Do NOT close the window after you confirm and are redirected to whatever you had entered as the app’s Advertiser Redirect URL.

Advertiser Redirect URL with the important auth_code parameter.

Note down the auth_code - we’ll need it combined with your app id and the secret to generate the access token (see below).

As the final piece of the puzzle, you will need software that allows you to make API requests like Postman or Insomnia. Or use your programming language of choice.

We’ll have to send the following request URL and JSON body:

POST https://business-api.tiktok.com/open_api/v1.2/oauth2/access_token/

{
          "auth_code": "402c52d65665186d78b4435097884dec0008cbf2",
          "secret": "b1b14c0484f1d50b746f60d7609bf47xxxxxxxxx",
          "app_id": "7104142337395130369"
      }

A successful response will include your access token and all available ad accounts (advertiser_ids):

200 means success! The author has received an access token.

I will not be explicitly adding or mentioning the access token for the remainder of the tutorial. Still, you need it as the Access-Token header for every request if you are using Postman or Insomnia.

Include the access token with every API request as a header.

I am going to be using Kitchn.io’s built-in TikTok integration. It allows me to not worry about the business logic instead of dealing with things like access tokens.

Examine your account, campaigns, ad groups, and ads via the TikTok Ads API

By far, the hardest part is now out of the way - time to dig in!

Let’s start with the basics. In TikTok, the account hierarchy is as follows:

Source: https://ads.tiktok.com/marketing_api/docs?id=1701890926105602

As shown above, the campaign is used to set an objective but acts somewhat like a shell. For example, we define our targeting and placement on the ad group level. And the ad stores all user-facing elements of our campaign, i.e., the creative.

Now that we have an access token and know more about TikTok’s campaign structure let’s dive in and see what we can find.

Head to the official TikTok documentation and click on “API Reference” under the “Campaign Management” section.

Get all campaigns from your TikTok ad account

To get all campaigns belonging to a specific account, we need to call the /campaign/get/ endpoint:

https://business-api.tiktok.com/open_api/v1.2/campaign/get/

Of course, we need to let TikTok know for what account. We do this using the advertiser_id parameter, which is just your ad account id and the only required parameter to set.

You can find your ad account id in the URL of your browser when in the TikTok Ads Manager right after ?aadvid=:

Type caption (optional)

https://business-api.tiktok.com/open_api/v1.2/campaign/get?advertiser_id=6870790075194xxxx

Congrats - you made your first TikTok Ads API call! TikTok will respond with information about your request and a list of campaigns in your account.

{
         "code": 0,
         "message": "OK",
         "request_id": "202205250752310102510581820802D29B",
         "data": {
            "list": [
               ...
            ],
             "page_info": {
                 "page": 1,
                 "page_size": 10,
                 "total_page": 2,
                 "total_number": 12
             }
         }
      }

As you can see, only ten items were returned despite there being 12. We can fix this by either implementing pagination (a more advanced concept) or simply adding the page_size parameter to our request. The maximum is 1000, so we’ll use that. This makes our entire request:

https://business-api.tiktok.com/open_api/v1.2/campaign/get?advertiser_id=6870790075194xxxx?page_size=1000

For the remainder of this tutorial, we will only look at the list part of the response, assuming we got all relevant data back. So first, let’s look at one individual campaign:

{
          "opt_status": "DISABLE",
          "roas_bid": 0,
          "modify_time": "2020-11-13 13:44:30",
          "objective_type": "TRAFFIC",
          "is_new_structure": false,
          "budget": 0,
          "status": "CAMPAIGN_STATUS_DISABLE",
          "budget_mode": "BUDGET_MODE_INFINITE",
          "create_time": "2020-10-08 20:55:12",
          "objective": "LANDING_PAGE",
          "campaign_type": "REGULAR_CAMPAIGN",
          "campaign_name": "My Test Campaign",
          "deep_bid_type": null,
          "split_test_variable": null,
          "advertiser_id": 687079007519454xxxx,
          "campaign_id": 1680018437245954
      }

TikTok returns the campaign’s id, name, and objective, as well as some budget and bid settings. Also, the campaign seems paused or disabled.

Get all ad groups belonging to a TikTok campaign

Let’s use this campaign id to find the ad groups that belong to it. The base request to the TikTok Ads API looks very similar to the one before:

https://business-api.tiktok.com/open_api/v1.2/adgroup/get/?advertiser_id=687079007519454xxxx&page_size=1000

This request would return all ad groups in our account. Next, we need to use filtering to get those belonging to our campaign from above. Head over to the documentation to find all options. For now, we will use the campaign_ids filter.

https://business-api.tiktok.com/open_api/v1.2/adgroup/get/?advertiser_id=687079007519454xxxx&page_size=1000&filtering={"campaign_ids":["1680018437245954"]}

As you can see, we are adding a JSON object with the filtering parameter. This is a pattern to be used across many parts of the TikTok Ads API, so it’s worth remembering.

{
        "campaign_ids": [
          "1680018437245954"
        ]
      }

This returns all ad groups belonging to the specified campaign id. Let’s take a look at what data is specified here (for the sake of clarity, I have removed most irrelevant fields):

{
       "excluded_audience":[ ],
       "exclude_custom_actions":[ ],
       "placement":[ "PLACEMENT_TIKTOK" ],
       "schedule_start_time":"2020-10-09 10:58:24",
       "billing_event":"CPC",
       "adgroup_id":1680067909752866,
       "create_time":"2020-10-09 09:58:49",
       "advertiser_id":687079007519454xxxx,
       "adgroup_name":"My Ad Group",
       "external_type":"WEBSITE",
       "optimize_goal":"CLICK",
       "status":"ADGROUP_STATUS_CAMPAIGN_DISABLE",
       "opt_status":"DISABLE",
       "gender":"GENDER_UNLIMITED",
       "bid":0.15,
       "schedule_end_time":"2030-10-07 10:58:24",
       "campaign_id":1680018437245954,
       "campaign_name":"My Test Campaign",
       "keywords":[ "music" ],
       "budget":70,
       "bid_type":"BID_TYPE_CUSTOM",
       "budget_mode":"BUDGET_MODE_DAY",
       "placement_type":"PLACEMENT_TYPE_NORMAL",
       "age":[ "AGE_18_24", "AGE_25_34"],
       "location":[ 6252001 ]
      }

Let’s dig into some of the categories:

Status: This ad group is currently not delivering because its campaign is disabled.

Targeting: We are targeting the entire US based on the location id. All genders from 18 to 34 are being targeted.

Placement: There seems to be the manual placement of just the TikTok setup.

Budget and Bidding: A daily budget of 70 USD and a CPC bid of 0.15 cents is set up.

Target: We are sending users to a website.

Some of this looks familiar - some fields don’t make sense or are confusing based on the Ads Manager interface.

Get all ads belonging to a TikTok ad group

Let’s dive into what ads look like following the same URL and filtering approach as before:

https://business-api.tiktok.com/open_api/v1.2/ads/get/?advertiser_id=687079007519454xxxx&page_size=1000&filtering={"adgroup_ids":["1680067909752866"]}

This returns all ads - in our case, just one (some fields removed for simplicity’s sake).

{
       "create_time": "2020-10-09 10:00:35",
       "display_name": "Kitchn.io",
       "advertiser_id": 687079007519454xxxx,
       "open_url_type": "NORMAL",
       "call_to_action": "LEARN_MORE",
       "is_aco": false,
       "status": "AD_STATUS_CAMPAIGN_DISABLE",
       "campaign_name": "My Test Campaign",
       "adgroup_id": 1680067909752866,
       "video_id": "v07033700000bu03977sf236c4ixxxxx",
       "ad_format": "SINGLE_VIDEO",
       "ad_text": "Learn how to build on top of the TikTok Ads API.",
       "opt_status": "ENABLE",
       "campaign_id": 1680018437245954,
       "landing_page_url": "https://kitchn.io/builders",
       "adgroup_name": "My Ad Group",
       "ad_id": 1680067909753890,
       "ad_name": "My Ad",
       "image_ids": [ "v0201/8380125ea17a41a2a83f5e06864xxxxx" ]
      }

Once again, let’s dive in a bit:

Status: We can see that the ad itself is enabled but still not delivering due to its campaign being paused.

Identity: Instead of an IG account or FB page on Meta, here on TikTok, we seem to be simply defining a display name and profile picture (field removed).

Ad Format: A single video.

Creative: We can see that we have a video id and an image id (likely used as a thumbnail) with just one text element and are linking to a landing page, getting people to click with a “LEARN_MORE” CTA.

Report on your ads via the TikTok Ads API

Now that we looked at each ad object level let’s see if we can get the highest spending ad of our selected campaign over its entire lifetime.

BASIC report

We will need to create a BASIC report, which you can access at the following endpoint:

https://business-api.tiktok.com/open_api/v1.2/reports/integrated/get

There are quite a few parameters to choose from, and filtering works slightly differently. First, look at the entire URL needed and then break it down.

https://business-api.tiktok.com/open_api/v1.2/reports/integrated/get/?advertiser_id=687079007519454xxxx&report_type=BASIC&lifetime=true&data_level=AUCTION_AD&dimensions=["ad_id"]&filters=[{"field_name":"campaign_ids","filter_type":"IN","filter_value":"[1680018437245954]"}]

As you can see, we still use the same advertiser_id parameter. Some of the other parameters are relatively straightforward, like report_type and lifetime.

To get the data on the ad level, we need to combine two parameters:

data_level needs to be set to AUCTION_AD.
ad_id needs to be part of the dimensions parameter. Note that if we wanted to break down the data by day, we would also need to add that here.

Note: If we wanted to include adset or campaign level information for a report on ad level, we would have to do that as part of the metrics parameter - NOT the dimensions parameter.

Filtering

Lastly, let’s take a look at how filtering works. The filters parameter contains a list of objects that each have a name, type, and value:

[
        {
          "field_name":"campaign_ids",
          "filter_type":"IN",
          "filter_value":"[1680018437245954]"
        }
      ]

Just looking at it makes me feel a bit uneasy - to filter our campaigns, we need to refer to the campaign_ids (plural!) field and pass in a string as the value that contains comma-separated campaign ids are wrapped in [ and ].

Here’s what the response looks like:

[
         {
           "metrics": {
             "spend": "1265.87",
             "impressions": "3840449"
           },
           "dimensions": {
             "ad_id": 1680067909753890
           }
         },
       ...
      ]

This looks a bit more straightforward. TikTok returns some basic metrics and breaks the data by ad through the dimensions field.

The highest-spending ad seems to be the following.

{
         "metrics": {
           "spend": "3994.68",
           "impressions": "2244506"
         },
         "dimensions": {
           "ad_id": 1680018431123490
         }
      }

And that concludes our practical introduction to the TikTok Ads API.

If you want to learn more, stay tuned! In the following tutorial, I will share how you can change your existing campaigns and duplicate your best-performing ad from your testing campaign to your scaling campaign.

TikTok Ads API - A Practical Introduction to Reporting and Ad Management