This article guides connecting TikTok Ads to Avid for the first time or reconnecting expired connections. It covers required permissions, setup steps, and features like Insights reporting, Custom Audiences, and Events API via Pathways. It details troubleshooting, known limitations, and when to contact LockStep Support. The connection syncs daily TikTok campaign data and enables audience targeting and conversion event tracking through TikTok Ads Manager.
Use this article when
- You need to connect TikTok Ads to Avid for the first time.
- You need to reconnect an expired or broken TikTok connection.
- You want to send an Avid audience to TikTok as a Custom Audience. A Custom Audience is a list of people you can target with ads.
- You want to send conversion events to a TikTok Pixel through the Events API. A Pixel is TikTok's tracking snippet. The Events API sends those events to the Pixel.
Applies to and prerequisites
| Avid plan | Insights plan or Trial. Pathways is not available on the Benchmarks plan. If you do not see Pathways in the sidebar, contact your Account Manager or submit a support ticket. |
|---|---|
| TikTok account | A TikTok for Business account with Advertiser access, managed in TikTok Ads Manager. |
| TikTok Pixel | Required only if you plan to send conversion events. Create the Pixel in TikTok Ads Manager before you set up an Events API Pathway. |
| Avid permission | Access to Settings > Connections. Using Pathways also requires the pathways.edit or direct_mail.edit permission. |
| Time estimate | About 10 minutes. |
Permission matrix
TikTok shows these permissions on the sign-in screen. Leave every listed Ad Account permission checked.
Read Public User Information is marked Required and cannot be unchecked.
| Role (TikTok) | Required permission | What it enables in Avid | Where to verify |
|---|---|---|---|
| TikTok for Business user | Read Public User Information (Required) | Completes sign-in | TikTok sign-in screen, under View Your Public Info |
| Advertiser access | Reporting | Insights reporting sync | The Reporting checkbox, and TikTok Ads Manager |
| Advertiser access | Audience Management | Custom Audience Pathways | The Audience Management checkbox, and TikTok Ads Manager > Assets > Audiences |
| Advertiser access | Pixel Management | Events API Pathways and the Pixel dropdown | The Pixel Management checkbox on the sign-in screen |
| TikTok for Business user | Ad Account Management, Ads Management, and Creative Management | Completes the Avid app authorization TikTok shows | TikTok sign-in screen, under Access Your Ad Account For |
Connect TikTok Ads to Avid
-
In Avid, go to Settings > Connections.
You see your connected systems and Add system.
-
Select Add system.
The Add a System window opens.
-
Select Advertising, then select the TikTok Ads tile.
The tile shows Insights and Pathways badges. It does not show a Playbooks badge.
-
Select Authenticate.
A TikTok window opens. Sign in with the TikTok for Business account that has Advertiser access. Use Switch account if the wrong user is signed in.
-
TikTok shows Avid is requesting permissions to:
- Read Public User Information (Required), under View Your Public Info
- Under Access Your Ad Account For: Ad Account Management, Ads Management, Reporting, Creative Management, Pixel Management, and Audience Management
Leave every listed Ad Account permission checked. Read Public User Information cannot be unchecked.
TikTok may also show this trust message:
Please ensure you trust this application as it may get access to your advertising data. After authorization, you can manage permissions via TikTok For Business User Settings. -
TikTok may email a verification code before you can select Confirm.
If you see Verify Your Identity, enter the code from Verification Email into Verification Code.
Use Send again if the email does not arrive. Then select Confirm, or Close to cancel.
Select Confirm on the TikTok permission screen. Select Cancel only if you want to stop.
- You return to Avid. What you see depends on how many Advertisers you can access.
-
One Advertiser: Avid selects it for you.
You see an alert titled Connection Successful:
You've successfully connected your TikTok Ads instance to Avid. The data will begin syncing momentarily.
On Settings > Connections, the system name is TikTok Ads. The connection name is the Advertiser name.
-
More than one Advertiser: The connection name is Unconfigured until you finish.
The modal heading is Reconnect TikTok Ads. It also says:
This connection looks unhealthy. Reconnect or verify your credentials so Avid can resume syncing data.
That copy appears because the Advertiser is not selected yet. Do not select Authenticate again. Select an Advertiser, then select Save.
The form also says:
We've successfully connected to your TikTok account. The last step is selecting which Advertiser you'd like to use. To connect more than one Advertiser, go through the connection process again once finished here.
-
Expected result: The TikTok Ads connection on Settings > Connections shows your Advertiser name. Status moves from Initializing to Syncing to Active.
Reconnect an existing connection
If your connection stops working, reconnect from Settings > Connections.
- Open Settings > Connections.
- Open the TikTok Ads connection. The modal heading is Reconnect TikTok Ads.
- Select Authenticate and sign in with a TikTok for Business account that can access the same Advertiser.
You see:
You've successfully updated your TikTok Ads connection. The data will begin syncing momentarily.
If you sign in with the wrong TikTok account, Avid shows:
The TikTok account selected does not have access to {connection name}. Please try again with a different account.What the connection enables
Insights reporting
Avid pulls TikTok campaign data into Insights on a daily schedule. Hourly TikTok reports are not available.
After the first successful reporting sync, Avid creates a data set named TikTok Ad Performance ({connection name}). Open the TikTok Ads connection on Settings > Connections to find it. That data set includes spend, impressions, clicks, reach, conversion goal, landing URL, and UTM fields. UTM fields are the tracking parameters in your ad URLs.
Campaign, ad group, and ad performance can appear in Insights after that first sync. The first sync includes daily performance from January 1, 2022 forward. Deleted ads can still appear in Insights.
You can also use Sync Now in the connection's Actions menu if you have Connections edit access.
Custom Audiences via Pathways
Push Avid audiences to TikTok as Custom Audiences through Pathways.
- Go to Pathways and open the Add a new Pathway tab.
- Select your audience.
- In Step 2: Choose a Destination, select TikTok Ads: {advertiser name}.
- Choose Custom Audience (Customer List) as the destination object.
- Map source columns to TikTok fields on the column mapping screen.
Avid creates or updates a Custom Audience named AVID - {segment name} in TikTok Ads Manager.
Avid uploads data when you trigger the Pathway, not on a fixed daily schedule. It uses one identifier type per upload. Extra mapped identifier columns are ignored for that upload.
If the audience is empty, the Pathway completes with 0 records. It does not fail. The Pathway can stay on Syncing in Pathways > Manage Pathways while TikTok is matching the file. A populated match count can complete the job even when TikTok still marks the audience invalid below about 1,000 matched users.
Avid hashes identifiers with SHA-256 before it sends them to TikTok. Learn more in the Data Security and Compliance FAQ.
Avid creates and updates the Custom Audience. It does not attach that audience to a TikTok campaign. After the sync completes, attach the audience to your campaign in TikTok Ads Manager.
Custom Audience field mapping
| Avid field | Notes |
|---|---|
Hashed automatically. Maps to EMAIL. |
|
| Phone | Hashed automatically. Maps to PHONE. |
| Mobile Ad ID | Hashed automatically. Maps to MOBILE_AD_ID. Also accepts MAID, IDFA, or GAID. |
Each row needs at least one of these identifiers. Rows without a supported identifier do not sync.
Avid uses one identifier type per upload. Extra mapped identifier columns are ignored for that upload.
If more than one identifier column is mapped, Avid uses Email first, then Phone, then Mobile Ad ID.
Blank values in the chosen column are skipped. They do not fall back to another identifier on that row.
Events API (Pixel) via Pathways
Send conversion events such as donations to TikTok through Pathways.
- Go to Pathways and open the Add a new Pathway tab.
- Select your audience.
- In Step 2: Choose a Destination, select TikTok Ads: {advertiser name}.
- Choose Events API (Pixel) as the destination object.
- Map your event fields, including the destination Pixel, on the column mapping screen.
Events appear against the mapped Pixel in TikTok Ads Manager.
Required fields are Pixel ID, Action Source, Event ID, Event Name, and Event Time.
The mapping template defaults Event Name to Purchase, Action Source to web, and Currency Code to USD. Use Purchase for donation conversions.
Events API field mapping
Map Pixel ID under Additional Columns and choose a Pixel from the dropdown.
Action Source options are Website (web), App (app), Offline (offline), and CRM (crm).
Event Name options include Purchase, Complete Payment, Lead, Complete Registration, View Content, and the other standard events in the dropdown.
| Avid field | Required |
|---|---|
| Pixel ID | Required |
| Action Source | Required |
| Event ID | Required |
| Event Name | Required |
| Event Time | Required |
| Optional identifier. Hashed automatically. | |
| Phone | Optional identifier. Hashed automatically. |
| Conversion Value | Optional |
| Currency Code | Optional |
| Event Source URL | Optional |
| Client IP Address | Optional |
| Client User Agent | Optional |
| First Name | Optional. Hashed automatically. |
| Last Name | Optional. Hashed automatically. |
| City | Optional. Hashed automatically. |
| State or Region | Optional. Hashed automatically. |
| Zip or Postal Code | Optional. Hashed automatically. |
| Country Code | Optional. Hashed automatically. |
| Gender | Optional. Hashed automatically. |
| Date of Birth (YYYYMMDD) | Optional. Hashed automatically. |
| Order ID | Optional |
Test and verify
| Checkpoint | What to look for |
|---|---|
| After connecting | The TikTok Ads connection on Settings > Connections shows Active and your Advertiser name. |
| After reporting sync | Status is Active, with a recent Last synced date. Open the TikTok Ads connection and look for the data set TikTok Ad Performance ({connection name}). Data can appear in Insights after the first sync. |
| After a Custom Audience sync | Check Pathways > Manage Pathways for sync status. Confirm a Custom Audience named AVID - {segment name} in TikTok Ads Manager under Assets > Audiences. |
| After an Events API sync | Check Pathways > Manage Pathways for sync status. Confirm events against the mapped Pixel in TikTok Ads Manager. |
Troubleshooting
Connection errors
| Error message | Cause | Fix |
|---|---|---|
TikTok did not complete authorization. Please try again. |
You denied access, or TikTok returned an error during sign-in. | Retry from Settings > Connections. Select Confirm and leave the listed permissions checked. |
Something went wrong when connecting to TikTok. Please try again. |
Sign-in finished, but Avid could not complete the connection. | Retry the connection. Sign in with a TikTok for Business account that has Advertiser access. |
The TikTok account selected does not have access to {connection name}. Please try again with a different account. |
You reconnected with a TikTok account that cannot access this Advertiser. | Use Switch account and sign in with a user who has access to that Advertiser. |
The authenticated user does not have any Advertisers. Please try again. |
The signed-in TikTok user has no Advertisers. | Sign in with a different TikTok for Business account, or ask your TikTok admin to grant Advertiser access. |
The advertiser has not been selected. |
The connection was created, but the Advertiser step was skipped. | Open the TikTok Ads connection in Settings > Connections, select an Advertiser, then select Save. |
Please select an account |
You saved without choosing an Advertiser. | Select an Advertiser, then select Save. |
TikTok connection is missing an advertiser ID. |
The connection has no Advertiser selected. | Select an Advertiser and save, or reconnect and choose the Advertiser. |
Pathway sync issues
Sync details are available in Pathways > Manage Pathways.
A Custom Audience Pathway can stay on Syncing while TikTok is matching the file. That is expected. An empty audience completes with 0 records.
| Error message | Cause | Fix |
|---|---|---|
TikTok Conversions pathway requires a Pixel ID. In Additional Columns, map Pixel ID and choose a pixel from the dropdown. |
The Events API Pathway has no Pixel mapped. | Map Pixel ID under Additional Columns and choose a Pixel from the dropdown. |
TikTok audience CSV is missing an identifier column (EMAIL, PHONE, MOBILE_AD_ID / MAID / IDFA / GAID). |
The Custom Audience mapping has no supported identifier. | Map at least one of Email, Phone, or Mobile Ad ID. |
TikTok audience CSV is missing a header row. |
The Custom Audience file has no header row. | Re-run the Pathway after the audience export includes a header row. If it still fails, contact LockStep Support. |
Unable to read TikTok audience CSV. |
Avid could not read the Custom Audience file. | Re-run the Pathway. If it still fails, contact LockStep Support. |
Unable to reach TikTok. Please try again. |
Avid could not reach the TikTok Marketing API. | Re-run the Pathway. If it still fails, confirm the TikTok Ads connection is Active, then retry. |
TikTok did not return a file path after upload. |
TikTok accepted the request but did not return an upload path. | Re-run the Pathway. If it still fails, contact LockStep Support. |
TikTok did not return a custom audience ID after creation. |
TikTok created the request but did not return an audience ID. | Re-run the Pathway. If it still fails, contact LockStep Support. |
TikTok custom audience has expired. |
The Custom Audience in TikTok is no longer valid. | Confirm the audience in TikTok Ads Manager, then re-run the Pathway. |
TikTok custom audience matching failed. |
TikTok could not match the uploaded identifiers. | Confirm Email, Phone, or Mobile Ad ID is mapped. Matching can stay invalid below about 1,000 matched users. That is a TikTok limit, not an Avid block. |
Cannot create lookalike audience: The base custom audience is too small. This will automatically be retried in 1 hour. |
Avid creates lookalikes for modeled segments. The base Custom Audience is too small. | Wait for the automatic retry in 1 hour. |
Cannot create lookalike audience: The base segment for this modeled segment could not be found. This will be retried in 24 hours once the base segment has finished processing. |
The modeled lookalike is waiting on its base audience. | Confirm the base Custom Audience Pathway has run, then re-run the modeled Pathway. The message mentions a 24-hour retry. Avid does not currently schedule that retry. |
Cannot create lookalike audience: Unable to access the base custom audience. The audience may not exist or you may not have permission to access it. |
TikTok could not read the seed Custom Audience. | Confirm Advertiser access and that AVID - {segment name} still exists in TikTok Ads Manager. |
Known limitations
- Reporting syncs daily. Hourly TikTok reports are not available. Avid only syncs daily ad reports. Use the daily Insights refresh or Sync Now. Pathways sync only when you trigger them.
-
Avid does not attach audiences to campaigns. After a successful push, attach
AVID - {segment name}in TikTok Ads Manager. - Custom Audience matching can stay invalid below about 1,000 matched users. This is a TikTok platform limit, not an Avid block.
- Events API Pathways require a Pixel ID. A Pixel is not required to connect TikTok Ads or to push Custom Audiences.
- Events API Pathways only append events. They do not replace existing events.
- Event Source URL, Conversion Value, and Currency Code are optional.
- Lookalikes are United States and narrow size only. Avid creates them for modeled segments. They are not a destination you pick. Avid does not offer other countries or sizes. Attach the lookalike in TikTok Ads Manager.
-
Custom Audience Pathways do not produce a downloadable row-level success or failure file. Check Pathways > Manage Pathways and TikTok Ads Manager for status. If you click a success or failure count, Avid may show
Error downloading records. Please try again.orDownload file not found for this sync run. - Playbooks is not part of this connection. The TikTok Ads tile shows Insights and Pathways only.
- Access can expire. If your TikTok connection stops working, reconnect from Settings > Connections.
When to contact LockStep Support
Contact LockStep Support if:
- The connection fails repeatedly after you confirm Advertiser access in TikTok Ads Manager.
- A Pathway sync fails with an error not listed above.
- The Advertiser dropdown does not show the account you expect.
Include the following when you reach out:
- The exact error message (copy the full text).
- The Pathway name, and whether it is a Custom Audience or Events API Pathway.
- The Advertiser name shown on the TikTok Ads connection.
- The Pixel ID, if the issue is an Events API Pathway.
- The email address of the person who connected the TikTok account.
- The date and time of the last successful sync, if you know it.
- A screenshot of the error, if visible.
Next steps
- Connect an integration
- What are Pathways and Audiences?
- Set up a Pathway
- What integrations work with Pathways?
- Understand Pathways sync summary numbers
- Restore Pathway sync after connection changes
- Data Security and Compliance FAQ
- Snapchat Ads
- Google Ads
- Connections: A deeper look at platform integrations
For agency partners
Avid does not send an explicit scope list on the authorize request. TikTok shows the permission checkboxes on https://business-api.tiktok.com/portal/auth.
On Settings > Connections, the system name is TikTok Ads and the connection name is the Advertiser name. In Step 2: Choose a Destination, the tile label is TikTok Ads: {advertiser name}.
Pathway destination objects use the keys customer (Custom Audience) and conversion_event (Events API).
Custom Audience segments are created or reused as AVID - {segment name}. Avid hashes identifiers with SHA-256 before send.
Custom Audience supported operations are mirror and upsert. Mirror sends REPLACE. Upsert sends APPEND. Conversion events support append.
Inbound reporting uses the Airbyte TikTok Marketing connector. Custom Audience uploads use TikTok's Marketing API. Events API Pathways publish a conversion payload with destination tiktok.
Airbyte reporting defaults are not shown in the Connections form. They are start_date=2022-01-01, include_deleted=true, and attribution_window=3.
The first reporting sync starts at January 1, 2022. Historical reporting includes deleted ads.
After the first successful reporting sync, the result data set is TikTok Ad Performance ({connection name}).
If the client has no other primary campaign_performance data set, Avid marks this one primary. If Facebook or another connection is already primary, TikTok is not.
For modeled segments, Avid can create a lookalike with NARROW size, US location 6252001, TikTok placements, and include_source=false. Lookalikes are not a destination object in the Pathway picker.
To connect more than one Advertiser, run the connection process again after you finish the first Advertiser.