Connect TikTok Ads to Rig

Before you start

• A developer account on TikTok for Business, at business-api.tiktok.com.
• Admin access to the TikTok Ads Manager account you want to sync, so you can complete the authorisation.
• Your advertiser ID, which sits under Account Info in TikTok Ads Manager.

One connection covers one advertiser ID. If you run several ad accounts, add a connection for each and give them names you will recognise later.

Create the Marketing API app

1. Sign in at business-api.tiktok.com and open the developer portal.
2. Create an app, and add the Marketing API product to it.
3. Select the permissions the app needs. Rig only reads, so reporting and ad account read access are enough. Nothing Rig does requires write scopes.
4. Set a redirect URI. Any URL you control will do, because all you need from it is the authorisation code sitting in the address bar. Rig does not host a callback page for TikTok Ads.
5. Copy the App ID and secret. Treat the secret like a password.
6. Submit the app for review, and wait for TikTok to approve it.

Authorise your ad account

1. In the developer portal, open your app and copy its Advertiser authorization URL.
2. Open that URL in a browser signed in to the ad account you want to sync.
3. Approve the app, and select the advertiser account it should reach.
4. TikTok sends you back to your redirect URI with auth_code in the query string. Copy that value.

Exchange the code for a token

The authorisation code is single use and short lived. Trade it for a long-lived access token, which is the value Rig actually stores:

curl -X POST https://business-api.tiktok.com/open_api/v1.3/oauth2/access_token/ \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "YOUR_APP_ID",
    "secret": "YOUR_APP_SECRET",
    "auth_code": "THE_CODE_FROM_THE_REDIRECT"
  }'

Read data.access_token out of the response. That token is long lived and does not rotate, so you paste it once and Rig keeps using it until you revoke the app in TikTok.

Connect it in Rig

Adding a source needs a workspace owner, or a role with the Manage connections permission, on a workspace where you manage your own connections. If the Connectors tab says “Data ingestion for this workspace is managed by Rig”, ask an owner or Rig support to add the source.

1. In Rig, open Connections, choose the Connectors tab and go to Sources & actions.
2. Search for TikTok Ads, open the card and click Connect.
3. TikTok access token: paste the access token from the exchange. The auth code will not work here.
4. Advertiser ID: the ID from Account Info in TikTok Ads Manager. It has to be one the token is authorised for.
5. Click Continue. Rig checks the credentials and lists the streams it can reach, so choose the ones you want and click Connect.
6. The source then syncs on its schedule, which is nightly unless you change it. To load data straight away, click Sync on its row; Test pulls a small sample first if you want to check the connection.

Rig syncs nightly by default. To change that, use the frequency menu on the source's row under Sources & actions, which only whoever connected the source or a workspace owner can change: Nightly and Hourly run on UTC, Manual turns automatic syncs off, and Custom… lets you set your own schedule and timezone. Keep your data fresh covers the options in full.

What Rig pulls in

TikTok Ads lands in its own tiktok_ads schema in your warehouse, and stays current with incremental syncs.

• Campaigns, ad groups and ads, the structure of the account
• Daily campaign performance: spend, impressions, reach, clicks, CTR, CPC, CPM, conversions, cost per conversion and conversion rate

Performance arrives at campaign by day, through yesterday. Ads and ad groups sync as structure rather than as metrics, so you can group, filter and label by them, but spend is attributed no finer than the campaign. If you need creative-level numbers, they are not in this connector today.

The first sync reaches back several years and drains in 30 day windows, which is TikTok's per-request cap rather than a Rig limit, so a cold start takes a while and resumes where it left off. After that, Rig re-pulls the last seven days on every run and merges the result, because TikTok restates recent days as late conversions land and spend reconciles.

Troubleshooting

• Error 40105 on every call: you pasted the auth code instead of the access token. Go back and exchange it, then paste what comes out.
• Every stream shows as unavailable: the advertiser ID is not one this token can reach. Rig checks the pairing before it syncs anything, so this is usually a token from a different app or an authorisation that covered another advertiser. Re-run the authorisation against the right account.
• The sync fails but nothing looks broken: TikTok returns HTTP 200 on failures and puts the real status in the response body, so Rig surfaces TikTok's own message along with a request_id. Quote that ID if you raise it with us or with TikTok.
• It worked and then stopped: the token does not expire on a timer, but it dies the moment the app is revoked in TikTok. Generate a new one through the same authorise and exchange steps and paste it in.
• Yesterday's numbers moved: that is the restatement window doing its job. TikTok keeps adjusting recent days, so treat the last week as provisional and anything older as settled.

What people use this for

• Keep more history than the platform hands back
• Track cost per conversion by campaign
• Monitor spend pacing against budget
• Join TikTok spend to revenue for blended CAC

More ideas for using TikTok Ads