Skip to main content
TikTok Ads logo
  • Category: marketing
  • Auth: OAUTH2
  • Composio-managed OAuth available? Yes
  • Tools: 404
  • Triggers: 0
  • Slug: TIKTOK_ADS
  • Version: 20261103_00

Tools

Slug: TIKTOK_ADS_ADD_BC_PARTNERAdd another Business Center as a partner and optionally share advertiser or catalog assets with it.

Input Parameters

string
required
Business Center ID adding the partner.
array
Up to 50 asset IDs to share.
string ("ADVERTISER" | "CATALOG")
Type of assets to share: ADVERTISER or CATALOG.
string
required
Business Center ID to add as a partner.
string ("ADMIN" | "AD_PROMOTE")
Catalog role for shared catalog assets. TikTok defaults to AD_PROMOTE when applicable.
string ("ADMIN" | "ANALYST" | "OPERATOR")
Advertiser role for shared advertiser assets. TikTok defaults to ANALYST when applicable.
string
Optional source child Business Center ID.
string
Optional target child Business Center ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_APPEAL_ADGROUPSubmit an appeal for a rejected ad group or an ad within it. This starts an external TikTok review, cannot be withdrawn through this tool, and may require human follow-up; confirm the rejection and supporting evidence before submitting.

Input Parameters

string
Ad ID. Optional.
string
required
Ad group ID.
string
required
Advertiser ID.
string
The reason for the appeal.
array
List of attachment links.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_APPEAL_SMART_PLUS_ADSubmit an appeal for a Smart+ ad review decision. Once submitted, the appeal cannot be withdrawn through this tool.

Input Parameters

string
required
Advertiser ID that owns the ad.
string
Appeal reason, up to 512 characters.
array
Provider attachment references supporting the appeal.
string
required
Smart+ ad ID to appeal.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_APPLY_DMP_CUSTOM_AUDIENCEApply a custom audience to ad groups or disconnect it from them.

Input Parameters

string ("Include" | "Exclude")
Required for Apply; include or exclude the audience.
string ("Apply" | "Disconnect")
required
Operation to perform on the audience.
array
required
Ad group IDs under the same advertiser account.
string
required
Advertiser ID.
string
required
Custom audience ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_ASSIGN_BC_ASSETAssign a Business Center asset and its asset-specific role to a member.

Input Parameters

string
required
Business Center ID.
string
required
Business Center user ID receiving access.
string
required
Asset ID to assign.
string ("ADVERTISER" | "CATALOG" | "TIKTOK_SHOP" | "LEAD" | "TT_ACCOUNT" | "MANAGED_BUSINESS_ACCOUNT")
required
Type of the asset to assign.
string ("ADMIN" | "AD_PROMOTION")
Shop role; required for TikTok Shop assets.
string ("ADMIN" | "AD_PROMOTE")
Catalog role; required for catalog assets.
string ("ADMIN" | "OPERATOR" | "ANALYST")
Advertiser role; required for advertiser assets.
array
Ad-delivery roles; required for TikTok account assets.
string
Form library role; required for lead assets.
array
One Business Account management role; required for managed business account assets.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_ASSIGN_BC_MEMBERAssign one or more existing members from source child Business Centers to a target child Business Center, optionally setting basic and finance roles.

Input Parameters

string
required
ID of the Business Center performing the assignment.
array
required
Members to assign to the target child Business Center (1-100).
string
required
ID of the child Business Center to which to assign the members.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_ASSIGN_TIKTOK_ACCOUNT_TO_ADVERTISERLink a TikTok account to an ad account in the same Business Center.

Input Parameters

string
required
Business Center ID that owns the TikTok account asset.
string
required
TikTok account asset ID to link to the advertiser.
string ("TT_ACCOUNT" | "MANAGED_BUSINESS_ACCOUNT")
TikTok account asset type: TT_ACCOUNT or MANAGED_BUSINESS_ACCOUNT.
string
required
ID of an ad account in the same Business Center to which to link the TikTok account.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_AUTHORIZE_IDENTITY_MUSICCheck whether every song in a TikTok post is authorized for a specific identity, targeting-location set, and ad deployment window. This does not grant creator or post authorization; the selected identity and post must already be authorized for advertiser use.

Input Parameters

string
required
Ad deployment end time in UTC, YYYY-MM-DD HH:MM:SS.
string
required
TikTok post ID. Sent to TikTok as item_id.
array
required
Targeting locations, exactly matching the intended ad.
string
required
Ad deployment start time in UTC, YYYY-MM-DD HH:MM:SS.
string
required
Identity ID authorized to use the post.
string
required
Ad account ID.
string ("AUTH_CODE" | "TT_USER" | "BC_AUTH_TT")
required
Identity type: AUTH_CODE, TT_USER, or BC_AUTH_TT.
string
Business Center ID; required for BC_AUTH_TT.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_AUTHORIZE_TT_VIDEOApply a creator-issued authorization code so an advertiser may use that specific TikTok post as a Spark Ad. The creator must generate the code, and duet, stitch, or mentioned-original posts also require the original post’s authorization code.

Input Parameters

string
required
Creator-issued Spark post authorization code. Per TikTok’s contract, replace every plus sign (+) in the code with %2B before calling.
string
required
Advertiser ID receiving the Spark post authorization.
string
Creator-issued authorization code for an original post referenced by a duet, stitch, or mention; at most one mentioned post is supported.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_BIND_CATALOG_EVENTSOURCEBind a mobile app, website Pixel, or both to a catalog.

Input Parameters

string
required
Business Center ID.
string
Mobile app ID; at least app_id or pixel_code is required.
string
required
Catalog ID.
string
Website Pixel code; at least app_id or pixel_code is required.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_BIND_OPTIMIZER_RULE_BATCHBind or unbind optimizer rules from existing advertising objects.

Input Parameters

string ("ZH" | "EN" | "JA")
Language of returned messages.
array
required
Rule binding operations.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CANCEL_DMP_CUSTOM_AUDIENCE_SHAREStop sharing a custom audience with an advertiser.

Input Parameters

string
required
Advertiser ID performing the operation.
string
required
Audience ID to stop sharing.
string
required
Advertiser ID to stop sharing the audience with.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CANCEL_REPORT_TASKCancel a queued or processing asynchronous TikTok report task. Confirm the advertiser and disposable task ID before calling because cancellation is irreversible.

Input Parameters

string
required
Queued or processing asynchronous report task ID to cancel.
string
required
Advertiser ID associated with the report task.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CANCEL_RF_ORDERCancel the R&F ad order. This operation is destructive or irreversible; confirm exact disposable targets before calling. This operation can affect billing, credit, invoices, budgets, contracts, or payments; require explicit approval and an isolated account.

Input Parameters

array
required
ID of the ad group to be withdrawn (ID must correspond to R&F ad group).
string
required
Advertiser ID

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CHANGELOG_TASK_DOWNLOADRead the status and change-log content returned for an advertiser’s change-log task.

Input Parameters

string
required
Change-log download task ID to retrieve.
string
required
Advertiser ID that owns the change-log task.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CHECK_ADVERTISER_TERM_STATUSCheck whether a TikTok advertiser has signed a specified agreement.

Input Parameters

string ("InstantPage" | "LeadAds" | "Pixel" | "ReachFrequency")
required
Type of TikTok agreement to check.
string
required
Advertiser ID whose agreement status to check.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CHECK_BLOCKEDWORDCheck whether specified words are blocked for an advertiser without changing moderation settings.

Input Parameters

string
required
Advertiser ID.
array
required
List of words whose blocked status to check.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CHECK_BLOCKEDWORD_TASKCheck whether a blocked-word export task is running, succeeded, or failed. Call the download action only after SUCCEED.

Input Parameters

string
required
Blocked-word export task ID.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CHECK_CAMPAIGN_COPY_TASKGet the results of an asynchronous copy task for a Manual Campaign. Availability may depend on account entitlement.

Input Parameters

string
required
Asynchronous campaign copy task ID.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CHECK_CHANGELOG_TASKCheck whether an advertiser change-log download task is processing, successful, or failed.

Input Parameters

string
required
Change-log download task ID to check.
string
required
Advertiser ID that owns the change-log task.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CHECK_COMMENT_TASKCheck whether a comment export task is running, succeeded, or failed. Call the download action only after SUCCEED.

Input Parameters

string ("BIDDING" | "BRAND")
Comment source: BIDDING or BRAND.
string
required
Comment export task ID.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CHECK_FILE_NAMESCheck whether one or more image or video file names are already used in an advertiser account.

Input Parameters

array
File names to check in one batch (maximum 20).
string
Single image or video file name to check.
string ("VIDEO" | "IMAGE")
Type of the single file. Required with file_name even though TikTok documents VIDEO as the provider default.
string
required
Advertiser account ID that owns the files.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CHECK_GMV_MAX_STORE_AVAILABILITYCheck a TikTok Shop’s availability for Product GMV Max campaigns.

Input Parameters

string
required
TikTok Shop store ID to check for Product GMV Max availability.
string
required
Advertiser account ID for which to check TikTok Shop availability.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CHECK_MMM_DATA_REQUESTCheck one MMM export job. Poll conservatively because TikTok documents up to 24 hours of processing but no polling-rate contract.

Input Parameters

string
required
MMM request ID returned by create or history.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CHECK_PAGE_LEAD_TASKPoll an existing TikTok lead download task. Provide the task ID and exactly one owning advertiser or Business Center form-library context; the polling operation does not require the original ad or Instant Form target.

Input Parameters

string
required
Lead download task ID returned by task creation.
string
Form library ID after leads have migrated to a Business Center.
string ("eu" | "us")
Use eu for EEA/Switzerland/UK leads, us for US leads, or omit for other regions.
string
Advertiser ID when leads remain under an ad account.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CHECK_REPORT_TASKCheck, without polling, whether an asynchronous report task is queued, processing, successful, failed, or canceled.

Input Parameters

string
required
Asynchronous report task ID.
string
required
Advertiser ID associated with the task.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CHECK_SMART_PLUS_CAMPAIGN_COPY_TASKGet the results of an asynchronous Upgraded Smart+ campaign copy task.

Input Parameters

string
required
ID of the asynchronous Upgraded Smart+ campaign copy task.
string
required
Advertiser account ID that owns the campaign copy task.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CHECK_UNIONPAY_VERIFICATION_REQUIREMENTCheck whether a business license requires UnionPay verification before submitting advertiser verification details.

Input Parameters

string
required
Business license number to check for a UnionPay verification requirement.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CHECK_VBO_ELIGIBILITYCheck VBO bidding eligibility for a proposed campaign configuration; some options require allowlisting.

Input Parameters

string
Promoted application ID.
string
Pixel ID; use with optimization_event where supported.
string
TikTok Shop ID for Product Sales.
array
required
Apps where ads will be delivered.
string
required
Advertiser ID.
string ("REGULAR_CAMPAIGN" | "IOS14_CAMPAIGN")
Regular or iOS 14 Dedicated Campaign type.
string ("SAN" | "SKAN")
Dedicated Campaign attribution type: SAN or SKAN.
string ("APP_PROMOTION" | "WEB_CONVERSIONS" | "PRODUCT_SALES")
required
VBO-capable advertising objective.
string ("APP_ANDROID" | "APP_IOS" | "GAME" | "LEAD_GENERATION" | "LEAD_GEN_CLICK_TO_CALL" | "LEAD_GEN_CLICK_TO_SOCIAL_MEDIA_APP_MESSAGE" | "LEAD_GEN_CLICK_TO_TT_DIRECT_MESSAGE" | "LIVE_SHOPPING" | "MINI_APP" | "PRODUCT_SHOPPING" | "TIKTOK_SHOP" | "VIDEO_SHOPPING" | "WEBSITE" | "WEBSITE_OR_DISPLAY")
required
Promotion type.
string ("OCCUPIED" | "UNOCCUPIED")
Whether the campaign occupies the iOS 14 campaign quota.
string ("APP_INSTALL" | "APP_RETARGETING")
App promotion type.
boolean
Whether Campaign Budget Optimization is enabled.
string
Conversion-event code required with pixel_id.
boolean
Whether SKAdNetwork attribution is disabled.
string ("MANUAL" | "SMART_PLUS" | "UPGRADED_SMART_PLUS")
Campaign automation type.
boolean
Whether this is a Smart+ Campaign.
boolean
Whether this is an Advanced Dedicated Campaign.
string ("ON" | "OFF")
Whether to use App Profile Page delivery optimization.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CONFIRM_TERMSign the Lead Generation Ads agreement for an advertiser.

Input Parameters

string ("InstantPage" | "LeadAds" | "Pixel" | "ReachFrequency")
required
Agreement type to sign.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_ADCreate one or more ordinary ads in an existing ad group using documented creative settings. New ads default to DISABLE so they do not start delivery or spend unless operation_status is explicitly set to ENABLE.

Input Parameters

array
required
Ads to create.
string
required
Ad group ID.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_ADGROUPCreate an ad group, disabled by default unless explicitly enabled; availability may depend on account entitlement or allowlisting. Starting January 1, 2027, creation under non-Search Legacy Manual Flow campaigns with Sales, App Promotion, or Lead Generation objectives is no longer supported.

Input Parameters

string
The App ID of the app to promote. You can get app_id by using the /app/list/ endpoint. Required in the following use cases: When objective_type is APP_PROMOTION and app_promotion_type is APP_RETARGETING (App retargeting).When objective_type is APP_PROMOTION , app_promotion_type is APP_INSTALL(App install) or APP_PREREGISTRATION (App Pre-registration), and it is not an iOS14 Dedicated Campaign. Note: You cannot specify an App that has not activated the SAN module on your MMP through this field to create ad groups. To ensure that TikTok SAN integration is enabled for your App, see How to transition to SAN for existing apps and How to integrate to SAN for new apps.
number
required
Ad group budget. The setting will be ignored when Campaign Budget Optimization (budget_optimize_on = TRUE) is enabled. For how to configure budget settings, see Budget. To directly see the daily budget value range for a currency, see Currency-Daily budget value range.
string ("GENDER_FEMALE" | "GENDER_MALE" | "GENDER_UNLIMITED")
Gender that you want to target. Enum values: GENDER_FEMALE,GENDER_MALE,GENDER_UNLIMITED.
string
required
You can choose between PACING_MODE_SMOOTH and PACING_MODE_FAST. For PACING_MODE_SMOOTH, the budget is allocated evenly within the scheduled time. PACING_MODE_FAST would consume budget and produce results as soon as possible. When Campaign Budget Optimization (budget_optimize_on) is on, your setting will be ignored and it will be set as PACING_MODE_SMOOTH. Otherwise, this field is required.
array
A list of targeting behavioral category objects.
boolean
Whether the promoted content is HFSS (High Fat, Salt, Sugar) Product/Brand. If your ad is promoting or prominently featuring a product/brand classed as high in fat, salt or sugar, set this field to true. In regulated regions, HFSS ads must only be targeted to users aged 18 or over. You can set this field to true when your targeting locations include locations in the UK, Australia, New Zealand, and the European Union. Supported values: true,false. Default value: false.
array
Valid only when you specify a valid location ID at the country or region level via location_ids at the same time. IDs of the Internet service providers (ISP) that you want to target. You can use /tool/targeting/list/ to get the ISP IDs that you can target for a location ID. Note: When you pass in isp_ids, you cannot set the placement as Global App Bundle only (placements =PLACEMENT_GLOBAL_APP_BUNDLE).
string
Bidding strategy that determines how the system manages your cost per result, spends your budget, and how it delivers ads. Required when Campaign Budget Optimization (CBO) is enabled (budget_optimize_on = TRUE). For enum values, see Enumeration - Bidding Strategy. Note For new ad groups created under one CBO campaign, this field should be the same as the first ad group.
string
Required when optimization_goal is set to CONVERT or VALUE. Not supported when optimization_goal is not set to CONVERT or VALUE. Pixel ID. To obtain the list of Pixel IDs within your ad account, use /pixel/list/.
number
Required when deep_bid_type is VO_MIN_ROAS. ROAS goal for Value Optimization. Value range: For in-app advertising scenarios (objective_type is APP_PROMOTION, optimization_goal is VALUE, and optimization_event is AD_REVENUE_VALUE): 0.01-10.For Product Shopping Ads with product source as TikTok Shop (shopping_ads_type is PRODUCT_SHOPPING_ADS and product_source is STORE): 0.01-20.For other scenarios: 0.01-1,000.
string
Required in any of the following scenarios: shopping_ads_type is VIDEO and product_source is STORE.shopping_ads_type is PRODUCT_SHOPPING_ADS and product_source is STORE. Optional when shopping_ads_type is LIVE.ID of the TikTok Shop. Note: To get the TikTok Shop ID, you can use /bc/asset/get/: When in the response asset_type is TIKTOK_SHOP, the returned asset_id is the TikTok Shop ID.
number
Required when bid_type is BID_TYPE_CUSTOM and billing_event is CPC, CPM, or CPV. Bid price. The average cost per result that you want to achieve (for Cost Cap bidding strategy). When Campaign Budget Optimization (budget_optimize_on) is on, we suggest that you set the same bid value for all ad groups in the campaign. bid_price needs to be lower than budget set at the campaign level and ad group level. See Bidding-Bidding limits to learn more about the bid verification mechanism.
integer
Frequency, together with frequency_schedule, controls how often people see your ad (only available for REACH ads). The below conditions should be both met:1 1 For example, frequency = 2 & frequency_schedule = 3 means “show ads no more than twice every 3 day”.
array
Codes of the languages that you want to target. For the list of languages codes supported, see Enumeration - Language Code. You can get language codes via /tool/language/, and if you don’t want to limit the languages you target, assign an empty value to this field or do not pass in this field.
array
Age groups you want to target. For enum values, see Enumeration - Age Group. In certain scenarios, creation of ad groups that target the age group 13-17 (AGE_13_17) in the US, Latin America, the European Economic Area, the UK, Switzerland, or Canada will not be allowed. See New age restrictions for ads on TikTok to learn more. If you use targeting options that are not supported for the age group 13-17 in the US , Latin America, the European Economic Area, the UK, Switzerland, or Canada and leave the age_groups field unspecified or set it as [], the field will default to ["AGE_18_24", "AGE_25_34", "AGE_35_44", "AGE_45_54", "AGE_55_100"]. Note: If the ad group targets the age group 13-17 (AGE_13_17) in the US, Latin America, the European Economic Area, the UK, Switzerland, or Canada and you typically leave the age_groups field unspecified or set it as [], we recommend that you explicitly specify the exact age groups that you want to target, such as AGE_18_24, in the field.
array
Required when sales_destination is WEB_AND_APP at the campaign level. Details of the app or apps to promote. Max size: 2. You can specify any of the following in this field:an Android appan iOS appan Android app and an iOS app
string
When product_source is CATALOG or STORE, this field is required. When shopping_ads_type is LIVE, the parameters catalog_id, catalog_authorized_bc_id, store_id, store_authorized_bc_id are optional. If you specify a TikTok Shop through these parameters for your Live Shopping Ads, sales of products belonging to the TikTok Shop will be reported. If you don’t specify a TikTok Shop, sales of products showcased in the TikTok account (identity_id) will be reported. Catalog ID. When product_source is CATALOG, set this field to the catalog that you want to promote products from. When product_source is STORE, set this field to the catalog bound to the TikTok Shop that you want to promote products from.You can use /store/list/ to get the catalog_id, store_id and store_authorized_bc_id for available stores under an ad account. Note: Starting June 30th, 2024, when product_source is STORE, you will no longer need to pass catalog_id because it will be ignored.
string
Ad delivery arrangement, in the format of a string that consists of 48 x 7 characters. Each character is mapped to a 30-minute timeframe from Monday to Sunday. Each character can be set to either 0 or 1. 1 represents delivery in the 30-minute timeframe, and 0 stands for non-delivery in the 30-minute timeframe. The first character is mapped to 0:01-0:30 of Monday; The second character is mapped to 0:31-1:00 of Monday, and the last character represents 23:31-0:00 Sunday. Note: If not specified, all-0, or all-1 are considered as full-time delivery.
array
Delivery placements. Required for placement_type=PLACEMENT_TYPE_NORMAL; ignored and system-selected for PLACEMENT_TYPE_AUTOMATIC. Supported: PLACEMENT_TIKTOK, PLACEMENT_PANGLE, PLACEMENT_GLOBAL_APP_BUNDLE; do not use deprecated PLACEMENT_TOPBUZZ or PLACEMENT_HELO. Placements cannot be updated after creation. Global App Bundle supports Brazil, Indonesia, Vietnam, Philippines, Thailand, Malaysia, Mexico, Saudi Arabia, and Japan; it does not support optimization_goal=TRAFFIC_LANDING_PAGE_VIEW, and Auction Reach use is allowlist-only. With objective_type=REACH, Global App Bundle cannot be combined with contextual_tag_ids; when it is the only placement, brand_safety_type=THIRD_PARTY is invalid. For objective_type=PRODUCT_SALES, use only PLACEMENT_TIKTOK.
string
Request ID with which you can create ad groups with duplicate names. To create ad groups with duplicate names, send two requests for creating ad groups with the same adgroup_name and different request_id. It also supports idempotency to prevent you from sending the same request twice within 10 seconds. If you retry requests with the same request ID multiple times within 10 seconds, then only one will succeed. It is different from the request_id returned in the response parameters, which is used to uniquely identify an HTTP request. The value should be a string representation of a 64-bit integer number. Example: 123456789
string ("SEVEN_DAYS" | "ZERO_DAY")
VBO IAA/IAP bidding window: SEVEN_DAYS (day 7, default) or ZERO_DAY (day 0). For Minimum ROAS, selects the target ROAS window and the system aims for average ROAS at or above the target. For Highest Value, selects the value-maximization window and the system aims to spend the budget fully. VBO availability is scenario-dependent and allowlist-only; day 0/day 7 VBO IAA or IAP in Advanced Dedicated Campaign and Android scenarios is also allowlist-only. Once set, this field cannot be updated.
string ("BUDGET_MODE_TOTAL" | "BUDGET_MODE_DAY" | "BUDGET_MODE_DYNAMIC_DAILY_BUDGET")
required
Ad group budget mode; ignored when Campaign Budget Optimization is enabled. BUDGET_MODE_TOTAL: lifetime budget and requires schedule_type=SCHEDULE_START_END plus schedule_end_time. BUDGET_MODE_DYNAMIC_DAILY_BUDGET: weekly average; daily spend <=125% of average and weekly spend <=7 times average. Use it for non-lifetime budgets with TRAFFIC, APP_PROMOTION, WEB_CONVERSIONS, LEAD_GENERATION, Video Shopping PRODUCT_SALES, REACH, VIDEO_VIEWS, or ENGAGEMENT; the last three are allowlist-only. BUDGET_MODE_DAY: daily budget; schedule_type may be SCHEDULE_START_END or SCHEDULE_FROM_NOW, but dynamic daily is recommended for REACH, VIDEO_VIEWS, and ENGAGEMENT.
string
required
The ID of the campaign that the ad group belongs to.
array
Carriers that you want to target. The carriers must be consistent with the location(s) that you want to target. Use /tool/carrier/ to get the enum values. A carrier is valid only when the in_use field for the carrier is true.
string
Required and valid only when shopping_ads_type is VIDEO and product_source is SHOWCASE or shopping_ads_type is LIVE. Identity ID.
array
Target zip/postal code IDs. Unless saved_audience_id supplies targeting, provide location_ids, zipcode_ids, or both; their combined location/zip/postal ID count cannot exceed 3,000. Get IDs as geo_id with geo_type=ZIP_CODE from /tool/targeting/search/; use /tool/targeting/info/ for details. ZIP codes support the US; postal codes support Canada, Brazil, Indonesia, Thailand, and Vietnam, with the latter four allowlist-only. Not supported with special_industries or objective_type=RF_REACH; placements must include PLACEMENT_TIKTOK. Locations cannot overlap (for example, US and California). After initially targeting the US, updates may change to other US locations but cannot remove all US locations and leave only non-US countries.
string
required
Ad group name. Length limit: 512 characters and cannot contain emoji.
array
List of audience IDs. You can get audience IDs by using the /dmp/custom_audience/list/ endpoint.
number
Bid price for the selected in-app event bidding strategy. Required when next_day_retention is specified.
array
Unless saved_audience_id supplies targeting, set location_ids, zipcode_ids, or both. IDs of the locations that you want to target. Max size: 3,000. If you provide both location_ids and zipcode_ids, the combined total of location IDs, zip code IDs, and postal code IDs cannot exceed 3,000 per ad group. To get the available locations and corresponding IDs based on your placement and objective, use the /tool/targeting/search/ or /tool/region/ endpoint. To get the list of location IDs, see Location IDs. Note: Overlapping targeted locations are not supported. For instance, you cannot target the U.S. and the state of California at the same time. If you target locations in the US via location_ids or zipcode_ids during ad group creation, you can subsequently update those IDs to other US locations but you cannot remove all US locations to target only non-US countries.
string
Required when messaging_app_type is WHATSAPP or ZALO. The WhatsApp or Zalo phone number. For WhatsApp, use the same WhatsApp phone number connected to the Messagement Management Tool (MMT). Note: Once set, this field cannot be updated.
string
required
Advertiser ID.
object
Rules that specify your audience, valid if objective_type is TRAFFIC or APP_PROMOTION. For details, see Audience Rules.
string
Required and valid only when app_promotion_type is APP_RETARGETING at the campaign level. Not supported when app_promotion_type is not set to APP_RETARGETING at the campaign level. App retargeting audience type. Enum value:NEW_CUSTOM_AUDIENCE (retargeting custom audience). If you want to specify an empty retargeting custom audience for your App Retargeting ads, do not pass audience_ids and excluded_audience_ids. If you want to specify a non-empty retargeting custom audience for your App Retargeting ads, you can specify an Include Audience via audience_ids, or an Exclude Audience via excluded_audience_ids , or both simultaneously. If both audience_ids and excluded_audience_ids are specified, they cannot contain the same IDs.
string
required
Events that you want to pay for. For enum values, see Enumeration - Billing Event. To learn about the billing event associated with a specific optimization goal, see Corresponding billing event for an optimization goal.
string ("VO_MIN_ROAS" | "VO_HIGHEST_VALUE")
Bidding strategy for in-app events. Required when Campaign Budget Optimization (CBO) is enabled (budget_optimize_on = true) and optimization_goal is VALUE. Enum values: VO_MIN_ROAS (allowlisted), VO_HIGHEST_VALUE (allowlisted). For details, see Enumeration - Deep Event Bidding Strategy. Note: When secondary_optimization_event is specified, you need to pass in deep_bid_type at the same time.
string ("AUTH_CODE" | "TT_USER" | "BC_AUTH_TT")
Required and valid only when shopping_ads_type is VIDEO and product_source is SHOWCASE or shopping_ads_type is LIVE. Identity type. Enum values: AUTH_CODE (Authorized Post User), TT_USER (TikTok Business Account User), BC_AUTH_TT(The TikTok account that a Business Center is authorized to access). See Identities for details.
array
Device connection types that you want to target. For enum values, see Enumeration - Connection Type.
string
required
The schedule type can be either SCHEDULE_START_END or SCHEDULE_FROM_NOW. If you choose SCHEDULE_START_END, you need to specify a start time and an end time. If you choose SCHEDULE_FROM_NOW, you only need to specify a start time and the end time will be automatically set to 10 years later than the start time.If budget_mode is BUDGET_MODE_TOTAL, this field must be set to SCHEDULE_START_END.
string ("PLACEMENT_TYPE_AUTOMATIC" | "PLACEMENT_TYPE_NORMAL")
The placement strategy that decides where your ads will be shown. Enum values: PLACEMENT_TYPE_AUTOMATIC: Automatic placement. TikTok’s ad system will use smart calculations to give you the best combination of ad placements across all apps.PLACEMENT_TYPE_NORMAL: Select placement. By selecting your placement manually, you’ll be able to choose the apps to deliver your ads on. Default value: PLACEMENT_TYPE_NORMAL. Note: placement_type cannot be updated after the ad group has been created.If you set this field to PLACEMENT_TYPE_AUTOMATIC, the actual supported placements will be shown in the returned placements. For instance, if the actual supported placement is TikTok only, the returned placements value will be PLACEMENT_TIKTOK.
string ("UNSET" | "CATALOG" | "STORE" | "SHOWCASE")
Required only for Video or Product Shopping Ads. Product source: UNSET, CATALOG (catalog), STORE (TikTok Shop), or SHOWCASE (TikTok Showcase). For Product Shopping Ads, use STORE. For Video Shopping Ads, campaign_product_source=CATALOG permits only CATALOG; campaign_product_source=STORE permits STORE or SHOWCASE. Without a campaign-level source, all ad groups in a campaign must use either only CATALOG or only the STORE/SHOWCASE family. If historical ad groups mix CATALOG with STORE or SHOWCASE, no new ad group can be created in that campaign.
string
Promotion type (Optimization location). You need to specify the field when advertising objective (objective_type) for your campaign is NOT set as REACH, VIDEO_VIEWS, or ENGAGEMENT. For enum values, see Enumeration - Promotion Type. Note: If objective_type is ENGAGEMENT at the campaign level, you can only use EXTERNAL_OR_DISPLAY in this field.
boolean
Whether to disable sharing of ads in this ad group to third-party platforms. Default value: false. The value trueis valid when the conditions below are all met:objective_type at the campaign level is set as one of the following objectives: APP_PROMOTION, WEB_CONVERSIONS, REACH, TRAFFIC, VIDEO_VIEWS, ENGAGEMENT, LEAD_GENERATION. Placement: placement_type= PLACEMENT_TYPE_AUTOMATIC orplacement_type= PLACEMENT_TYPE_NORMAL, and placements = PLACEMENT_TIKTOK
string ("ALL" | "HIGH")
Spending power that you want to target. Enum values: ALL, HIGH. If it is set to HIGH, you can target high spending users who typically spend more on purchases on TikTok ads than average users. Note:This field does not support the advertising objectives PRODUCT_SALES and RF_REACH at the campaign level. See Advertising objectives for details. This field supports Automatic Placement and Select Placement with TikTok included. Therefore, you need to set placement_type to PLACEMENT_TYPE_AUTOMATIC, or include PLACEMENT_TIKTOK in the value of placements. Note that if you specify Pangle as a placement, the spending power targeting won’t take effect on Pangle. When auto_targeting_enabled is true at the ad group level, then spending_power will be automatically set to ALL.
string
Conversion bid statistic type, bid for EVERYTIME (Each Purchase)/ NONE (Unique Purchase). You can get statistic_type values suitable for your app event by using the /app/optimization_event/ endpoint.
string ("UNSET" | "IOS14_MINUS" | "IOS14_PLUS" | "ALL")
iOS targeting: UNSET targets iOS 14.4 or earlier; IOS14_MINUS targets before 14.0; IOS14_PLUS targets 14.5+ in Dedicated Campaigns; ALL targets 14.5+ only for iOS App Retargeting or catalog Video Shopping retargeting optimized to app. campaign_type=IOS14_CAMPAIGN requires IOS14_PLUS and allows at most two active ad groups. For IOS14_PLUS, use an iOS app_id, operating_systems=["IOS"], compatible min_ios_version, and optimization_goal in CLICK, INSTALL, IN_APP_EVENT, VALUE; omit min_android_version, shopping_ads_retargeting_type, and shopping_ads_retargeting_actions_days, and do not use ad-level deeplink_type=DEFERRED_DEEPLINK. Once IOS14_PLUS, it cannot change. App Retargeting 14.5+ requires ALL and min_ios_version>=14.5; omit this field for 14.4 or earlier. ALL is forced for iOS App Retargeting (APP_RETARGETING + APP_IOS) and iOS catalog Video Shopping app retargeting (VIDEO, CATALOG, APP_IOS, retargeting not OFF). Otherwise defaults to UNSET.
string
Required when ios14_targeting is specified. Minimum iOS version. For enum values, see Enumeration - Minimum iOS Version.
array
Required for Search Ads Campaigns (is_search_campaign is true at the campaign level).Not supported for non-Search Ads Campaigns (is_search_campaign is false at the campaign level). A list of search keywords, that is, words or phrases that are used to match your ads with the terms people are searching for. Max size: 1,000. To confirm whether a campaign is a Search Ads Campaign, call /campaign/get/ and check the is_search_campaign returned for the campaign. To learn more about Search Ads Campaigns, see Create Search Ads Campaigns. Note: For each ad group, you can configure a maximum of 1,000 search keywords.
string
Required and must be set to CPV(Cost per One View) when objective_type is VIDEO_VIEW. How you calculate and measure Cost per View. Note:bid_display_mode cannot be updated after creation. You don’t need to specify this field if your objective_type is not VIDEO_VIEW. The enum value of CPMV is deprecated in v1.3.
boolean
Whether to allow comments on your ads on TikTok.
array
IDs of the device models that you want to target. Use /tool/device_model/ to get the complete list of device model IDs and their statuses, and only active devices (is_active = True in the response of /tool/device_model/) can be used to create ads. Note: Device model (device_model_ids) and device price (device_price_ranges) cannot be set at the same time.
array
Household income that you want to target. Enum values: TOP5(Top 5% of ZIP codes), TOP10(Top 10% of ZIP codes), TOP10_25(Top 10% -25% of ZIP codes), TOP25_50(Top 25% - 50% of ZIP codes). Note: It only supports the ad objectives for Auction ads. See Advertising objectives for details. It is only applicable to the TikTok Placement in the US.
string ("ENABLE" | "DISABLE")
The status of the ad group when created. DISABLE is the safe default so the new ad group does not start delivery or spend. Pass ENABLE explicitly to make it eligible for delivery. To update its status after creation, use /adgroup/status/update/.
string ("NO_BRAND_SAFETY" | "EXPANDED_INVENTORY" | "STANDARD_INVENTORY" | "LIMITED_INVENTORY" | "THIRD_PARTY")
Brand safety type, valid only with placements=["PLACEMENT_TIKTOK"]; default NO_BRAND_SAFETY. NO_BRAND_SAFETY: full inventory, including possible mature themes; deprecated next version. EXPANDED_INVENTORY: most inappropriate and mature content removed; replaces NO_BRAND_SAFETY next version. STANDARD_INVENTORY: content appropriate for most brands. LIMITED_INVENTORY: no mature themes. THIRD_PARTY: third-party filtering and requires brand_safety_partner. Use /tool/region/ for eligible regions. First-party filtering for Auction APP_PROMOTION, WEB_CONVERSIONS, TRAFFIC, LEAD_GENERATION, and PRODUCT_SALES, and all third-party filtering, are allowlist-only.
string
The time frame when you would like a conversion to happen after a user clicks on or views your ad. Your ad delivery will be optimized using the conversion data during the time frame you select. This setting will not impact your attribution data. Currently, this field is available only when your promotion product is an app. If no value is specified for this field, the default values will be used. For different optimize goals, the default values are different. If the optimize goal(optimization_goal) is INSTALL, the default value is ONE_DAY_CLICK_OR_ONE_DAY_VIEW. If the optimize goal(optimization_goal) is IN_APP_EVENT, the default value is SEVEN_DAY_CLICK_OR_ONE_DAY_VIEW. For enum values, see Enumeration - Conversion Window.
boolean
Whether the promoted content complies with LHF (Less Healthy Foods) regulations. By setting is_lhf_compliance to true, you confirm that any food or drink products you advertise on TikTok in the UK comply with the 2024 Less Healthy Foods Regulations and all other applicable laws. Supported values: true,false. Default value: false. Note: Starting January 1st, 2026, when your ad targets locations in the UK and is_hfss is true, is_lhf_compliance is required and must be set to true.
array
Device operating systems that you want to target. Only one value is allowed. Enum values: ANDROID, IOS. This field is required in two scenarios: objective_type is APP_PROMOTION``objective_type is TRAFFIC and promotion_type is APP_IOS or APP_ANDROID
string
required
Optimization goal; specify its corresponding billing_event. For Install with in-app event, use INSTALL plus a valid secondary_optimization_event, with normal placement containing only PLACEMENT_PANGLE, PLACEMENT_GLOBAL_APP_BUNDLE, or both. Since November 30, 2024, new/copied APP_PROMOTION ad groups cannot use Install with in-app event on PLACEMENT_TIKTOK or automatic placement; existing groups are unaffected. For LEAD_GEN_CLICK_TO_TT_DIRECT_MESSAGE, LEAD_GEN_CLICK_TO_SOCIAL_MEDIA_APP_MESSAGE, or LEAD_GEN_CLICK_TO_CALL, default is CLICK. VIDEO_VIEW is no longer valid; for campaign objective_type=VIDEO_VIEWS, use ENGAGED_VIEW or ENGAGED_VIEW_FIFTEEN. New ad groups in one CBO campaign must match the first ad group’s goal. Consult Optimization Goal enumerations for valid values and CBO compatibility.
string
Required when messaging_app_type is WHATSAPP or ZALO. The region code for the WhatsApp or Zalo phone number. Example: US. To obtain the region code (phone_region_code) and region calling code (phone_region_calling_code) for the region that is associated with a specific phone number, use /tool/phone_region_code/. Note: Once set, this field cannot be updated.
string
Saved Audience ID from /dmp/saved_audience/create/. Valid only when the campaign has no Housing, Employment, or Credit specical_industries, objective_type is not PRODUCT_SALES, TikTok placement is selected, and auto_targeting_enabled is not true. The Saved Audience and ad group must have the same advertiser ID. Do not also pass targeting options already contained in the Saved Audience. Its device settings must not conflict with the ad group, such as Android versus ios14_targeting=IOS14_PLUS, or iOS versus an Android app. Use /dmp/saved_audience/list/ to diagnose targeting conflicts. Any saved age_groups must satisfy current age restrictions.
string
Required when schedule_type is SCHEDULE_START_END or budget_mode is BUDGET_MODE_TOTAL. Schedule end time (UTC+0), in the format of "YYYY-MM-DD HH:MM:SS". The end time cannot be later than "2038-01-01 00:00:00".
string ("VIDEO" | "LIVE" | "PRODUCT_SHOPPING_ADS")
Required and valid only when objective_type is PRODUCT_SALES. Shopping ads type. Enum values: VIDEO: Video Shopping Ads.LIVE: Live Shopping Ads.PRODUCT_SHOPPING_ADS: Product Shopping Ads. To find out the introduction to different Shopping Ads types and the steps of creating Video Shopping Ads, Live Shopping Ads, and Product Shopping Ads, see Create Shopping Ads.
array
Contextual tag IDs. You can use /tool/contextual_tag/get/ to get available contextual tags. See Contextual targeting to learn more about how to use contextual targeting. Note: This is an allowlist-only feature. If you would like to access it, please contact your TikTok representative.Only supports REACH and VIDEO_VIEWS as objectives (objective_type) at the campaign level. Not supported when brand_safety_type is set to THIRD_PARTY.
integer
Frequency schedule, together with frequency, controls how often people see your ad (only available for REACH ads). See frequency fields for more.
string ("MESSENGER" | "WHATSAPP" | "ZALO" | "LINE" | "IM_URL")
Valid only when promotion_type=LEAD_GEN_CLICK_TO_SOCIAL_MEDIA_APP_MESSAGE; required for optimization_goal=CONVERSATION, where ZALO, LINE, and IM_URL are not allowed. For optimization_goal=CLICK, defaults to IM_URL. Values: MESSENGER requires a Facebook Page ID in messaging_app_account_id; LINE requires a LINE Business ID there; WHATSAPP or ZALO requires phone_region_code, phone_region_calling_code, and phone_number; IM_URL uses a custom instant-messaging URL. Once set, this field cannot be updated.
number
Valid only when placements is PLACEMENT_PANGLE and secondary_optimization_event is NEXT_DAY_OPEN. Day 2 retention ratio. Formula: next_day_retention = conversion_bid_price/deep_cpa_bid. Value range: (0,1]. Note: If you want to use this field, please pass in conversion_bid_price, deep_cpa_bid, and next_day_retention at the same time, and make sure the value of them meets the calculation formula. Otherwise there might be unexpected errors.
string
Required in any of the following scenarios:pixel_id is specified.pixel_id is not specified and optimization_goal is IN_APP_EVENT or VALUE. Conversion event. For the supported app and pixel events, see Conversion events. To find out the supported events for your app, use /app/optimization_event/. NoteFor new ad groups created under one CBO campaign, this field should be the same as the first ad group.When optimization_goal is PAGE_VISIT, optimization_event will be automatically set as PAGE_VISIT.
array
Targeting device price range. 10000 means 1000+. The numbers must be in multiples of 50. Important: The upper limit you set will be added by 50 and the resulting new number will be used as the actual upper limit for device targeting. The actual upper limit is shown in the ad group settings in TikTok Ads Manager. If you set and get the price range of [0, 250], it actually means [0, 300].
string
Minimum device Android version. For enum values, see Enumeration - Minimum Android Version.
string
required
Schedule start time (UTC+0), in the format of "YYYY-MM-DD HH:MM:SS". The start time can be up to 12 hours earlier than the current time, but cannot be later than "2028-01-01 00:00:00".
object
Settings about targeting expansion. Note: Starting June, 2024, you can no longer enable Automatic targeting or Targeting expansion for your ad groups. To ensure a smooth API integration, we recommend you migrate to Smart Targeting.
string ("IAS" | "OPEN_SLATE")
Required only when brand_safety_type is THIRD_PARTY, and placements needs to be set to &#91;"PLACEMENT_TIKTOK"&#93;. Brand safety partner. Enum values: IAS, OPEN_SLATE(The partner is named DoubleVerify on TikTok Ads Manager because the partner has been acquired by DoubleVerify). To get the countries and regions that your ads can be deployed to based on your brand safety settings, use the /tool/region/ endpoint. You need to pass in the brand safety type and brand safety partner. Note: Pre-bid third-party brand safety solutions are currently allowlist-only features. If you would like to access them, please contact your TikTok representative. Once set, this field cannot be modified.
number
Required when bid_type is BID_TYPE_CUSTOM and billing_event is OCPM. Where you can set a target cost per conversion for oCPM(Optimized Cost per Mille). conversion_bid_price needs to be lower than budget set at the campaign level and ad group level. See Bidding-Bidding limits to learn more about the bid verification mechanism.
string
The ID of the Custom Conversion to use in the ad group. Valid only when the following conditions are all met:Either pixel_id or app_id is specified.A Custom Conversion has been configured for the pixel_id or app_id.The optimization_goal is set to CONVERT or IN_APP_EVENT.The parameter optimization_event is specified and matches the Standard Event associated with the Custom Conversion.The status of the Custom Conversion is Active or No recent activity. To obtain the list of Custom Conversions associated with a Pixel or an App, use /custom_conversion/list/. To confirm the eligibility of the Custom Conversion for ad group creation:Ensure the returned optimization_event matches the optimization_event specified during ad group creation.Ensure the activity_status is NO_RECENT_ACTIVITY or ACTIVE.
array
IDs of additional interest categories that you want to use to target audience. To search for additional interest categories, use /targeting/search/ (recommended) or /tool/interest_keyword/recommend/.
string
Message event set ID. Required when promotion_type=LEAD_GEN_CLICK_TO_SOCIAL_MEDIA_APP_MESSAGE, optimization_goal=CONVERSATION, and the selected Messenger or WhatsApp account matches no existing event set. Call /ctm/message_event_set/get/: if matched_event_set exists, this field is ignored and auto-filled with that unique set; if empty, choose an ID from message_event_set_list. Messenger is identified by messaging_app_account_id; WhatsApp by phone_region_code, phone_region_calling_code, and phone_number. Once set, it cannot be updated.
array
TikTok subplacements; valid only for campaign objective_type REACH, VIDEO_VIEWS, or ENGAGEMENT, with placement_type=PLACEMENT_TYPE_NORMAL and placements=["PLACEMENT_TIKTOK"]. Values: IN_FEED, SEARCH_FEED, TIKTOK_LITE, LEMON8. If provided, include IN_FEED. LEMON8 requires REACH; TIKTOK_LITE requires Japan or South Korea in location_ids. SEARCH_FEED, TIKTOK_LITE, and Auction Reach LEMON8 are allowlist-only and cannot use brand_safety_type=THIRD_PARTY. Reach with LEMON8 cannot specify contextual_tag_ids. TIKTOK_LITE cannot be used for creation or copying after July 19, 2025; if already used, Japan and South Korea cannot both be removed. Once set, this field cannot be updated. Interactive add-ons: SEARCH_FEED supports only Display Card; TIKTOK_LITE supports only Display Card, Countdown Sticker, and Gift Code Sticker, subject to objective compatibility.
array
List of audience ID to be excluded. You can get audience IDs by using the /dmp/custom_audience/list/ endpoint.
array
IDs of general interest categories that you want to use to target audiences. To search for or list general interest category IDs, use /targeting/search/ (recommended) or /tool/interest_category/.To get recommended interest category IDs based on your industry, use /tool/targeting_category/recommend/.
string ("INSTANT_PAGE" | "EXTERNAL_WEBSITE")
Valid when objective_type at the campaign level is LEAD_GENERATION. The promotion type for Lead Generation objective. You can find out how to create lead generation ads in Lead Generation Ads. Enum values: INSTANT_PAGE:Instant Form. To create a fast-loading in-app TikTok Instant Form to collect more leads. EXTERNAL_WEBSITE:Website Form. To use a landing page that has the Website Form or the TikTok Instant Page that redirects to the website with the Website Form to collect more leads. Once this field is set to EXTERNAL_WEBSITE and optimization_goal is CLICK, do not pass pixel_id and optimization_event.
boolean
Whether to enable Automatic Search Placement. For APP_PROMOTION, WEB_CONVERSIONS, TRAFFIC, or LEAD_GENERATION with automatic placement, or normal placement including PLACEMENT_TIKTOK, it defaults to true; omit/set true to enable or set false to disable. It is forced to false and cannot be true for Search Ads campaigns (is_search_campaign=true) with WEB_CONVERSIONS, TRAFFIC, or LEAD_GENERATION; for other objectives; or for normal placement without PLACEMENT_TIKTOK.
boolean
Whether to enable automated targeting. Note: Starting June, 2024, you can no longer enable Automatic targeting or Targeting expansion for your ad groups. To ensure a smooth API integration, we recommend you migrate to Smart Targeting.
array
Pangle app block list ID. You can get an ID via the app_package_id field returned by Get Pangle block list. It only takes effect when Pangle placement is selected.
array
Valid only when the following conditions are met: At the campaign level: objective_type is REACH, VIDEO_VIEWS, ENGAGEMENT, RF_REACH, APP_PROMOTION,WEB_CONVERSIONS,TRAFFIC, or LEAD_GENERATION. At the ad group level: placements is set to &#91;"PLACEMENT_TIKTOK"&#93;. brand_safety_type is set to STANDARD_INVENTORY or LIMITED_INVENTORY.Content exclusion category IDs. You can use /tool/content_exclusion/get/ to get a list of content category IDs (excluded_category_list) that can be excluded from being displayed next to your ads.
string
The strategy that your creatives will be delivered. Enum values: CUSTOM (custom). Default value: CUSTOM (custom). Note: Automated ads (creative_material_mode = DYNAMIC) have been deprecated. We recommend that you create Smart Creative ads ( creative_material_mode = CUSTOM) to ensure a smoother migration journey. See here to find out how to create Smart Creative ads.
string ("UNSET" | "TIKTOK_NATIVE_PAGE")
TikTok Instant Page type in the ad group. Enum values:UNSET: To not use TikTok Instant Page. TIKTOK_NATIVE_PAGE: To use TikTok Instant Page. If this field is set to TIKTOK_NATIVE_PAGE at the ad group level, pixel_id is not supported and you need to specify a TikTok Instant Page through page_id at the ad level.To learn about how to create App Pre-registration ads, refer to here. Note: When app_promotion_type at the campaign level is APP_PREREGISTRATION, this field is required.
boolean
Whether to turn on Smart audience. Supported values: true, false. To learn more about Smart audience and how to turn on Smart audience, see Smart Targeting.
string
Required when store_id is passed. ID of the Business Center that is authorized to access the store (store_id).
string ("UNSET" | "EVERY" | "ONCE")
Event count (Statistic type) for the ad group. The way that people’s actions are counted after only viewing or clicking an ad. Enum values: UNSET: Unset. EVERY: Every. To count multiple events from someone as separate conversions. ONCE: Once. To count multiple events from someone as 1 conversion. To learn about the allowed values of this field for different advertising objective scenarios, refer to Attribution window and event count. Note: If you don’t manually pass click_attribution_window, engaged_view_attribution_window, view_attribution_window and attribution_event_count, then default settings, if any, will be used. To confirm whether a default setting is used when you don’t manually pass this field, use /adgroup/get/. Once set, this field cannot be updated.
array
When shopping_ads_retargeting_type is LAB3, you need to pass in either included_custom_actions or excluded_custom_actions. The custom action that you want to use as “Exclude” conditions for filtering out the shopping ads audiences to be retargeted.
array
When shopping_ads_retargeting_type is LAB3, you need to pass in either included_custom_actions or excluded_custom_actions. The custom action that you want to use as “Include” conditions for filtering out the shopping ads audiences to be retargeted.
string
Valid only when the following conditions are met: At the campaign level: objective_type is REACH, VIDEO_VIEWS or ENGAGEMENT. At the ad group level:placements is set to &#91;"PLACEMENT_TIKTOK"&#93;.brand_safety_type is set to STANDARD_INVENTORY or LIMITED_INVENTORY. Vertical sensitivity category ID. You can use /tool/content_exclusion/get/ to get a list of vertical categories containing sensitive content (vertical_sensitivity_list) that can be excluded from appearing next to your ads.
boolean
Whether users can download your video ads on TikTok(cannot be updated once created).
string ("OFF" | "ONE_DAY" | "SEVEN_DAYS")
View-through attribution window: OFF, ONE_DAY, or SEVEN_DAYS; allowed values vary by objective. Manual configuration requires both view_attribution_window and click_attribution_window; optional engaged_view_attribution_window also requires both. If all attribution-window fields and attribution_event_count are omitted, provider defaults may apply; inspect /adgroup/get/. Once set, this field cannot be updated.
string
Required when shopping_ads_type is VIDEO and product_source is CATALOG or STORE. Optional when shopping_ads_type is LIVE. Not supported when shopping_ads_type is PRODUCT_SHOPPING_ADS and product_source is STORE. ID of the Business Center that has permission for the catalog. For catalogs in Business Center, you must specify the ID of the Business Center that a catalog belongs to. Note: Starting June 30th, 2024, when product_source is STORE, you will no longer need to pass catalog_authorized_bc_id because it will be ignored.
string ("OFF" | "ONE_DAY" | "SEVEN_DAYS" | "FOURTEEN_DAYS" | "TWENTY_EIGHT_DAYS")
Click-through attribution window: OFF, ONE_DAY, SEVEN_DAYS, FOURTEEN_DAYS, or TWENTY_EIGHT_DAYS; allowed values vary by objective. Manual configuration requires both click_attribution_window and view_attribution_window; engaged_view_attribution_window is optional but also requires both. If all attribution-window fields and attribution_event_count are omitted, provider defaults may apply; inspect /adgroup/get/. Once set, this field cannot be updated.
string ("PIXEL" | "OFFLINE" | "CRM")
Required when deep_funnel_optimization_status is ON. The event source type. Enum values: PIXEL: Pixel. OFFLINE: Offline Event Set.CRM: CRM Event Set.
string
Required when messaging_app_type is MESSENGER or LINE.Ignored when messaging_app_type is WHATSAPP, ZALO, or IM_URL. The ID of the instant messaging app account. When messaging_app_type is MESSENGER, specify the Facebook Page ID via this field.To find your Facebook Page ID, go to your Facebook Page and click About below your cover photo, then click Page transparency.When messaging_app_type is LINE, specify the LINE Business ID via this field.To find your LINE Business ID, go to your LINE official account page.When messaging_app_type is WHATSAPP, this field will be ignored and be set as the corresponding WhatsApp phone number automatically populated based on the specified phone_region_code, phone_region_calling_code, and phone_number. Note: Once set, this field cannot be updated.
string
Required when identity_type is BC_AUTH_TT. ID of the Business Center that a TikTok Account User in Business Center identity is associated with.
string
Required when messaging_app_type is WHATSAPP or ZALO. The region calling code for the WhatsApp or Zalo phone number. Example: +1. To obtain the region code (phone_region_code) and region calling code (phone_region_calling_code) for the region that is associated with a specific phone number, use /tool/phone_region_code/. Note: Once set, this field cannot be updated.
boolean
Valid only when at the campaign level is_search_campaign is true. Whether to enable automated keywords and let the system automatically generate keywords after you add ads. This expands high-quality traffic to improve performance. View high-performing automated keywords in reporting. Supported values: true, false. Default value: false. Note: Automated keywords in Search Ads Campaigns are currently an allowlist-only feature. If you would like to access it, please contact your TikTok representative.
string
Required when deep_funnel_optimization_status is ON. Event Source ID. When deep_funnel_event_source is PIXEL, specify a Pixel ID via this field. To obtain a list of Pixels, use /pixel/list/.When deep_funnel_event_source is OFFLINE, specify an Offline Event Set ID via this field. To obtain a list of Offline Event Set IDs, use /offline/get/. When deep_funnel_event_source is CRM, specify a CRM Event Set ID via this field. To obtain a list of CRM Event Set IDs, use /crm/list/.
string
Secondary goal for optimization_goal=INSTALL or VALUE; see Secondary-goal events for valid values. When specified, also pass deep_bid_type. Since November 30, 2024, new/copied APP_PROMOTION ad groups cannot use INSTALL plus a secondary event on TikTok-only or automatic placement. Normal placement containing only PLACEMENT_PANGLE, PLACEMENT_GLOBAL_APP_BUNDLE, or both remains supported; existing TikTok ad groups are unaffected.
string ("LAB1" | "LAB2" | "LAB3" | "OFF")
Required when shopping_ads_type is VIDEO and product_source is CATALOG. The retargeting type of shopping ads. Enum values: LAB1: Retargeting audiences who viewed products or added products to cart but didn’t purchase products. LAB2: Retargeting audiences who added products to cart but didn’t purchase products. LAB3: Retargeting audiences using custom combination. OFF: No retargeting.
string ("ON" | "OFF")
Whether to use App Profile Page or not. Enum values: ON, OFF. Note: App Profile Page is not supported in a Dedicated Campaign with optimization goal as in-app event and bid strategy as cost cap. Therefore, you cannot set this field to ON when the following conditions are all met:ios14_targeting is set to IOS14_PLUS``optimization_goal is set to IN_APP_EVENT``bid_type is set to BID_TYPE_CUSTOM
string
Required when deep_funnel_optimization_status is ON. Deep funnel optimization event. To find out the supported values for Standard Events available for Pixels, Offline Event Sets, and CRM Event Sets, see the “Event name for ad creation” column in Supported Pixel events. To find the list of optimization events for a Pixel, use /pixel/list/ and check the returned optimization_event. Example: SHOPPING.
array
IDs of purchase intention categories that you want to use to target audiences with an interest in purchases related to a content category. To search for or list purchase intention category IDs, use /targeting/search/. Note:Do not pass in purchase_intention_keyword_ids and interest_keyword_ids at the same time. Otherwise, keyword conflict will occur.purchase_intention_keyword_ids only supports Auction ads with theobjective_type as APP_PROMOTION,WEB_CONVERSIONS,LEAD_GENERATION, TRAFFIC, or PRODUCT_SALES with product_source as CATALOG, and the placement setting should include TikTok (PLACEMENT_TIKTOK) or Pangle (PLACEMENT_PANGLE).
string ("ON" | "OFF")
Valid only when promotion_type is LEAD_GENERATION. The status of deep funnel optimization. Deep funnel optimization optimizes both your upper funnel events and deeper funnel events. You can select a secondary event alongside the primary optimization event, which can help improve campaign effectiveness. Enum values: ON: To enable deep funnel optimization. OFF: To disable deep funnel optimization. Default value: OFF. To learn about how to configure deep funnel optimization for Lead Generation ads, see Lead Generation ad with optimization location as Instant Form and Lead Generation ad with optimization location as Website. Note: Deep funnel optimization with CRM events is currently an allowlist-only feature. If you would like to access it, please contact your TikTok representative. Deep funnel optimization with Pixel or Offline events is generally available.
string ("ONE_DAY" | "SEVEN_DAYS")
Attribution window after at least six seconds of video viewing: ONE_DAY or SEVEN_DAYS; allowed values vary by objective. If provided, also pass click_attribution_window and view_attribution_window. If all attribution-window fields and attribution_event_count are omitted, provider defaults may apply; inspect /adgroup/get/. Once set, this field cannot be updated.
boolean
Whether to turn on Smart interests & behaviors. Supported values: true, false. To learn more about Smart interests & behaviors and how to turn on Smart interests & behaviors, see Smart Targeting.
array
Valid only for Pangle placement. Do not specify this field and included_pangle_audience_package_ids at the same time. IDs of the Pangle audiences that you want to exclude. You can get audience IDs (package_id) by using the /pangle_audience_package/get/ endpoint. The bind_type for the package should be EXCLUDE.
array
Valid only for Pangle placement. Do not specify this field and excluded_pangle_audience_package_ids at the same time. IDs of the Pangle audiences that you want to include. You can get audience IDs (package_id) by using the /pangle_audience_package/get/ endpoint. The bind_type for the package should be INCLUDE.
integer
Required when shopping_ads_retargeting_type is LAB1 or LAB2. The valid time range for the specified audience action. Audiences who have completed the specified action within the time range will be retargeted by the shopping ads. Value range: 1, 2, 3, 7, 14, 30, 60, 90, 180.
string ("OR" | "AND")
Logical relation between the Video Shopping Ads retargeting audience and custom audience_ids. Valid only with shopping_ads_type=VIDEO, product_source=CATALOG, shopping_ads_retargeting_type in LAB1, LAB2, or LAB3, and provided audience_ids. OR targets members of either audience; AND targets members of both. Omission also uses intersection (AND). Once set, it cannot be manually reset to null.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_ADGROUP_RFCreate an R&F ad group. Availability may depend on TikTok allowlisting or account entitlement.

Input Parameters

string
ID of the promoted mobile application.
number
Budget. Required only when rf_purchased_type is FIXED_BUDGET. Use the value returned by the ad inventory estimate API.
string
Audience gender. For more details, see Enumeration - Audience Gender.
boolean
Whether the promoted content is HFSS foods (foods that are high in fat, salt, or sugar). Please note that the European market prohibits the promotion of HFSS foods to underage users.
string ("STANDARD_FEED" | "TOP_FEED")
Feed type option. Enum values: STANDARD_FEED, TOP_FEED. STANDARD_FEED refers to large inventory with normal CPM price while TOP_FEEDrefers to limited inventory with higher CPM price.
integer
required
frequency, together with frequency_schedule, controls how often people see your ad (only available for REACH ads). For example, frequency = 2 & frequency_schedule = 3 means “show ads no more than twice every 3 days”. The following conditions should be met:1 ≤ frequency ≤ frequency_schedule.1 ≤ frequency_schedule ≤ min (schedule_end_time - schedule_start_time, 30).The frequency cap determined by frequency and frequency_schedule does not exceed four times a day.
array
Codes of the languages that you want to target. For the list of languages codes supported, see Enumeration - Language Code.
array
Age groups you want to target. If your targeting locations include Israel or Brazil, AGE_13_17 cannot be used. For enum values, see Enumeration - Age Group. In certain scenarios, creation of ad groups that target the age group 13-17 (AGE_13_17) in the US will not be allowed. See New age restrictions for ads on TikTok to learn more. If you use targeting options that are not supported for the age group 13-17 in the US and leave the age_groups field unspecified or set it as [], an error will occur. You need to explicitly specify the exact age groups that you want to target, such as AGE_18_24, in the field to avoid any errors.
string
required
Request ID with which you can create ad groups with duplicate names. It also supports idempotency to prevent you from sending the same request twice. It is different from the request_id returned in the response parameters, which is used to uniquely identify an HTTP request. The value should be a string representation of a 64-bit integer number. Example: "123456789"
string
required
The campaign the ad group belongs to.
array
Carriers that you want to target. A carrier is valid only when the in_use field for the carrier is true. The carriers must be consistent with the location(s) that you want to target. Use Get Carriers to get carrier IDs.
string
required
Name of the ad group. It must not exceed 100 characters or contain any emojis.
array
IDs of the audiences that you want to target. For an audience to be targeted or excluded in R&F ads, you must set audience_sub_type to REACH_FREQUENCY when creating or updating the audience. Note: You cannot use Lookalike Audience in R&F ads. Otherwise, an error will occur.
array
required
IDs of the targeted locations. The location can be at the country or region level, the Province, DMA (Designated Market Area) or Metropolitan level, or the city level. Location targeting supports a single country or region only. If you want to target multiple locations, they must from the same country or region. You can find the supported countries and regions in About Reach & Frequency.
string
required
Advertiser ID.
string ("STANDARD" | "SCHEDULE" | "SEQUENCE" | "VIEW_OPTIMIZE" | "OPTIMIZE")
Ad delivery strategy. STANDARD: even delivery; unavailable for View+ (optimization_goal=REACH, cpv_video_duration=SIX_SECONDS). SCHEDULE: delivery in specified periods and requires schedules. SEQUENCE: specified ad order and requires expected_orders. VIEW_OPTIMIZE: maximize view-through rate and available only for View+. OPTIMIZE: deprecated optimized delivery.
array
Device connection types that you want to target. Default value: unlimited. For enum values, see Enumeration - Connection Type.
string ("APP_ANDROID" | "APP_IOS" | "WEBSITE" | "WEBSITE_OR_DISPLAY")
required
Promotion type and you can decide where you’d like to promote your products using this field. Enum values: APP_ANDROID, APP_IOS, WEBSITE, WEBSITE_OR_DISPLAY. If objective_type is RF_REACH, set this field to WEBSITE_OR_DISPLAY.
array
Ad delivery information. When delivery_mode is set to SEQUENCE, the number of objects in this array represents the number of ads that you will specify the sequence for.
boolean
Whether sharing to third-party platforms is disabled for ads in this ad group. Default value: False.
integer
Purchased user reach, in units of 1,000. Required only when rf_purchased_type is FIXED_REACH. Use the value returned by the ad inventory estimate API.
boolean
Whether to prohibit users from commenting on your ads on TikTok. Default value: False.
array
IDs of the device models that you want to target. Currently only brand-level model IDs are supported. When this field is specified, device_price_ranges must not be specified. For enum values of device model IDs on different levels, please see Device Models. Note: Only active devices (is_active = True in the response of /tool/device_model/) can be used to create ads.
string ("NO_BRAND_SAFETY" | "EXPANDED_INVENTORY" | "STANDARD_INVENTORY" | "LIMITED_INVENTORY" | "THIRD_PARTY")
R&F brand safety type; default NO_BRAND_SAFETY. NO_BRAND_SAFETY: full inventory, possibly beside mature themes. EXPANDED_INVENTORY: most inappropriate and mature content removed; replaces NO_BRAND_SAFETY as the next-version default. STANDARD_INVENTORY: content appropriate for most brands. LIMITED_INVENTORY: no mature themes. THIRD_PARTY: third-party filtering and requires brand_safety_partner; this option is allowlist-only. Use /tool/region/ for eligible regions.
array
Device operating systems that you want to target. Enum values: ANDROID, IOS, PC.
string ("REACH" | "VIDEO_VIEW" | "CLICK" | "POST_ENGAGEMENT" | "INSTALL")
required
The measurable results you’d like to drive with your ads. It must be aligned with the value for objective_type on the campaign level. Enum values: REACH, VIDEO_VIEW, CLICK, POST_ENGAGEMENT, INSTALL. Note:For TikTok Pulse ad groups where rf_campaign_type is set to PULSE in /campaign/create/ at the campaign level, if you want to use the 6s view-through rate (View+) optimization goal, set optimization_goal to REACH and cpv_video_duration to SIX_SECONDS.The 6s view-through rate (View+) optimization goal in TikTok Pulse ad groups is currently an allowlist-only feature. If you would like to access it, please contact your TikTok representative.
string ("FIXED_SHOW" | "FIXED_REACH" | "FIXED_BUDGET")
required
Buying type. Allowed values: FIXED_SHOW: Purchase to achieve a fixed amount of impressions.FIXED_REACH: Purchase to reach a fixed number of users.FIXED_BUDGET: Purchase with a fixed budget.
string
required
Schedule end time (UTC+0), in the format of YYYY-MM-DD HH:MM:SS. The time interval between schedule_start_time and schedule_end_time must not exceed 90 days. The value of this field must be at YYYY-MM-DD HH:59:59 for the time zone where the ad will be delivered. For instance, if an advertiser in the UTC-5 time zone wants to create an R&F ad group that ends delivery on November 10th, 2023, this field must be set to "2023-11-10 04:59:59".
array
Contextual tag IDs from /tool/contextual_tag/get/. Not supported with brand_safety_type=THIRD_PARTY or feed_type=TOP_FEED. rf_campaign_type=PULSE requires at least one PREMIUM tag. Max Pulse supports AE, AU, BR, CA, DE, ES, FR, GB, IT, MX, SA, TR, US; Category Lineups support US, CA, BR, AU, GB, FR, IT, ES, DE. Both are allowlist-only.
string
Required when optimization_goal is VIDEO_VIEW or when you want to use the 6s view-through rate (View+) optimization goal. The target video view duration. Enum value: SIX_SECONDS. Note: For TikTok Pulse campaigns where rf_campaign_type is set to PULSE in /campaign/create/ at the campaign level, if you want to use the 6s view-through rate (View+) optimization goal, set optimization_goal to REACH and cpv_video_duration to SIX_SECONDS.
integer
required
frequency_schedule, together with frequency, controls how often people see your ad (only available for REACH ads). See frequency field for more.
string
Conversion event for the ad group. It is required when the promoted object is an App with tracking urls. For the supported app events, see Conversion events. You can use the /app/external_action/ endpoint to find out the supported events for your app.
array
Targeting device price range. 10000 means 1000+. The numbers must be in multiples of 50. Important: The upper limit you set will be added by 50 and the resulting new number will be used as the actual upper limit for device targeting. The actual upper limit is shown in the ad group settings in TikTok Ads Manager. If you set and get the price range of [0, 250], it actually means [0, 300].
string
required
Schedule start time (UTC+0), in the format of YYYY-MM-DD HH:MM:SS. The time interval between schedule_start_time and schedule_end_time must not exceed 90 days. The value of this field must be at YYYY-MM-DD HH:00:00 for the time zone where the ad will be delivered. For instance, if an advertiser in the UTC-5 time zone wants to create an R&F ad group that starts delivery on November 1st, 2023, this field must be set to "2023-11-01 05:00:00".
string ("IAS" | "OPEN_SLATE")
Brand safety partner for Reach and Frequency ads. Required when brand_safety_type is THIRD_PARTY. Enum values: IAS, OPEN_SLATE(The partner is named DoubleVerify on TikTok Ads Manager because the partner has been acquired by DoubleVerify). Note: Pre-bid third-party brand safety solutions are currently allowlist-only features. If you would like to access them, please contact your TikTok representative. Once set, this field cannot be modified.
integer
Impressions to be purchased, in units of 1,000. Required only when rf_purchased_type is FIXED_SHOW. Use the value returned by the ad inventory estimate API.
array
IDs of the audiences that you want to exclude. For an audience to be targeted or excluded in R&F ads, you must set audience_sub_type to REACH_FREQUENCY when creating or updating the audience. Note: You cannot use Lookalike Audience in R&F ads. Otherwise, an error will occur.
array
List of interest categories that you want to target. Use /tool/interest_category/ endpoint to get the complete list of interest categories.
array
Valid when brand_safety_type is set to STANDARD_INVENTORY or LIMITED_INVENTORY. Content exclusion category IDs. You can use /tool/content_exclusion/get/ to get a list of content category IDs (excluded_category_list) that can be excluded from being displayed next to your ads.
boolean
Whether users can download your video ads on TikTok(cannot be updated once created). Default value: false.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_APPCreate a mobile app for an advertiser.

Input Parameters

string ("AdBrix" | "Adform" | "Adjust" | "Adzcore" | "AppAdforce" | "AppLink" | "AppMetrica" | "AppsFlyer" | "BASE" | "BigCommerce" | "Cafe24" | "Cinarra" | "Dentsu" | "DoubleClick" | "ECWID" | "FlashTalking" | "Huangbaoche" | "Kantar" | "Kochava" | "Lazada" | "LeadBolt" | "Macromil" | "Magento" | "Metaps" | "Nielsen" | "OpenCart" | "Other" | "Placed_powered_by_Foursquare" | "PrestaShop" | "SHOPLINE" | "Salesforce" | "ServingsSys" | "Shopify" | "Singular" | "Square" | "Tenjin" | "Testee" | "TikTokCustomInstantPage" | "TikTokEC1PSeller" | "TikTokEC3PStore" | "TikTokLeadAd" | "TlnkIo" | "Vidoadsplus" | "Weborama" | "WooCommerce" | "doubleverify" | "myTracker")
Third-party tracking partner enum value.
string
required
Application download URL.
object
Third-party tracking URLs.
string
required
Advertiser ID.
string ("RETARGETING" | "NON_RETARGETING")
Retargeting attribution setting; defaults to NON_RETARGETING.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_BCCreate a persistent TikTok Business Center organization. This may establish a new administrative and billing boundary with no cleanup operation documented for this tool; obtain explicit approval immediately before execution and verify the name, company, registration area, currency, timezone, type, and contact data.

Input Parameters

string
Business Center type. The SDK contract enumerates codes 1, 5, and 6 and defaults to NORMAL.
string
required
Business Center name.
string
Business Center currency.
string
required
Business Center timezone code.
string
Company name.
object
Business Center contact information.
string
Plugin partner identifier.
string
Registration area code.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_BC_ADVERTISERCreate a persistent ad account in a Business Center, optionally configure its invoice grouping, Payment Portfolio linkage, and spending budget. Account creation can succeed even if portfolio binding or budget setup fails. Obtain explicit owner and finance approval immediately before execution; verify identity, region, currency, timezone, qualifications, tax data, payer, portfolio, and budget settings, then inspect both setup-result objects. Some options require TikTok allowlisting.

Input Parameters

string
required
Business Center ID.
object
Billing information required for applicable France, Brazil, or Mexico registrations.
object
Contact information.
object
Payment Portfolio and initial budget settings.
object
required
Business information.
object
required
Ad account information.
object
Billing Group and invoice grouping settings.
object
Qualification information required for AGENCY or SELF_SERVICE_AGENCY Business Centers; do not provide it for DIRECT Business Centers.
boolean
Whether to add the account to a Billing Group; this is allowlist-only.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_BC_BILLING_GROUPCreate a persistent Billing Group and assign ad accounts to it. This changes invoice grouping and may make the group the Business Center default; obtain explicit approval immediately before execution and verify the Business Center, account IDs, immutable group type, email recipients, and is_primary setting.

Input Parameters

string
required
Business Center ID.
boolean
Whether this becomes the default Billing Group.
array
required
Ad account IDs to include. TikTok requires Auction accounts to be grouped together except accounts registered in France, Brazil, or Mexico; a Reservation group contains one Reservation account.
string
required
Billing Group name.
string ("AUCTION" | "RESERVATION")
Advertising type for all accounts in the group; this cannot be edited later.
array
Email addresses associated with the Billing Group.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_BC_INVOICE_TASKCreate a task that generates an invoice list, batch of invoice PDFs, or detailed billing report for later download. This exports finance-sensitive data and creates external task state; obtain explicit approval immediately before execution, verify the Business Center, invoice, output type, date range, payment filters, and campaign, and retrieve the result only to an approved storage destination.

Input Parameters

string
required
Business Center ID.
object
Invoice filters for the generated file.
string
Invoice ID; required for BILLING_REPORT and optional as a filter for other types.
string ("INVOICE_LIST" | "INVOICE_BATCH" | "BILLING_REPORT")
required
INVOICE_LIST creates XLSX, INVOICE_BATCH creates ZIP of PDFs, and BILLING_REPORT creates XLSX.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_BLOCKEDWORDAdd exact words to an advertiser’s moderation block list. Review the words and advertiser ID before calling because future matching comments may be affected.

Input Parameters

string
required
Advertiser ID whose moderation list will change.
array
required
Words to add to the advertiser’s blocked-word list.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_BLOCKEDWORD_TASKCreate an asynchronous export task for an advertiser’s blocked words. Save the returned task ID, poll CHECK_BLOCKEDWORD_TASK until SUCCEED, then download it.

Input Parameters

string ("EN" | "JA" | "ZH")
Export language: EN, JA, or ZH.
string
required
Advertiser ID whose blocked words to export.
array
Optional blocked words to include in the export.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_BUSINESS_CENTER_ASSET_GROUPCreate an Asset Group in a TikTok Business Center, add advertiser assets and members, and optionally assign each member an advertiser access role.

Input Parameters

string
required
Business Center ID in which to create the Asset Group.
array
required
Advertiser assets to include (1-200).
array
required
Business Center members to include (1-50).
string
required
Name of the Asset Group to create.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_BUSINESS_CENTER_ORGANIZATION_ACCOUNTCreate an Organization Account in an authorized Business Center.

Input Parameters

string
required
Business Center ID in which to create the Organization Account.
string
Optional Organization Account handle, up to 24 characters. It cannot consist solely of numbers.
string
required
Display name for the Organization Account, up to 30 characters.
object
Optional profile image file for the Organization Account.
object
Qualification information. TikTok requires this when the Business Center type is AGENCY or SELF_SERVICE_AGENCY. It remains optional here because this request does not include the Business Center type.
string ("AR" | "AU" | "AT" | "BD" | "BE" | "BR" | "BG" | "KH" | "CA" | "CL" | "CO" | "HR" | "CY" | "CZ" | "DK" | "EC" | "EG" | "EE" | "FI" | "FR" | "DE" | "GR" | "HU" | "ID" | "IQ" | "IE" | "IL" | "IT" | "JP" | "JO" | "KZ" | "KW" | "LV" | "LT" | "LU" | "MY" | "MX" | "MA" | "NL" | "NZ" | "NO" | "PK" | "PE" | "PH" | "PL" | "PT" | "RO" | "SA" | "SG" | "SK" | "SI" | "ZA" | "KR" | "ES" | "SE" | "CH" | "TW" | "TH" | "TR" | "AE" | "GB" | "US" | "VN")
required
Operating region for the Organization Account. Businesses based in Chinese mainland must select a region other than China; CN is not available.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_BUSINESS_SPARK_ADCreate a campaign, ad group, and Spark Ad in one request. TikTok’s endpoint contract does not document their initial delivery status; the created resources may become eligible for delivery and spend, so verify their status after creation.

Input Parameters

number
Campaign budget.
string ("GENDER_FEMALE" | "GENDER_MALE" | "GENDER_UNLIMITED")
Audience gender targeting.
string
Optional Spark Ad name, up to 512 characters; emojis are unsupported.
string ("BID_TYPE_CUSTOM" | "BID_TYPE_NO_BID")
Custom bidding or maximum delivery without a bid.
number
Custom standard bid price.
number
Maximum impressions per user in the frequency schedule (1-1,000).
array
Audience age groups.
string ("BUDGET_MODE_TOTAL" | "BUDGET_MODE_DAY")
Total or daily budget mode.
string
Authorized identity ID.
string
Optional ad group name, up to 512 characters; emojis are unsupported.
array
Location IDs, maximum 3,000. Either this field or saved_audience_id must be supplied.
string
required
Authorized advertiser account ID.
string
Optional campaign name, up to 512 characters; emojis are unsupported.
string ("AUTH_CODE" | "TT_USER" | "BC_AUTH_TT")
TikTok identity authorization type.
string ("SCHEDULE_START_END" | "SCHEDULE_FROM_NOW")
Finite or continuous delivery schedule.
string ("APPLY_NOW" | "BOOK_NOW" | "CALL_NOW" | "CHECK_AVAILABLILITY" | "CONTACT_US" | "DOWNLOAD_NOW" | "EXPERIENCE_NOW" | "GET_QUOTE" | "GET_SHOWTIMES" | "GET_TICKETS_NOW" | "INSTALL_NOW" | "INTERESTED" | "LEARN_MORE" | "LISTEN_NOW" | "ORDER_NOW" | "PLAY_GAME" | "PREORDER_NOW" | "READ_MORE" | "SEND_MESSAGE" | "SHOP_NOW" | "SIGN_UP" | "SUBSCRIBE" | "VIEW_NOW" | "VIEW_PROFILE" | "VISIT_STORE" | "WATCH_LIVE" | "WATCH_NOW" | "JOIN_THIS_HASHTAG" | "SHOOT_WITH_THIS_EFFECT" | "VIEW_VIDEO_WITH_THIS_EFFECT")
Call to action shown on the Spark Ad.
string ("REACH" | "TRAFFIC" | "VIDEO_VIEWS" | "ENGAGEMENT")
Campaign objective that determines valid optimization goals.
string
Authorized TikTok post ID.
string
Landing page URL when supported by the optimization goal.
string ("REACH" | "CLICK" | "TRAFFIC_LANDING_PAGE_VIEW" | "ENGAGED_VIEW" | "FOLLOWERS" | "PAGE_VISIT")
Optimization goal compatible with objective_type.
string
Saved Audience ID. Either this field or location_ids must be supplied.
string
UTC+0 end time in YYYY-MM-DD HH:MM:SS format.
number
Frequency-cap period in days (1-30).
string
UTC+0 start time in YYYY-MM-DD HH:MM:SS format.
number
Custom conversion bid price.
string
Authorizing Business Center ID, required for BC_AUTH_TT identities.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_CAMPAIGNCreate a Manual Campaign with documented campaign, objective, budget, RTA, and iOS settings.

Input Parameters

string
Promoted app ID required for applicable iOS 14 campaigns.
number
Budget required for finite budget modes.
string
Realtime API strategy ID.
string
Purchase order number.
string
64-bit integer represented as a string for idempotency and duplicate names.
string ("BUDGET_MODE_TOTAL" | "BUDGET_MODE_DYNAMIC_DAILY_BUDGET" | "BUDGET_MODE_DAY" | "BUDGET_MODE_INFINITE")
Campaign budget mode; required unless objective_type is RF_REACH.
string
required
Advertiser ID.
string
required
Campaign name, maximum 512 characters; emoji is unsupported.
string ("REGULAR_CAMPAIGN" | "IOS14_CAMPAIGN")
Campaign type.
string
required
Advertising objective code.
boolean
Whether catalog-based advertising is enabled.
boolean
Whether RTA bidding is enabled.
string ("ENABLE" | "DISABLE")
Initial campaign status.
string ("STANDARD" | "PULSE")
Reach and Frequency campaign type.
string ("TIKTOK_SHOP" | "WEBSITE" | "APP" | "WEB_AND_APP")
Sales destination; required with virtual_objective_type.
string ("APP_INSTALL" | "APP_RETARGETING" | "APP_PREREGISTRATION")
App promotion type; required for APP_PROMOTION.
boolean
Whether Campaign Budget Optimization is enabled.
boolean
Whether to create an allowlisted Search Ads Campaign.
array
Special ad categories.
string ("POSTBACK_WINDOW_MODE1" | "POSTBACK_WINDOW_MODE2" | "POSTBACK_WINDOW_MODE3")
SKAN 4.0 postback window for a disabled iOS 14 campaign.
boolean
Whether to disable SKAN attribution for an eligible campaign.
string
Combined Sales objective.
string ("CATALOG" | "STORE")
Product source required for PRODUCT_SALES.
boolean
Whether RTA product selection is enabled.
boolean
Whether this is an Advanced Dedicated Campaign.
string ("ON" | "OFF")
Whether to optimize using an app profile page.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_CAMPAIGN_COPY_TASKCreate an asynchronous Manual Campaign copy task. Copied nested resources may default to enabled unless explicitly disabled.

Input Parameters

number
Copied campaign budget.
string
Realtime API strategy ID.
string
Purchase order number.
string
required
Idempotency request ID cached for 10 seconds.
string
required
Source Manual Campaign ID.
array
Ad groups to customize, maximum ten.
string
required
Advertiser ID.
string
Copied campaign name.
string ("SCHEDULE_START_END" | "SCHEDULE_FROM_NOW")
Schedule mode for copied ad groups.
string ("DEFAULT" | "CUSTOM")
Copy mode.
string ("ENABLE" | "DISABLE")
Copied campaign status.
string ("TIKTOK_SHOP" | "WEBSITE" | "APP" | "WEB_AND_APP")
Copied campaign sales destination.
string
UTC schedule end.
string
UTC schedule start.
string
Combined Sales objective.
boolean
Whether the copy is an Advanced Dedicated Campaign.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_CAMPAIGN_SPCCreate a legacy Smart+ campaign through TikTok’s SPC route, which is marked for deprecation. Campaigns default to enabled unless disabled in the request.

Input Parameters

string
Promoted app ID.
number
required
Campaign budget.
string ("GENDER_FEMALE" | "GENDER_MALE" | "GENDER_UNLIMITED")
Target gender.
string ("BID_TYPE_NO_BID" | "BID_TYPE_CUSTOM")
Bidding strategy.
App deeplink.
string
Pixel ID.
number
Target ROAS.
string ("WEB_ALL_IN_ONE" | "UNSET")
Web campaign type.
number
Target click cost.
array
Creative portfolio IDs, maximum one.
array
Target languages.
array
Page IDs, maximum one.
array
Apps promoted for WEB_AND_APP, maximum two.
string
Catalog ID.
string
336-character weekly delivery grid.
array
Selected placements.
array
Ad title objects.
array
URL parameters, maximum 14.
string ("SEVEN_DAYS" | "ZERO_DAY")
Value optimization window.
string ("BUDGET_MODE_DAY" | "BUDGET_MODE_DYNAMIC_DAILY_BUDGET")
Budget mode.
string
Non-Spark identity ID.
array
Customized product IDs, maximum 20.
array
required
Target location IDs.
object
Product promotion information.
string
required
Advertiser ID.
string ("OCPM" | "CPC")
required
Billing event.
string
required
Campaign name.
string ("REGULAR_CAMPAIGN" | "IOS14_CAMPAIGN")
Campaign type.
string ("DEFAULT" | "AEO" | "VO_MIN_ROAS" | "VO_HIGHEST_VALUE")
Deep-event bidding strategy.
Deeplink type.
string
Non-Spark identity type.
string ("SCHEDULE_START_END" | "SCHEDULE_FROM_NOW")
required
Schedule type.
string ("APP_PROMOTION" | "WEB_CONVERSIONS" | "LEAD_GENERATION")
required
Advertising objective.
string ("PLACEMENT_TYPE_NORMAL" | "PLACEMENT_TYPE_AUTOMATIC")
Placement strategy.
string
Product set ID.
string
Catalog product source.
string ("APP_ANDROID" | "APP_IOS" | "WEBSITE" | "LEAD_GENERATION")
required
Optimization location.
boolean
Whether sharing is disabled.
object
WEB_AND_APP disclaimer details.
array
required
Documented media information, maximum 30.
string
Tracking app ID.
boolean
Whether comments are disabled.
string ("ON" | "OFF")
Spark Ads-only mode.
string ("ENABLE" | "DISABLE")
Initial campaign status.
string ("18+" | "25+")
Target age floor.
string
CTA portfolio ID.
array
Landing-page mappings, maximum 30.
string ("CLICK" | "INSTALL" | "IN_APP_EVENT" | "VALUE" | "CONVERT" | "TRAFFIC_LANDING_PAGE_VIEW" | "LEAD_GENERATION")
required
Optimization goal.
string ("WEBSITE" | "WEB_AND_APP")
Sales destination required with virtual_objective_type.
string
UTC schedule end.
string
App promotion type required for APP_PROMOTION.
string
Click tracking URL.
string
Conversion event.
array
Special ad categories.
array
Call-to-action objects.
string
required
UTC schedule start.
number
Target conversion or landing-page-view cost.
boolean
Whether to disable SKAN attribution.
array
Excluded audience IDs.
string ("ALL" | "PRODUCT_SET" | "CUSTOMIZED_PRODUCTS")
Product selection type.
string ("INSTANT_PAGE" | "EXTERNAL_WEBSITE")
Lead generation optimization location.
array
Third-party app tracking settings, maximum four.
array
Blocked Pangle app IDs.
string
TikTok Instant Page type.
string
Combined Sales objective.
string ("UNSET" | "EVERY" | "ONCE")
Attribution event count mode.
boolean
Catalog creative auto-selection.
string
Impression tracking URL.
boolean
Whether video download is disabled.
string
View attribution window.
boolean
Automatic interactive add-ons.
string
Catalog Business Center ID.
string
Click attribution window.
string ("PIXEL" | "OFFLINE" | "CRM")
Deep-funnel event source.
boolean
Exclude users under 18; only true is supported.
string
Automatic budget adjustment strategy.
string
Deep-funnel source ID.
string ("OPEN" | "UNSET")
Smart+ Web catalog status.
string
Deep-funnel event.
boolean
Advanced Dedicated Campaign status.
string ("ON" | "OFF")
App profile page optimization state.
string ("ON" | "OFF")
Deep-funnel optimization status.
string
Engaged-view attribution window.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_CATALOGCreate a catalog in a TikTok Business Center; some catalog types require allowlisting.

Input Parameters

string
required
Catalog name, up to 128 characters.
string
required
Business Center ID.
object
required
Catalog region and currency configuration.
string ("ECOM" | "GENERIC" | "HOTEL" | "FLIGHT" | "DESTINATION" | "ENTERTAINMENT" | "AUTO_VEHICLE" | "AUTO_MODEL" | "ONLINE_TO_OFFLINE" | "MINI_SERIES")
required
TikTok catalog type.
string
Creative asset type, when supported.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_CATALOG_FEEDCreate a scheduled catalog feed. INCREMENTAL preserves products omitted from the next import; OVERWRITE permanently removes omitted products, so confirm the complete source file before using it.

Input Parameters

string
required
Business Center ID.
string
required
Feed name.
string
required
Catalog ID.
string ("INCREMENTAL" | "OVERWRITE")
required
INCREMENTAL adds or updates products. OVERWRITE replaces the feed’s catalog data and permanently removes products omitted from the next feed import; confirm the complete source file before choosing OVERWRITE.
object
Optional remote-feed schedule.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_CATALOG_PRODUCT_DIAGNOSTIC_TASKCreate an asynchronous download task for catalog product diagnostic information.

Input Parameters

string ("ar" | "cs-CZ" | "de" | "en" | "es" | "fil" | "fr" | "id" | "it" | "ja" | "ko" | "ms" | "pl-PL" | "pt" | "ru" | "sv-SE" | "th" | "tr" | "vi" | "zh")
Language for the downloaded diagnostic information.
string
required
Business Center ID that owns the catalog.
string
Optional catalog feed ID to diagnose.
string
Optional diagnostic issue ID to include.
string
required
E-commerce catalog ID to diagnose.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_CATALOG_PRODUCT_SETCreate an E-commerce catalog product set from an uploaded CSV file.

Input Parameters

object
required
CSV defining the product set, with at most 5,000 rows.
string
required
Business Center ID that owns the E-commerce catalog.
string
required
E-commerce catalog ID in which to create the product set.
string
required
MD5 hash of the uploaded file for integrity verification.
string
required
Unique product set name, up to 28 characters.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_CATALOG_SETCreate a catalog product set using one AND or OR condition group.

Input Parameters

string
required
Business Center ID.
string
required
Catalog ID.
object
required
Exactly one and or or list of filter conditions.
string
required
Product set name, up to 128 characters.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_CHANGELOG_TASKCreate an asynchronous download task for an advertiser’s change log.

Input Parameters

string ("BIDDING_AND_OPTIMIZATION" | "BUDGET" | "STATUS" | "TARGETING")
Change-log module to query.
string
Query end time, no more than 30 days after start_time.
string
Timezone for returned values. Supply an exact timezone value from TikTok’s Appendix-Time Zone list; this field remains open because the list is not published as an endpoint-specific enum.
array
Object IDs to include in the change-log query.
string
Inclusive query start time in YYYY-MM-DD HH:MM:SS format.
string ("AD" | "ADGROUP" | "ADVERTISER" | "CAMPAIGN" | "INSTANT_FORM")
Type of object IDs being queried.
array
Change-log field names by which TikTok should order the export. The exact allowed field list is provider-maintained and not exposed as an exhaustive enum.
string
required
Advertiser ID whose change log to export.
array
Change-log operation types to include.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_COMMENT_TASKCreate an asynchronous comment export for a specific advertiser, ad group, and date range. Review the filter because exported comments may contain personal data; poll CHECK_COMMENT_TASK before downloading.

Input Parameters

string ("EN" | "JA" | "ZH")
Export language: EN, JA, or ZH.
string
required
End date of the export range in YYYY-MM-DD format.
string ("ASC" | "DESC")
Ascending or descending sort order.
string ("CREATE_TIME" | "LIKES" | "REPLIES")
Field used to sort exported comments.
string
required
Start date of the export range in YYYY-MM-DD format.
array
Optional comment IDs to export.
array
Comment type filters: ALL, COMMENT, or REPLY.
string
required
Field to search by; only ADGROUP_ID is supported.
string
required
Ad group ID used as the search value.
string
required
Advertiser ID whose comments to export.
array
Comment status filters: ALL, PUBLIC, or HIDDEN.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_CREATIVE_AUTO_MESSAGECreate a welcome message within a TikTok advertiser account.

Input Parameters

string
required
Advertiser account ID.
object
required
Welcome message required for WELCOME_MESSAGE.
string
required
Automatic-message type. The documented value is WELCOME_MESSAGE.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_CREATIVE_PORTFOLIOCreate a typed creative portfolio. Availability may depend on TikTok entitlement.

Input Parameters

string
required
Advertiser ID.
array
required
Portfolio content objects.
string
TikTok creative portfolio type.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_CREATIVE_PRE_REVIEW_TASKCreate a task to pre-review creative materials for one location.

Input Parameters

boolean
Whether the materials are for e-commerce.
string
required
Advertiser account ID.
array
required
Materials to pre-review (1-5).
array
required
Exactly one target location code.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_CRMCreate a CRM Event Set configuration in an advertiser account. This does not report or ingest CRM events; an advertiser can have at most 50 CRM Event Sets.

Input Parameters

string
required
Unique CRM Event Set name, from 1 to 40 characters after trimming.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_CUSTOM_CONVERSIONCreate a Custom Conversion configuration; this does not ingest conversion events.

Input Parameters

string
required
Unique Custom Conversion name; starts with a letter and contains no emoji.
array
required
One to ten conversion rules.
string
Optional description without emoji.
string
required
Advertiser ID.
string
required
Pixel ID or SAN app platform ID.
string
Configured custom event to associate, when applicable.
string ("PIXEL" | "APP")
required
PIXEL or APP event source.
string
Standard event associated with the conversion; required for PIXEL sources.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_DMP_CUSTOM_AUDIENCECreate a custom audience from previously uploaded encrypted customer files.

Input Parameters

array
required
Uploaded audience file paths; fewer than 50 are recommended.
string
required
Advertiser ID.
string ("EMAIL_SHA256" | "FIRST_MD5" | "FIRST_SHA256" | "GAID_MD5" | "GAID_SHA256" | "IDFA_MD5" | "IDFA_SHA256" | "MULTIPLE_TYPES" | "PHONE_SHA256")
required
Encryption type shared by every uploaded file.
string ("NORMAL" | "REACH_FREQUENCY")
Audience subtype: NORMAL or REACH_FREQUENCY.
integer
Audience retention period in days (1-365).
boolean
Whether to enable audience enhancement.
string
required
Audience name (maximum 128 characters).

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_DMP_CUSTOM_AUDIENCE_LOOKALIKECreate a lookalike custom audience from an eligible source audience.

Input Parameters

string
required
Advertiser ID.
object
required
Lookalike audience settings.
string
required
Audience name (maximum 128 characters).

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_DMP_CUSTOM_AUDIENCE_RULECreate a custom audience from conditional inclusion and exclusion event rules.

Input Parameters

object
required
Inclusion and optional exclusion rule sets.
string
Identity ID required for organic-video and live-video audiences.
string
required
Advertiser ID.
string ("ENGAGEMENT" | "ENGAGEMENT_ORGANIC_VIDEO" | "ENGAGEMENT_LIVE_VIDEO" | "APP" | "PIXEL" | "LEAD_GENERATION" | "BUSINESS_ACCOUNT" | "TIKTOK_SHOP" | "OFFLINE")
required
Provider audience type.
string ("TT_USER" | "BC_AUTH_TT")
Identity type required for organic-video and live-video audiences.
boolean
Whether to refresh the audience automatically.
string ("NORMAL" | "REACH_FREQUENCY")
Audience subtype for standard or Reach & Frequency ads.
integer
Audience retention period (1-365 days).
boolean
Whether to enable audience enhancement.
string
required
Audience name (maximum 128 characters).
string
Business Center ID required for a Business Center-authorized TikTok identity.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_DMP_SAVED_AUDIENCECreate a reusable Saved Audience from targeting criteria.

Input Parameters

string ("GENDER_FEMALE" | "GENDER_MALE" | "GENDER_UNLIMITED")
Target gender.
array
Action targeting objects.
array
Target language codes.
array
Target age groups.
array
Target carrier IDs.
array
Included audience IDs.
array
required
Non-overlapping target location IDs.
string
required
Advertiser ID.
array
Target connection types.
string
Minimum iOS version.
array
Target device model IDs.
array
Target device operating system.
array
Target device price ranges.
string
Minimum Android version.
string
required
Saved Audience name without emoji (maximum 512 characters).
array
Interest keyword IDs.
array
Excluded audience IDs.
array
Interest category IDs.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_GMV_MAX_CAMPAIGNCreate a GMV Max campaign for a TikTok Shop. The action does not set a campaign operation status.

Input Parameters

number
Optional campaign budget.
number
Optional ROAS bid.
string
required
TikTok Shop store ID.
array
Optional shop items for the campaign.
string
required
Client deduplication request ID.
string
required
Authorized advertiser account ID.
string
required
Name for the new GMV Max campaign.
string
required
Deep bid type; the official contract supports VO_MIN_ROAS.
array
Optional identities available to the campaign.
string ("SCHEDULE_FROM_NOW" | "SCHEDULE_START_END")
required
Campaign schedule type.
array
Optional item group IDs (1-50).
object
Optional promotion-day schedule configuration.
string
required
Optimization goal; the official contract supports VALUE.
string
Required for SCHEDULE_START_END, in the provider’s date-time string format.
string ("LIVE" | "PRODUCT")
required
GMV Max shopping ads type: LIVE or PRODUCT.
boolean
Whether automatic budget management is enabled.
string
required
Campaign start time in the provider’s date-time string format.
string ("ALL" | "CUSTOMIZED_PRODUCTS")
Optional product selection type.
string
required
Business Center ID authorizing the store.
boolean
Whether affiliate posts are enabled.
array
Optional custom anchor videos (maximum 2000).
string ("AUTO_SELECTION" | "CUSTOM_SELECTION")
Optional product video selection type.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_GMV_MAX_CAMPAIGN_SESSIONCreate and start a max delivery session for a product or a creative boost session for a video. Starting the session can begin delivery and spend.

Input Parameters

string
required
Max delivery or creative boost session configuration.
string
required
TikTok Shop store ID.
string
required
Product GMV Max campaign ID.
string
required
Authorized advertiser account ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_GMV_MAX_CUSTOMIZED_POSTSCreate shop-level customized TikTok posts linking videos to products. The response may include a list of posts that could not be created.

Input Parameters

string
required
TikTok Shop ID.
string
required
Advertiser ID.
string
required
Business Center ID authorized to access the TikTok Shop.
array
required
Videos and products to link (maximum 200).

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_GMV_MAX_EXCLUSIVE_AUTHORIZATIONGrant an ad account exclusive authorization for a TikTok Shop.

Input Parameters

string
required
TikTok Shop ID.
string
required
Ad account to authorize exclusively for the TikTok Shop.
string
required
Business Center ID that owns the TikTok Shop.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_IDENTITYCreate a customized advertiser identity. This does not authorize a TikTok creator account or a creator post; use the relevant TikTok account or Spark post authorization flow for those identities.

Input Parameters

string
Uploaded square avatar image ID; omit to use TikTok’s default image.
string
required
Identity display name, at most 100 characters.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_MMM_DATA_REQUESTCreate an irreversible Media Mix Modeling export job after explicit confirmation. Processing can take up to 24 hours, and the request cannot be cancelled through this tool once submitted.

Input Parameters

string
Optional email address to notify when processing changes state.
boolean
required
Must be true to confirm creation of an uncancellable MMM export job that may process and package advertiser measurement data for up to 24 hours.
object
required
MMM export selection and date range.
array
required
Authorized advertiser IDs for this export; five or fewer are recommended.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_OFFLINECreate an Offline Event Set configuration; this does not upload or ingest offline events.

Input Parameters

string
required
Unique Offline Event Set name.
string
required
Offline Event Set description.
string
required
Advertiser ID.
boolean
Enable Auto Tracking for future campaigns.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_OPTIMIZER_RULECreate automated optimizer rules.

Input Parameters

string ("ZH" | "EN" | "JA")
Language of error messages.
array
required
Rules to create.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_PAGE_LEAD_MOCKCreate a disposable test lead for an Instant Form or direct-message source; remove it after testing.

Input Parameters

string
Instant Form ID; required for INSTANT_FORM and unsupported for DIRECT_MESSAGE.
string
Form library ID when creating under a Business Center.
string ("INSTANT_FORM" | "DIRECT_MESSAGE")
Test-lead source.
string
Advertiser ID when creating under an ad account.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_PAGE_LEAD_TASKCreate an asynchronous export task for leads from one Instant Form or ad. This is a lead export endpoint, not Events API ingestion; only ad-account or Business Center admins can use it.

Input Parameters

string
Ad ID to export leads for; mutually exclusive with page_id.
string
Instant Form ID to export leads for; mutually exclusive with ad_id.
string
Form library ID after leads have migrated to a Business Center.
string ("eu" | "us")
Use eu for EEA/Switzerland/UK leads, us for US leads, or omit for other regions.
string
Advertiser ID when leads remain under an ad account.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_PAYMENT_PORTFOLIOCreate a SHARED Payment Portfolio and link ad accounts so they jointly use centrally managed funds. This creates persistent financial configuration; obtain explicit finance-owner approval immediately before execution and verify the name, every account ID, same-client eligibility, and administrator access.

Input Parameters

array
required
Ad account IDs to link (maximum 20). All must belong to the same client; one invalid ID causes the entire call to fail.
string
required
Payment Portfolio name.
string
Portfolio type. SHARED centrally manages funds across linked accounts.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_PIXELCreate a TikTok Pixel configuration; this does not ingest web events.

Input Parameters

string
required
Unique Pixel name without emoji.
string
Merchant partner name, when applicable.
string
required
Advertiser ID.
string ("ONLINE_STORE" | "FILLING_FORM" | "CONTACTS" | "LANDING_PAGE" | "CUSTOMIZE_EVENTS")
Deprecated Pixel category; omit for new Pixels.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_PIXEL_EVENTCreate standard Pixel Event configurations and rules; this endpoint does not ingest event occurrences.

Input Parameters

string
required
Pixel ID.
array
required
Pixel Event configurations to create.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_REPORT_TASKCreate an asynchronous TikTok report task and return its task ID; use the separate check and download tools to observe completion and retrieve output.

Input Parameters

array
Metric names; defaults upstream to spend and impressions.
string
Inclusive end date.
string
Custom download file name.
array
Asynchronous report filters.
string ("AUCTION_AD" | "AUCTION_ADGROUP" | "AUCTION_ADVERTISER" | "AUCTION_CAMPAIGN" | "RESERVATION_AD" | "RESERVATION_ADGROUP" | "RESERVATION_ADVERTISER" | "RESERVATION_CAMPAIGN")
Report data level.
array
required
Asynchronous report dimensions.
string ("ASC" | "DESC")
Sort order.
string
Inclusive start date.
string
Metric used for sorting.
string ("BASIC" | "AUDIENCE" | "CATALOG")
required
Asynchronous report type.
string ("AUCTION" | "RESERVATION")
Ad service type.
string
Single advertiser ID; ignored when advertiser_ids is supplied.
string ("CSV_DOWNLOAD" | "CSV_STRING" | "XLSX_DOWNLOAD")
Asynchronous report output format.
array
One to five advertiser IDs belonging to the same user.
boolean
Request lifetime metrics.
boolean
Translate dimension and metric titles in the output.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_SMART_CREATIVE_ADSCreate current Smart Creative ads in an ad group configured with creative_material_mode=SMART_CREATIVE. TikTok returns a mock processing result without ad IDs; wait 2-3 seconds and call GET_SMART_CREATIVE_MATERIALS to read final data. This is not the retired DYNAMIC ACO mode.

Input Parameters

array
Card or sticker ID (maximum one).
array
Instant Page IDs (1-3).
string
required
Ad group ID whose creative_material_mode is SMART_CREATIVE.
array
Distinct ad titles (1-5).
string
required
Advertiser account ID.
Optional app deep link (maximum one).
object
Settings shared by generated ads.
array
required
Distinct image, video, or Spark materials.
array
Displayed app or landing-page names.
array
Landing-page destinations.
array
Distinct call-to-action texts (1-3).

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_SMART_PLUS_ADCreate a Smart+ ad disabled for review in an existing Smart+ ad group. Use the separate Smart+ ad status tool to enable it.

Input Parameters

string
required
Smart+ ad name.
array
Instant Pages (maximum 3).
string
required
Ad group ID in which to create the ad.
array
Ad text variants (maximum 5).
string
required
Advertiser ID that owns the ad group.
array
Creative variants (1-31).
Deep-link destinations (maximum 1).
object
Common ad material configuration.
string
Initial status. Only DISABLE is accepted so the ad is created disabled for review.
array
Auto-message configuration (maximum 1).
array
Call-to-action variants (maximum 3).
array
Landing pages (maximum 1).
array
Interactive add-ons (maximum 1).

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_SMART_PLUS_ADGROUPCreate a Smart+ ad group disabled for review in an existing Smart+ campaign. Use the separate Smart+ ad group status tool to enable it.

Input Parameters

string
Promoted app ID.
number
Budget.
string ("BID_TYPE_CUSTOM" | "BID_TYPE_MAX_CONVERSION" | "BID_TYPE_NO_BID")
Bid type.
string
Pixel ID.
number
ROAS bid.
number
Bid price.
string
Catalog ID.
string
Dayparting schedule.
number
Minimum budget.
object
Phone information.
array
Placements.
string
required
Caller-provided deduplication token.
string ("SEVEN_DAYS" | "ZERO_DAY")
Value-based optimization window.
string ("BUDGET_MODE_DAY" | "BUDGET_MODE_DYNAMIC_DAILY_BUDGET" | "BUDGET_MODE_INFINITE" | "BUDGET_MODE_TOTAL")
Budget mode.
string
required
Campaign ID in which to create the ad group.
number
Deep conversion CPA bid.
string
Identity ID.
string
required
Ad group name.
string ("ZALO_OFFICIAL_ACCOUNT" | "ZALO_PHONE_ACCOUNT")
Zalo account ID type.
string
required
Advertiser ID that owns the campaign.
string ("CPA" | "CPC" | "CPM" | "CPV" | "GD" | "OCPM")
required
Billing event.
string ("AEO" | "DEFAULT" | "MIN" | "PACING" | "VO_HIGHEST_VALUE" | "VO_MIN" | "VO_MIN_ROAS")
Deep bid type.
string ("BC_AUTH_TT" | "TT_USER")
Identity type.
string ("SCHEDULE_FROM_NOW" | "SCHEDULE_START_END")
required
Schedule type.
string ("PLACEMENT_TYPE_AUTOMATIC" | "PLACEMENT_TYPE_NORMAL")
Placement type.
string ("CATALOG" | "SHOWCASE" | "STORE" | "UNSET")
Product source.
string ("AEO_APK" | "APP_ANDROID" | "APP_IOS" | "LEAD_GENERATION" | "LEAD_GEN_CLICK_TO_CALL" | "LEAD_GEN_CLICK_TO_SOCIAL_MEDIA_APP_MESSAGE" | "LEAD_GEN_CLICK_TO_TT_DIRECT_MESSAGE" | "LIVE_SHOPPING" | "MINI_APP" | "PRODUCT_SHOPPING" | "TIKTOK_SHOP" | "VIDEO_SHOPPING" | "WEBSITE" | "WEBSITE_OR_DISPLAY")
required
Promotion type.
boolean
Whether sharing is disabled.
object
required
Audience targeting specification.
boolean
Whether comments are disabled.
string
Open API partner.
string
Initial status. Only DISABLE is accepted so the ad group is created disabled for review.
string ("ANCHOR_CLICK" | "ANCHOR_CLICK_PURCHASE" | "AUTOMATED_VALUE" | "CLICK" | "CONVERSATION" | "CONVERSION_LEADS" | "CONVERT" | "DESTINATION_VISIT" | "ENGAGED_VIEW" | "ENGAGED_VIEW_FIFTEEM" | "FOLLOWERS" | "INSTALL" | "IN_APP_EVENT" | "LEAD_GENERATION" | "MESSAGE" | "MT_LIVE_FOLLOW" | "MT_LIVE_ROOM" | "MT_LIVE_SHOPPING" | "PAGE_VISIT" | "POST_ENGAGEMNT" | "PREFERRED_LEAD" | "PRODUCT_CLICK_IN_LIVE" | "PROFILE_VIEWS" | "REACH" | "SHOW" | "TRAFFIC_LANDING_PAGE_VIEW" | "VALUE" | "VIDEO_VIEW")
required
Optimization goal.
string
Schedule end time.
string ("IM_URL" | "LINE" | "MESSENGER" | "WHATSAPP" | "ZALO")
Messaging app type.
string ("ACTIVE" | "ACTIVE_PAY" | "ACTIVE_REGISTER" | "ADD_BILLING" | "ADD_BOOKSHELF" | "ADD_PAYMENT_INFO" | "ADD_TO_WISHLIST" | "ANCHOR_CLICK" | "APPLET_DEAL" | "APPLICATION_APPROVAL" | "APPOINTMENT_DOWNLOAD_BUTTON" | "ASCRIPTION_PHONE" | "AUTHORIZATION" | "BANKCARD_INFORMATION" | "BOOST" | "BUTTON" | "CERTIFICATION_INFORMATION" | "CLICK_CALL_DY" | "CLICK_DOWNLOAD" | "CLICK_LANDING_PAGE" | "CLICK_SHOPWINDow" | "CLICK_WEBSITE" | "CLUE_CONFIRM" | "CLUE_HIGH_INTENTION" | "CLUE_INTERFLOW" | "CLUE_PAY_SUCCEED" | "COMMENT_ACTION" | "COMMODITY_CLICK" | "COMPLETE_TUTORIAL" | "CONSULT" | "CONSULT_CLUE" | "CONSULT_EFFECTIVE" | "CONVERSION_LEADS" | "COUPON" | "CREATE_GAMEROLE" | "CUSTOMER_EFFECTIVE" | "CUSTOMIZE_PRODUCT" | "DEEP_PURCHASE" | "DESTINATION_VISIT" | "DIALBACK" | "DIALBACK_CONFIRM" | "DIALBACK_CONNECT" | "DOWNLOAD_BUTTON" | "DOWNLOAD_DETAIL" | "DOWNLOAD_FINISH" | "DOWNLOAD_START" | "EC_CLICK_BUY" | "EC_CLICK_PRODUCT" | "EC_CONFRIM_DEAL" | "EC_LIVE_CART" | "EC_LIVE_CLICK_PRODUCT_ACTION" | "EC_LIVE_COMMENT_ACTION" | "EC_LIVE_ENTER_ACTION" | "EC_LIVE_FOLLOW_ACTION" | "EC_LIVE_GIFT_ACTION" | "EC_LIVE_NATIVE_ACTION" | "EC_LIVE_ORDER" | "EC_LIVE_REDIRECT_TO_STORE_ACTION" | "EC_LIVE_SLIDECART_CLICK_ACTION" | "EC_SUBMIT_ORDER" | "EFFECTIVE_COPY" | "ENGAGED_SESSION" | "ENGAGED_VIEW" | "ENGAGED_VIEW_FIFTEEN" | "ENTER_HOMEPAGE" | "FEED_LIVE_HOMEPAGE" | "FIND_LOCATION" | "FOLLOW_ACTION" | "FOLLOW_LIVE_ENTER" | "FOLLOW_VIDEO_PLAY_FINISH" | "FORM" | "FORM_ANSWER" | "FORM_BUTTON" | "FORM_CONNECT" | "FORM_DEEP" | "FORM_DETAIL" | "GAME_ADDICTION" | "HIGHVALUE_CLUE" | "IDCARD_INFORMATION" | "IMPRESSION_LEVEL_AD_REVENUE" | "INITIATE_ORDER" | "INSTALL_FINISH" | "INTENTION_CLUE" | "INVALID_CLUE" | "IN_APP_AD_CLICK" | "IN_APP_AD_IMPR" | "IN_APP_CART" | "IN_APP_DETAIL_UV" | "IN_APP_ORDER" | "IN_APP_PAY" | "IN_APP_UV" | "LANDING_PAGE_VIEW" | "LAUNCH_APP" | "LIKE_ACTION" | "LINK_ACTION" | "LIVE_APPOINTMENT" | "LIVE_CARD_CLICK" | "LIVE_CLICK_PRODUCT_ACTION" | "LIVE_COMMENT_ACTION" | "LIVE_ENTER_ACTION" | "LIVE_FOLLOW_ACTION" | "LIVE_GIFT_ACTION" | "LIVE_HOMEPAGE" | "LIVE_JOIN_GROUP" | "LIVE_NATIVE_ACTION" | "LIVE_REDIRECT_TO_STORE_ACTION" | "LIVE_ROOM_ACTION" | "LIVE_SLIDECART_CLICK_ACTION" | "LIVE_STAY_TIME" | "LIVE_SUCCESSORDER_ACTION" | "LIVE_SUCESSORDER_PAY" | "LOAN" | "LOAN_APPLY" | "LOAN_COMPLETION" | "LOAN_CREDIT" | "LOCATION_ACTION" | "LOGIN" | "LOGIN_ACTION" | "LONGTERM_CUSTOMER" | "LOTTERY" | "LT_ROI" | "MAP_SEARCH" | "MESSAGE" | "MESSAGE_ACTION" | "MESSAGE_CLICK" | "MESSAGE_CLUE" | "MESSAGE_JOIN_GROUP" | "MESSAGE_SELF_SERVICE" | "MESSAGE_SEND" | "MULTIPLE" | "MULTI_NATIVE_ACTION" | "NATIVE_ACTION" | "NAV_BAR" | "NEW_FOLLOW_ACTION" | "NEXT_DAY_OPEN" | "NOVEL_CHAPTER" | "ON_WEB_ADD_TO_WISHLIST" | "ON_WEB_CART" | "ON_WEB_DETAIL" | "ON_WEB_ORDER" | "ON_WEB_REGISTER" | "ON_WEB_SEARCH" | "ON_WEB_SUBSCRIBE" | "OTHER" | "OTO_PAY" | "OTO_STAY_TIME" | "PAGE_VIEW" | "PAGE_VISIT" | "PAID_CLUE" | "PAY_ACTION" | "PERSONAL_INFORMATION" | "PHONE" | "PHONE_BUTTON" | "PHONE_CONFIRM" | "PHONE_CONNECT" | "PHONE_DETAIL" | "PHONE_EFFECTIVE" | "PREFERRED_LEAD" | "PREMIUM_PAYMENT" | "PRE_LOAN_CREDIT" | "PURCHASE_OF_GOODS" | "PURCHASE_ROI" | "QQ" | "RATE" | "READING_TIME" | "REDIRECT" | "REDIRECT_TO_SHOP" | "REDIRECT_TO_STORE" | "REGISTER_ACTION" | "RESERVATION" | "RSS" | "SALES_LEAD" | "SCHEDULE" | "SEARCH" | "SEVEN_DAY_OPEN" | "SHARE_ACTION" | "SHOPPING" | "SHOPPING_ACTION" | "SHOPPING_CART" | "START_TRIAL" | "STAY_TIME" | "SUBMIT_APPLICATION" | "SUBSCRIBE" | "SUCCESSORDER_ACTION" | "SUCCESSORDER_PAY" | "UG_EFFECTIVE_ACTION" | "UG_EFFECTIVE_DEAL" | "UG_EFFECTIVE_SHARE" | "UG_EFFECTIVE_SPEECH" | "UG_ROI" | "UNLOCK_ACHIEVEMENT" | "UPDATE_LEVEL" | "VIEW" | "VOTE" | "XPATH")
Optimization event.
string
Movie premiere date.
string
required
Schedule start time.
number
Conversion bid price.
string
Custom conversion ID.
string
Message event set ID.
string ("EXTERNAL_WEBSITE" | "INSTANT_PAGE" | "UNSET")
Promotion target type.
string ("TIKTOK_NATIVE_PAGE" | "UNSET")
Promotion website type.
string ("EVERY" | "ONCE" | "UNSET")
Attribution event counting mode.
boolean
Whether video download is disabled.
string ("FOURTEEN_DAYS" | "OFF" | "ONE_DAY" | "SEVEN_DAYS" | "TWENTY_EIGHT_DAYS" | "UNSET")
View attribution window.
string
Catalog-authorizing Business Center ID.
string ("FOURTEEN_DAYS" | "OFF" | "ONE_DAY" | "SEVEN_DAYS" | "TWENTY_EIGHT_DAYS" | "UNSET")
Click attribution window.
string ("CRM" | "OFFLINE" | "PIXEL")
Deep-funnel event source.
string
Messaging app account ID.
string
Identity-authorizing Business Center ID.
string
Deep-funnel event source ID.
boolean
Whether suggested audience is enabled.
string ("AUTOMATIC" | "MANUAL")
Targeting optimization mode.
string ("ACTIVE" | "ACTIVE_PAY" | "ACTIVE_REGISTER" | "ADD_BILLING" | "ADD_BOOKSHELF" | "ADD_PAYMENT_INFO" | "ADD_TO_WISHLIST" | "ANCHOR_CLICK" | "APPLET_DEAL" | "APPLICATION_APPROVAL" | "APPOINTMENT_DOWNLOAD_BUTTON" | "ASCRIPTION_PHONE" | "AUTHORIZATION" | "BANKCARD_INFORMATION" | "BOOST" | "BUTTON" | "CERTIFICATION_INFORMATION" | "CLICK_CALL_DY" | "CLICK_DOWNLOAD" | "CLICK_LANDING_PAGE" | "CLICK_SHOPWINDow" | "CLICK_WEBSITE" | "CLUE_CONFIRM" | "CLUE_HIGH_INTENTION" | "CLUE_INTERFLOW" | "CLUE_PAY_SUCCEED" | "COMMENT_ACTION" | "COMMODITY_CLICK" | "COMPLETE_TUTORIAL" | "CONSULT" | "CONSULT_CLUE" | "CONSULT_EFFECTIVE" | "CONVERSION_LEADS" | "COUPON" | "CREATE_GAMEROLE" | "CUSTOMER_EFFECTIVE" | "CUSTOMIZE_PRODUCT" | "DEEP_PURCHASE" | "DESTINATION_VISIT" | "DIALBACK" | "DIALBACK_CONFIRM" | "DIALBACK_CONNECT" | "DOWNLOAD_BUTTON" | "DOWNLOAD_DETAIL" | "DOWNLOAD_FINISH" | "DOWNLOAD_START" | "EC_CLICK_BUY" | "EC_CLICK_PRODUCT" | "EC_CONFRIM_DEAL" | "EC_LIVE_CART" | "EC_LIVE_CLICK_PRODUCT_ACTION" | "EC_LIVE_COMMENT_ACTION" | "EC_LIVE_ENTER_ACTION" | "EC_LIVE_FOLLOW_ACTION" | "EC_LIVE_GIFT_ACTION" | "EC_LIVE_NATIVE_ACTION" | "EC_LIVE_ORDER" | "EC_LIVE_REDIRECT_TO_STORE_ACTION" | "EC_LIVE_SLIDECART_CLICK_ACTION" | "EC_SUBMIT_ORDER" | "EFFECTIVE_COPY" | "ENGAGED_SESSION" | "ENGAGED_VIEW" | "ENGAGED_VIEW_FIFTEEN" | "ENTER_HOMEPAGE" | "FEED_LIVE_HOMEPAGE" | "FIND_LOCATION" | "FOLLOW_ACTION" | "FOLLOW_LIVE_ENTER" | "FOLLOW_VIDEO_PLAY_FINISH" | "FORM" | "FORM_ANSWER" | "FORM_BUTTON" | "FORM_CONNECT" | "FORM_DEEP" | "FORM_DETAIL" | "GAME_ADDICTION" | "HIGHVALUE_CLUE" | "IDCARD_INFORMATION" | "IMPRESSION_LEVEL_AD_REVENUE" | "INITIATE_ORDER" | "INSTALL_FINISH" | "INTENTION_CLUE" | "INVALID_CLUE" | "IN_APP_AD_CLICK" | "IN_APP_AD_IMPR" | "IN_APP_CART" | "IN_APP_DETAIL_UV" | "IN_APP_ORDER" | "IN_APP_PAY" | "IN_APP_UV" | "LANDING_PAGE_VIEW" | "LAUNCH_APP" | "LIKE_ACTION" | "LINK_ACTION" | "LIVE_APPOINTMENT" | "LIVE_CARD_CLICK" | "LIVE_CLICK_PRODUCT_ACTION" | "LIVE_COMMENT_ACTION" | "LIVE_ENTER_ACTION" | "LIVE_FOLLOW_ACTION" | "LIVE_GIFT_ACTION" | "LIVE_HOMEPAGE" | "LIVE_JOIN_GROUP" | "LIVE_NATIVE_ACTION" | "LIVE_REDIRECT_TO_STORE_ACTION" | "LIVE_ROOM_ACTION" | "LIVE_SLIDECART_CLICK_ACTION" | "LIVE_STAY_TIME" | "LIVE_SUCCESSORDER_ACTION" | "LIVE_SUCESSORDER_PAY" | "LOAN" | "LOAN_APPLY" | "LOAN_COMPLETION" | "LOAN_CREDIT" | "LOCATION_ACTION" | "LOGIN" | "LOGIN_ACTION" | "LONGTERM_CUSTOMER" | "LOTTERY" | "LT_ROI" | "MAP_SEARCH" | "MESSAGE" | "MESSAGE_ACTION" | "MESSAGE_CLICK" | "MESSAGE_CLUE" | "MESSAGE_JOIN_GROUP" | "MESSAGE_SELF_SERVICE" | "MESSAGE_SEND" | "MULTIPLE" | "MULTI_NATIVE_ACTION" | "NATIVE_ACTION" | "NAV_BAR" | "NEW_FOLLOW_ACTION" | "NEXT_DAY_OPEN" | "NOVEL_CHAPTER" | "ON_WEB_ADD_TO_WISHLIST" | "ON_WEB_CART" | "ON_WEB_DETAIL" | "ON_WEB_ORDER" | "ON_WEB_REGISTER" | "ON_WEB_SEARCH" | "ON_WEB_SUBSCRIBE" | "OTHER" | "OTO_PAY" | "OTO_STAY_TIME" | "PAGE_VIEW" | "PAGE_VISIT" | "PAID_CLUE" | "PAY_ACTION" | "PERSONAL_INFORMATION" | "PHONE" | "PHONE_BUTTON" | "PHONE_CONFIRM" | "PHONE_CONNECT" | "PHONE_DETAIL" | "PHONE_EFFECTIVE" | "PREFERRED_LEAD" | "PREMIUM_PAYMENT" | "PRE_LOAN_CREDIT" | "PURCHASE_OF_GOODS" | "PURCHASE_ROI" | "QQ" | "RATE" | "READING_TIME" | "REDIRECT" | "REDIRECT_TO_SHOP" | "REDIRECT_TO_STORE" | "REGISTER_ACTION" | "RESERVATION" | "RSS" | "SALES_LEAD" | "SCHEDULE" | "SEARCH" | "SEVEN_DAY_OPEN" | "SHARE_ACTION" | "SHOPPING" | "SHOPPING_ACTION" | "SHOPPING_CART" | "START_TRIAL" | "STAY_TIME" | "SUBMIT_APPLICATION" | "SUBSCRIBE" | "SUCCESSORDER_ACTION" | "SUCCESSORDER_PAY" | "UG_EFFECTIVE_ACTION" | "UG_EFFECTIVE_DEAL" | "UG_EFFECTIVE_SHARE" | "UG_EFFECTIVE_SPEECH" | "UG_ROI" | "UNLOCK_ACHIEVEMENT" | "UPDATE_LEVEL" | "VIEW" | "VOTE" | "XPATH")
Deep-funnel optimization event.
string ("OFF" | "ON" | "UNSET")
Deep-funnel optimization status.
string ("FOURTEEN_DAYS" | "OFF" | "ONE_DAY" | "SEVEN_DAYS" | "TWENTY_EIGHT_DAYS" | "UNSET")
Engaged-view attribution window.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_SMART_PLUS_CAMPAIGNCreate a Smart+ campaign disabled for review. Use the separate Smart+ campaign status tool to enable it after review.

Input Parameters

string
Optional promoted application ID.
number
Optional campaign budget.
string
Optional purchase order number.
string
required
Client deduplication request ID.
string ("BUDGET_MODE_DYNAMIC_DAILY_BUDGET" | "BUDGET_MODE_TOTAL")
Optional campaign budget mode.
string ("ECOMMERCE" | "MINI_SERIES" | "TRAVEL_ENTERTAINMENT")
Optional Smart+ catalog type.
string
required
Authorized advertiser account ID.
string
required
Name for the new Smart+ campaign.
string ("IOS14_CAMPAIGN" | "REGULAR_CAMPAIGN")
Optional dedicated campaign type: regular or iOS 14 campaign.
string ("SAN" | "SKAN" | "UNSET")
Optional bid attribution alignment type.
string ("APP_PROMOTION" | "LEAD_GENERATION" | "WEB_CONVERSIONS")
required
Campaign objective type.
boolean
Whether catalog use is enabled for the campaign.
string
Optional Open API partner identifier.
string
Initial campaign status. Only DISABLE is accepted so the campaign is created paused for review.
string
Optional campaign sales destination.
string
Optional application promotion type.
boolean
Whether campaign budget optimization is on.
array
Optional regulated-industry categories: CREDIT, EMPLOYMENT, or HOUSING.
string ("POSTBACK_WINDOW_MODE1" | "POSTBACK_WINDOW_MODE2" | "POSTBACK_WINDOW_MODE3")
Controls when TikTok reclaims campaign quota after the campaign is paused or deleted: POSTBACK_WINDOW_MODE1 after 4 days, MODE2 after 13 days, or MODE3 after 41 days.
boolean
Whether SKAdNetwork campaign behavior is disabled.
boolean
Whether this is a promotional campaign.
boolean
Whether this is an advanced dedicated campaign; TikTok defaults this to true.
string ("OFF" | "ON")
Whether the promoted app’s profile page is ON or OFF for this campaign.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_SMART_PLUS_CAMPAIGN_COPY_TASKCreate and start an asynchronous copy task for an Upgraded Smart+ campaign. The copied campaign defaults to DISABLE, but copied ad groups and copied ads default to ENABLE. To keep all copied resources ineligible for delivery and spend, explicitly set operation_status to DISABLE on the campaign and on every copied ad group and ad; otherwise provider defaults may enable nested resources.

Input Parameters

number
Copied campaign budget.
string
Seven-day delivery grid containing exactly 48 x 7 characters.
string
required
Idempotency request ID cached for 10 seconds.
string
required
Source Upgraded Smart+ campaign ID.
array
Ad groups to customize (maximum 10).
string
required
Advertiser account ID.
string
Copied campaign name (maximum 512 characters).
string ("SCHEDULE_START_END" | "SCHEDULE_FROM_NOW")
Schedule mode for all copied ad groups.
string ("DEFAULT" | "CUSTOM")
DEFAULT or CUSTOM deep-copy mode.
string ("ENABLE" | "DISABLE")
Copied campaign status.
string
UTC schedule end in YYYY-MM-DD HH:MM:SS format.
string
UTC schedule start in YYYY-MM-DD HH:MM:SS format.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_SPLIT_TESTCreate an ad-group or campaign-level split test. Campaign-level tests may require allowlisting.

Input Parameters

array
Exactly two split-test cells; required for CAMPAIGN tests.
number
Total test budget; required for ADGROUP and forbidden for CAMPAIGN tests.
string
required
End time in YYYY-MM-DD HH:MM:SS UTC.
string
Key metric to monitor from TikTok’s documented metric enumeration.
array
Ad group IDs; for ADGROUP tests provide this or cells.
string
required
Start time in YYYY-MM-DD HH:MM:SS UTC.
string
required
Advertiser ID.
string ("BIDDING_OPTIMIZATION" | "TARGTING" | "CREATIVE" | "CUSTOM")
Test variable; defaults provider-side by split-test level.
string ("ADGROUP" | "CAMPAIGN")
ADGROUP or CAMPAIGN split-test level.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_CREATE_VIDEO_FIX_TASKSCreate up to 10 Smart Fix tasks for advertiser-owned videos.

Input Parameters

array
required
Smart Fix tasks (1-10).
string
required
Advertiser account ID that owns the videos.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_DELETE_BC_ASSET_ADMINRemove a single lead or TikTok account asset from a Business Center. This revokes the Business Center relationship and can move a lead asset back to its prior ad account.

Input Parameters

string
required
Business Center ID.
array
required
Single asset ID to remove from the Business Center.
string ("LEAD" | "TT_ACCOUNT")
required
Type of the asset being removed.
string
Optional child Business Center ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_DELETE_BC_MEMBERRemove an existing member from the Business Center or revoke a pending invitation. This revokes access or invalidates the invitation; confirm the exact disposable user ID or email before calling.

Input Parameters

string
required
Business Center ID.
string
Existing member’s user ID when removing a member.
string
Invited user’s email when revoking an invitation.
string
Optional child Business Center ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_DELETE_BC_PARTNERRemove the partner relationship from the Business Center. This revokes the partner relationship and associated access; confirm both exact disposable Business Center IDs before calling.

Input Parameters

string
required
Business Center ID.
string
required
Partner Business Center ID to remove.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_DELETE_BC_PARTNER_ASSETCancel sharing the specified assets with the partner Business Center. The partner loses access to those assets; confirm the exact disposable partner and asset IDs before calling.

Input Parameters

string
required
Business Center ID.
array
required
Asset IDs whose sharing relationship will be cancelled.
string ("ADVERTISER" | "CATALOG" | "LEAD" | "PIXEL" | "TIKTOK_SHOP" | "TT_ACCOUNT")
required
Type shared by all specified assets.
string
required
Partner Business Center ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_DELETE_BLOCKEDWORDDestructively remove exact words from an advertiser’s moderation block list. Confirm the advertiser and disposable targets before calling; comments containing removed words may no longer be flagged.

Input Parameters

string
required
Advertiser ID whose moderation list will change.
array
required
Exact words to remove from the blocked-word list.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_DELETE_BUSINESS_CENTER_ASSET_GROUPDelete one Asset Group from a TikTok Business Center. This destructive operation revokes members’ access to the grouped assets, but does not delete the underlying members or assets.

Input Parameters

string
required
Business Center ID containing the Asset Group to delete.
array
required
Exactly one Asset Group ID to delete. This revokes members’ access to the grouped assets without deleting the members or assets.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_DELETE_CATALOGPermanently delete a catalog from a Business Center.

Input Parameters

string
required
ID of the Business Center that owns the catalog.
string
required
ID of the catalog to delete.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_DELETE_CATALOG_FEEDPermanently delete a catalog feed.

Input Parameters

string
required
Business Center ID.
string
required
Feed ID to delete.
string
required
Catalog ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_DELETE_CATALOG_PRODUCTRemove products from a catalog using the ID list for that catalog type.

Input Parameters

string
required
Business Center ID.
string
Feed ID; omit to process the default catalog.
array
E-commerce SKU IDs to delete, at most 1,000.
array
Generic catalog item IDs to delete, at most 10,000.
array
Hotel IDs to delete, at most 1,000.
string
required
Catalog ID.
array
Flight IDs to delete, at most 1,000.
array
Mini-series IDs to delete, at most 1,000.
array
Online-to-offline listing IDs to delete, at most 10,000.
array
Vehicle IDs to delete, at most 1,000.
array
Destination IDs to delete, at most 1,000.
array
Entertainment media-title IDs to delete.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_DELETE_CATALOG_SETPermanently delete one to ten catalog product sets.

Input Parameters

string
required
Business Center ID.
string
required
Catalog ID.
array
required
One to ten product set IDs to delete.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_DELETE_CATALOG_VIDEOPermanently delete one uploaded video from an E-commerce catalog. This does not remove copies already synchronized to advertiser creative libraries.

Input Parameters

string
required
Business Center ID that owns the E-commerce catalog.
string
required
E-commerce catalog ID containing the uploaded video.
array
required
Exactly one uploaded catalog video ID to delete.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_DELETE_COMMENTPermanently delete one of your own comments on a TikTok ad created by a Customized User or TTBA identity. Confirm the advertiser, ad, video, identity, and comment IDs before calling; deletion cannot be undone.

Input Parameters

string
required
Ad ID associated with the comment.
string
required
Exact comment ID to delete.
string
required
Identity ID authorized to manage the comment.
string
required
Advertiser ID that owns the ad.
string ("CUSTOMIZED_USER" | "TT_USER")
required
Managing identity type: CUSTOMIZED_USER or TT_USER.
string
required
TikTok video ID containing the comment.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_DELETE_CREATIVE_ASSETSDelete video or image assets owned by a TikTok advertiser account. Some requested assets may fail to delete; the response can include their IDs.

Input Parameters

array
Image IDs to delete (1-50 when supplied).
array
Video IDs to delete (1-50 when supplied).
string
required
Advertiser account ID that owns the assets.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_DELETE_CREATIVE_PORTFOLIOPermanently delete up to 100 eligible creative portfolios. Use only explicitly confirmed disposable targets; one invalid ID fails the batch.

Input Parameters

string
required
Advertiser ID that owns the portfolios.
array
required
IDs of 1-100 disposable creative portfolios to permanently delete. Product Card, Product Tile, and CTA portfolios cannot be deleted by this endpoint. TikTok rejects the entire request if any ID does not exist or was already deleted; confirm every target before calling.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_DELETE_CUSTOM_CONVERSIONDelete a Custom Conversion configuration; this does not delete ingested events.

Input Parameters

string
required
Advertiser ID.
string
required
Custom Conversion ID to delete.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_DELETE_DMP_CUSTOM_AUDIENCEDelete between one and 100 custom audiences.

Input Parameters

string
required
Advertiser ID.
array
required
Audience IDs to delete (1-100).

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_DELETE_DMP_SAVED_AUDIENCEDelete up to 100 Saved Audiences.

Input Parameters

string
required
Advertiser ID.
array
required
Saved Audience IDs to delete (maximum 100).

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_DELETE_GMV_MAX_CAMPAIGN_SESSIONPermanently delete a GMV Max session from an advertiser account.

Input Parameters

string
required
GMV Max session ID to delete.
string
required
Authorized advertiser account ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_DELETE_GMV_MAX_CUSTOMIZED_POSTSPermanently delete shop-level customized TikTok posts.

Input Parameters

string
required
TikTok Shop store ID.
string
Product GMV Max campaign ID. This is required by TikTok when any specified item_id was used to create a campaign-level customized post. Obtain it by listing campaigns with the PRODUCT_GMV_MAX promotion-type filter.
string
required
Authorized advertiser account ID.
string
required
Business Center ID authorized for the TikTok Shop.
array
required
Customized TikTok posts to delete (maximum 200).

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_DELETE_IDENTITYPermanently delete a customized user identity from an advertiser account.

Input Parameters

string
required
Customized user identity ID to delete.
string
required
Advertiser ID that owns the identity.
string
required
Identity type; TikTok supports only CUSTOMIZED_USER for deletion.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_DELETE_OFFLINEDelete an Offline Event Set configuration; this is not an event-ingestion operation.

Input Parameters

string
required
Offline Event Set ID to delete.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_DELETE_PAGE_LEAD_MOCKPermanently delete one exact disposable TikTok test lead. Confirm the owner and lead ID before calling.

Input Parameters

string
required
Exact disposable test-lead ID to delete.
string
Form library ID when the test lead belongs to a Business Center.
string
Advertiser ID when the test lead belongs to an ad account.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_DELETE_PIXEL_EVENTDelete a Pixel Event configuration; this does not delete ingested event occurrences.

Input Parameters

string
required
Configured Pixel Event ID from LIST_PIXEL.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_DELETE_PLAYABLEPermanently delete one exact playable asset. Confirm the advertiser and a disposable playable ID before calling.

Input Parameters

string
required
Exact disposable playable asset ID to delete.
string
required
Advertiser ID that owns the playable asset.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_DELETE_SEARCH_AD_NEGATIVE_KEYWORDSDelete negative keywords from one Search Ads campaign or ad group in an authorized advertiser account.

Input Parameters

string
required
Campaign or ad-group ID that owns the keywords.
array
required
Negative-keyword IDs to delete.
string ("CAMPAIGN" | "ADGROUP")
required
Whether object_id identifies a campaign or ad group.
string
required
Authorized advertiser account ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_DELETE_SMART_PLUS_RESOURCESPermanently delete up to 20 Smart+ campaigns, ad groups, or ads. Deletion may partially succeed; inspect the returned results.

Input Parameters

array
required
Smart+ campaign, ad group, or ad IDs to delete (1-20).
string
required
Advertiser ID that owns the resources.
string ("CAMPAIGN" | "ADGROUP" | "AD")
required
Type of Smart+ resource identified by resource_ids.
string ("POSTBACK_WINDOW_MODE1" | "POSTBACK_WINDOW_MODE2" | "POSTBACK_WINDOW_MODE3" | "UNSET")
Optional campaign postback window mode; valid only for CAMPAIGN.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_DISABLE_BUSINESS_CENTER_ADVERTISERIrreversibly disable one ad account in a TikTok Business Center. TikTok may reject accounts that are delivering ads, suspended, unpaid, mid-transfer, or have unbilled autopay charges.

Input Parameters

string
required
Business Center ID that contains the ad account.
array
required
Ad account ID to disable. TikTok requires exactly one ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_DISCOVER_SEARCH_KEYWORD_IDEASDiscover search keyword ideas and historical search metrics.

Input Parameters

array
required
One to ten English seed keywords.
string ("BRAND" | "NON_BRAND" | "ALL")
Brand classification filter.
string ("ASC" | "DESC")
Keyword idea sorting order.
string ("AVG_MONTHLY_SEARCHES" | "THREE_MONTH_CHANGE" | "YEAR_OVER_YEAR_CHANGE" | "COMPETITION")
Field used to sort keyword ideas.
string
required
Advertiser ID.
array
Single target country or region code.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_DOWNLOAD_BC_INVOICEDownload one Business Center invoice. The file contains finance-sensitive billing data; confirm the Business Center and invoice IDs, obtain authorization to access the invoice, and store or share the returned file only in an approved location.

Input Parameters

string
required
Business Center ID.
string
required
Invoice ID to download.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_DOWNLOAD_BLOCKEDWORD_TASKDownload the result of a succeeded blocked-word export task. Confirm the advertiser and task IDs and store the moderation data only in an approved location.

Input Parameters

string
required
Succeeded blocked-word export task ID.
string
required
Advertiser ID that owns the export task.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_DOWNLOAD_COMMENT_TASKDownload CSV content from a succeeded comment export task. The file can contain public user content and identifiers; confirm the advertiser and task, then store or share it only in an approved location.

Input Parameters

string
required
Succeeded comment export task ID.
string
required
Advertiser ID that owns the export task.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_DOWNLOAD_PAGE_LEAD_TASKDownload the CSV or ZIP produced by a completed TikTok lead export task. The file contains customer lead data, expires about 10 minutes after generation, and must be stored or shared only in an approved location.

Input Parameters

string
required
Completed lead download task ID.
string
Form library ID when leads are under a Business Center.
string ("eu" | "us")
Use eu for EEA/Switzerland/UK leads, us for US leads, or omit for other regions.
string
Advertiser ID when leads are under an ad account.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_DOWNLOAD_REPORT_TASKRetrieve output for a successful asynchronous report task: temporary download URL metadata for CSV_DOWNLOAD or XLSX_DOWNLOAD tasks, or inline UTF-8 CSV content for CSV_STRING tasks. Responses larger than 4,000,000 bytes are rejected.

Input Parameters

string
required
Successful asynchronous report task ID.
string
required
Advertiser ID associated with the task.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_DOWNLOAD_SEARCH_AD_NEGATIVE_KEYWORDDownload negative keywords for a campaign or ad group. Returns a spreadsheet file reference for file responses or TikTok’s result data for successful JSON responses.

Input Parameters

string
required
Campaign or ad-group ID whose negative keywords to download.
string ("CAMPAIGN" | "ADGROUP")
required
Whether object_id identifies a campaign or ad group.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_EDIT_CREATIVE_IMAGEResize or Gaussian-pad an advertiser image.

Input Parameters

integer
required
Edited image width, at least 3 pixels.
integer
required
Edited image height, at least 3 pixels.
string
required
Image ID.
string
Edited image name; TikTok generates one when omitted.
string ("fix_size" | "only_gauss_pad" | "gauss_padding_reserve_score")
Image editing method.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_END_SPLIT_TESTEnd an in-progress split test. This transition is irreversible.

Input Parameters

string
required
Advertiser ID.
string
required
Split test group ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_ESTIMATE_AD_AUDIENCE_SIZEEstimate audience size for documented placement, promotion, and targeting settings. Availability may depend on account entitlement.

Input Parameters

string
Promoted app ID; required for APP_PROMOTION.
string ("GENDER_FEMALE" | "GENDER_MALE" | "GENDER_UNLIMITED")
Target gender.
array
Behavior targeting objects.
array
Internet service provider IDs.
string
Pixel ID; provide with external_action when applicable.
array
Target language codes.
array
Target age groups.
string
Catalog ID; required for PRODUCT_SALES.
array
Placements; required for selected placement.
array
Target carrier IDs.
array
Target ZIP or postal code IDs.
array
Included custom audience IDs.
array
Target location IDs.
string
required
Advertiser ID.
object
Audience rule for TRAFFIC or WEB_CONVERSIONS.
string
App-retargeting audience type.
array
Target connection types.
string
required
Advertising objective code.
string ("PLACEMENT_TYPE_AUTOMATIC" | "PLACEMENT_TYPE_NORMAL")
Placement type.
string
Product set ID; 0 selects all product sets.
string ("UNSET" | "CATALOG" | "STORE")
Product source; required for PRODUCT_SALES.
string
Promotion type; required for PRODUCT_SALES.
string ("ALL" | "HIGH")
Target spending power.
string ("UNSET" | "IOS14_MINUS" | "IOS14_PLUS")
iOS targeting mode.
string
Minimum iOS version.
array
Target device model IDs.
array
Target household-income bands.
array
Target operating system; at most one.
string
required
Optimization goal code.
array
Contextual tag IDs.
array
Device price range boundaries in multiples of 50.
string
Minimum Android version.
object
Deprecated targeting-expansion settings.
array
Interest keyword IDs.
array
Excluded custom audience IDs.
array
Interest category IDs.
boolean
Deprecated automated-targeting switch.
array
Blocked Pangle app IDs.
array
Excluded LAB3 audience actions.
array
Included LAB3 audience actions.
string
Business Center ID for a Business Center catalog.
string ("LAB1" | "LAB2" | "LAB3" | "OFF")
Shopping Ads retargeting type.
array
Purchase-intention keyword IDs.
array
Excluded Pangle audience package IDs.
array
Included Pangle audience package IDs.
integer ("1" | "2" | "3" | "7" | "14" | "30" | "60" | "90" | "180")
Shopping retargeting lookback days.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_ESTIMATE_RF_INVENTORYGet inventory estimates. Availability may depend on TikTok allowlisting or account entitlement.

Input Parameters

number
Budget. Required when rf_purchased_type = FIXED_BUDGET. Based on the budget amount that you specify, we will return the estimated values for other fields.
string ("STANDARD_FEED" | "TOP_FEED")
Feed type option. Enum values: STANDARD_FEED, TOP_FEED. STANDARD_FEED refers to large inventory with normal CPM price while TOP_FEEDrefers to limited inventory with higher CPM price.
integer
required
Frequency. This parameter, together with the frequency_schedule parameter, determines the upper limit for how frequently an ad is shown to users (only for R&F ads). For example, if frequency = 2 and frequency_schedule = 3, it means the ad will be displayed at most twice every 3 days. The following conditions should be met:1 ≤ frequency ≤ frequency_schedule1 ≤ frequency_schedule ≤ min(schedule_end_time - schedule_start_time, 30). The frequency cap determined by frequency and frequency_schedule does not exceed four times a day.
string
required
Advertiser ID
object
required
Audience targeting rules
string
required
The advertising objective. Enum values: RF_REACH.
integer
Number of users reached to be purchased, in the unit of 1,000. Required when rf_purchased_type = FIXED_REACH. Based on the reach amount that you specify, we will return the estimated values for other fields.
string ("STANDARD" | "PULSE")
When objective_type is specified as RF_REACH, use this field to set the campaign as a TikTok Pulse campaign, then you can get available premium contextual tags. Enum values: STANDARD (Reach & Frequency campaign), PULSE (TikTok Pulse campaign). If you set this field as PULSE, only one location ID (location_id) will be returned. Note: Do not pass in this field when objective_type is not specified as RF_REACH.You need to pass the location_id value returned in this endpoint to location_ids when you use /adgroup/rf/create/ to create a TikTok Pulse ad group.
string ("FIXED_SHOW" | "FIXED_REACH" | "FIXED_BUDGET")
Buying type. Allowed values: FIXED_SHOW: Purchase to achieve a fixed amount of impressions.FIXED_REACH: Purchase to reach a fixed number of users.FIXED_BUDGET: Purchase with a fixed budget.
string
required
End time (UTC+0): format “YYYY-MM-DD HH:MM:SS”. The HH:MM:SS value must be equal to 23:59:59 for the target region. For example, 2020-11-11 04:59:59 is equal to 2020-11-10 23:59:59 in the UTC-5 time zone. The time interval between schedule_end_time and schedule_start_time must not exceed 30 days. Note: If the targeting locations (location_ids) you specify observe Daylight Saving Time, ignore Daylight Saving Time and pass in Standard Time. For example, if you want to end the schedule for the Netherlands at 2022-11-02 23:59:59 local time (Daylight Saving Time has started, UTC+2 timezone) , you need to regard the time zone of the Netherlands as Standard Time Zone (UTC+1) and specify this field as 2022-11-02 22:59:59.
string ("SIX_SECONDS" | "TWO_SECONDS")
The target video view duration. Enum values: SIX_SECONDS, TWO_SECONDS.
integer
required
Frequency cycle (in days). This parameter, together with the frequency parameter, determines the upper limit for how frequently an ad is displayed to users (only for R&F ads). Please see the description for the frequency field.
string
required
Start time (UTC+0): format “YYYY-MM-DD HH:MM:SS”. The HH:MM:SS value must be equal to 00:00:00 for the target region. For example, 2020-10-24 05:00:00 is equal to 2020-10-24 00:00:00 in the UTC-5 time zone. Note: If the targeting locations (location_ids) you specify observe Daylight Saving Time, ignore Daylight Saving Time and pass in Standard Time. For example, if you want to start the schedule for the Netherlands at 2022-04-02 00:00:00 local time (Daylight Saving Time has started, UTC+2 timezone), you need to regard the time zone of the Netherlands as Standard Time Zone (UTC+1) and specify this field as 2022-04-02 23:00:00.
integer
Impressions to be purchased, in the unit of 1,000. Required when rf_purchased_type = FIXED_SHOW. Based on the impression amount that you specify, we will return the estimated values for other fields.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GENERATE_CREATIVE_SMART_TEXTGenerate Smart Text recommendations for an ad group.

Input Parameters

integer
Number of generated texts (1-20).
array
Non-empty keywords; required for CUSTOMIZED parameters.
string ("EN" | "JA" | "RU" | "VI")
Language; required for CUSTOMIZED parameters.
string
required
Ad group ID.
string ("RECOMMENDED" | "CUSTOMIZED")
Whether TikTok predicts or the caller supplies parameters.
string
Industry ID.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_ACCOUNT_VERIFICATIONCheck the verification status of an ad account or Business Center.

Input Parameters

string
Business Center ID. Provide this or advertiser_id, but not both.
string
Ad account ID. Provide this or bc_id, but not both.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_ACCOUNT_VERIFICATION_FILETYPEGet available verification document types for a region.

Input Parameters

string ("BUSINESS" | "INDIVIDUAL")
required
The verification type: BUSINESS or INDIVIDUAL.
string
required
Country or region code in ISO 3166 format, such as US.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_AD_BENCHMARK_REPORTGet one page of ad benchmark dimensions and dynamic numeric metrics, scoped by exactly one ad_ids, adgroup_ids, or campaign_ids filter.

Input Parameters

integer
Result page number.
object
required
Exactly one ad, ad group, or campaign ID filter.
integer
Results per page.
string
Provider-supported benchmark sort type; no fixed enum is verified.
array
required
Benchmark dimensions to return. Retained, provider-reported accepted examples are AD_CATEGORY, EXTERNAL_ACTION, LOCATION, and PLACEMENT; no complete enum has been independently verified.
string
Provider field name to sort by. No sort-field vocabulary is independently verified.
string
required
Advertiser account ID.
array
Provider field names for benchmark metrics to return as dynamic numeric values. No complete metric vocabulary is verified.
string
Benchmark comparison time window sent as a string. Retained, provider-reported examples are 7, 14, 30, and 60; no complete enum has been independently verified.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_ADDITIONAL_INTEREST_CATEGORIESGet up to 50 additional interest categories by ID and language.

Input Parameters

object
Audience-type filtering conditions.
string
required
Advertiser ID.
array
required
Additional interest categories to retrieve (1-50).

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_ADGROUP_DIAGNOSESGet issue diagnoses and suggestions for active ad groups, optionally filtering by ad-group IDs and issue category.

Input Parameters

object
Diagnosis filtering conditions.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_ADGROUP_QUOTAGet the dynamic quota on active ad groups.

Input Parameters

string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_ADGROUP_REVIEWGet review info of ad groups.

Input Parameters

string
Language.
array
required
The list of ad group IDs. Currently, we support a maximum of 20 ad group IDs in the request.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_ADGROUP_RF_ESTIMATEDGet estimated info of R&F ad groups.

Input Parameters

array
required
Ad group ids
string
required
Advertiser id

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_AD_REVIEWGet review information for one to 100 ads.

Input Parameters

string
Language.
array
required
Ad IDs to review (1-100).
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_ADVERTISER_ACCOUNTSGet advertiser account profiles for specified IDs, or discover authorized accounts using stored OAuth advertiser IDs or app credentials. Discovery requires one of those metadata sources and may return either profiles or account summaries.

Input Parameters

array
Advertiser information fields to return; omit for TikTok’s default field set.
array
Authorized advertiser account IDs whose full profiles to retrieve. Omit to discover every advertiser account authorized for this connection.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_APPGet information about a mobile app configured for an advertiser.

Input Parameters

string
required
App ID.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_APP_OPTIMIZATION_EVENTGet app conversion events available for advertising optimization.

Input Parameters

string
required
App ID.
boolean
Whether the app uses SKAdNetwork features.
string
Advertising objective.
array
Apps where ads will be delivered; conditionally required for normal placement.
string
required
Advertiser ID.
boolean
Whether to return only available conversion events.
string
Placement strategy: PLACEMENT_TYPE_AUTOMATIC or PLACEMENT_TYPE_NORMAL.
string
required
Optimization goal.
string
App promotion type, conditionally required for app-promotion objectives.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_APP_OPTIMIZATION_EVENT_RETARGETINGGet app retargeting events available for audience rules.

Input Parameters

string
required
App ID.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_ASSET_BINDING_QUOTAGet ad binding quota usage for a TikTok identity asset in an advertiser account.

Input Parameters

string
required
Identity asset ID whose binding quota to retrieve.
string
required
Asset type. TikTok currently supports only IDENTITY.
string
required
Advertiser ID whose asset binding quota to retrieve.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_AUDIENCE_INSIGHTGet overlap details for a benchmark custom audience and up to four comparison audiences.

Input Parameters

string
required
Advertiser ID.
string
required
Accessible custom audience ID used as the benchmark.
array
Accessible comparison audience IDs (maximum 4).

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_AUDIENCE_INSIGHTSGet one audience insight dimension for locations or a custom audience.

Input Parameters

array
Locations (maximum 5); mutually exclusive with custom_audience_id.
array
required
Single response dimension.
string
required
Advertiser ID.
object
Audience targeting filters.
string
Custom audience ID; mutually exclusive with locations and selected_audience.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_BC_ASSET_ADMINGet one page of assets administered by a Business Center.

Input Parameters

integer
Initial page number.
string
required
Business Center ID.
object
Optional structured asset filtering conditions.
integer
Assets per page (1-50).
string ("ADVERTISER" | "CATALOG" | "TIKTOK_SHOP" | "PIXEL" | "LEAD" | "TT_ACCOUNT" | "MANAGED_BUSINESS_ACCOUNT")
required
Asset type: ADVERTISER, CATALOG, TIKTOK_SHOP, PIXEL, LEAD, TT_ACCOUNT, or MANAGED_BUSINESS_ACCOUNT.
string
Optional child Business Center ID.
string
Opaque continuation token from a previous response; resend the same filtering object when continuing a filtered listing.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_BC_ASSET_MEMBERGet one page of Business Center members assigned to an asset.

Input Parameters

integer
Initial page number.
string
required
Business Center ID.
string
required
Asset ID whose assigned members to return.
object
Optional member filtering conditions.
integer
Members per page (1-20).
string ("ADVERTISER" | "CATALOG" | "LEAD" | "MANAGED_BUSINESS_ACCOUNT")
required
Asset type for advertiser, catalog, lead, or managed business account.
string
Opaque continuation token from a previous response; resend the same filtering object when continuing a filtered listing.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_BC_INVOICEReturn one page of Business Center invoices using type, payment, title, ID, and issuance-time filters. TikTok makes these invoices available to the Business Center’s Finance Managers and Finance Analysts; results may contain sensitive invoice, tax, address, and balance data.

Input Parameters

integer
Initial page number.
string
required
Business Center ID.
string
Invoice issuance range end in YYYY-MM-DD HH:MM:SS format; provide with start_time.
integer
Invoices per page (1-50).
string
Invoice ID filter.
string
Invoice issuance range start in YYYY-MM-DD HH:MM:SS format; provide with end_time.
string
Opaque continuation token returned by a previous call.
array
Payment statuses to include.
string
Invoice title filter.
array
required
Invoice types to return. AUTO_PAY must be the only value when used; other supported values are RECON and CREDIT.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_BC_INVOICE_TASKGet the status and available download URL of an asynchronous Business Center billing report task.

Input Parameters

string
required
Business Center ID.
string
required
Asynchronous invoice download task ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_BC_INVOICE_UNPAIDRead the reconciliation-invoice unpaid amount for a Business Center. This exposes finance-sensitive balance data; confirm the Business Center and limit disclosure of the returned amount and currency to authorized recipients.

Input Parameters

string
required
Business Center ID.
string
required
Invoice type. TikTok supports RECON for reconciliation invoices.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_BC_PARTNER_ASSETGet one page of assets shared with or by a partner Business Center.

Input Parameters

integer
Initial page number.
string
required
Business Center ID.
object
Optional partner-asset filtering conditions.
integer
Assets per page (1-50).
string ("ADVERTISER" | "CATALOG")
required
Partner asset type.
string
required
Partner Business Center ID.
string ("SHARED" | "SHARING")
required
Share direction: shared with this BC or shared by this BC.
string
Opaque continuation token from a previous response; resend the same filtering object when continuing a filtered listing.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_BID_PROTECTION_DETAILSGet bid protection history and ad credits for specified Upgraded Smart+ campaigns or ad groups over a date range. The start date must be within the past 60 days, and the number of IDs accepted depends on the date range.

Input Parameters

string
required
Inclusive end date in YYYY-MM-DD format.
array
required
Campaign or ad group IDs to query. All IDs must belong to advertiser_id. The maximum count is floor(200 / date difference), with a minimum denominator of one day.
string ("CAMPAIGN" | "ADGROUP")
required
Level of the requested bid protection history.
string
required
Inclusive start date in YYYY-MM-DD format.
string
required
Authorized advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_BID_PROTECTION_STATUSESGet bid protection statuses for up to 200 Upgraded Smart+ campaigns or ad groups.

Input Parameters

array
required
One to 200 campaign or ad group IDs belonging to advertiser_id.
string ("CAMPAIGN" | "ADGROUP")
required
Level of the requested bid protection statuses.
string
required
Authorized advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_BRAND_SAFETY_PARTNER_AUTHORIZATION_STATUSGet the Brand Safety measurement partner authorization status for Zefr for an advertiser.

Input Parameters

string
Brand Safety post-bid measurement partner. The supported value is Zefr.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_BUSINESS_CENTER_ADVERTISER_ATTRIBUTESGet currencies and registration regions available when creating ad accounts in a Business Center.

Input Parameters

string
required
Business Center ID whose supported advertiser attributes to retrieve.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_BUSINESS_CENTER_ASSET_GROUPGet the assets or members of an Asset Group in a Business Center.

Input Parameters

integer
Initial result page to retrieve (1 or greater).
string
required
Business Center ID containing the Asset Group.
string
Optional keyword passed in TikTok’s structured filtering object for the requested ASSET or MEMBER collection.
integer
Number of assets or members to return in this page (1 or greater).
string
Opaque continuation token returned by a previous call; omit for the first page and pass it back unchanged for the next page.
string ("ASSET" | "MEMBER")
required
Entity collection to retrieve: ASSET or MEMBER.
string
required
Asset Group ID whose assets or members to retrieve.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_BUSINESS_CENTER_BALANCERead the balance of a TikTok Business Center or Payment Portfolio. This action only retrieves financial information and never funds an account.

Input Parameters

string
required
Business Center ID whose balance to retrieve.
string
Payment Portfolio ID whose balance to retrieve. Use a portfolio belonging to the same client as the specified Business Center; omit this field to retrieve the Business Center’s own balance.
string
Optional child Business Center ID whose balance to retrieve under bc_id. Omit it when retrieving the parent Business Center or Payment Portfolio balance.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_CAMPAIGN_QUOTA_INFOGet SKAN Dedicated Campaign quota information by ad network.

Input Parameters

string
required
SKAN 4.0 app ID whose campaign quota to retrieve.
string
Optional ID of an ad group within a SKAN 4 campaign.
string
Optional SKAN campaign ID for campaign-specific quota information.
string
required
Advertiser account ID whose SKAN campaign quota to retrieve.
boolean
Whether to include advertiser-level campaign quota information.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_CATALOG_AVAILABLE_COUNTRYGet regions where ads for catalogs in a Business Center can be delivered.

Input Parameters

string
required
Business Center ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_CATALOG_CATEGORY_INSIGHTSGet up to 50 top trending product categories and availability metrics for an eligible E-commerce catalog, optionally filtered by category IDs.

Input Parameters

object
Optional category filter. Obtain category IDs from the filter endpoint.
string
required
Eligible E-commerce catalog ID containing at least 20 products.
string
required
Business Center ID that owns the eligible E-commerce catalog.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_CATALOG_EVENTSOURCE_BINDGet apps and pixels bound as event sources to a catalog.

Input Parameters

string
required
Business Center ID.
string
required
Catalog ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_CATALOG_FEEDGet all feeds in a catalog or one feed by ID.

Input Parameters

string
required
Business Center ID.
string
Feed ID to return. Omit to return every feed in the catalog.
string
required
Catalog ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_CATALOG_FEED_LOGGet processing log entries for the last 10 operations of a catalog feed.

Input Parameters

string
required
Business Center ID.
string
required
Feed ID whose log to return.
string
required
Catalog ID.
string
Optional provider context value. Pass the provider-issued string unchanged.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_CATALOG_INSIGHT_FILTERSGet one page of provider-approved category, brand, or availability filter values for product insight endpoints. TikTok returns no pagination metadata, so choose page and page_size explicitly when requesting additional pages.

Input Parameters

integer
Result page to request. TikTok returns no pagination metadata.
integer
Filter values to request (1-200); TikTok suggests 50 for a complete set.
string
required
Eligible E-commerce catalog ID containing at least 20 products.
string ("CATEGORY_ID" | "BRAND" | "AVAILABILITY")
required
Filter values to retrieve: category IDs, brands, or availability values.
string
required
Business Center ID that owns the eligible E-commerce catalog.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_CATALOG_LEXICONGet the provider-defined lexicon list for a catalog.

Input Parameters

string
required
Business Center ID.
string
required
Catalog ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_CATALOG_LOCATION_CURRENCYGet supported country or region and currency combinations for catalogs.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_CATALOG_OVERVIEWGet product audit totals for a catalog.

Input Parameters

string
required
Business Center ID.
string
required
Catalog ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_CATALOG_PRODUCTGet one page of catalog products with optional IDs, filters, and ordering.

Input Parameters

integer
Initial provider page number.
string
required
Business Center ID.
object
Product ordering settings. Encoded as TikTok’s JSON query object.
array
SKU IDs to retrieve (up to 1,000).
integer
Products per page (1-500).
string
required
Catalog ID.
object
Product filtering conditions. Encoded as TikTok’s JSON query object.
array
Short-drama series IDs to retrieve (up to 1,000).
string
Opaque continuation token from a previous call; omit for the first page.
array
Product IDs to retrieve (up to 1,000).
array
Product set IDs to retrieve (up to 100).
string ("AVAILABLE" | "ALL")
Return ad-available products or all products.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_CATALOG_PRODUCT_DIAGNOSTIC_TASKGet an asynchronous catalog product diagnostic task result.

Input Parameters

string
required
Business Center ID that owns the catalog.
string
required
Catalog product diagnostic task ID.
string
required
Catalog ID associated with the task.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_CATALOG_PRODUCT_LOGGet processing counts, errors, warnings, and download links for a product handling task.

Input Parameters

string
required
Business Center ID.
string ("en" | "zh-CN" | "ja-JP" | "de" | "es" | "fr" | "hi-IN" | "id" | "it" | "ko" | "ms" | "ru" | "th" | "tr" | "vi")
Language for log messages.
string
required
Catalog ID.
string
required
Product handling log ID.
string
Optional provider context value; pass it unchanged.
string
Optional advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_CATALOG_SETGet all product sets in a catalog or one product set by ID.

Input Parameters

string
required
Business Center ID.
string
required
Catalog ID whose product sets to return.
string
Optional product set ID.
boolean
Whether to calculate and return each set’s product count.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_CATALOG_SET_PRODUCTRequest one page of products in a catalog product set. The response must contain both a products list and a separate list for pagination validation.

Input Parameters

integer
Initial provider page number.
string
required
Business Center ID.
integer
Products per page (1-100).
string
required
Catalog ID.
string
Opaque continuation token; omit for the first page.
string
required
Product set ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_CATALOG_VIDEO_LOGGet processing counts, errors, warnings, and download URLs for a catalog video task.

Input Parameters

string
required
Business Center ID.
string ("en" | "zh-CN" | "ja-JP" | "de" | "es" | "fr" | "hi-IN" | "id" | "it" | "ko" | "ms" | "ru" | "th" | "tr" | "vi")
Language for log messages.
string
required
Catalog ID.
string
required
Catalog video handling log ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_CATALOG_VIDEO_PACKAGEGet catalog video packages, optionally restricted to one package ID.

Input Parameters

string
required
Business Center ID.
string
required
Catalog ID.
string
Optional catalog video package ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_CONTENT_EXCLUSION_CATEGORY_DETAILSGet details for content exclusion or vertical sensitivity category IDs.

Input Parameters

array
required
Content exclusion or vertical sensitivity category IDs.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_CONTEXTUAL_TAG_DETAILSGet details for specified contextual tag IDs.

Input Parameters

string
required
Advertiser ID.
array
required
Contextual tag IDs to retrieve.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_CREATIVE_ASSETSReturn metadata for specified video or image assets in an authorized advertiser’s Ads Asset Library.

Input Parameters

array
required
Video or image asset IDs to retrieve. Video requests support at most 60 IDs; image requests support at most 100 IDs.
string ("VIDEO" | "IMAGE")
required
Type of Ads Asset Library asset to retrieve.
string
required
Authorized advertiser account ID that owns or can access the assets.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_CREATIVE_PORTFOLIOGet a creative portfolio by ID. Availability may depend on TikTok entitlement.

Input Parameters

string
required
Advertiser ID.
string
required
Creative portfolio ID returned by portfolio creation.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_CREATIVE_PRE_REVIEW_TASKGet the result of a creative pre-review task.

Input Parameters

string
required
Creative pre-review task ID to retrieve.
string
required
Advertiser account ID that owns the creative pre-review task.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_CREATIVE_REPORTReturn one page of creative material performance with exact JSON-encoded filter and field-selection query parameters.

Input Parameters

integer
Initial provider page.
string
Inclusive end date in advertiser time zone.
boolean
Query lifetime data instead of a date range.
object
Creative filtering object, JSON-encoded into the query.
integer
Rows per page (1-1000).
string ("ASC" | "DESC")
Sort order.
string
Creation-time or metric field used for sorting.
string
Inclusive start date in advertiser time zone.
array
Documented creative information field names.
string
Opaque continuation token from a previous response.
string
required
Advertiser ID.
string ("VIDEO" | "IMAGE" | "INSTANT_PAGE")
required
Creative material type.
array
Documented creative metric or dimension field names.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_CTM_MESSAGE_EVENT_SETGet message event sets available for instant-messaging ad creation.

Input Parameters

string
required
Advertiser ID.
string
Exact message event set name to filter by.
string ("MESSENGER" | "WHATSAPP" | "ZALO")
required
Instant messaging app type.
array
Message event set IDs to filter by, with at most 10 IDs.
string
required
Messaging account ID, phone number, Facebook Page ID, or Zalo account ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_CUSTOM_AUDIENCE_DETAILSGet current status and modification history for specified owned or shared custom audiences.

Input Parameters

integer
Maximum number of modification-history entries to request (1-100).
string
required
Authorized advertiser account ID whose audiences to read.
array
required
Audience IDs whose details to return (1-100).

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_CUSTOM_AUDIENCE_SHARING_LOGGet the advertisers with which a specific TikTok custom audience has been shared, including each sharing status.

Input Parameters

string
required
Advertiser ID that owns the custom audience.
string
required
Custom audience ID whose sharing log to retrieve.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_CUSTOM_CONVERSIONGet one Custom Conversion configured for a Pixel or app event source.

Input Parameters

string
required
Advertiser ID.
string
required
Pixel ID or SAN app platform ID matching event_source_type.
string ("PIXEL" | "APP")
required
PIXEL or APP event source.
string
required
Custom Conversion ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_DIAGNOSTIC_CATALOG_EVENTSOURCE_ISSUEGet detected catalog app or pixel event source issues and suggested solutions.

Input Parameters

string
required
Business Center ID.
string
Required for an APP event source.
string
required
Catalog ID.
string ("VIEW_CONTENT" | "ADD_TO_CART" | "PURCHASE")
Event type to diagnose.
string
Required for a PIXEL event source.
string ("YESTERDAY" | "LAST_7_DAYS" | "LAST_30_DAYS")
Diagnostic time range.
string ("PIXEL" | "APP")
required
App or pixel event source.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_DMP_CUSTOM_AUDIENCE_APPLY_LOGReturn one page of the latest application log for specified custom audiences.

Input Parameters

integer
Initial page number.
string
Timezone for returned timestamps; defaults to UTC.
integer
Results per page.
string
Opaque cursor from the previous page.
string
required
Advertiser ID that owns the audiences.
array
required
Owned custom audience IDs.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_FILE_MUSICGet one page of advertiser music and return a continuation cursor.

Input Parameters

integer
Initial provider page.
object
Music search filters. Resubmit this value with a continuation cursor.
integer
Music entries per page; some search modes allow at most 200.
string ("CREATIVE_ASSET" | "CAROUSEL_ADS" | "CATALOG_CAROUSEL")
Scenario where the music will be used.
string
Opaque continuation token from a previous call.
string ("SEARCH_BY_KEYWORD" | "SEARCH_BY_RECOMMEND" | "SEARCH_BY_LIKED" | "SEARCH_BY_HISTORY" | "SEARCH_BY_MUSIC_ID" | "SEARCH_BY_SOURCE")
Music search mode for Carousel Ads or catalog carousel music.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_FILE_VIDEO_SUGGESTCOVERGet up to ten suggested thumbnail images for an advertiser video.

Input Parameters

string
required
Video ID.
string
required
Advertiser ID.
integer
Number of cover candidates (1-10).

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_GMV_MAX_BID_RECOMMENDATIONGet TikTok’s recommended GMV Max bid for an eligible advertiser and shop.

Input Parameters

string
required
TikTok Shop store ID used for the recommendation.
string
Optional TikTok identity ID used for the recommendation.
string
required
Authorized advertiser account ID.
array
Optional item group IDs included in the recommendation (1-50).
string
required
Optimization goal; the official contract supports VALUE.
string ("LIVE" | "PRODUCT")
required
GMV Max shopping ads type: LIVE or PRODUCT.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_GMV_MAX_CAMPAIGNGet one page of GMV Max campaigns.

Input Parameters

integer
Initial page number.
array
Campaign fields to return; omit to return all fields.
object
required
Filters on the GMV Max campaigns.
integer
Page size (1-100).
string
Opaque continuation token from a previous response.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_GMV_MAX_CAMPAIGN_INFOGet information for one GMV Max campaign owned by an authorized advertiser.

Input Parameters

string
required
GMV Max campaign ID to retrieve.
string
required
Authorized advertiser account ID that owns the GMV Max campaign.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_GMV_MAX_CAMPAIGN_SESSIONSGet max delivery or creative boost session details by 1 to 20 exact session IDs. This is an ID lookup, not the active-session campaign listing; use LIST_GMV_MAX_CAMPAIGN_SESSIONS to list active sessions for one Product GMV Max campaign.

Input Parameters

array
required
Exact max delivery or creative boost session IDs to retrieve (1 to 20). This selects by session IDs rather than campaign ID; use LIST_GMV_MAX_CAMPAIGN_SESSIONS instead to discover active sessions by Product GMV Max campaign ID.
string
required
Authorized advertiser account ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_GMV_MAX_EXCLUSIVE_AUTHORIZATIONGet an advertiser account’s exclusive authorization status for a TikTok Shop.

Input Parameters

string
required
TikTok Shop store ID to check.
string
required
Advertiser account ID whose exclusive authorization to check.
string
required
Business Center ID authorized for the TikTok Shop.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_GMV_MAX_REPORTRun one paginated Product or LIVE GMV Max campaign report.

Input Parameters

integer
Initial result page.
array
required
Current official GMV Max metric identifiers. Compatibility varies for all, Product, creative, duration, and LIVE report families.
string
required
Inclusive end date in YYYY-MM-DD, in the ad-account time zone.
object
Documented GMV Max report filters.
integer
Rows in this page (1-1000).
string ("ASC" | "DESC")
Sort order.
array
required
Exactly one GMV-Max-eligible TikTok Shop ID.
array
required
One to three GMV Max report dimensions.
string ("cost" | "net_cost" | "orders" | "cost_per_order" | "gross_revenue" | "roi" | "product_impressions" | "product_clicks" | "product_click_rate" | "ad_click_rate" | "ad_conversion_rate" | "ad_video_view_rate_2s" | "ad_video_view_rate_6s" | "ad_video_view_rate_p25" | "ad_video_view_rate_p50" | "ad_video_view_rate_p75" | "ad_video_view_rate_p100" | "live_views" | "cost_per_live_view" | "10_second_live_views" | "cost_per_10_second_live_view" | "live_follows")
Supported Product or LIVE report metric to sort by.
string
required
Inclusive start date in YYYY-MM-DD, in the ad-account time zone.
string
Opaque continuation token from a previous response; omit for the first page.
string
required
Authorized advertiser ID.
boolean
Return aggregate metrics across all matching pages.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_GMV_MAX_VIDEO_PRODUCT_LINKSGet product linkage details of videos in customized posts.

Input Parameters

array
required
TikTok video IDs (maximum 20).
string
required
TikTok Shop ID.
string
Product GMV Max campaign ID when videos are used in campaign-level posts.
string
required
Advertiser ID.
string
required
Business Center ID authorized to access the TikTok Shop.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_IDENTITY_GETReturn one page of advertiser identities. Creator-account capabilities and availability are authorization gates: inspect can_pull_video, can_push_video, ads_only_mode, is_gpppa, and available_status before using an identity for posts or Spark Ads.

Input Parameters

integer
Initial provider page number.
object
Customized-identity filtering, valid only when identity_type is CUSTOMIZED_USER or omitted.
integer
Identities to return per page (1-100).
string
Opaque continuation cursor from a previous response; omit for the first page and repeat the same filtering value when continuing.
string
required
Advertiser ID.
string ("CUSTOMIZED_USER" | "AUTH_CODE" | "TT_USER" | "BC_AUTH_TT")
Identity type; omit to return all identity types.
string
Business Center ID; required when identity_type is BC_AUTH_TT.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_IDENTITY_INFOGet one advertiser identity. BC_AUTH_TT identities require the authorizing Business Center ID; returned capability flags determine whether that creator can retrieve, publish, or manage content.

Input Parameters

string
required
Identity ID.
string
required
Advertiser ID.
string ("CUSTOMIZED_USER" | "AUTH_CODE" | "TT_USER" | "BC_AUTH_TT")
required
Identity type.
string
Business Center ID; required when identity_type is BC_AUTH_TT.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_IDENTITY_LIVEReturn one page of live videos for an authorized TikTok account identity. The identity must expose live access; BC_AUTH_TT also requires its authorizing Business Center ID.

Input Parameters

string
required
TikTok account identity ID.
string
Opaque timestamp cursor from the previous response; omit for the first page.
string
required
Advertiser ID.
string ("TT_USER" | "BC_AUTH_TT")
required
Identity type: TT_USER or BC_AUTH_TT.
string
Business Center ID; required for BC_AUTH_TT.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_IDENTITY_NATIVE_SERIESReturn one page of TikTok Series from a specified TikTok account identity that the advertiser can promote. This only lists available Series and does not create or purchase them.

Input Parameters

integer
Maximum Series to return on this page (1-100).
string
required
TikTok account identity ID whose promotable Series to retrieve.
string
Opaque continuation cursor from the previous page; omit for the first page.
string
required
Advertiser ID.
string ("TT_USER" | "BC_AUTH_TT")
required
Identity type: TT_USER or BC_AUTH_TT.
string
Business Center ID; required when identity_type is BC_AUTH_TT.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_IDENTITY_VIDEO_GETReturn one page of posts visible through an authorized identity. AUTH_CODE exposes only creator-authorized posts; TT_USER and BC_AUTH_TT access depends on the account’s can_pull_video capability, privacy status, and Business Center authorization.

Input Parameters

integer
Posts to return (1-20).
string
Post text or exact post ID search; valid only for AUTH_CODE identities.
string ("VIDEO" | "CAROUSEL")
Post type: VIDEO or CAROUSEL.
string
required
Authorized identity ID.
string
Opaque provider cursor from the previous page; omit for the first page.
string
required
Advertiser ID.
string ("AUTH_CODE" | "TT_USER" | "BC_AUTH_TT")
required
Identity type: AUTH_CODE, TT_USER, or BC_AUTH_TT.
boolean
Exclude ads-only posts; true returns at most the 500 most recent organic posts.
string
Business Center ID; required for BC_AUTH_TT.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_IDENTITY_VIDEO_INFOGet one or up to 20 posts associated with an authorized identity. Private/friends-only visibility and expired AUTH_CODE authorization can limit returned media; BC_AUTH_TT requires its authorizing Business Center ID.

Input Parameters

string
One post ID; mutually exclusive with item_ids.
array
One to 20 post IDs; mutually exclusive with item_id.
string
required
Identity ID associated with the requested posts.
string
required
Advertiser ID.
string ("AUTH_CODE" | "TT_USER" | "BC_AUTH_TT")
required
Identity type: AUTH_CODE, TT_USER, or BC_AUTH_TT.
string
Business Center ID; required for BC_AUTH_TT.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_LEADRetrieve lead answers and attribution metadata. The response can contain names, contact details, and other personal data supplied through form or direct-message questions; call only for an authorized advertiser or Business Center library, minimize retention, and do not disclose or reuse it outside the consented lead-processing purpose.

Input Parameters

string
Instant Form page ID; required for INSTANT_FORM and unsupported for DIRECT_MESSAGE.
string
Form-library ID when the lead belongs to a Business Center library.
string ("INSTANT_FORM" | "DIRECT_MESSAGE")
required
Lead source: INSTANT_FORM or DIRECT_MESSAGE.
string
Advertiser ID when the lead belongs to an ad account.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_LEAD_FIELDRetrieve only the field names and form metadata for Instant Form or direct-message leads. Lead schemas can reveal what personal data is collected; use only for an authorized advertiser or Business Center library and do not expose the result beyond the intended lead-processing purpose.

Input Parameters

string
Instant Form page ID; required for INSTANT_FORM and unsupported for DIRECT_MESSAGE.
string
Form-library ID when leads belong to a Business Center library.
string ("INSTANT_FORM" | "DIRECT_MESSAGE")
required
Lead source: INSTANT_FORM or DIRECT_MESSAGE.
string
Advertiser ID when leads belong to an ad account.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_MINISGet one page of TikTok Minis within an ad account.

Input Parameters

integer
Initial page number.
integer
Page size (1-50).
string
Opaque continuation token from a previous response.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_MMM_DOWNLOAD_URLObtain a seven-day signed URL for a completed MMM compressed CSV. This action does not follow the URL or download the sensitive report.

Input Parameters

string
required
Completed MMM request ID whose compressed CSV URL to obtain.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_MMM_REQUEST_HISTORYRetrieve MMM request metadata for a UTC+0 date interval. TikTok returns each history item as JSON-formatted text and does not document pagination.

Input Parameters

string
required
Inclusive history end date in YYYY-MM-DD format, interpreted in UTC+0.
string
required
Inclusive history start date in YYYY-MM-DD format, interpreted in UTC+0.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_OFFLINEList Offline Event Set configurations; this management endpoint does not ingest offline events.

Input Parameters

string
Offline Event Set name to match.
string
Advertiser ID.
array
Offline Event Set IDs to match.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_OPTIMIZER_RULEGet automated optimizer rules by ID.

Input Parameters

array
required
IDs of the rules to retrieve.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_OPTIMIZER_RULE_RESULTGet automated optimizer rule result details.

Input Parameters

string ("ZH" | "EN" | "JA")
Language of execution results.
string
required
Advertiser ID.
array
required
Result references containing rule execution IDs and rule IDs.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_PAGEReturn one page of Instant Forms and other TikTok Instant Page types.

Input Parameters

integer
Initial provider page number.
string
Exact page-title filter.
string ("EDITED" | "PUBLISHED")
Instant Page status filter.
integer
Results per page (1-100).
string
Form library ID; mutually exclusive with advertiser_id.
string
Opaque continuation token from a previous response.
string
Advertiser ID; mutually exclusive with library_id.
string ("LEAD_GEN" | "STORE_FRONT" | "APP_PROFILE_PAGE" | "TIKTOK_INSTANT_PAGE" | "SHOP_ADS_PLP" | "SHOP_ADS_PDP" | "POP_UP_FORM")
Single page type; ignored when business_types is set.
array
Page types to include.
object
Page update-time range filter.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_PAGE_FIELDGet the field definitions and metadata for one TikTok Instant Form.

Input Parameters

string
required
ID of the Instant Form.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_PAGE_LEAD_MOCKGet the current test lead for an Instant Form or direct-message lead source.

Input Parameters

string
Instant Form ID; required for INSTANT_FORM and unsupported for DIRECT_MESSAGE.
string
Form library ID when the lead belongs to a Business Center.
string ("INSTANT_FORM" | "DIRECT_MESSAGE")
Test-lead source.
string
Advertiser ID when the lead belongs to an ad account.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_PAGE_LIBRARYReturn one page of Business Center form libraries accessible to the connected user.

Input Parameters

integer
Initial provider page number.
integer
Records per page.
string
Opaque continuation token from a previous response.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_PANGLE_BLOCK_LISTGet an advertiser’s Pangle app block list and its last modification time.

Input Parameters

string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_PAYMENT_PORTFOLIOReturn one page of Payment Portfolios, cash balances, and credit line usage. This exposes highly sensitive financial capacity and account relationships; confirm the Business Center and filters and disclose results only to authorized finance administrators.

Input Parameters

integer
Initial page number.
string
required
Business Center ID. By default TikTok can return portfolios belonging to the same client even when they are not linked to this Business Center.
object
Optional Payment Portfolio filters.
integer
Portfolios per page (1-50).
string
Opaque continuation token returned by a previous call. Repeat filtering with the cursor so later pages use the same filter.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_PAYMENT_PORTFOLIO_ADVERTISERReturn one page of ad accounts linked to a Payment Portfolio. This is read-only but reveals finance-sensitive payment relationships; confirm the portfolio ID and disclose the result only to authorized finance administrators.

Input Parameters

integer
Initial page number.
integer
Ad accounts per page (1-50).
string
Opaque continuation token returned by a previous call.
string
required
Payment Portfolio ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_PAYMENT_PORTFOLIO_USERReturn one page of users authorized for a Payment Portfolio. This is read-only but reveals finance access assignments; confirm the portfolio ID and disclose the result only to authorized administrators.

Input Parameters

integer
Initial page number.
integer
Users per page (1-50).
string
Opaque continuation token returned by a previous call.
string
required
Payment Portfolio ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_PIXEL_EVENT_STATSGet UTC Pixel Event statistics; this reporting endpoint does not ingest events.

Input Parameters

array
required
One to ten Pixel IDs.
object
required
UTC reporting range of at most 30 days.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_PIXEL_INSTANT_PAGE_EVENTGet supported TikTok Instant Page event options for an optimization goal.

Input Parameters

string
required
Advertiser ID.
boolean
Whether the use case is retargeting.
string ("CONVERSIONS" | "APP_PROMOTION")
required
CONVERSIONS or APP_PROMOTION.
string
required
Optimization goal.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_PLAYABLEReturn one page of playable assets for an advertiser.

Input Parameters

integer
Initial provider page number.
string ("AUDIT_FAIL" | "AUDIT_SUCCESS" | "VALIDATE_FAIL" | "VALIDATE_SUCCESS" | "VALIDATING")
Playable validation or audit status.
integer
Results per page (1-100).
string
Opaque continuation token from a previous response.
string
Playable asset ID filter.
string
Playable URL filter.
string
required
Advertiser ID.
string
Playable asset name filter.
string ("UPLOADED" | "SAVED" | "DELETED")
Playable operation status.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_REPORT_INTEGRATEDReturn one page of a synchronous TikTok report with dimensions, metrics, advertiser lists, and filters encoded as provider JSON query values.

Input Parameters

integer
Initial provider page.
string
Business Center ID for BC reports.
array
Metric names, JSON-encoded in the query.
string
Inclusive query end date.
array
Filtering conditions, JSON-encoded in the query.
integer
Rows per page (1-1000).
string
Report data level.
array
Dimension names, JSON-encoded in the query.
string ("ASC" | "DESC")
Sort order.
string ("REGULAR" | "CHUNK")
Deprecated query mode; CHUNK disables pagination.
string
Inclusive query start date.
string
Opaque continuation token from a previous response.
string
Metric used for sorting.
string ("BASIC" | "AUDIENCE" | "PLAYABLE_MATERIAL" | "CATALOG" | "BC" | "TT_SHOP")
required
Report family.
string ("AUCTION" | "RESERVATION")
Ad service type.
string
Single advertiser ID.
array
Up to five advertiser IDs, JSON-encoded in the query.
boolean
Request lifetime metrics where supported.
boolean
Return aggregate metrics when supported.
boolean
Normalize multi-advertiser metrics to UTC.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_RF_DELIVERY_TIMEZONEGet R&F time zones.

Input Parameters

array
required
Country codes to be queried. Example:US . See Appendix - Location Code
string
required
Advertiser ID

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_SEARCH_AD_HEALTH_DIAGNOSESGet Search Ads Campaign Health diagnoses for an ad group or ads.

Input Parameters

array
Ad IDs from one Search Ads ad group (maximum 50).
string
Existing Search Ads ad-group ID; ignored when ad_ids is set.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_SEARCH_REGIONGet all locations available to an advertiser, with translated names.

Input Parameters

string ("zh" | "fr" | "es" | "ko" | "vi" | "en" | "hi" | "it" | "tr" | "ru" | "ja" | "id" | "de" | "ms" | "ar" | "th")
Language for returned region names.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_SHOWCASE_IDENTITYGet the identity with Showcase permission under an ad account.

Input Parameters

string
required
Advertiser account ID whose Showcase identity to retrieve.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_SMART_CREATIVE_MATERIALSGet current Smart Creative materials for 1-100 ad groups. The provider returns one complete bounded result and documents no page or cursor wire parameters. This reads SMART_CREATIVE mode, not retired DYNAMIC ACO.

Input Parameters

array
required
Smart Creative ad group IDs to read (1-100).
string
required
Advertiser account ID.
array
Use NULL_FIELD to omit null-valued response fields.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_SMART_PLUS_MATERIAL_REPORTGet one page of Smart+ material overview or breakdown reporting.

Input Parameters

integer
Initial result page.
array
Metrics supported by the selected report type.
string
Report end date in YYYY-MM-DD format.
integer
Rows in this page (1-100).
string ("ASC" | "DESC")
Sort order.
array
required
Dimensions supported by the selected report type.
string ("achieve_level" | "achieve_level_rate" | "ad_impression_ad_revenue_day0" | "ad_impression_ad_revenue_day2" | "ad_impression_ad_revenue_roas_day0" | "ad_impression_ad_revenue_roas_day2" | "ad_impression_ad_revenue_roas_day6" | "add_billing" | "add_billing_rate" | "add_payment_info" | "add_payment_info_rate" | "add_to_wishlist" | "add_to_wishlist_rate" | "ads_impression_events" | "anchor_click_rate" | "anchor_clicks" | "app_event_add_to_cart" | "app_event_add_to_cart_rate" | "app_install" | "average_video_play" | "avg_value_per_pageview" | "button_click" | "button_click_rate" | "checkout" | "checkout_rate" | "clicks" | "clicks_on_hashtag_challenge" | "clicks_on_music_disc" | "comments" | "complete_payment" | "complete_payment_rate" | "complete_payment_roas" | "complete_tutorial" | "complete_tutorial_rate" | "conversion" | "conversion_rate_v2" | "cost_per_achieve_level" | "cost_per_add_billing" | "cost_per_add_payment_info" | "cost_per_add_to_wishlist" | "cost_per_app_event_add_to_cart" | "cost_per_app_install" | "cost_per_button_click" | "cost_per_checkout" | "cost_per_complete_payment" | "cost_per_complete_tutorial" | "cost_per_conversion" | "cost_per_create_gamerole" | "cost_per_create_group" | "cost_per_cta_app_install" | "cost_per_cta_conversion" | "cost_per_cta_purchase" | "cost_per_cta_registration" | "cost_per_custom_app_event" | "cost_per_custom_page_event" | "cost_per_day7_retention" | "cost_per_download_start" | "cost_per_engaged_view_through_conversion" | "cost_per_evta_app_install" | "cost_per_evta_payments_completed" | "cost_per_evta_purchase" | "cost_per_evta_registration" | "cost_per_form" | "cost_per_in_app_ad_click" | "cost_per_in_app_ad_impr" | "cost_per_initiate_checkout" | "cost_per_ix_button_click_count" | "cost_per_ix_page_view_count" | "cost_per_ix_product_click_count" | "cost_per_join_group" | "cost_per_landing_page_view" | "cost_per_launch_app" | "cost_per_loan_apply" | "cost_per_loan_credit" | "cost_per_loan_disbursement" | "cost_per_login" | "cost_per_next_day_open" | "cost_per_offline_add_payment_info_event" | "cost_per_offline_add_to_cart_event" | "cost_per_offline_add_to_wishlist_event" | "cost_per_offline_click_button_event" | "cost_per_offline_complete_registration_event" | "cost_per_offline_contact_event" | "cost_per_offline_download_event" | "cost_per_offline_form_event" | "cost_per_offline_initiate_checkout_event" | "cost_per_offline_place_order_event" | "cost_per_offline_search_event" | "cost_per_offline_shopping_event" | "cost_per_offline_subscribe_event" | "cost_per_offline_view_content_event" | "cost_per_on_web_add_to_wishlist" | "cost_per_on_web_order" | "cost_per_on_web_subscribe" | "cost_per_online_consult" | "cost_per_onsite_add_billing" | "cost_per_onsite_add_to_wishlist" | "cost_per_onsite_destination_visit" | "cost_per_onsite_download_start" | "cost_per_onsite_form" | "cost_per_onsite_initiate_checkout_count" | "cost_per_onsite_on_web_cart" | "cost_per_onsite_on_web_detail" | "cost_per_onsite_shopping" | "cost_per_page_content_view_event" | "cost_per_page_event_search" | "cost_per_pageview" | "cost_per_purchase" | "cost_per_ratings" | "cost_per_registration" | "cost_per_sales_lead" | "cost_per_search" | "cost_per_spend_credits" | "cost_per_start_trial" | "cost_per_subscribe" | "cost_per_total_achieve_level" | "cost_per_total_add_to_wishlist" | "cost_per_total_app_event_add_to_cart" | "cost_per_total_checkout" | "cost_per_total_complete_tutorial" | "cost_per_total_create_gamerole" | "cost_per_total_create_group" | "cost_per_total_day7_retention" | "cost_per_total_in_app_ad_click" | "cost_per_total_in_app_ad_impr" | "cost_per_total_join_group" | "cost_per_total_launch_app" | "cost_per_total_loan_apply" | "cost_per_total_loan_credit" | "cost_per_total_loan_disbursement" | "cost_per_total_login" | "cost_per_total_next_day_open" | "cost_per_total_purchase" | "cost_per_total_ratings" | "cost_per_total_registration" | "cost_per_total_sales_lead" | "cost_per_total_search" | "cost_per_total_spend_credits" | "cost_per_total_start_trial" | "cost_per_total_subscribe" | "cost_per_total_unlock_achievement" | "cost_per_total_view_content" | "cost_per_unique_ad_impression_event" | "cost_per_unique_custom_app_event" | "cost_per_unlock_achievement" | "cost_per_user_registration" | "cost_per_view_content" | "cost_per_vta_app_install" | "cost_per_vta_conversion" | "cost_per_vta_payments_completed" | "cost_per_vta_purchase" | "cost_per_vta_registration" | "cost_per_web_event_add_to_cart" | "cost_pre_ad_impression_event" | "cost_total_add_payment_info" | "countdown_sticker_recall_clicks" | "cpc" | "cpm" | "create_gamerole" | "create_gamerole_rate" | "create_group" | "create_group_rate" | "cta_app_install" | "cta_conversion" | "cta_purchase" | "cta_registration" | "ctr" | "custom_app_event_rate" | "custom_app_events" | "custom_app_events_value" | "custom_page_event_rate" | "custom_page_events" | "custom_page_events_value" | "customized_ad_impression_event_rate" | "day7_retention" | "day7_retention_rate" | "download_start" | "download_start_rate" | "duet_clicks" | "engaged_view" | "engaged_view_15s" | "engaged_view_through_conversions" | "engagement_rate" | "engagements" | "evta_app_install" | "evta_payments_completed" | "evta_purchase" | "evta_registration" | "follows" | "form" | "form_rate" | "gross_impressions" | "impressions" | "in_app_ad_click" | "in_app_ad_click_rate" | "in_app_ad_impr" | "in_app_ad_impr_rate" | "initiate_checkout" | "initiate_checkout_rate" | "interactive_add_on_activity_clicks" | "interactive_add_on_destination_clicks" | "interactive_add_on_impressions" | "interactive_add_on_option_a_clicks" | "interactive_add_on_option_b_clicks" | "ix_average_video_play" | "ix_button_click_count" | "ix_button_click_count_rate" | "ix_page_duration_avg" | "ix_page_view_count" | "ix_page_view_count_rate" | "ix_page_viewrate_avg" | "ix_product_click_count" | "ix_product_click_count_rate" | "ix_video_views" | "ix_video_views_p100" | "ix_video_views_p25" | "ix_video_views_p50" | "ix_video_views_p75" | "join_group" | "join_group_rate" | "landing_page_view_rate" | "launch_app" | "launch_app_rate" | "likes" | "live_effective_views" | "live_product_clicks" | "live_views" | "loan_apply" | "loan_apply_rate" | "loan_credit" | "loan_credit_rate" | "loan_disbursement" | "loan_disbursement_rate" | "login" | "login_rate" | "messaging_conversation_rate_instant_messaging_app" | "messaging_conversation_rate_tiktok_direct_message" | "messaging_cost_per_conversation_instant_messaging_app" | "messaging_cost_per_conversation_tiktok_direct_message" | "messaging_total_conversation_instant_messaging_app" | "messaging_total_conversation_tiktok_direct_message" | "next_day_open" | "next_day_open_rate" | "offline_add_payment_info_event_rate" | "offline_add_payment_info_events" | "offline_add_payment_info_events_value" | "offline_add_to_cart_event_rate" | "offline_add_to_cart_events" | "offline_add_to_cart_events_value" | "offline_add_to_wishlist_event_rate" | "offline_add_to_wishlist_events" | "offline_add_to_wishlist_events_value" | "offline_application_approval" | "offline_application_approval_rate" | "offline_click_button_event_rate" | "offline_click_button_events" | "offline_click_button_events_value" | "offline_complete_registration_event_rate" | "offline_complete_registration_events" | "offline_complete_registration_events_value" | "offline_contact_event_rate" | "offline_contact_events" | "offline_contact_events_value" | "offline_cost_per_application_approval" | "offline_cost_per_crm_event" | "offline_cost_per_custom_event" | "offline_cost_per_customize_product" | "offline_cost_per_find_location" | "offline_cost_per_preferred_lead" | "offline_cost_per_schedule" | "offline_cost_per_start_trial" | "offline_cost_per_submit_application" | "offline_crm_event_rate" | "offline_crm_event_value" | "offline_custom_event_rate" | "offline_customize_product_rate" | "offline_download_event_rate" | "offline_download_events" | "offline_download_events_value" | "offline_find_location_rate" | "offline_form_event_rate" | "offline_form_events" | "offline_form_events_value" | "offline_initiate_checkout_event_rate" | "offline_initiate_checkout_events" | "offline_initiate_checkout_events_value" | "offline_place_order_event_rate" | "offline_place_order_events" | "offline_place_order_events_value" | "offline_preferred_lead_rate" | "offline_preferred_leads" | "offline_schedule_rate" | "offline_search_event_rate" | "offline_search_events" | "offline_search_events_value" | "offline_shopping_event_rate" | "offline_shopping_events" | "offline_shopping_events_roas" | "offline_shopping_events_value" | "offline_start_trial_rate" | "offline_submit_application_rate" | "offline_subscribe_event_rate" | "offline_subscribe_events" | "offline_subscribe_events_value" | "offline_total_application_approval_value" | "offline_total_crm_events" | "offline_total_custom_event_value" | "offline_total_custom_events" | "offline_total_customize_product" | "offline_total_customize_product_value" | "offline_total_find_location" | "offline_total_find_location_value" | "offline_total_schedule" | "offline_total_schedule_value" | "offline_total_start_trial" | "offline_total_start_trial_value" | "offline_total_submit_application" | "offline_total_submit_application_value" | "offline_value_per_application_approval" | "offline_value_per_crm_event" | "offline_value_per_custom_event" | "offline_value_per_customize_product" | "offline_value_per_find_location" | "offline_value_per_schedule" | "offline_value_per_start_trial" | "offline_value_per_submit_application" | "offline_view_content_event_rate" | "offline_view_content_events" | "offline_view_content_events_value" | "on_web_add_to_wishlist" | "on_web_add_to_wishlist_per_click" | "on_web_order" | "on_web_order_rate" | "on_web_subscribe" | "on_web_subscribe_per_click" | "online_consult" | "online_consult_rate" | "onsite_active_by_conversion_time" | "onsite_ad_impression_ad_revenue_calendar_day0" | "onsite_ad_impression_ad_revenue_calendar_day13" | "onsite_ad_impression_ad_revenue_calendar_day6" | "onsite_ad_impression_ad_revenue_day0" | "onsite_ad_impression_ad_revenue_day13" | "onsite_ad_impression_ad_revenue_day6" | "onsite_ad_impression_ad_revenue_roas_calendar_day0" | "onsite_ad_impression_ad_revenue_roas_calendar_day13" | "onsite_ad_impression_ad_revenue_roas_calendar_day6" | "onsite_ad_impression_ad_revenue_roas_day0" | "onsite_ad_impression_ad_revenue_roas_day13" | "onsite_ad_impression_ad_revenue_roas_day6" | "onsite_ad_impression_rate" | "onsite_add_billing" | "onsite_add_billing_rate" | "onsite_add_to_cart_rate" | "onsite_add_to_wishlist" | "onsite_add_to_wishlist_rate" | "onsite_checkout_initiation_rate" | "onsite_cost_per_active" | "onsite_cost_per_active_by_conversion_time" | "onsite_cost_per_add_to_cart" | "onsite_cost_per_checkout_initiation" | "onsite_cost_per_product_details_page_view" | "onsite_cost_per_purchase" | "onsite_cost_per_total_ad_impression" | "onsite_cost_per_total_launch" | "onsite_cost_per_total_registration" | "onsite_cost_per_unique_ad_impression" | "onsite_cost_per_unique_launch" | "onsite_cost_per_unique_purchase" | "onsite_cost_per_unique_registration" | "onsite_destination_visit_rate" | "onsite_destination_visits" | "onsite_download_start" | "onsite_download_start_rate" | "onsite_form" | "onsite_form_rate" | "onsite_initiate_checkout_count" | "onsite_initiate_checkout_count_rate" | "onsite_launch_rate" | "onsite_on_web_cart" | "onsite_on_web_cart_rate" | "onsite_on_web_detail" | "onsite_on_web_detail_rate" | "onsite_product_details_page_view_rate" | "onsite_purchase_rate" | "onsite_purchase_roas_calendar_day0" | "onsite_purchase_roas_calendar_day13" | "onsite_purchase_roas_calendar_day6" | "onsite_purchase_roas_day0" | "onsite_purchase_roas_day13" | "onsite_purchase_roas_day6" | "onsite_purchase_value_calendar_day0" | "onsite_purchase_value_calendar_day13" | "onsite_purchase_value_calendar_day6" | "onsite_purchase_value_day0" | "onsite_purchase_value_day13" | "onsite_purchase_value_day6" | "onsite_purchases_roas" | "onsite_registration_rate" | "onsite_shopping" | "onsite_shopping_rate" | "onsite_shopping_roas" | "onsite_total_active" | "onsite_total_ad_impression" | "onsite_total_ad_impression_value" | "onsite_total_add_to_cart" | "onsite_total_add_to_cart_value" | "onsite_total_checkout_initiation" | "onsite_total_checkout_initiation_value" | "onsite_total_filtered_out_form_submission" | "onsite_total_launch" | "onsite_total_product_details_page_view" | "onsite_total_product_details_page_view_value" | "onsite_total_purchase" | "onsite_total_purchase_value" | "onsite_total_registration" | "onsite_unique_ad_impression" | "onsite_unique_launch" | "onsite_unique_purchase" | "onsite_unique_registration" | "onsite_value_per_ad_impression_value" | "onsite_value_per_add_to_cart" | "onsite_value_per_checkout_initiation" | "onsite_value_per_product_details_page_view" | "onsite_value_per_purchase" | "page_content_view_event_rate" | "page_content_view_events" | "page_event_search" | "page_event_search_rate" | "pageview_rate" | "paid_engaged_view" | "paid_engaged_view_15s" | "paid_engagement_engaged_view" | "paid_engagement_engaged_view_15s" | "playable_download_button_click_count" | "playable_first_scene_view_count" | "playable_page_view_count" | "playable_second_scene_view_count" | "playable_third_scene_view_count" | "product_clicks" | "product_cta" | "product_impressions" | "profile_visits" | "profile_visits_rate" | "purchase" | "purchase_rate" | "ratings" | "ratings_rate" | "real_time_app_install" | "real_time_app_install_cost" | "real_time_conversion" | "real_time_conversion_rate_v2" | "real_time_cost_per_conversion" | "registration" | "registration_rate" | "sales_lead" | "sales_lead_rate" | "search" | "search_rate" | "shares" | "shop_gross_revenue_by_order_submission" | "shop_total_items_purchased" | "shop_total_purchase_by_order_submission" | "single_image_ctr" | "single_image_impression_rate" | "single_image_impressions" | "skan_achieve_level" | "skan_achieve_level_rate" | "skan_add_payment_info" | "skan_add_payment_info_rate" | "skan_add_to_cart" | "skan_add_to_cart_rate" | "skan_add_to_wishlist" | "skan_add_to_wishlist_rate" | "skan_app_install" | "skan_app_install_withheld" | "skan_checkout" | "skan_checkout_rate" | "skan_complete_tutorial" | "skan_complete_tutorial_rate" | "skan_conversion" | "skan_conversion_rate_v2" | "skan_cost_per_achieve_level" | "skan_cost_per_add_payment_info" | "skan_cost_per_add_to_cart" | "skan_cost_per_add_to_wishlist" | "skan_cost_per_app_install" | "skan_cost_per_checkout" | "skan_cost_per_complete_tutorial" | "skan_cost_per_conversion" | "skan_cost_per_create_gamerole" | "skan_cost_per_create_group" | "skan_cost_per_cta_app_install" | "skan_cost_per_cta_conversion" | "skan_cost_per_cta_purchase" | "skan_cost_per_cta_registration" | "skan_cost_per_in_app_ad_click" | "skan_cost_per_in_app_ad_impr" | "skan_cost_per_join_group" | "skan_cost_per_launch_app" | "skan_cost_per_loan_apply" | "skan_cost_per_loan_credit" | "skan_cost_per_loan_disbursement" | "skan_cost_per_login" | "skan_cost_per_purchase" | "skan_cost_per_ratings" | "skan_cost_per_registration" | "skan_cost_per_result" | "skan_cost_per_sales_lead" | "skan_cost_per_search" | "skan_cost_per_spend_credits" | "skan_cost_per_start_trial" | "skan_cost_per_subscribe" | "skan_cost_per_total_achieve_level" | "skan_cost_per_total_add_to_cart" | "skan_cost_per_total_add_to_wishlist" | "skan_cost_per_total_checkout" | "skan_cost_per_total_complete_tutorial" | "skan_cost_per_total_create_gamerole" | "skan_cost_per_total_create_group" | "skan_cost_per_total_in_app_ad_click" | "skan_cost_per_total_in_app_ad_impr" | "skan_cost_per_total_join_group" | "skan_cost_per_total_launch_app" | "skan_cost_per_total_loan_apply" | "skan_cost_per_total_loan_credit" | "skan_cost_per_total_loan_disbursement" | "skan_cost_per_total_login" | "skan_cost_per_total_purchase" | "skan_cost_per_total_ratings" | "skan_cost_per_total_registration" | "skan_cost_per_total_sales_lead" | "skan_cost_per_total_search" | "skan_cost_per_total_spend_credits" | "skan_cost_per_total_start_trial" | "skan_cost_per_total_subscribe" | "skan_cost_per_total_unlock_achievement" | "skan_cost_per_total_view_content" | "skan_cost_per_unlock_achievement" | "skan_cost_per_view_content" | "skan_cost_per_vta_app_install" | "skan_cost_per_vta_conversion" | "skan_cost_per_vta_purchase" | "skan_cost_per_vta_registration" | "skan_cost_total_add_payment_info" | "skan_create_gamerole" | "skan_create_gamerole_rate" | "skan_create_group" | "skan_create_group_rate" | "skan_cta_app_install" | "skan_cta_conversion" | "skan_cta_purchase" | "skan_cta_registration" | "skan_in_app_ad_click" | "skan_in_app_ad_click_rate" | "skan_in_app_ad_impr" | "skan_in_app_ad_impr_rate" | "skan_join_group" | "skan_join_group_rate" | "skan_launch_app" | "skan_launch_app_rate" | "skan_loan_apply" | "skan_loan_apply_rate" | "skan_loan_credit" | "skan_loan_credit_rate" | "skan_loan_disbursement" | "skan_loan_disbursement_rate" | "skan_login" | "skan_login_rate" | "skan_purchase" | "skan_purchase_rate" | "skan_ratings" | "skan_ratings_rate" | "skan_registration" | "skan_registration_rate" | "skan_result" | "skan_result_rate" | "skan_sales_lead" | "skan_sales_lead_rate" | "skan_search" | "skan_search_rate" | "skan_spend_credits" | "skan_spend_credits_rate" | "skan_start_trial" | "skan_start_trial_rate" | "skan_subscribe" | "skan_subscribe_rate" | "skan_total_achieve_level" | "skan_total_achieve_level_value" | "skan_total_add_payment_info" | "skan_total_add_to_cart" | "skan_total_add_to_cart_value" | "skan_total_add_to_wishlist" | "skan_total_add_to_wishlist_value" | "skan_total_checkout" | "skan_total_checkout_value" | "skan_total_complete_tutorial" | "skan_total_complete_tutorial_value" | "skan_total_create_gamerole" | "skan_total_create_gamerole_value" | "skan_total_create_group" | "skan_total_create_group_value" | "skan_total_in_app_ad_click" | "skan_total_in_app_ad_click_value" | "skan_total_in_app_ad_impr" | "skan_total_in_app_ad_impr_value" | "skan_total_join_group" | "skan_total_join_group_value" | "skan_total_launch_app" | "skan_total_loan_apply" | "skan_total_loan_credit" | "skan_total_loan_disbursement" | "skan_total_login" | "skan_total_purchase" | "skan_total_purchase_value" | "skan_total_ratings" | "skan_total_ratings_value" | "skan_total_registration" | "skan_total_repetitive_active_pay_roas" | "skan_total_sales_lead" | "skan_total_sales_lead_value" | "skan_total_search" | "skan_total_spend_credits" | "skan_total_spend_credits_value" | "skan_total_start_trial" | "skan_total_subscribe" | "skan_total_subscribe_value" | "skan_total_unlock_achievement" | "skan_total_unlock_achievement_value" | "skan_total_view_content" | "skan_total_view_content_value" | "skan_unlock_achievement" | "skan_unlock_achievement_rate" | "skan_view_content" | "skan_view_content_rate" | "skan_vta_app_install" | "skan_vta_conversion" | "skan_vta_purchase" | "skan_vta_registration" | "sound_usage_clicks" | "spend" | "spend_credits" | "spend_credits_rate" | "start_trial" | "start_trial_rate" | "stitch_clicks" | "subscribe" | "subscribe_rate" | "total_achieve_level" | "total_achieve_level_value" | "total_active_pay_roas" | "total_ad_impression_events_value" | "total_ad_impression_roas" | "total_add_billing_value" | "total_add_payment_info" | "total_add_to_wishlist" | "total_add_to_wishlist_value" | "total_app_event_add_to_cart" | "total_app_event_add_to_cart_value" | "total_button_click_value" | "total_checkout" | "total_checkout_value" | "total_complete_payment_rate" | "total_complete_tutorial" | "total_complete_tutorial_value" | "total_create_gamerole" | "total_create_gamerole_value" | "total_create_group" | "total_create_group_value" | "total_day7_retention" | "total_day7_retention_value" | "total_download_start_value" | "total_form_value" | "total_in_app_ad_click" | "total_in_app_ad_click_value" | "total_in_app_ad_impr" | "total_in_app_ad_impr_value" | "total_initiate_checkout_value" | "total_join_group" | "total_join_group_value" | "total_landing_page_view" | "total_launch_app" | "total_loan_apply" | "total_loan_credit" | "total_loan_disbursement" | "total_login" | "total_next_day_open" | "total_on_web_add_to_wishlist_value" | "total_on_web_order_value" | "total_on_web_subscribe_value" | "total_online_consult_value" | "total_onsite_add_billing_value" | "total_onsite_add_to_wishlist_value" | "total_onsite_form_value" | "total_onsite_initiate_checkout_count_value" | "total_onsite_on_web_cart_value" | "total_onsite_on_web_detail_value" | "total_onsite_shopping_value" | "total_page_event_search_value" | "total_page_view_content_events_value" | "total_pageview" | "total_purchase" | "total_purchase_roas_day0" | "total_purchase_roas_day2" | "total_purchase_roas_day6" | "total_purchase_value" | "total_purchase_value_day0" | "total_purchase_value_day2" | "total_purchase_value_day6" | "total_ratings" | "total_ratings_value" | "total_registration" | "total_sales_lead" | "total_sales_lead_value" | "total_search" | "total_spend_credits" | "total_spend_credits_value" | "total_start_trial" | "total_subscribe" | "total_subscribe_value" | "total_unlock_achievement" | "total_unlock_achievement_value" | "total_user_registration_value" | "total_value_per_pageview" | "total_view_content" | "total_view_content_value" | "total_web_event_add_to_cart_value" | "tt_playlist_visit" | "tt_playlist_visit_rate" | "unique_ad_impression_events" | "unique_custom_app_events" | "unlock_achievement" | "unlock_achievement_rate" | "user_registration" | "user_registration_rate" | "value_per_ad_impression_event" | "value_per_add_billing" | "value_per_button_click" | "value_per_checkout" | "value_per_complete_payment" | "value_per_custom_app_event" | "value_per_custom_page_event" | "value_per_download_start" | "value_per_form" | "value_per_initiate_checkout" | "value_per_offline_add_payment_info_event" | "value_per_offline_add_to_cart_event" | "value_per_offline_add_to_wishlist_event" | "value_per_offline_click_button_event" | "value_per_offline_complete_registration_event" | "value_per_offline_contact_event" | "value_per_offline_download_event" | "value_per_offline_form_event" | "value_per_offline_initiate_checkout_event" | "value_per_offline_place_order_event" | "value_per_offline_search_event" | "value_per_offline_shopping_event" | "value_per_offline_subscribe_event" | "value_per_offline_view_content_event" | "value_per_on_web_add_to_wishlist" | "value_per_on_web_order" | "value_per_on_web_subscribe" | "value_per_online_consult" | "value_per_onsite_add_billing" | "value_per_onsite_add_to_wishlist" | "value_per_onsite_form" | "value_per_onsite_initiate_checkout_count" | "value_per_onsite_on_web_cart" | "value_per_onsite_on_web_detail" | "value_per_onsite_shopping" | "value_per_page_content_view_event" | "value_per_page_event_search" | "value_per_total_achieve_level" | "value_per_total_add_to_wishlist" | "value_per_total_app_event_add_to_cart" | "value_per_total_complete_tutorial" | "value_per_total_create_gamerole" | "value_per_total_create_group" | "value_per_total_day7_retention" | "value_per_total_in_app_ad_click" | "value_per_total_in_app_ad_impr" | "value_per_total_join_group" | "value_per_total_purchase" | "value_per_total_ratings" | "value_per_total_sales_lead" | "value_per_total_spend_credits" | "value_per_total_subscribe" | "value_per_total_unlock_achievement" | "value_per_total_view_content" | "value_per_user_registration" | "value_per_web_event_add_to_cart" | "video_play_actions" | "video_views_p100" | "video_views_p25" | "video_views_p50" | "video_views_p75" | "video_watched_2s" | "video_watched_6s" | "view_content" | "view_content_rate" | "vta_app_install" | "vta_complete_payment" | "vta_complete_payment_roas" | "vta_complete_payment_value" | "vta_conversion" | "vta_purchase" | "vta_registration" | "web_event_add_to_cart" | "web_event_add_to_cart_rate" | "website_application_approval" | "website_application_approval_rate" | "website_cost_per_application_approval" | "website_cost_per_cta_purchase" | "website_cost_per_customize_product" | "website_cost_per_engaged_session" | "website_cost_per_find_location" | "website_cost_per_schedule" | "website_cost_per_start_trial" | "website_cost_per_submit_application" | "website_cta_purchase" | "website_cta_purchase_roas" | "website_cta_purchase_value" | "website_customize_product_rate" | "website_engaged_session_rate" | "website_find_location_rate" | "website_schedule_rate" | "website_start_trial_rate" | "website_submit_application_rate" | "website_total_application_approval_value" | "website_total_customize_product" | "website_total_customize_product_value" | "website_total_engaged_session" | "website_total_find_location" | "website_total_find_location_value" | "website_total_schedule" | "website_total_schedule_value" | "website_total_start_trial" | "website_total_start_trial_value" | "website_total_submit_application" | "website_total_submit_application_value" | "website_value_per_application_approval" | "website_value_per_customize_product" | "website_value_per_find_location" | "website_value_per_schedule" | "website_value_per_start_trial" | "website_value_per_submit_application")
Metric supported for sorting by the selected report type.
string
Report start date in YYYY-MM-DD format.
array
Ad group IDs (1-200).
string
Continuation cursor from a previous response’s next_cursor. Omit for the first page; pass the returned value back verbatim to fetch the next page.
string ("OVERVIEW" | "BREAKDOWN")
required
Select the overview or breakdown report endpoint.
array
Campaign IDs (1-200).
string
required
Authorized advertiser ID.
boolean
Query lifetime performance; available only for OVERVIEW.
array
Main material IDs (1-400).
array
Smart+ ad IDs (1-200).
array
Ad text entity IDs (1-400).
array
Main material type filters.
array
Call-to-action entity IDs (1-400).
array
Interactive add-on entity IDs (1-400).

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_SMART_PLUS_REVIEW_INFOGet review information for Smart+ ads or ad materials.

Input Parameters

string
Response language selector.
array
required
Smart+ ad or ad material IDs to inspect (1-100).
string
required
Advertiser ID that owns the resources.
string ("AD" | "AD_MATERIAL")
required
Whether resource_ids contains Smart+ ad or ad material IDs.
object
Optional review details to include.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_SPLIT_TEST_RESULTGet the current status and statistical results of a split test.

Input Parameters

string
required
Advertiser ID.
string
required
Split test group ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_STORE_PRODUCTGet one page of products within a TikTok Shop.

Input Parameters

integer
Initial page number.
string
required
Business Center ID.
string
required
TikTok Shop ID.
object
Product filtering conditions.
integer
Page size (1-100).
string ("ASC" | "DESC")
Sort direction.
string ("min_price" | "historical_sales")
Field to sort by.
string
Opaque continuation token from a previous response.
string
Advertiser ID, required when ad_creation_eligible is specified.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_SUBSCRIPTIONReturn one page of webhook subscriptions configured for a developer application.

Input Parameters

integer
Initial provider page number.
string
required
Developer application ID from My Apps.
string
required
Developer application secret from My Apps.
integer
Subscriptions per page (1-1000).
string
Opaque continuation token from a previous response. Resend secret with the token; secrets are never stored in continuation cursors.
string ("REPORT_DATA_CHANGE" | "AD_ACCOUNT_SUSPENSION" | "LEAD" | "AD_GROUP" | "AD" | "TCM_VIDEOS" | "CREATIVE_FATIGUE" | "API_SERVICE_STATUS")
Optional subscribed object type to filter by.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_TARGETING_HASHTAGSGet targeting hashtag names and availability by keyword ID.

Input Parameters

array
required
Hashtag keyword IDs to retrieve.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_TARGETING_TAG_DETAILSGet geographical or ISP targeting tag details by targeting ID.

Input Parameters

string ("GEO" | "ISP")
Targeting scene for the supplied IDs.
array
Required placements for the GEO scene.
string
required
Advertiser ID.
array
required
Location, postal-code, or ISP targeting IDs (maximum 1,000).
string ("REACH" | "TRAFFIC" | "VIDEO_VIEWS" | "LEAD_GENERATION" | "ENGAGEMENT" | "APP_PROMOTION" | "WEB_CONVERSIONS" | "PRODUCT_SALES")
Required for the GEO scene.
string
Promotion type required for applicable GEO objectives.
string ("ANDROID" | "IOS")
Device operating system for GEO targeting.
string ("NO_BRAND_SAFETY" | "EXPANDED_INVENTORY" | "STANDARD_INVENTORY" | "LIMITED_INVENTORY" | "THIRD_PARTY")
Brand safety type for GEO targeting on TikTok placement.
string ("IAS" | "OPEN_SLATE")
Required with THIRD_PARTY brand safety.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_TERMGet an advertiser agreement in the requested language.

Input Parameters

string ("EN" | "JA" | "ZH")
Language of the agreement.
string ("InstantPage" | "LeadAds" | "Pixel" | "ReachFrequency")
required
Type of agreement to retrieve.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_TIKTOK_INVENTORY_FILTERSGet the Brand Safety Hub settings configured for an advertiser account.

Input Parameters

string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_TT_VIDEOResolve a creator-issued Spark post authorization code into post, creator, media, and authorization-window details. Possessing advertiser OAuth does not authorize the creator’s post; the creator must issue the code, and expired or restricted posts may not be usable.

Input Parameters

string
required
Creator-issued authorization code for the Spark post. Pass the raw code; the query transport percent-encodes plus signs so they are not interpreted as spaces.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_USER_INFOReturn the identity of the TikTok for Business user authenticated by the current connection.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_VIDEO_FIX_TASKGet the results of a Smart Fix task.

Input Parameters

string
required
Smart Fix task ID to retrieve.
string
required
Advertiser account ID that owns the Smart Fix task.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_GET_VIDEO_PERFORMANCE_REPORTGet one page of in-second AD or VIDEO performance. VIDEO mode supports either lifetime data or a bounded start_time/end_time window and returns dynamic metric arrays with ad_id, video_id, and duration info.

Input Parameters

integer
Result page number.
object
required
Report filters and optional VIDEO time window.
integer
Results per page (1-500).
string ("ASC" | "DES")
ASC or provider-documented DES sort order (not DESC).
string
Provider field to sort by. Retained, provider-reported examples are AD_ID and CREATE_TIME; no complete enum has been independently verified.
string ("AD" | "VIDEO")
AD (default) or VIDEO report mode. Only VIDEO mode accepts start_time, end_time, and lifetime filters.
string
required
Advertiser account ID.
array
Provider field names for in-second performance metrics to return as numeric arrays. No complete metric vocabulary is verified.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_INVITE_BC_MEMBERInvite users to a Business Center and optionally assign advertiser and finance roles.

Input Parameters

string
required
Business Center ID.
array
required
One to 50 user email addresses to invite.
array
Up to 50 advertiser IDs assigned to invited users.
string ("ADMIN" | "STANDARD")
Basic Business Center role: ADMIN or STANDARD.
string
Asset type; only ADVERTISER is supported.
object
Optional advanced finance role.
string ("ADMIN" | "ANALYST" | "OPERATOR")
Advertiser role assigned to invited users; defaults to analyst.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_AD_GROUPSList regular or mixed-automation ad group inventory through TikTok’s generic /adgroup/get/ endpoint. This reader can filter MANUAL, SMART_PLUS, or UPGRADED_SMART_PLUS campaigns; use LIST_SMART_PLUS_ADGROUPS when the request specifically requires TikTok’s dedicated Smart+ ad group endpoint.

Input Parameters

integer
Initial ad group result page to retrieve.
array
Generic ad group fields to return. Verified selections include adgroup_id and adgroup_name; other provider-supported field names remain free-form.
integer
Maximum ad groups to return in this page (1-1000).
string
Continuation token returned by a previous call; omit for the first page.
array
Ad group IDs to return from this list endpoint.
string
TikTok bid-strategy code to filter by. Use a strategy supported for the advertiser’s objective and buying type.
array
Ad group buying-type filters.
array
Campaign IDs whose ad groups to return.
string
Ad group name filter.
string
required
Authorized advertiser account ID whose ad groups to read.
array
TikTok billing-event codes to filter by. The supported set depends on the objective and is not restricted to an unverified fixed enum.
string
TikTok objective-type code to filter by for this advertiser.
string
Primary-status code from TikTok’s Ad Management status enumeration. Defaults to STATUS_NOT_DELETE.
string
TikTok promoted-destination or promoted-object type code to filter by.
string
Detailed TikTok ad-group delivery or review status code. The provider-maintained set is not exposed here as an exhaustive enum.
string
TikTok optimization-goal code to filter by for the selected objective.
boolean
Filter by split-test status.
string ("CUSTOM" | "SMART_CREATIVE" | "DYNAMIC")
Creative material-mode filter.
array
Campaign system-origin filters.
string ("MANUAL" | "SMART_PLUS" | "UPGRADED_SMART_PLUS")
Campaign automation type to filter by.
string
Inclusive ad group creation-time filter end.
string
Inclusive ad group creation-time filter start.
array
Field types to omit from the response.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_ADSList regular or mixed-automation ad inventory through TikTok’s generic /ad/get/ endpoint. This reader can filter MANUAL, SMART_PLUS, or UPGRADED_SMART_PLUS campaigns; use LIST_SMART_PLUS_ADS when the request specifically requires TikTok’s dedicated Smart+ ad endpoint.

Input Parameters

integer
Initial ad result page to retrieve.
array
Legacy creative IDs to return. For Upgraded Smart+ ad-level IDs, use current_ad_ids instead; do not provide both ID filters.
array
Generic ad fields to return. Verified selections include ad_id and ad_name; other provider-supported field names remain free-form.
integer
Maximum ads to return in this page (1-1000).
string ("APP" | "TIKTOK_INSTANT_PAGE" | "WEBSITE" | "SOCIAL_MEDIA_APP" | "PHONE_CALL")
Ad destination filter.
string
Opaque continuation cursor from a previous call; omit for the first page.
array
Ad group IDs whose ads to return.
array
Ad buying-type filters.
array
Campaign IDs whose ads to return.
string
required
Authorized advertiser account ID whose ads to read.
array
Current TikTok ad-level IDs, including Upgraded Smart+ ad IDs (maximum 100). Use this instead of ad_ids for those resources; do not provide both.
string
Return ads modified after this time.
string
TikTok objective-type code to filter by. The provider’s supported set varies by advertiser features, so this field is not restricted to a fixed enum.
string
Primary-status code from TikTok’s Ad Management status enumeration. Defaults to STATUS_NOT_DELETE.
string
Detailed TikTok ad delivery or review status code. This provider-maintained set is not exposed here as an exhaustive enum.
string
TikTok optimization-goal code to filter by. Use a value supported for the advertiser and campaign objective.
string ("CUSTOM" | "SMART_CREATIVE" | "DYNAMIC")
Creative material-mode filter.
array
Campaign system-origin filters.
string ("MANUAL" | "SMART_PLUS" | "UPGRADED_SMART_PLUS")
Campaign automation type to filter by.
string
Inclusive ad creation-time filter end.
string
Inclusive ad creation-time filter start.
array
Field types to omit from the response.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_ADVERTISER_BALANCESGet one page of ad account balances and budgets for a TikTok Business Center, with optional account filters and detailed balance fields.

Input Parameters

integer
Initial result page to retrieve (1 or greater).
string
required
Business Center ID whose ad account balances to retrieve.
array
Additional balance and budget fields to return. TikTok omits these fields by default; requesting all additional fields together requires page_size=1.
string
Ad account name or ad account ID keyword used in TikTok’s filtering object.
integer
Maximum ad account balances to return in this page (1-50).
string
Child Business Center ID when retrieving balances for a child center.
string
Opaque continuation token returned by a previous call; omit for the first page.
array
Ad account display statuses included in TikTok’s filtering object.
string
Payment Portfolio ID used in TikTok’s filtering object. This filter requires the allowlisted multiple Payment Portfolios feature.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_ADVERTISER_BUDGET_CHANGESGet one page of budget change audit records for an ad account.

Input Parameters

integer
Initial result page to retrieve.
string
UTC end date in YYYY-MM-DD; must be supplied with start_date.
integer
Maximum budget changes to return in this page (1-50).
string
UTC start date in YYYY-MM-DD; must be supplied with end_date.
string
Opaque continuation token from a previous call; omit for the first page.
string
required
Ad account ID whose budget change history to retrieve.
string
required
Business Center ID that owns the ad account.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_ADVERTISER_QUALIFICATIONSList one page of reusable advertiser qualification records in a Business Center, optionally filtered by verification status.

Input Parameters

integer
Initial result page to retrieve.
boolean
Filter by whether TikTok has verified the qualification.
integer
Maximum qualifications to return in this page (1-100).
string
Opaque continuation token from a previous call; omit for the first page.
string
required
Business Center ID whose reusable advertiser qualifications to retrieve.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_ADVERTISER_TIMEZONESGet time zones available to advertisers.

Input Parameters

string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_ADVERTISER_TRANSACTIONSList one page of advertiser billing transactions accessible through a Business Center, with fund type, account, and UTC date filters. Transaction type defaults to transfers and can be changed.

Input Parameters

integer
Initial result page to retrieve.
string
required
Business Center ID. The Business Center must not have type NORMAL and the connected user must have finance access.
string
Ad account name or ad account ID to search for.
string
Transaction search end date in UTC, formatted YYYY-MM-DD. TikTok defaults to today; it must be no more than one year after start_date.
integer
Maximum transaction records to return in this page (1-50).
array
Fund types to include. Omit to include both cash and grant transactions.
string
Transaction search start date in UTC, formatted YYYY-MM-DD. TikTok defaults to 90 days ago.
string
Opaque continuation token returned by a previous call; omit for the first page.
string ("TRANS_TYPE_TRANSFER" | "TRANS_TYPE_TAX" | "TRANS_TYPE_COST" | "TRANS_TYPE_PAYMENT")
Billing type: transfer, tax, consumption, or payment. Tax and consumption transactions do not return a funds_type.
boolean
Whether TikTok should summarize transaction records by ad account.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_APPGet the mobile apps configured for an advertiser.

Input Parameters

string
required
Advertiser ID.
array
List of app platform IDs used to filter results.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_APP_ATTRIBUTION_SOURCESGet attribution sources and data sources available for a mobile app.

Input Parameters

string
required
Mobile app ID returned by the app list endpoint.
string
required
Advertiser ID.
string ("REGULAR_CAMPAIGN" | "IOS14_CAMPAIGN")
Campaign type.
string
Optimization event used to filter attribution sources.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_BC_BILLING_GROUP_ADVERTISERReturn one page of ad accounts assigned to a Billing Group. This is read-only but exposes finance-sensitive billing membership; confirm the Business Center and Billing Group before retrieving or sharing the result.

Input Parameters

integer
Initial page number.
string
required
Business Center ID.
integer
Advertisers to return per page (1-50).
string
Opaque continuation token returned by a previous call.
string
required
Billing Group ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_BC_INVOICE_TASKReturn one page of asynchronous Business Center invoice list or invoice batch download tasks, including available download URLs. These references expose finance-sensitive billing files; confirm the Business Center and share or download them only to approved destinations.

Input Parameters

integer
Initial page number.
string
required
Business Center ID.
integer
Tasks to return per page (1-50).
string
Opaque continuation token returned by a previous call.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_BLOCKEDWORDReturn one page of an advertiser’s blocked-word moderation list and an opaque continuation cursor when more results exist.

Input Parameters

object
Pagination information sent in TikTok’s page_info query object.
string
Opaque continuation token from a previous response; omit for the first page.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_BUSINESS_CENTER_ACCOUNT_COSTSGet one page of aggregate Business Center costs and itemized advertiser cost records.

Input Parameters

integer
Initial result page to retrieve.
string
Advertiser ID or name to fuzzy-match.
string
End date in YYYY-MM-DD in the ad account time zone.
integer
Maximum cost records to return in this page (1-50).
string
Start date in YYYY-MM-DD in the ad account time zone.
string
Opaque continuation token from a previous call; omit for the first page.
string
required
Business Center ID whose Business Center and ad-account costs to retrieve.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_BUSINESS_CENTER_ACCOUNT_TRANSACTIONSGet one page of itemized billing transactions for a Business Center, its ad accounts, or a Payment Portfolio, including invoice, tax, billing-type, and account details.

Input Parameters

integer
Initial result page to retrieve.
string
Closed-interval end in YYYY-MM-DD HH:MM:SS.
integer
Maximum transaction records to return in this page (1-50).
string
Closed-interval start in YYYY-MM-DD HH:MM:SS.
array
Ad account IDs to include (1-100); valid at ADVERTISER level.
string
Opaque continuation token from a previous call; omit for the first page.
string
Ad account name to fuzzy-match; valid at ADVERTISER level.
array
Billing types to include: CASH or CREDIT.
array
Ad account ownership categories to include; valid at ADVERTISER level.
string ("BC" | "ADVERTISER" | "PAYMENT_PORTFOLIO")
Level at which to retrieve transactions.
array
Provider transaction-type codes to include, such as ORDER_CREATION_PAYMENT. TikTok does not publish a closed enum.
string
required
Business Center ID whose account transactions to retrieve.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_BUSINESS_CENTER_ACTIVITY_LOG_ENTRIESGet one page of activity-log records for a Business Center.

Input Parameters

string ("ar" | "cs-CZ" | "de" | "en" | "es" | "fil" | "fr" | "id" | "it" | "ja" | "ko" | "ms" | "pl-PL" | "pt" | "ru" | "sv-SE" | "th" | "tr" | "vi" | "zh")
Activity-log language.
integer
Initial result page to retrieve.
string
required
Business Center ID whose activity log to retrieve.
object
Optional date and activity filters.
integer
Maximum activity records in this page (1-50).
string ("DESC" | "ASC")
Activity-log sort direction.
string
Sort by the activity time represented by each entry’s time field.
string
Opaque continuation token from a previous call; omit for the first page.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_BUSINESS_CENTER_ADVERTISERSList one page of advertiser-account assets assigned to the authorized user in a specified TikTok Business Center.

Input Parameters

integer
Initial result page to retrieve.
string
Asset name or ID keyword.
string
Bound user’s TikTok for Business ID.
integer
Maximum advertiser assets in this page (1-50).
string
Pending Business Center user’s email.
string
Opaque continuation token returned by a previous call; omit for the first page.
string
required
Authorized Business Center ID whose assigned advertiser accounts to list.
string
Child Business Center ID when reading tiered assets.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_BUSINESS_CENTER_ASSET_GROUPSGet one page of Asset Groups in a TikTok Business Center.

Input Parameters

integer
Initial result page to retrieve.
string
required
Business Center ID whose Asset Groups to list.
string
Keyword used to filter Asset Groups.
integer
Maximum Asset Groups to return in this page; must be at least 1.
string
Opaque continuation token returned by a previous call; omit for the first page and pass it back unchanged for the next page.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_BUSINESS_CENTER_ASSET_PARTNERSGet one page of Business Center partners associated with an asset.

Input Parameters

integer
Initial result page to retrieve.
string
Partner name keyword to filter by.
string
required
ID of the asset identified by asset_type: an ad account, catalog, domain, lead, pixel, storefront, TikTok Shop, or TikTok account ID.
integer
Maximum partners to return in this page (1-50).
string ("ADVERTISER" | "CATALOG" | "DOMAIN" | "LEAD" | "PIXEL" | "STOREFRONT" | "TIKTOK_SHOP" | "TT_ACCOUNT")
required
Asset type: ADVERTISER, CATALOG, DOMAIN, LEAD, PIXEL, STOREFRONT, TIKTOK_SHOP, or TT_ACCOUNT.
string
Opaque continuation token returned by a previous call; omit for the first page and pass it back unchanged for the next page.
string
required
Business Center ID that owns the asset.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_BUSINESS_CENTER_BILLING_GROUPSGet one page of billing groups in a TikTok Business Center.

Input Parameters

integer
Initial result page to retrieve (1 or greater).
string
required
Business Center ID whose billing groups to retrieve.
string ("VALID" | "INVALID")
Billing Group status to include: VALID or INVALID.
integer
Maximum billing groups to return in this page (1-50).
string
Opaque continuation token returned by a previous call; omit for the first page and pass it back unchanged for the next page.
string ("ACCOUNT" | "ADVERTISER")
Party billed on invoices: ACCOUNT bills agencies, while ADVERTISER bills advertisers.
string
Billing Group ID to match.
string ("ACCOUNT" | "ADVERTISER")
How invoices are handled: ACCOUNT combines invoices, while ADVERTISER handles each advertiser’s invoices separately.
string
Billing group name to match (1-256 characters).
string ("AUCTION" | "RESERVATION")
Advertising type of the billing group’s ad accounts: AUCTION or RESERVATION.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_BUSINESS_CENTER_MEMBERSGet one page of members in a TikTok Business Center.

Input Parameters

integer
Initial result page to retrieve.
string
Keyword to filter members by.
integer
Maximum members to return in this page (1-20).
string ("ADMIN" | "STANDARD")
Basic Business Center role to filter by: ADMIN or STANDARD.
string
Opaque continuation token returned by a previous call; omit for the first page and pass it back unchanged for the next page.
string ("BOUND" | "PENDING" | "REJECTED" | "UNBOUND")
Business Center relation status to filter by: BOUND, PENDING, REJECTED, or UNBOUND.
string
required
Business Center ID whose members to list.
string
Child Business Center ID when listing members in a tiered structure.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_BUSINESS_CENTER_PARTNERSGet one page of partners for a TikTok Business Center.

Input Parameters

string
Partner name keyword to filter the results by.
integer
Initial result page to retrieve (1 or greater).
string
required
Business Center ID whose partners to retrieve.
integer
Maximum partners to return in this page (1-50).
string
Opaque continuation token returned by a previous call; omit for the first page and pass it back unchanged for the next page.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_BUSINESS_CENTERSList one page of Business Centers accessible to the connected TikTok authorization, optionally restricted to one Business Center ID.

Input Parameters

integer
Initial result page to retrieve.
string ("SINGLE_ACCOUNT" | "TIERED_ACCOUNT")
Business Center account scene.
string
Business Center filter keyword.
integer
Maximum Business Centers in this page (1-50).
string
Opaque continuation token returned by a previous call; omit for the first page and pass it back unchanged for the next page.
string ("ASSET" | "MEMBER" | "PARTNER" | "TIER")
Resource type searched by the keyword.
string ("CHILD" | "PARENT")
Tiered Business Center relationship to return.
string
Business Center ID to return; omit to discover all accessible Business Centers.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_BUSINESS_CENTER_TRANSACTIONSGet one page of Business Center-level cash or grant fund movements, with aggregate charged and paid amounts. Use account transactions instead for itemized ad-account, Payment Portfolio, invoice, tax, or billing details.

Input Parameters

integer
Initial result page to retrieve.
string
required
Business Center ID whose transaction records to retrieve.
string
Latest transaction date to include, formatted YYYY-MM-DD. TikTok defaults to today.
integer
Maximum transaction records to return in this page (1-50).
array
Fund types to include: cash or non-cash grant funds. Omit to include both fund types.
string
Earliest transaction date to include, formatted YYYY-MM-DD. TikTok defaults to 90 days ago.
string
Opaque continuation token returned by a previous call; omit for the first page and pass it back unchanged for the next page.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_CAMPAIGN_LABELSList one page of campaign labels for an authorized advertiser.

Input Parameters

integer
Initial result page to retrieve.
integer
Maximum campaign labels to return in this page (1-1000).
string
Opaque continuation token from a previous call; omit for the first page.
string
required
Authorized advertiser account ID.
array
Campaign label IDs to include (maximum 50, each exactly 19 digits).
array
Campaign label names to include (maximum 10).
array
Campaign label types to include.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_CAMPAIGNSList regular or mixed-automation campaign inventory through TikTok’s generic /campaign/get/ endpoint. This reader can filter MANUAL, SMART_PLUS, or UPGRADED_SMART_PLUS campaigns; use LIST_SMART_PLUS_CAMPAIGNS when the request specifically requires TikTok’s dedicated Smart+ campaign endpoint.

Input Parameters

integer
Initial campaign result page to retrieve.
array
Generic campaign fields to return. Verified selections include campaign_id and campaign_name; other provider-supported field names remain free-form.
integer
Maximum campaigns to return in this page (1-1000).
array
TikTok Shop store IDs to filter by (maximum 10). Provide gmv_max_promotion_types in the same request when using this filter.
string
Opaque continuation token returned by a previous call; omit for the first page.
array
Campaign buying-type filters.
array
Campaign IDs to return from this list endpoint.
string
required
Authorized advertiser account ID whose campaigns to read.
string
Campaign name filter supported by the campaign list endpoint.
string ("REGULAR_CAMPAIGN" | "IOS14_CAMPAIGN")
Regular or iOS 14 campaign type filter.
string
TikTok campaign objective code to filter by. The provider’s supported set varies by advertiser features and is not restricted to a fixed enum.
string
Primary-status code from TikTok’s Campaign Status enumeration.
string
Detailed TikTok campaign delivery or review status code. The provider-maintained set is not exposed here as an exhaustive enum.
string
TikTok optimization-goal code to filter by for the campaign objective.
string ("TIKTOK_SHOP" | "WEBSITE" | "APP" | "WEB_AND_APP")
Campaign sales-destination filter.
boolean
Filter by split-test status.
array
Creative campaign-type filters.
string ("CATALOG" | "STORE")
Campaign product-source filter.
array
Campaign system-origin filters.
array
Deprecated GMV Max promotion-type filters; use only for legacy queries.
string ("MANUAL" | "SMART_PLUS" | "UPGRADED_SMART_PLUS")
Campaign automation type to filter by.
string
Inclusive campaign creation-time filter end.
string
Inclusive campaign creation-time filter start.
boolean
Filter by Smart Performance Campaign status.
array
Field types to omit from the response.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_CATALOG_PRODUCT_DIAGNOSTICSGet one page of synchronous catalog product diagnostic information.

Input Parameters

string ("ar" | "cs-CZ" | "de" | "en" | "es" | "fil" | "fr" | "id" | "it" | "ja" | "ko" | "ms" | "pl-PL" | "pt" | "ru" | "sv-SE" | "th" | "tr" | "vi" | "zh")
Language for diagnostic text.
integer
Result page number.
string
required
Business Center ID that owns the catalog.
string
Optional catalog feed ID to diagnose.
object
Optional issue severity and category filters.
integer
Issues per page (1-20).
string
required
Catalog ID to diagnose.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_CATALOGSList catalogs in a specified TikTok Business Center, optionally restricted to one catalog ID.

Input Parameters

integer
Initial catalog result page to retrieve.
integer
Maximum catalogs to request in this page (1-1000).
string
Catalog ID to return from this list endpoint.
string
Continuation token returned by a previous call. Omit it for the first page and pass it back unchanged to fetch the next page.
string
required
Authorized Business Center ID whose catalogs to read.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_CATALOG_VIDEOSGet one page of uploaded videos from a catalog.

Input Parameters

integer
Result page number.
string
required
Business Center ID that owns the catalog.
integer
Videos per page (1-50).
string
required
Catalog ID whose uploaded videos to retrieve.
array
Up to 50 catalog video IDs to retrieve.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_COMMENTRead one page of comments for a specific advertiser, ad group, and date range. Returns an opaque continuation cursor and does not change moderation state.

Input Parameters

integer
Initial page number.
string
required
End date in YYYY-MM-DD format.
integer
Page size (1-100).
string ("ASC" | "DESC")
Sort order.
string ("CREATE_TIME" | "LIKES" | "REPLIES")
Field to sort by: CREATE_TIME, LIKES, or REPLIES.
string
required
Start date in YYYY-MM-DD format.
string
Opaque continuation token from a previous response; omit for the first page.
array
Comment types: ALL, COMMENT, or REPLY.
string
required
Field to search by; only ADGROUP_ID is supported.
string
required
Ad group ID to search for.
string
required
Advertiser ID.
array
Comment statuses: ALL, HIDDEN, or PUBLIC.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_CONTENT_EXCLUSION_CATEGORIESGet content exclusion and vertical sensitivity categories for an objective.

Input Parameters

string
required
Advertiser ID.
string ("REACH" | "VIDEO_VIEWS" | "ENGAGEMENT")
required
Advertising objective.
string ("NO_BRAND_SAFETY" | "EXPANDED_INVENTORY" | "STANDARD_INVENTORY" | "LIMITED_INVENTORY")
Brand safety inventory tier.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_CONTEXTUAL_TAGSGet contextual tags available for an objective and optional regions.

Input Parameters

array
Country or region codes.
string
required
Advertiser ID.
string ("REACH" | "VIDEO_VIEWS" | "RF_REACH")
required
Advertising objective.
string ("PULSE" | "STANDARD")
Reach and Frequency campaign type; only valid for RF_REACH.
string ("EXPANDED_INVENTORY" | "LIMITED_INVENTORY" | "NO_BRAND_SAFETY" | "STANDARD_INVENTORY" | "THIRD_PARTY")
Brand safety inventory type.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_CREATIVE_AUTO_MESSAGESGet one page of welcome messages within a TikTok advertiser account.

Input Parameters

string
Initial provider page number (at least 1).
string
Number of welcome messages per page (1-100).
string
Opaque continuation token returned by a previous call.
string
required
Advertiser account ID whose welcome messages will be returned.
string
Optional automatic-message ID to retrieve.
string
required
Automatic-message type. The documented value is WELCOME_MESSAGE.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_CREATIVE_FATIGUE_RESULTSGet one page of Creative Fatigue Detection results for an ad. This API is available only to allowlisted advertisers.

Input Parameters

integer
Result page number.
string
required
Ad ID whose fatigue results to retrieve.
string
required
Open-interval end date in YYYY-MM-DD in the advertiser time zone.
integer
Results per page (1-500).
string
required
Closed-interval start date in YYYY-MM-DD in the advertiser time zone.
string
required
Advertiser account ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_CREATIVE_PORTFOLIOSList one provider page of interactive creative portfolios for an advertiser.

Input Parameters

integer
Initial provider page to retrieve.
integer
Maximum portfolios to return in this page (1-100; defaults to 10).
string
Opaque continuation token from a previous response; omit for the first page.
string
required
Advertiser ID whose portfolios to list.
array
Portfolio IDs to include in the filtering object.
array
Valid portfolio types to include in the filtering object.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_CRMGet CRM Event Sets for an advertiser, optionally filtered by name or ID.

Input Parameters

string
Exact CRM Event Set name to filter by, from 1 to 40 characters.
string
required
Advertiser ID.
array
CRM Event Set IDs to filter by, with at most 50 IDs.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_CUSTOM_AUDIENCESList one page of owned and shared custom audiences for an authorized advertiser, optionally restricted to specified audience IDs.

Input Parameters

integer
Initial custom-audience result page to retrieve.
integer
Maximum audiences to return in this page (1-100).
string
Continuation cursor from a previous response. Omit for the first page; pass it back unchanged to fetch the next page.
string
required
Authorized advertiser account ID whose audiences to read.
array
Audience IDs to return from this list endpoint (1-100 when supplied).

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_CUSTOM_CONVERSIONReturn one page of Custom Conversions configured for a Pixel or app event source.

Input Parameters

integer
Initial provider page.
integer
Results per page (1-1000).
string ("DESC" | "ASC")
Ascending or descending order.
string ("CREATE_TIME" | "TOTAL_COUNT")
Result sorting field.
string
Opaque token returned by a previous call.
string
required
Advertiser ID.
string
Name fuzzy match or exact ID.
string
required
Pixel ID or SAN app platform ID.
string ("PIXEL" | "APP")
required
PIXEL or APP event source.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_DMP_SAVED_AUDIENCEReturn one page of Saved Audience details.

Input Parameters

integer
Initial page number.
integer
Results per page (1-100).
string
Opaque cursor from the previous page.
string
required
Advertiser ID.
array
Saved Audience IDs to return (maximum 100).

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_GMV_MAX_CAMPAIGN_SESSIONSList active max delivery or creative boost sessions for one Product GMV Max campaign ID. This is the campaign-scoped active-session listing; use GET_GMV_MAX_CAMPAIGN_SESSIONS to retrieve specific sessions by session IDs.

Input Parameters

string
required
Product GMV Max campaign ID whose active max delivery or creative boost sessions to list. This selects by campaign, not by session IDs; use GET_GMV_MAX_CAMPAIGN_SESSIONS for exact session ID lookups.
string
required
Authorized advertiser account ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_GMV_MAX_CUSTOMIZED_POSTSList one page of shop-level customized TikTok posts for GMV Max.

Input Parameters

integer
Initial result page (at least 1).
string
Post search keyword. To search by item_id, provide a numeric string of at least 19 characters; ordinary text remains a keyword search.
string
required
TikTok Shop store ID.
integer
Number of posts in this page (1-50).
string ("ASC" | "DESC")
Optional ascending or descending sort direction.
string ("GMV" | "POST_TIME" | "VIDEO_VIEWS" | "VIDEO_LIKES" | "CLICK_THROUGH_RATE" | "PRODUCT_CLICKS")
Field by which to sort customized posts.
string
Optional Product GMV Max campaign ID used to limit the customized posts. Obtain it by listing campaigns with the PRODUCT_GMV_MAX promotion-type filter.
string
Opaque continuation token from a previous response.
array
Product SPU IDs by which to filter customized posts.
string
required
Authorized advertiser account ID.
array
Identity filters (maximum 20).
string
required
Creative source; this endpoint accepts CUSTOMIZED.
boolean
Whether to include videos authorized by authorization code.
string
required
Business Center ID authorized for the TikTok Shop.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_GMV_MAX_IDENTITIESList identities available to an advertiser for GMV Max campaigns.

Input Parameters

string
required
TikTok Shop store ID for which to get GMV Max identities.
string
required
Advertiser account ID for which to get GMV Max identities.
string
required
Business Center ID authorized for the TikTok Shop.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_GMV_MAX_OCCUPYING_ADSCheck which Shopping Ads occupy one TikTok Shop identity or product asset.

Input Parameters

string
required
TikTok Shop store ID containing the identity or product.
array
required
Exactly one asset ID to check. For SPU, use a product SPU ID from the specified TikTok Shop.
string
required
Advertiser account ID whose Shopping Ads occupancy to check.
string ("IDENTITY_TT_USER" | "IDENTITY_BC_AUTH_TT" | "IDENTITY_TTS_TT" | "SPU")
required
Type of occupied identity or product: IDENTITY_TT_USER, IDENTITY_BC_AUTH_TT, IDENTITY_TTS_TT, or SPU.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_GMV_MAX_STORESList TikTok Shops available to an advertiser for GMV Max campaigns.

Input Parameters

string
required
Advertiser account ID for which to list available TikTok Shops.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_GMV_MAX_VIDEOSList one page of authorized or custom-post-eligible TikTok posts for a Product GMV Max campaign.

Input Parameters

integer
Initial result page (at least 1).
string
Post search keyword. To specifically search by item_id, use a numeric string of at least 19 characters; other text is searched as a keyword.
string
required
TikTok Shop store ID.
integer
Number of posts in this page (1-50).
string ("ASC" | "DESC")
Authorized-post sort direction. Sent together with sort_field when custom_posts_eligible is false or omitted.
string ("GMV" | "POST_TIME" | "VIDEO_VIEWS" | "VIDEO_LIKES" | "CLICK_THROUGH_RATE" | "PRODUCT_CLICKS")
Authorized-post sort field. Valid only when custom_posts_eligible is false or omitted.
string
Opaque continuation token from a previous response.
array
Product SPU IDs. Up to 50 are allowed normally; exactly one is required when custom_posts_eligible is true.
string
required
Authorized advertiser account ID.
array
Identity filters (maximum 20).
boolean
Whether to include videos authorized by authorization code.
boolean
Whether to return only posts eligible for customized-post creation.
string
required
Business Center ID authorized for the store.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_OPTIMIZER_RULEGet one page of automated optimizer rules by filters.

Input Parameters

integer
Initial page number.
string
Timezone used for returned date and time fields.
object
Rule filters.
integer
Page size.
string
Opaque continuation token from a previous response.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_OPTIMIZER_RULE_RESULTGet one page of automated optimizer rule results.

Input Parameters

string ("EN" | "ZH" | "JA")
Language of error messages.
integer
Initial page number.
object
Rule-result filters.
integer
Page size.
string
Opaque continuation token from a previous response.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_PANGLE_AUDIENCE_PACKAGESList the include and exclude audience packages available for an advertiser’s Pangle targeting configuration.

Input Parameters

string
required
Advertiser ID whose Pangle audience packages to retrieve.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_PHONE_REGION_CODESGet region names, region codes, and calling codes for phone numbers.

Input Parameters

string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_PIXELReturn one page of Pixels and their configured Pixel Events.

Input Parameters

string
Exact Pixel Code filter.
string
Fuzzy Pixel name filter.
integer
Initial provider page.
string ("EARLIEST_CREATE" | "LATEST_CREATE")
Creation-time sorting order.
string
Exact Pixel ID filter.
object
Additional Pixel filters.
integer
Pixels per page (1-20).
string
Opaque token returned by a previous call.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_SEARCH_AD_NEGATIVE_KEYWORDSList one page of negative keywords for a campaign or ad group in an authorized advertiser account.

Input Parameters

integer
Initial result page to retrieve.
string
required
Campaign or ad-group ID whose keywords to read.
integer
Maximum negative keywords to return in this page (1-50).
string
Opaque continuation token from a previous call; omit for the first page.
string ("CAMPAIGN" | "ADGROUP")
required
Whether object_id identifies a campaign or ad group.
string
required
Authorized advertiser account ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_SHOWCASE_PRODUCTSGet one page of products available in a Showcase.

Input Parameters

integer
Initial result page to retrieve.
object
Optional product SPU filter.
integer
Products in this page (1-1000).
string
required
ID of the identity bound to the Showcase.
string
Opaque continuation token from a previous call; omit for the first page.
array
required
Country or region codes in which the products will be targeted.
string
required
Authorized advertiser account ID.
string ("TT_USER" | "BC_AUTH_TT")
required
Showcase identity type: TT_USER or BC_AUTH_TT.
string
Business Center ID; required when identity_type is BC_AUTH_TT.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_SHOWCASE_REGIONSGet the regions targetable by a Showcase-bound identity.

Input Parameters

string
required
ID of the identity bound to the Showcase.
string
required
Authorized advertiser account ID.
string ("TT_USER" | "BC_AUTH_TT")
required
Showcase identity type: TT_USER or BC_AUTH_TT.
string
Business Center ID; required when identity_type is BC_AUTH_TT.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_SMART_PLUS_ADGROUPSList Smart+ ad group details through TikTok’s dedicated /smart_plus/adgroup/get/ endpoint. Select this instead of LIST_AD_GROUPS for an exact Smart+ endpoint read; use LIST_AD_GROUPS for regular or mixed-automation inventory.

Input Parameters

integer
Initial result page.
array
Smart+ ad group fields to return from the dedicated Smart+ endpoint. Verified selections include adgroup_id and adgroup_name; other provider-supported field names remain free-form.
integer
Page size (1-1000).
array
Ad group ID filter.
string
Continuation token from a prior call.
string
Ad group name filter.
array
Campaign ID filter.
string
required
Advertiser ID whose Smart+ ad groups to read.
string ("APP_PROMOTION" | "LEAD_GENERATION" | "WEB_CONVERSIONS")
Objective filter.
string ("STATUS_ALL" | "STATUS_DELETE" | "STATUS_DELIVERY_OK" | "STATUS_DISABLE" | "STATUS_FROZEN" | "STATUS_NOT_DELETE" | "STATUS_NOT_DELIVERY" | "STATUS_RF_CLOSED" | "STATUS_TIME_DONE")
Primary status filter.
string ("APP" | "INSTANT_FORM" | "LEAD_GEN_CLICK_TO_CALL" | "LEAD_GEN_CLICK_TO_SOCIAL_MEDIA_APP_MESSAGE" | "LEAD_GEN_CLICK_TO_TT_DIRECT_MESSAGE" | "OTHERS" | "WEBSITE")
Promotion type filter.
string ("ADGROUP_STATUS_ADVERTISER_AUDIT" | "ADGROUP_STATUS_ADVERTISER_AUDIT_DENY" | "ADGROUP_STATUS_ALL" | "ADGROUP_STATUS_AUDIT" | "ADGROUP_STATUS_AUDIT_DENY" | "ADGROUP_STATUS_BALANCE_EXCEED" | "ADGROUP_STATUS_BUDGET_EXCEED" | "ADGROUP_STATUS_CAMPAIGN_DELETE" | "ADGROUP_STATUS_CAMPAIGN_DISABLE" | "ADGROUP_STATUS_CAMPAIGN_EXCEED" | "ADGROUP_STATUS_CREATE" | "ADGROUP_STATUS_DELETE" | "ADGROUP_STATUS_DELIVERY_OK" | "ADGROUP_STATUS_DISABLE" | "ADGROUP_STATUS_FROZEN" | "ADGROUP_STATUS_IDENTITY_USED_BY_GMV_MAX_AD" | "ADGROUP_STATUS_INDUSTRY_QUALIFICATION_DENY" | "ADGROUP_STATUS_INDUSTRY_QUALIFICATION_EXPIRED" | "ADGROUP_STATUS_INDUSTRY_QUALIFICATION_MISSING" | "ADGROUP_STATUS_LIVE_NOT_START" | "ADGROUP_STATUS_NOT_DELETE" | "ADGROUP_STATUS_NOT_START" | "ADGROUP_STATUS_PARTIAL_AUDIT_DELIVERY_OK" | "ADGROUP_STATUS_PARTIAL_AUDIT_NO_DELIVERY" | "ADGROUP_STATUS_PIXEL_UNBIND" | "ADGROUP_STATUS_PROMOTE_AD_NOT_APPROVED" | "ADGROUP_STATUS_PROMOTE_WITHDRAW_ORDER" | "ADGROUP_STATUS_REAUDIT" | "ADGROUP_STATUS_RF_ADGROUP_INVALID" | "ADGROUP_STATUS_RF_AD_AUDIT_DENY" | "ADGROUP_STATUS_RF_BOOKING" | "ADGROUP_STATUS_RF_CLOSED_OTHERS" | "ADGROUP_STATUS_RF_DEDUCTION_FAILED" | "ADGROUP_STATUS_RF_NO_DELIVERY_CREATIVE" | "ADGROUP_STATUS_RF_NO_VALID_CREATIVE" | "ADGROUP_STATUS_RF_SCHEDULE" | "ADGROUP_STATUS_RF_SHORT_BALANCE" | "ADGROUP_STATUS_RF_TERMINATE" | "ADGROUP_STATUS_RF_TIME_DONE" | "ADGROUP_STATUS_RF_WITHDRAW_ORDER" | "ADGROUP_STATUS_SEARCH_KEYWORDS_IN_REVIEW" | "ADGROUP_STATUS_SEARCH_KEYWORDS_NOT_AVAILABLE" | "ADGROUP_STATUS_SEARCH_KEYWORDS_PARTIAL_APPROVED" | "ADGROUP_STATUS_SHADOW_ADGROUP_REAUDIT" | "ADGROUP_STATUS_TIME_DONE" | "ADVERTISER_ACCOUNT_INVALID" | "ADVERTISER_ACCOUNT_PUNISH" | "ADVERTISER_CONTRACT_PENDING" | "STATUS_DELETE" | "STATUS_DELIVERY_OK" | "STATUS_DISABLE" | "STATUS_FROZEN" | "STATUS_NOT_DELIVERY" | "STATUS_RF_CLOSED" | "STATUS_TIME_DONE")
Secondary delivery-status filter.
string ("ANCHOR_CLICK_PURCHASE" | "CLICK" | "CONVERSATION" | "CONVERSION_LEADS" | "CONVERT" | "DESTINATION_VISIT" | "ENGAGED_VIEW" | "ENGAGED_VIEW_FIFTEEN" | "FOLLOWERS" | "GMV" | "INITIATE_CHECKOUTS" | "INSTALL" | "IN_APP_EVENT" | "LEAD_GENERATION" | "MESSAGE" | "MT_LIVE_ROOM" | "MT_LIVE_SHOPPING" | "PAGE_VISIT" | "POST_ENGAGEMENT" | "PRODUCT_CLICK_IN_LIVE" | "PROFILE_VIEWS" | "PURCHASES" | "REACH" | "SHOW" | "TRAFFIC_LANDING_PAGE_VIEW" | "VALUE" | "VIDEO_VIEW")
Optimization goal filter.
string
Creation-time filter end.
string
Creation-time filter start.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_SMART_PLUS_ADSList Upgraded Smart+ ad details for an advertiser through TikTok’s dedicated Smart+ endpoint, with optional filters and pagination. Returned creative lists include only explicitly selected creatives, not automatically added creatives.

Input Parameters

integer
Initial result page.
array
Smart+ ad fields to return from the dedicated Smart+ endpoint. Verified selections include ad_id and ad_name; other provider-supported field names remain free-form.
integer
Page size (1-100).
array
Ad group ID filter.
string
Continuation token from a prior call.
array
Campaign ID filter.
string
required
Advertiser ID whose Smart+ ads to read.
string
Modification-time lower bound.
string ("APP_PROMOTION" | "LEAD_GENERATION" | "WEB_CONVERSIONS")
Objective filter.
string ("STATUS_ALL" | "STATUS_CLOSED" | "STATUS_DELETE" | "STATUS_DELIVERY_OK" | "STATUS_DISABLE" | "STATUS_FROZEN" | "STATUS_NOT_DELETE" | "STATUS_NOT_DELIVERY" | "STATUS_RF_CLOSED" | "STATUS_TIME_DONE")
Primary status filter.
string ("ADGROUP_STATUS_FROZEN" | "ADVERTISER_ACCOUNT_PUNISH" | "ADVERTISER_CONTRACT_PENDING" | "AD_STATUS_ADGROUP_ASSET_AUTHORIZATION_LOST" | "AD_STATUS_ADGROUP_AUDIT_DENY" | "AD_STATUS_ADGROUP_DELETE" | "AD_STATUS_ADGROUP_DISABLE" | "AD_STATUS_ADGROUP_INDUSTRY_QUALIFICATION_DENY" | "AD_STATUS_ADGROUP_INDUSTRY_QUALIFICATION_EXPIRED" | "AD_STATUS_ADGROUP_INDUSTRY_QUALIFICATION_MISSING" | "AD_STATUS_ADGROUP_PARTIAL_AUDIT_NO_DELIVERY" | "AD_STATUS_ADVERTISER_AUDIT" | "AD_STATUS_ADVERTISER_AUDIT_DENY" | "AD_STATUS_ALL" | "AD_STATUS_ANCHOR_UNAVAILABLE" | "AD_STATUS_ASSET_AUTHORIZATION_LOST" | "AD_STATUS_AUDIT" | "AD_STATUS_AUDIT_DENY" | "AD_STATUS_BAD" | "AD_STATUS_BALANCE_EXCEED" | "AD_STATUS_BUDGET_EXCEED" | "AD_STATUS_CAMPAIGN_DELETE" | "AD_STATUS_CAMPAIGN_DISABLE" | "AD_STATUS_CAMPAIGN_EXCEED" | "AD_STATUS_COLLECTION_TOGGLED_OFF" | "AD_STATUS_DELETE" | "AD_STATUS_DELIVERY_AND_REAUDIT" | "AD_STATUS_DELIVERY_AND_TRANSCODING_FAIL" | "AD_STATUS_DELIVERY_OK" | "AD_STATUS_DISABLE" | "AD_STATUS_DONE" | "AD_STATUS_EXPLORING" | "AD_STATUS_GOOD" | "AD_STATUS_LIVE_OFFLINE" | "AD_STATUS_MUSIC_AUTHORIZATION_MISSING" | "AD_STATUS_NOT_DELETE" | "AD_STATUS_NOT_START" | "AD_STATUS_OK" | "AD_STATUS_PARTIAL_AUDIT_DELIVERY_OK" | "AD_STATUS_PIXEL_UNBIND" | "AD_STATUS_PRIVACY_POLICY_AUDIT" | "AD_STATUS_PRIVACY_POLICY_REJECTED" | "AD_STATUS_PROCESS_AUDIO" | "AD_STATUS_PRODUCT_UNAVAILABLE" | "AD_STATUS_PROMOTE_ADGROUP_CLOSED" | "AD_STATUS_PROMOTE_AD_OFFLINE_AUDIT" | "AD_STATUS_REAUDIT" | "AD_STATUS_REVIEW_PARTIALLY_APPROVED" | "AD_STATUS_SHOWCASE_AUTHORIZATION_LOST" | "AD_STATUS_UNEXPLORED")
Secondary status filter.
string ("ANCHOR_CLICK_PURCHASE" | "CLICK" | "CONVERSATION" | "CONVERSION_LEADS" | "CONVERT" | "DESTINATION_VISIT" | "ENGAGED_VIEW" | "ENGAGED_VIEW_FIFTEEN" | "FOLLOWERS" | "GMV" | "INITIATE_CHECKOUTS" | "INSTALL" | "IN_APP_EVENT" | "LEAD_GENERATION" | "MESSAGE" | "MT_LIVE_ROOM" | "MT_LIVE_SHOPPING" | "PAGE_VISIT" | "POST_ENGAGEMENT" | "PRODUCT_CLICK_IN_LIVE" | "PROFILE_VIEWS" | "PURCHASES" | "REACH" | "SHOW" | "TRAFFIC_LANDING_PAGE_VIEW" | "VALUE" | "VIDEO_VIEW")
Optimization goal filter.
array
Smart+ ad ID filter.
string
Creation-time filter end.
string
Creation-time filter start.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_SMART_PLUS_CAMPAIGNSList Smart+ campaign details through TikTok’s dedicated /smart_plus/campaign/get/ endpoint. Select this instead of LIST_CAMPAIGNS for an exact Smart+ endpoint read; use LIST_CAMPAIGNS for regular or mixed-automation inventory.

Input Parameters

integer
Result page number.
array
Smart+ campaign fields to return from the dedicated Smart+ endpoint. Verified selections include campaign_id and campaign_name; other provider-supported field names remain free-form.
object
Optional Smart+ campaign filters.
integer
Maximum results on this page (1-1000).
string
Opaque continuation token from a previous response; omit for the first page.
string
required
Authorized advertiser account ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_STOREGet available TikTok Shops under an ad account.

Input Parameters

string
TikTok Shop ID by which to filter.
string
Store type; the documented value is TIKTOK_SHOP.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_TARGETABLE_CARRIERSGet carriers available for ad targeting by country or region.

Input Parameters

string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_TARGETABLE_DEVICE_MODELSGet device models available for ad targeting.

Input Parameters

string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_TARGETABLE_ISPSGet ISP targeting tags supported for specified country- or region-level locations.

Input Parameters

string
required
Targeting scene; this endpoint supports ISP targeting.
array
required
Country- or region-level location IDs whose supported ISPs to return (maximum 1,000).
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_TARGETABLE_LANGUAGESGet languages available for ad targeting.

Input Parameters

string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_TARGETABLE_OS_VERSIONSGet operating-system versions available for targeting.

Input Parameters

string ("ANDROID" | "IOS")
required
Operating system type.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_TARGETABLE_REGIONSGet locations available for an advertiser’s placement, objective, and campaign settings.

Input Parameters

string
Language for returned location names.
array
required
Apps where ads will be delivered.
string ("ALL" | "TO_COUNTRY" | "TO_PROVINCE" | "TO_CITY" | "TO_DISTRICT")
Deepest administrative location level to return.
string
required
Advertiser ID.
string
required
Campaign objective type.
string
Promotion type or optimization location.
string ("ANDROID" | "IOS")
Target device operating system.
string ("STANDARD" | "PULSE")
Reach-and-frequency campaign type when objective_type is RF_REACH.
string ("NO_BRAND_SAFETY" | "EXPANDED_INVENTORY" | "STANDARD_INVENTORY" | "LIMITED_INVENTORY" | "THIRD_PARTY")
Brand safety inventory type for TikTok placement.
string ("VIDEO" | "LIVE" | "PRODUCT_SHOPPING_ADS")
Shopping ads type for PRODUCT_SALES objectives.
string ("APP_INSTALL" | "APP_RETARGETING" | "APP_PREREGISTRATION" | "MINIS")
Required for APP_PROMOTION objectives.
string ("IAS" | "OPEN_SLATE")
Required when brand_safety_type is THIRD_PARTY.
string ("INSTANT_PAGE" | "EXTERNAL_WEBSITE")
Lead-generation promotion target type.
boolean
Whether this is an upgraded Smart+ Search Ads campaign.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_TARGETING_ACTION_CATEGORIESGet targeting action categories available to an advertiser.

Input Parameters

string ("en" | "zh" | "ja" | "de" | "es" | "fr" | "id" | "it" | "ko" | "ru" | "th" | "tr" | "vi" | "ar" | "pt" | "ms")
Language for category names.
string
required
Advertiser ID.
array
Special ad categories to filter for.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_TARGETING_INTEREST_CATEGORIESGet advertiser interest categories, optionally filtered by placement and special industry.

Input Parameters

integer ("1" | "2")
Interest category version: 1 for interest_category or 2 for interest_category_v2.
string ("en" | "zh" | "ja" | "de" | "es" | "fr" | "id" | "it" | "ko" | "ru" | "th" | "tr" | "vi" | "ar" | "pt" | "ms")
Language for returned category names.
array
Placements whose version-2 interest categories to return.
string
required
Advertiser ID.
array
Special ad categories to filter for.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_TIKTOK_LINKED_AD_ACCOUNTSList one page of ad accounts linked to one TikTok account asset in a Business Center.

Input Parameters

integer
Initial result page to retrieve.
string
required
TikTok account asset ID whose linked ad accounts to list.
integer
Maximum assigned TikTok accounts to return in this page (1-50).
string ("TT_ACCOUNT" | "MANAGED_BUSINESS_ACCOUNT")
required
TikTok account asset type: TT_ACCOUNT or MANAGED_BUSINESS_ACCOUNT.
string
Opaque continuation token returned by a previous call; omit for the first page and pass it back unchanged for the next page.
string
required
Business Center ID that owns the TikTok account asset.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_LIST_TT_VIDEOReturn one page of Spark posts bound to an advertiser. Each post remains subject to its creator-issued authorization status and window; advertiser OAuth alone does not grant rights to use a creator’s post.

Input Parameters

integer
Initial provider page number.
string
Fuzzy post-text search or exact post ID search.
integer
Posts per page (1-50).
array
Post types to include; defaults upstream to VIDEO and CAROUSEL.
string
Opaque continuation cursor from the previous response; omit for the first page.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_MIGRATE_CATALOGMigrate a catalog from an ad account to a Business Center.

Input Parameters

string
required
ID of the Business Center to migrate the catalog to.
string
required
ID of the catalog to migrate.
string
required
ID of the ad account that owns the catalog.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_PROMOTE_SPLIT_TESTEnd a split test by promoting its selected winning ad group and starting that ad group’s delivery, which may incur spend.

Input Parameters

string
required
Advertiser ID.
string
required
Winning ad group ID to run.
string
required
Split test group ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_QUERY_RF_CONTRACTRead whether an advertiser has a valid Reach & Frequency or TikTok Pulse contract for a specified date. This operation does not create, update, or otherwise mutate contracts or financial settings. Availability may depend on TikTok allowlisting or account entitlement.

Input Parameters

string
required
Advertiser ID
string
required
A certain date within the contract validity, or the start/end time of an ad group. Format: “2020-09-18”.
string ("STANDARD" | "PULSE")
Use this field to specify whether you want to query TikTok Pulse contract. Enum values: STANDARD (Reach & Frequency), PULSE(TikTok Pulse). Note: This is an allowlist-only feature. If you would like to access it, please contact your TikTok representative.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_RECOMMEND_BIDGet a suggested bid for an objective and target locations.

Input Parameters

string
Campaign ID; use 0 when no campaign exists yet.
array
required
IDs of locations to target.
string
required
Advertiser ID.
string ("APP_PROMOTION" | "ENGAGEMENT" | "LEAD_GENERATION" | "PRODUCT_SALES" | "REACH" | "RF_REACH" | "TRAFFIC" | "VIDEO_VIEWS" | "WEB_CONVERSIONS")
required
TikTok campaign objective.
string ("ACTIVE" | "ACTIVE_PAY" | "ACTIVE_REGISTER" | "ADD_BOOKSHELF" | "ADD_PAYMENT_INFO" | "ADD_TO_WISHLIST" | "ANCHOR_CLICK" | "APPLET_DEAL" | "APPOINTMENT_DOWNLOAD_BUTTON" | "ASCRIPTION_PHONE" | "AUTHORIZATION" | "BANKCARD_INFORMATION" | "BOOST" | "BUTTON" | "CERTIFICATION_INFORMATION" | "CLICK_CALL_DY" | "CLICK_DOWNLOAD" | "CLICK_LANDING_PAGE" | "CLICK_SHOPWINDow" | "CLICK_WEBSITE" | "CLUE_CONFIRM" | "CLUE_HIGH_INTENTION" | "CLUE_INTERFLOW" | "CLUE_PAY_SUCCEED" | "COMMENT_ACTION" | "COMMODITY_CLICK" | "COMPLETE_TUTORIAL" | "CONSULT" | "CONSULT_CLUE" | "CONSULT_EFFECTIVE" | "CONVERSION_LEADS" | "COUPON" | "CREATE_GAMEROLE" | "CUSTOMER_EFFECTIVE" | "DEEP_PURCHASE" | "DESTINATION_VISIT" | "DIALBACK" | "DIALBACK_CONFIRM" | "DIALBACK_CONNECT" | "DOWNLOAD_BUTTON" | "DOWNLOAD_DETAIL" | "DOWNLOAD_FINISH" | "DOWNLOAD_START" | "EC_CLICK_BUY" | "EC_CLICK_PRODUCT" | "EC_CONFRIM_DEAL" | "EC_LIVE_CART" | "EC_LIVE_CLICK_PRODUCT_ACTION" | "EC_LIVE_COMMENT_ACTION" | "EC_LIVE_ENTER_ACTION" | "EC_LIVE_FOLLOW_ACTION" | "EC_LIVE_GIFT_ACTION" | "EC_LIVE_NATIVE_ACTION" | "EC_LIVE_ORDER" | "EC_LIVE_REDIRECT_TO_STORE_ACTION" | "EC_LIVE_SLIDECART_CLICK_ACTION" | "EC_SUBMIT_ORDER" | "EFFECTIVE_COPY" | "ENGAGED_VIEW" | "ENGAGED_VIEW_FIFTEEN" | "ENTER_HOMEPAGE" | "FEED_LIVE_HOMEPAGE" | "FOLLOW_ACTION" | "FOLLOW_LIVE_ENTER" | "FOLLOW_VIDEO_PLAY_FINISH" | "FORM" | "FORM_ANSWER" | "FORM_BUTTON" | "FORM_CONNECT" | "FORM_DEEP" | "FORM_DETAIL" | "GAME_ADDICTION" | "HIGHVALUE_CLUE" | "IDCARD_INFORMATION" | "IMPRESSION_LEVEL_AD_REVENUE" | "INITIATE_ORDER" | "INSTALL_FINISH" | "INTENTION_CLUE" | "INVALID_CLUE" | "IN_APP_AD_CLICK" | "IN_APP_AD_IMPR" | "IN_APP_CART" | "IN_APP_DETAIL_UV" | "IN_APP_ORDER" | "IN_APP_PAY" | "IN_APP_UV" | "LANDING_PAGE_VIEW" | "LAUNCH_APP" | "LIKE_ACTION" | "LINK_ACTION" | "LIVE_APPOINTMENT" | "LIVE_CARD_CLICK" | "LIVE_CLICK_PRODUCT_ACTION" | "LIVE_COMMENT_ACTION" | "LIVE_ENTER_ACTION" | "LIVE_FOLLOW_ACTION" | "LIVE_GIFT_ACTION" | "LIVE_HOMEPAGE" | "LIVE_JOIN_GROUP" | "LIVE_NATIVE_ACTION" | "LIVE_REDIRECT_TO_STORE_ACTION" | "LIVE_ROOM_ACTION" | "LIVE_SLIDECART_CLICK_ACTION" | "LIVE_STAY_TIME" | "LIVE_SUCCESSORDER_ACTION" | "LIVE_SUCESSORDER_PAY" | "LOAN" | "LOAN_APPLY" | "LOAN_COMPLETION" | "LOAN_CREDIT" | "LOCATION_ACTION" | "LOGIN" | "LOGIN_ACTION" | "LONGTERM_CUSTOMER" | "LOTTERY" | "LT_ROI" | "MAP_SEARCH" | "MESSAGE" | "MESSAGE_ACTION" | "MESSAGE_CLICK" | "MESSAGE_JOIN_GROUP" | "MESSAGE_SELF_SERVICE" | "MESSAGE_SEND" | "MULTIPLE" | "MULTI_NATIVE_ACTION" | "NATIVE_ACTION" | "NAV_BAR" | "NEW_FOLLOW_ACTION" | "NEXT_DAY_OPEN" | "NOVEL_CHAPTER" | "ON_WEB_CART" | "ON_WEB_DETAIL" | "ON_WEB_ORDER" | "ON_WEB_REGISTER" | "OTHER" | "OTO_PAY" | "OTO_STAY_TIME" | "PAGE_VIEW" | "PAGE_VISIT" | "PAID_CLUE" | "PAY_ACTION" | "PAY_ROI" | "PERSONAL_INFORMATION" | "PHONE" | "PHONE_BUTTON" | "PHONE_CONFIRM" | "PHONE_CONNECT" | "PHONE_DETAIL" | "PHONE_EFFECTIVE" | "PREFERRED_LEAD" | "PREMIUM_PAYMENT" | "PRE_LOAN_CREDIT" | "PURCHASE_OF_GOODS" | "QQ" | "RATE" | "READING_TIME" | "REDIRECT" | "REDIRECT_TO_SHOP" | "REDIRECT_TO_STORE" | "REGISTER_ACTION" | "RESERVATION" | "RSS" | "SALES_LEAD" | "SEARCH" | "SEVEN_DAY_OPEN" | "SHARE_ACTION" | "SHOPPING" | "SHOPPING_ACTION" | "SHOPPING_CART" | "START_TRIAL" | "STAY_TIME" | "SUBSCRIBE" | "SUCCESSORDER_ACTION" | "SUCCESSORDER_PAY" | "UG_EFFECTIVE_ACTION" | "UG_EFFECTIVE_DEAL" | "UG_EFFECTIVE_SHARE" | "UG_EFFECTIVE_SPEECH" | "UG_ROI" | "UNLOCK_ACHIEVEMENT" | "UPDATE_LEVEL" | "VIEW" | "VOTE" | "XPATH")
TikTok conversion-event code for the ad group.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_RECOMMEND_INTEREST_CATEGORIESRecommend additional interest categories from one or more seed keywords.

Input Parameters

string ("FUZZ_MATCH" | "SEMANTIC_RECOMMEND")
Recommendation search mode.
integer
Maximum recommendations to return (1-50).
string
Single seed keyword; ignored upstream when keywords is supplied.
array
Seed keywords processed separately (maximum 10).
string ("fr" | "id" | "it" | "ja" | "ms" | "ar" | "vi" | "en" | "ru" | "es" | "th" | "tr" | "hi" | "zh" | "de" | "ko")
Seed keyword language.
string
required
Advertiser ID.
string ("GENERAL_INTEREST" | "PURCHASE_INTENTION")
Audience type; PURCHASE_INTENTION is deprecated.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_RECOMMEND_TARGETING_CATEGORIESRecommend interest and action targeting categories for specified regions and an optional app.

Input Parameters

string
Optional mobile app ID when promoting an app.
array
required
Country or region codes for recommendations.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_RECOMMEND_TARGETING_HASHTAGSGenerate targeting hashtag recommendations from up to ten seed keywords.

Input Parameters

array
required
Seed keywords for hashtag recommendations (maximum 10).
string ("AND" | "OR")
Whether recommendations combine all keywords or process each separately.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_REPLY_TO_COMMENTPublish a public reply to an ad comment as the specified TikTok identity. Confirm the account, target comment, identity, and final text before calling; the reply is externally visible.

Input Parameters

string
required
Public reply text to publish.
string
required
Ad ID associated with the target comment.
string
required
Comment ID to reply to.
string
required
Identity ID that will publish the reply.
string
required
Comment-post type. TikTok currently supports only REPLY.
string
required
Advertiser ID that owns the ad.
string ("CUSTOMIZED_USER" | "TT_USER")
required
Publishing identity type: CUSTOMIZED_USER or TT_USER.
string
required
TikTok video ID containing the target comment.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_SAVE_PLAYABLESave and name a previously uploaded playable asset for an advertiser.

Input Parameters

string
required
Uploaded playable asset ID to save.
string
required
Advertiser ID that owns the uploaded playable.
string
required
Playable asset name (1-20 characters).

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_SEARCH_FILE_IMAGE_ADSearch for one page of advertiser images and return a continuation cursor.

Input Parameters

integer
Initial provider page.
object
Image filters. Resubmit this value with a continuation cursor.
integer
Images per page (1-100).
string
Opaque continuation token from a previous call.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_SEARCH_FILE_VIDEO_ADSearch for one page of advertiser videos and return a continuation cursor.

Input Parameters

integer
Initial provider page.
object
Video filters. Resubmit this value with a continuation cursor.
integer
Videos per page (1-100).
string ("CREATE_TIME" | "MODIFY_TIME")
Descending sort field.
string
Opaque continuation token from a previous call.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_SEARCH_TARGETINGSearch for or list targeting categories and hashtags for interests and behaviors.

Input Parameters

string
Language of the seed keywords; defaults upstream to en.
object
Optional special-industry filters.
string
required
Advertiser ID.
string
required
Primary targeting type; only INTEREST_AND_BEHAVIOR is supported.
array
Seed keywords, each at most 100 characters.
array
Secondary interest and behavior targeting types to return.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_SEARCH_TARGETING_LOCATIONSSearch geographical targeting tags by location, ZIP-code, or postal-code keywords.

Input Parameters

array
required
Location, ZIP-code, or postal-code search terms.
array
Location types to include in search results.
array
required
Apps where ads will be delivered.
string ("FUZZY_SEARCH" | "BATCH_REGION_SEARCH" | "BATCH_ZIPCODE_SEARCH")
required
Fuzzy single search or batch region/ZIP-code search mode.
array
Country or region codes used to constrain results.
string
required
Advertiser ID.
string ("REACH" | "TRAFFIC" | "VIDEO_VIEWS" | "LEAD_GENERATION" | "ENGAGEMENT" | "APP_PROMOTION" | "WEB_CONVERSIONS" | "PRODUCT_SALES")
required
Campaign objective.
string
Promotion type required for applicable objectives.
string ("ANDROID" | "IOS")
Target device operating system.
string ("NO_BRAND_SAFETY" | "EXPANDED_INVENTORY" | "STANDARD_INVENTORY" | "LIMITED_INVENTORY" | "THIRD_PARTY")
Brand safety type for TikTok placement.
string ("IAS" | "OPEN_SLATE")
Required with THIRD_PARTY brand safety.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_SET_AUDIENCE_SEGMENTCreate a named audience segment or delete one by audience ID.

Input Parameters

string ("create" | "delete")
required
Create or delete an audience segment.
string
required
Advertiser ID.
string
Audience ID, required for delete.
string
Audience name, required for create.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_SET_SEARCH_AD_NEGATIVE_KEYWORDSSet negative keywords on Search Ads campaigns or ad groups. By default, add the supplied keywords while preserving existing values. With replace=true, replace each object’s entire existing negative-keyword set and remove any existing values that are not supplied.

Input Parameters

boolean
False adds the supplied keywords to each object’s existing negative keywords. True replaces each object’s entire existing negative-keyword set with the supplied keywords, removing values not supplied.
array
required
Negative keywords to add.
array
required
Campaign or ad-group IDs to receive the keywords.
string ("CAMPAIGN" | "ADGROUP")
required
Whether object_ids identify campaigns or ad groups.
string
required
Authorized advertiser account ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_SET_SMART_PLUS_DELIVERY_STATUSEnable or disable up to 20 Smart+ campaigns, ad groups, or ads; enabling may start delivery and spend. Updates may partially succeed, so inspect the returned results.

Input Parameters

array
required
Smart+ campaign, ad group, or ad IDs to update (1-20).
string
required
Advertiser ID that owns the resources.
string ("CAMPAIGN" | "ADGROUP" | "AD")
required
Type of Smart+ resource identified by resource_ids.
string ("DISABLE" | "ENABLE")
required
Delivery operation to apply: ENABLE or DISABLE.
string ("POSTBACK_WINDOW_MODE1" | "POSTBACK_WINDOW_MODE2" | "POSTBACK_WINDOW_MODE3" | "UNSET")
Optional campaign postback window mode; valid only for CAMPAIGN.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_SHARE_CREATIVE_ASSETSShare controlled creative assets from one advertiser with specified target advertiser accounts.

Input Parameters

string ("VIDEO" | "IMAGE" | "MUSIC")
Type of creative assets being shared.
array
required
Material IDs to share (1-20).
string
required
Source advertiser ID that controls the assets.
array
required
Target advertiser IDs that will receive the assets (1-10).

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_SHARE_CUSTOM_AUDIENCESShare up to ten custom audiences with up to ten advertisers in the same Business Center.

Input Parameters

object
Optional operation context.
string
required
Operator advertiser ID.
array
required
Custom audience IDs to share (1-10).
array
required
Recipient advertisers in the same Business Center (1-10).

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_SUBMIT_ACCOUNT_VERIFICATIONSubmit sensitive business or individual identity details for external review of an ad account or Business Center; the submission cannot be withdrawn through this tool.

Input Parameters

string
Business Center ID. Provide this or advertiser_id, but not both.
string
Ad account ID. Provide this or bc_id, but not both.
object
Business verification details. Provide one form only.
object
Individual identity verification details. Provide one form only.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_SUBMIT_CREATIVE_SMART_TEXTSubmit feedback parameters for an existing Smart Text recommendation flow. This feedback operation does not generate text; use GENERATE_CREATIVE_SMART_TEXT to create recommendations.

Input Parameters

integer
Number of texts to generate (1-20).
array
Keywords; required for CUSTOMIZED parameters.
string ("EN" | "JA" | "RU" | "VI")
Language; required for CUSTOMIZED parameters.
string
required
Ad group ID.
string ("RECOMMENDED" | "CUSTOMIZED")
Whether TikTok predicts or the caller supplies recommendation parameters.
string
Industry ID.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_SUBMIT_UNIONPAY_VERIFICATIONSubmit identity and UnionPay account details to verify an eligible business license. This starts a sensitive review with no documented rollback.

Input Parameters

string
required
Ad account ID created with the business license being verified.
string
required
UnionPay account number containing 12-19 digits.
string
required
Identity document number in the format required for its document type.
string
required
Business Center ID that owns the ad account being verified.
string
required
Legal representative name on the identity document.
string
required
Legal representative’s phone number containing exactly 11 digits.
string ("ID_CARD" | "PASSPORT" | "HK_MACAO_EXIT_ENTRY_PERMIT" | "TAIWAN_MAINLAND_TRAVEL_PERMIT" | "HK_MACAO_MAINLAND_TRAVEL_PERMIT")
Type of the legal representative’s identity document.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_SUBSCRIBE_SUBSCRIPTIONCreate a webhook subscription for a developer application and external callback URL.

Input Parameters

string
required
Developer application ID from My Apps.
string
required
Developer application secret from My Apps.
string
required
Public webhook callback URL.
string ("REPORT_DATA_CHANGE" | "AD_ACCOUNT_SUSPENSION" | "LEAD" | "AD_GROUP" | "AD" | "TCM_VIDEOS" | "CREATIVE_FATIGUE" | "API_SERVICE_STATUS")
required
Object whose events will be delivered.
object
required
Entity-specific subscription details.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_TRANSFER_BCIrreversibly recharge or deduct cash, vouchers, or credit for an ad account or Business Center. This moves real financial value and cannot be assumed reversible. Require explicit finance-owner confirmation immediately before execution; verify the level, payer and payee IDs, portfolio, RECHARGE versus REFUND direction, currency context, every amount, minimum transfer limits, and a fresh idempotency request ID. Never retry with a different request ID after an uncertain result. Some behavior is allowlist-only.

Input Parameters

string
required
Business Center ID.
string
Idempotency request ID. Reusing it prevents duplicate processing; ad-account idempotency is allowlist-only and guaranteed for 30 minutes.
object
Detailed cash, voucher, or credit amounts, valid only at ADVERTISER level.
number
Positive cash or credit amount, rounded to two decimal places.
string
Child Business Center ID supported by the SDK request contract.
number
Positive voucher amount, rounded to two decimal places; unsupported at BC level.
string
Ad account ID, required at ADVERTISER level.
string ("RECHARGE" | "REFUND")
required
Payment operation. RECHARGE adds funds or credit; REFUND deducts funds or credit.
string ("ADVERTISER" | "BC")
ADVERTISER moves funds for an ad account; BC changes Business Center credit balance.
string
Payment Portfolio ID, required when the client has multiple portfolios.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_TRANSFER_BC_PIXELPermanently transfer ownership of the specified advertiser pixel to the destination Business Center. This ownership transfer is irreversible through this tool; confirm the exact pixel and destination Business Center before calling.

Input Parameters

string
required
Destination Business Center ID.
string
required
Pixel code to transfer.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_TRANSFER_PAGE_LIBRARYMigrate an advertiser’s leads into a newly created Business Center form library. Confirm both account IDs before changing lead ownership location.

Input Parameters

string
required
Business Center ID to migrate the advertiser’s leads to.
string
required
ID of the advertiser that owns the leads.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UNASSIGN_BC_ASSETRevoke the specified member’s access to the Business Center asset. The member immediately loses the assigned permissions; confirm the exact disposable member and asset before calling.

Input Parameters

string
required
Business Center ID.
string
required
Business Center user ID losing access.
string
required
Asset ID whose member access will be revoked.
string ("ADVERTISER" | "CATALOG" | "LEAD" | "TT_ACCOUNT" | "MANAGED_BUSINESS_ACCOUNT")
required
Type of the asset.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UNASSIGN_TIKTOK_ACCOUNT_FROM_ADVERTISERUnlink a TikTok account from an ad account in the same Business Center. This destructively removes the existing account association.

Input Parameters

string
required
Business Center ID that owns the TikTok account asset.
string
required
TikTok account asset ID to unlink from the advertiser.
string ("TT_ACCOUNT" | "MANAGED_BUSINESS_ACCOUNT")
required
TikTok account asset type: TT_ACCOUNT or MANAGED_BUSINESS_ACCOUNT.
string
required
ID of an ad account in the same Business Center from which to unlink the TikTok account.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UNBIND_CATALOG_EVENTSOURCEUnbind a mobile app, website Pixel, or both from a catalog.

Input Parameters

string
required
Business Center ID.
string
Mobile app ID to unbind.
string
required
Catalog ID.
string
Website Pixel code to unbind.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UNBIND_TT_VIDEOIrreversibly remove an advertiser’s binding to the exact Spark post. Confirm the advertiser and post with the user before calling; using the post again requires a valid creator-issued authorization flow.

Input Parameters

string
required
Exact Spark post ID to unbind.
string
required
Advertiser ID currently bound to the Spark post.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UNSUBSCRIBE_SUBSCRIPTIONIrreversibly cancel a developer-app webhook subscription.

Input Parameters

string
required
Developer application ID from My Apps.
string
required
Developer application secret from My Apps.
string
required
Subscription ID returned by the subscription endpoints.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_ADUpdate ordinary ads and their creative fields in an ad group. Updates default the AI-generated-content disclosure to NOT_DECLARED; most standard creatives also require media, ad text and a call to action, or a TikTok post ID, even for patch-style updates.

Input Parameters

array
required
Ads and creative fields to update; each object requires ad_id.
string
required
Ad group ID.
boolean
Whether to apply a patch-style update.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_ADGROUPUpdate an ad group, including irreversible changes to its HFSS setting. Availability may depend on TikTok allowlisting or account entitlement.

Input Parameters

number
Advertising budget. It cannot be updated when Campaign Budget Optimization (budget_optimize_on) is on. For how to configure budget settings, see Budget. To directly see the daily budget value range for a currency, see Currency-Daily budget value range. Note: The new budget should be at least 105% of the current spend. You can run a synchronous report or an asynchronous report to get the spend data via the Basic data metric spend .
string
Gender that you want to target. Enum: GENDER_FEMALE,GENDER_MALE,GENDER_UNLIMITED
string
You can choose between PACING_MODE_SMOOTH and PACING_MODE_FAST. For PACING_MODE_SMOOTH, the budget is allocated evenly within the scheduled time. PACING_MODE_FAST would consume budget and produce results as soon as possible. When Campaign Budget Optimization (budget_optimize_on) is on, your setting will be ignored and it will be set as PACING_MODE_SMOOTH. Otherwise, this field is required.
array
A list of targeting behavioral category objects.
boolean
Whether the promoted content is HFSS (High Fat, Salt, Sugar) Product/Brand. If your ad is promoting or prominently featuring a product/brand classed as high in fat, salt or sugar, set this field to true. In regulated regions, HFSS ads must only be targeted to users aged 18 or over. You can set this field to true when your targeting locations include locations in the UK, Australia, New Zealand, and the European Union. Supported values: true,false. Note: You can only update this setting from false to true but not vice versa.
array
IDs of the Internet service providers (ISP) that you want to target. Valid only when you specify a valid location ID at the country or region level via location_ids at the same time. You can use /tool/targeting/list/ to get the ISP IDs that you can target for a location ID. Note: When you pass in isp_ids, you cannot set the placement as Global App Bundle only (placements =PLACEMENT_GLOBAL_APP_BUNDLE).
string
Bidding strategy that determines how the system manages your cost per result, spends your budget, and how it delivers ads. For enum values, see Enumeration - Bidding Strategy. This field cannot be updated when Campaign Budget Optimization (CBO) is enabled (budget_optimize_on = TRUE).
number
Required when deep_bid_type is VO_MIN_ROAS. ROAS goal for Value Optimization. Value range: For in-app advertising scenarios (objective_type is APP_PROMOTION, optimization_goal is VALUE, and optimization_event is AD_REVENUE_VALUE): 0.01-10.For Product Shopping Ads with product source as TikTok Shop (shopping_ads_type is PRODUCT_SHOPPING_ADS and product_source is STORE): 0.01-20.For other scenarios: 0.01-1,000.
number
Valid only when bid_type is BID_TYPE_CUSTOM and billing_event is CPC, CPM, or CPV. Bid price. The average cost per result that you want to achieve (for Cost Cap bidding strategy). When Campaign Budget Optimization (budget_optimize_on) is on, we suggest that you set the same bid value for all ad groups in the campaign. bid_price needs to be lower than budget set at the campaign level and ad group level. See Bidding-Bidding limits to learn more about the bid verification mechanism.
integer
Frequency, together with frequency_schedule, controls how often people see your ad (only available for REACH ads). The below conditions should be both met:1 1 For example, frequency = 2 & frequency_schedule = 3 means “show ads no more than twice every 3 day”.
array
Codes of the languages that you want to target. For the list of languages codes supported, see Enumeration - Language Code. You can get language codes via /tool/language/, and if you don’t want to limit the languages you target, assign an empty value to this field or do not pass in this field.
string
required
Ad group ID.
array
Age groups you want to target. For enum values, see Enumeration - Age Group. In certain scenarios, creation of ad groups that target the age group 13-17 (AGE_13_17) in the US, Latin America, the European Economic Area, the UK, Switzerland, or Canada will not be allowed. See New age restrictions for ads on TikTok to learn more.If you are impacted by the restrictions and leave the age_groups field unspecified or set it as [] without setting exclude_age_under_eighteen to true, an error will occur. If the ad group targets the age group 13-17 (AGE_13_17) in the US, Latin America, the European Economic Area, the UK, Switzerland, or Canada and you typically leave the age_groups field unspecified or set it as [], we recommend that you set exclude_age_under_eighteen to true simultaneously to avoid any errors.
string
Ad delivery arrangement, in the format of a string that consists of 48 x 7 characters. Each character is mapped to a 30-minute timeframe from Monday to Sunday. Each character can be set to either 0 or 1. 1 represents delivery in the 30-minute timeframe, and 0 stands for non-delivery in the 30-minute timeframe. The first character is mapped to 0:01-0:30 of Monday; The second character is mapped to 0:31-1:00 of Monday, and the last character represents 23:31-0:00 Sunday. Note: If not specified, all-0, or all-1 are considered as full-time delivery.
array
Carriers that you want to target. A carrier is valid only when the in_use field for the carrier is true. The carriers must be consistent with the location(s) that you want to target. See Get Carriers for detailed information.
array
Target zip/postal code IDs; incremental updates are supported. Provide location_ids, zipcode_ids, or both; combined count <=3,000. Get IDs as geo_id with geo_type=ZIP_CODE from /tool/targeting/search/. ZIP codes support the US; postal codes support Canada, Brazil, Indonesia, Thailand, Vietnam, with the latter four allowlist-only. Not supported with special_industries or objective_type=RF_REACH; placements must include PLACEMENT_TIKTOK. Locations cannot overlap. After initially targeting the US, updates cannot remove all US locations and leave only non-US countries. To clear these IDs, pass []; because targeting is mandatory, also provide location_ids if these were the only locations.
string
Ad group name, maximum character allowed is 512 and it cannot contain emoji.
array
An list of audience IDs. You can get audience IDs by using the /dmp/custom_audience/list/ endpoint.
number
Specify bid price in this field after you’ve chosen a bidding strategy for in-app events, for example VO_MIN.
array
Target location IDs from /tool/targeting/search/ or /tool/region/. Provide location_ids, zipcode_ids, or both; their combined location/zip/postal ID count cannot exceed 3,000. Locations cannot overlap (for example, US and California). After initially targeting the US, updates may change to other US locations but cannot remove all US locations and leave only non-US countries. If tiktok_subplacements contains TIKTOK_LITE, Japan and South Korea cannot both be removed. To clear location IDs, pass []; because targeting is mandatory, also provide zipcode_ids if these were the only locations.
string
required
Advertiser ID.
object
Rules that specify your audience. Valid if objective_type is TRAFFIC or APP_PROMOTION. For details, see Audience Rules.
string
Required and valid only when app_promotion_type is APP_RETARGETING at the campaign level. Not supported when app_promotion_type is not set to APP_RETARGETING at the campaign level. App retargeting audience type. You need to use the same settings as when creating the ad group. Enum value:NEW_CUSTOM_AUDIENCE (retargeting custom audience). If you want to specify an empty retargeting custom audience for your App Retargeting ads, do not pass audience_ids and excluded_audience_ids. If you want to specify a non-empty retargeting custom audience for your App Retargeting ads, you can specify an Include Audience via audience_ids, or an Exclude Audience via excluded_audience_ids , or both simultaneously. If both audience_ids and excluded_audience_ids are specified, they cannot contain the same IDs.
string
Bidding strategy for in-app events. For enum values and their descriptions, see Enumeration - Deep-level Bidding Strategy. Note: When secondary_optimization_event is specified, you need to pass in deep_bid_type at the same time.
array
Device connection types that you want to target. For enum values, see Enumeration - Connection Type.
string
The schedule type can be either SCHEDULE_START_END or SCHEDULE_FROM_NOW. If you choose SCHEDULE_START_END, you need to specify a start time and an end time. If you choose SCHEDULE_FROM_NOW, you only need to specify a start time and the end time will be automatically set to 10 years later than the start time.
boolean
Whether to disable sharing of ads in this ad group to third-party platforms. The value Trueis valid when the conditions below are all met:objective_type at the campaign level is set as one of the following objectives: APP_PROMOTION, WEB_CONVERSIONS, REACH, TRAFFIC, VIDEO_VIEWS, ENGAGEMENT, LEAD_GENERATION. Placement: placement_type= PLACEMENT_TYPE_AUTOMATIC orplacement_type= PLACEMENT_TYPE_NORMAL, and placements = PLACEMENT_TIKTOK Note: This field supports incremental updates.
string ("ALL" | "HIGH")
Spending power that you want to target. Enum values: ALL, HIGH. If it is set to HIGH, you can target high spending users who typically spend more on purchases on TikTok ads than average users. Note: :This field does not support the advertising objectives PRODUCT_SALES and RF_REACH at the campaign level. See Advertising objectives for details. This field supports Automatic Placement and Select Placement with TikTok included. Therefore, you need to set placement_type to PLACEMENT_TYPE_AUTOMATIC, or include PLACEMENT_TIKTOK in the value of placements. Note that if you specify Pangle as a placement, the spending power targeting won’t take effect on Pangle. When auto_targeting_enabled is true at the ad group level, then spending_power will be automatically set to ALL.
string ("UNSET" | "IOS14_MINUS" | "IOS14_PLUS" | "ALL")
iOS targeting: UNSET targets iOS 14.4 or earlier; IOS14_MINUS targets before 14.0; IOS14_PLUS targets 14.5+ in Dedicated Campaigns; ALL targets 14.5+ only for iOS App Retargeting or catalog Video Shopping retargeting optimized to app. campaign_type=IOS14_CAMPAIGN requires IOS14_PLUS and allows at most two active ad groups. For IOS14_PLUS, use an iOS app_id, operating_systems=["IOS"], compatible min_ios_version, and optimization_goal in CLICK, INSTALL, IN_APP_EVENT, VALUE; omit min_android_version, shopping_ads_retargeting_type, and shopping_ads_retargeting_actions_days, and do not use ad-level deeplink_type=DEFERRED_DEEPLINK. Once IOS14_PLUS, it cannot change. App Retargeting 14.5+ requires ALL and min_ios_version>=14.5; omit this field for 14.4 or earlier. ALL is forced for iOS App Retargeting (APP_RETARGETING + APP_IOS) and iOS catalog Video Shopping app retargeting (VIDEO, CATALOG, APP_IOS, retargeting not OFF). Otherwise defaults to UNSET.
string
Required when ios14_targeting is specified. Minimum iOS version. For enum values, see Enumeration - Minimum iOS Version.
array
Valid only in Search Ads Campaigns. A list of search keywords, that is, words or phrases that are used to match your ads with the terms people are searching for. Max size: 1,000. To confirm whether a campaign is a Search Ads Campaign, call /campaign/get/ and check the is_search_campaign returned for the campaign. To learn more about Search Ads Campaigns, see Create Search Ads Campaigns. Note: For each ad group, you can configure a maximum of 1,000 search keywords.Once the search keywords or the targeted locations are updated, the keywords will go into the review process again.
boolean
Whether to allow comments on your ads on TikTok. Note: When deep funnel optimization is enabled, you cannot update deep_funnel_event_source, deep_funnel_event_source_id, and deep_funnel_optimization_event.
array
IDs of the device models that you want to target. Use /tool/device_model/ to get the complete list of device model IDs and their statuses, and only active devices (is_active = True in the response of /tool/device_model/) can be used to create ads. Note: Device model (device_model_ids) and device price (device_price_ranges) cannot be set at the same time.
array
Household income that you want to target. Enum values: TOP5(Top 5% of ZIP codes), TOP10(Top 10% of ZIP codes), TOP10_25(Top 10% -25% of ZIP codes), TOP25_50(Top 25% - 50% of ZIP codes). Currently, this field has the following limitations: Not supported in Reach&Frequency type ads.Only works on TikTok Placement in the US.
string ("EXPANDED_INVENTORY" | "STANDARD_INVENTORY" | "LIMITED_INVENTORY")
Brand safety type. EXPANDED_INVENTORY: most inappropriate and mature content removed; replaces NO_BRAND_SAFETY as the next-version default. STANDARD_INVENTORY: content appropriate for most brands. LIMITED_INVENTORY: no mature themes. Use /tool/region/ for eligible regions. Updating brand_safety_type, category_exclusion_ids, or vertical_sensitivity_id is allowlist-only and subject to pre-bid brand-safety update eligibility. First-party filtering for Auction APP_PROMOTION, WEB_CONVERSIONS, TRAFFIC, LEAD_GENERATION, and PRODUCT_SALES is also allowlist-only.
boolean
Whether the promoted content complies with LHF (Less Healthy Foods) regulations. By setting is_lhf_compliance to true, you confirm that any food or drink products you advertise on TikTok in the UK comply with the 2024 Less Healthy Foods Regulations and all other applicable laws. Supported values: true,false. Note: Starting January 1st, 2026, when your ad targets locations in the UK and is_hfss is true, is_lhf_compliance is required and must be set to true.
array
Device operating systems that you want to target. Only one value is allowed. Enum values: ANDROID, IOS. This field is required in two scenarios: objective_type is APP_PROMOTION``objective_type is TRAFFIC and promotion_type is APP_IOS or APP_ANDROID
string
Saved Audience ID from /dmp/saved_audience/create/. Valid only when the campaign has no Housing, Employment, or Credit specical_industries, objective_type is not PRODUCT_SALES, TikTok placement is selected, and auto_targeting_enabled is not true. The Saved Audience and ad group must have the same advertiser ID. Do not also pass targeting options already contained in the Saved Audience. Its device settings must not conflict with the ad group, such as Android versus ios14_targeting=IOS14_PLUS, or iOS versus an Android app. Use /dmp/saved_audience/list/ to diagnose targeting conflicts. Any saved age_groups must satisfy current age restrictions.
string
Required when schedule_type is SCHEDULE_START_END. Schedule end time (UTC+0), in the format of "YYYY-MM-DD HH:MM:SS". The end time cannot be later than "2038-01-01 00:00:00".
array
Contextual tag IDs. You can use /tool/contextual_tag/get/ to get available contextual tags. See Contextual targeting to learn more about how to use contextual targeting. Note: This is an allowlist-only feature. If you would like to access it, please contact your TikTok representative.Only supports REACH and VIDEO_VIEWS as objectives (objective_type) at the campaign level. Not supported when brand_safety_type is set to THIRD_PARTY.
integer
Frequency schedule, together with frequency, controls how often people see your ad (only available for REACH ads). See frequency fields for more.
number
Day 2 retention ratio. Formula: next_day_retention = conversion_bid_price/deep_cpa_bid. Value range is (0, 1]. Only valid when placements is PLACEMENT_PANGLE and secondary_optimization_event is NEXT_DAY_OPEN. Note: If you want to use this field, please pass in conversion_bid_price, deep_bid_type, and next_day_retention at the same time, and make sure the value of them meets the calculation formula. Otherwise there might be unexpected errors.
array
Targeting device price range. 10000 means 1000+. The numbers must be in multiples of 50. Important: The upper limit you set will be added by 50 and the resulting new number will be used as the actual upper limit for device targeting. The actual upper limit is shown in the ad group settings in TikTok Ads Manager. If you set and get the price range of [0, 250], it actually means [0, 300].
string
Minimum Android version. For enum values, see Enumeration - Minimum Android Version.
string
Required when you pass in schedule_type. Schedule start time (UTC+0), in the format of "YYYY-MM-DD HH:MM:SS". The start time can be up to 12 hours earlier than the current time, but cannot be later than "2028-01-01 00:00:00". Note: This field cannot be updated if the schedule_start_time for the ad group is earlier than the current time.
object
Settings about targeting expansion. Note: Starting June, 2024, you can no longer enable Automatic targeting or Targeting expansion for your ad groups. To ensure a smooth API integration, we recommend you migrate to Smart Targeting.
number
Valid only when bid_type is BID_TYPE_CUSTOM and billing_event is OCPM. Where you can set a target cost per conversion for oCPM (Optimized Cost per Mille). conversion_bid_price needs to be lower than budget set at the campaign level and ad group level. See Bidding-Bidding limits to learn more about the bid verification mechanism.
array
IDs of additional interest categories that you want to use to target audience. To search for additional interest categories, use /targeting/search/ (recommended) or /tool/interest_keyword/recommend/.
array
A list of audience IDs to be excluded. You can get audience IDs by using the /dmp/custom_audience/list/ endpoint.
array
IDs of general interest categories that you want to use to target audiences. To search for or list general interest category IDs, use /targeting/search/ (recommended) or /tool/interest_category/.To get recommended interest category IDs based on your industry, use /tool/targeting_category/recommend/.
boolean
Whether to include your ads in Search Ads, namely to show your ads to users when they search for your business on TikTok. You can only use this field when the following conditions are met:Advertising objective: The advertising objective (objective_type) is one of the following objectives: APP_PROMOTION,WEB_CONVERSIONS (with is_search_campaign as false),TRAFFIC, and LEAD_GENERATION.When objective_type is LEAD_GENERATION, promotion_type needs to be set to LEAD_GENERATION.Placements: placement_type is set to PLACEMENT_TYPE_AUTOMATIC, or placement_type is set to PLACEMENT_TYPE_NORMAL and PLACEMENT_TIKTOK is included in placements.You want to use this field to update the value of this field from false to true. If is_search_campaign is true, you cannot update the value of this field from false to true. To learn more about Search Ads, see Automatic Search Placement.
boolean
Whether to enable automated targeting. Enum values: true, false. Note: Starting June, 2024, you can no longer enable Automatic targeting or Targeting expansion for your ad groups. To ensure a smooth API integration, we recommend you migrate to Smart Targeting.
array
Pangle app block list ID. You can get an ID via the app_package_id field returned by Get Pangle block list. It only takes effect when Pangle placement is selected.
array
This field can only be updated when any of the following conditions is met: schedule_start_time of the ad group has not been reached. schedule_start_time of the ad group has been reached, but the operation_status is DISABLE and the cost is 0. To retrieve the schedule_start_time and operation_status of an ad group, use /adgroup/get/. Content exclusion category IDs. You can use /tool/content_exclusion/get/ to get a list of content category IDs (excluded_category_list) that can be excluded from being displayed next to your ads. Note: Updating Brand Safety settings, including brand_safety_type, category_exclusion_ids, and vertical_sensitivity_id, is currently an allowlist-only feature. If you would like to access it, please contact your TikTok representative.
boolean
Whether to turn on Smart audience. Enum values: true, false. To learn more about Smart audience and how to turn on Smart audience, see Smart Targeting.
array
The custom action that you want to use as “Exclude” conditions for filtering out the shopping ads audiences to be retargeted. When shopping_ads_retargeting_type is LAB3, you need to pass in either included_custom_actions or excluded_custom_actions.
array
The custom action that you want to use as “Include” conditions for filtering out the shopping ads audiences to be retargeted. When shopping_ads_retargeting_type is LAB3, you need to pass in either included_custom_actions or excluded_custom_actions.
string
This field can only be updated when any of the following conditions is met: schedule_start_time of the ad group has not been reached. schedule_start_time of the ad group has been reached, but the operation_status is DISABLE and the cost is 0. To retrieve the schedule_start_time and operation_status of an ad group, use /adgroup/get/. Vertical sensitivity category ID. You can use /tool/content_exclusion/get/ to get a list of vertical categories containing sensitive content (vertical_sensitivity_list) that can be excluded from appearing next to your ads. Note: Updating Brand Safety settings, including brand_safety_type, category_exclusion_ids, and vertical_sensitivity_id, is currently an allowlist-only feature. If you would like to access it, please contact your TikTok representative.
string
For catalogs in Business Center, you must specify the ID of the Business Center that a catalog belongs to. Note: Starting June 30th, 2024, when product_source is STORE, you can no longer use catalog_authorized_bc_id to update the ad group because it will be ignored. If you update existing ad group where product_source is STORE, the existing catalog_authorized_bc_id, if present for the ad groups, will no longer be returned.
string ("PIXEL" | "OFFLINE" | "CRM")
Required when deep_funnel_optimization_status is ON. The event source type. Enum values: PIXEL: Pixel. OFFLINE: Offline Event Set.CRM: CRM Event Set. Note: When deep funnel optimization is enabled, you cannot update deep_funnel_event_source, deep_funnel_event_source_id, and deep_funnel_optimization_event.
boolean
Valid only when at the campaign level is_search_campaign is true. Whether to enable automated keywords and let the system automatically generate keywords after you add ads. This expands high-quality traffic to improve performance. View high-performing automated keywords in reporting. Supported values: true, false. Default value: false. Note: Automated keywords in Search Ads Campaigns are currently an allowlist-only feature. If you would like to access it, please contact your TikTok representative.
boolean
Whether to exclude the ages younger than 18. Use this field only in scenarios where targeting the age group 13-17 (AGE_13_17) in the US, Latin America, the European Economic Area, the UK, Switzerland, or Canada is not supported. In other scenarios, this field is not supported. See the description of age_groups for details. Enum values: true, false. Default value: false.
string
Required when deep_funnel_optimization_status is ON. Event Source ID. When deep_funnel_event_source is PIXEL, specify a Pixel ID via this field. To obtain a list of Pixels, use /pixel/list/.When deep_funnel_event_source is OFFLINE, specify an Offline Event Set ID via this field. To obtain a list of Offline Event Set IDs, use /offline/get/. When deep_funnel_event_source is CRM, specify a CRM Event Set ID via this field. To obtain a list of CRM Event Set IDs, use /crm/list/. Note: When deep funnel optimization is enabled, you cannot update deep_funnel_event_source, deep_funnel_event_source_id, and deep_funnel_optimization_event.
string
The secondary goal when optimization goal (optimization_goal) is Install (INSTALL) or Value (VALUE). For enum values, see Conversion events - Secondary-goal events. Note: When secondary_optimization_event is specified, you need to pass in deep_bid_type at the same time.
string ("LAB1" | "LAB2" | "LAB3" | "OFF")
Valid when shopping_ads_type is VIDEO and product_source is CATALOG. The retargeting type of shopping ads. Enum values: LAB1: Retargeting audiences who viewed products or added products to cart but didn’t purchase products. LAB2: Retargeting audiences who added products to cart but didn’t purchase products. LAB3: Retargeting audiences using custom combination. OFF: No retargeting.
string
Required when deep_funnel_optimization_status is ON. Deep funnel optimization event. To find out the supported values for Standard Events available for Pixels, Offline Event Sets, and CRM Event Sets, see the “Event name for ad creation” column in Supported Pixel events. To find the list of optimization events for a Pixel, use /pixel/list/ and check the returned optimization_event. Example: SHOPPING.
array
IDs of purchase intention categories that you want to use to target audiences with an interest in purchases related to a content category. To search for or list purchase intention category IDs, use /targeting/search/. Note: The endpoint supports the incremental update of purchase_intention_keyword_ids.
string ("ON" | "OFF")
Valid only when promotion_type is LEAD_GENERATION. The status of deep funnel optimization. Deep funnel optimization optimizes both your upper funnel events and deeper funnel events. You can select a secondary event alongside the primary optimization event, which can help improve campaign effectiveness. Enum values: ON: To enable deep funnel optimization. OFF: To disable deep funnel optimization. Default value: OFF. To learn about how to configure deep funnel optimization for Lead Generation ads, see Lead Generation ad with optimization location as Instant Form and Lead Generation ad with optimization location as Website. Note: Deep funnel optimization with CRM events is currently an allowlist-only feature. If you would like to access it, please contact your TikTok representative. Deep funnel optimization with Pixel or Offline events is generally available.
boolean
Whether to turn on Smart interests & behaviors. Enum values: true, false. To learn more about Smart interests & behaviors and how to turn on Smart interests & behaviors, see Smart Targeting.
array
IDs of the Pangle audiences that you want to exclude. Valid only for Pangle placement. You can get audience IDs (package_id) by using the /pangle_audience_package/get/ endpoint. You need to set bind_type to EXCLUDE. Do not specify this field and included_pangle_audience_package_ids at the same time.
array
IDs of the Pangle audiences that you want to include. Valid only for Pangle placement. You can get audience IDs (package_id) by using the /pangle_audience_package/get/ endpoint. You need to set bind_type to INCLUDE. Do not specify this field and excluded_pangle_audience_package_ids at the same time.
integer
The valid time range for the specified audience action. Audiences who have completed the specified action within the time range will be retargeted by the shopping ads. Required when shopping_ads_retargeting_type is LAB1 or LAB2. Value range: 1, 2, 3, 7, 14, 30, 60, 90, 180.
string ("OR" | "AND")
Logical relation between the Video Shopping Ads retargeting audience and custom audience_ids. Valid only with shopping_ads_type=VIDEO, product_source=CATALOG, shopping_ads_retargeting_type in LAB1, LAB2, or LAB3, and provided audience_ids. OR targets members of either audience; AND targets members of both. Removing the custom audience after this is set automatically resets the relation to null.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_ADGROUP_BUDGETUpdate the budgets of ad groups. This operation can affect billing, credit, invoices, budgets, contracts, or payments; require explicit approval and an isolated account.

Input Parameters

array
Either budget or scheduled_budget has to be set. To update the lifetime budgets of one or more ad groups, specify budget.To update the daily budgets or dynamic daily budgets of one or more ad groups, specify scheduled_budget. Information about the new lifetime budgets that you want to set for one or more ad groups. Max size: 20. Note: The changes to the lifetime budgets of one or more ad groups will take effect immediately.
string
required
Advertiser ID.
array
Either budget or scheduled_budget has to be set. To update the lifetime budgets of one or more ad groups, specify budget.To update the daily budgets or dynamic daily budgets of one or more ad groups, specify scheduled_budget. Information about the scheduled budget changes to the daily budgets or dynamic daily budgets of one or more ad groups. Max size: 20. Note: The scheduled budget changes will take effect from 00:00 a.m. the following day in the ad account’s time zone.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_ADGROUP_RFUpdate an R&F ad group. Availability may depend on TikTok allowlisting or account entitlement.

Input Parameters

number
Budget. Please fill in this number based on the data returned via the ad inventory estimate API.
string
Target gender. For enum values, see Appendix - Enumeration - Audience Gender.
boolean
Whether the promoted content is HFSS foods (foods that are high in fat, salt, or sugar). Please note that the European market prohibits the promotion of HFSS foods to underage users.
string
Feed type option. Enum: STANDARD_FEED, TOP_FEED. STANDARD_FEED refers to large inventory with normal CPM price while TOP_FEEDrefers to limited inventory with higher CPM price.
integer
frequency, together with frequency_schedule, controls how often people see your ad (only available for REACH ads). For example, frequency = 2 & frequency_schedule = 3 means “show ads no more than twice every 3 days”. The following conditions should be met:1 ≤ frequency ≤ frequency_schedule.1 ≤ frequency_schedule ≤ min (schedule_end_time - schedule_start_time, 30).The frequency cap determined by frequency and frequency_schedule does not exceed four times a day.
array
Audience language. Available values: see Appendix - Enumeration - Audience Language.
string
required
ID of the ad group to be modified. The objective_type of the campaign it belongs to must be RF_REACH.
array
Audience age range. If your targeting locations include Israel or Brazil, AGE_13_17 cannot be used. For enum values, see Appendix - Enumeration - Audience Age Range. In certain scenarios, creation of ad groups that target the age group 13-17 (AGE_13_17) in the US will not be allowed. See New age restrictions for ads on TikTok to learn more. If you use targeting options that are not supported for the age group 13-17 in the US and leave the age_groups field unspecified or set it as [], an error will occur. You need to explicitly specify the exact age groups that you want to target, such as AGE_18_24, in the field to avoid any errors.
array
Carriers that you want to target. A carrier is valid only when the in_use field for the carrier is true. The carriers must be consistent with the location(s) that you want to target. For enum values (carrier_id), see Appendix - Carriers.
string
Name of the ad group. It must not exceed 100 characters or contain any emojis.
array
IDs of the audiences that you want to target. For an audience to be targeted or excluded in R&F ads, you must set audience_sub_type to REACH_FREQUENCY when creating or updating the audience. Note: You cannot use Lookalike Audience in R&F ads. Otherwise, an error will occur.
array
IDs of the targeted locations. The location can be at the country or region level, the Province, DMA (Designated Market Area) or Metropolitan level, or the city level. Location targeting supports a single country or region only. If you want to target multiple locations, they must be from the same country or region. You can find the supported countries and regions from Reach & Frequency.
string
required
Advertiser ID
string ("STANDARD" | "SCHEDULE" | "SEQUENCE" | "VIEW_OPTIMIZE" | "OPTIMIZE")
Ad delivery strategy. STANDARD: even delivery; unavailable for View+ (optimization_goal=REACH, cpv_video_duration=SIX_SECONDS). SCHEDULE: delivery in specified periods and requires schedules. SEQUENCE: specified ad order and requires expected_orders. VIEW_OPTIMIZE: maximize view-through rate and available only for View+. OPTIMIZE: optimized delivery.
array
Device connection types that you want to target. Default value: unlimited. For enum values, see Enumeration - Connection Type.
array
Ad delivery information. When delivery_mode is set to SEQUENCE, the number of objects in this array represents the number of ads that you will specify the sequence for.
boolean
Whether sharing to third-party platforms is disabled for ads in this ad group
integer
Number of users reached to be purchased, in the unit of 1,000. Please fill in this number based on the results of inventory estimation.
boolean
Whether to prohibit users from posting comments to your ads on TikTok.
array
IDs of the device models that you want to target. Currently only brand-level model IDs are supported. When this field is specified, device_price_ranges must not be specified. For enum values of device model IDs on different levels, please see Device Models. Note: Only active devices (is_active = True in the response of /tool/device_model/) can be used to create ads.
string ("EXPANDED_INVENTORY" | "STANDARD_INVENTORY" | "LIMITED_INVENTORY")
Brand safety type. EXPANDED_INVENTORY: most inappropriate and mature content removed; replaces NO_BRAND_SAFETY as the next-version default. STANDARD_INVENTORY: content appropriate for most brands. LIMITED_INVENTORY: no mature themes. Use /tool/region/ for eligible regions. Updating brand_safety_type, category_exclusion_ids, or vertical_sensitivity_id is allowlist-only and subject to pre-bid brand-safety update eligibility.
array
Operating system. See Appendix - Enumeration - Audience Operating System.
string
Buying type. Allowed values: FIXED_SHOW: Purchase to achieve a fixed amount of impressions.FIXED_REACH: Purchase to reach a fixed number of users.FIXED_BUDGE: Purchase with a fixed budget.
string
Schedule end time (UTC+0), in the format of YYYY-MM-DD HH:MM:SS. The time interval between schedule_start_time and schedule_end_time must not exceed 90 days. The value of this field must be at YYYY-MM-DD HH:59:59 for the time zone where the ad will be delivered. For instance, if an advertiser in the UTC-5 time zone wants to create an R&F ad group that ends delivery on November 10th, 2023, this field must be set to "2023-11-10 04:59:59".
array
Contextual tag IDs. You can use /tool/contextual_tag/get/ to get available contextual tags. Note: This is an allowlist-only feature. If you would like to access it, please contact your TikTok representative. Only supports RF_REACH as objectives (objective_type) at the campaign level. Not supported when brand_safety_type is set to THIRD_PARTY.Not supported when feed_type is set to TOP_FEED.If you set rf_campaign_type to PULSE in /campaign/create/, then you must enter contextual tags of PREMIUM type in this field.
integer
frequency_schedule, together with frequency, controls how often people see your ad (only available for REACH ads). See frequency field for more.
array
Targeting device price range. 10000 means 1000+. The numbers must be in multiples of 50. Important: The upper limit you set will be added by 50 and the resulting new number will be used as the actual upper limit for device targeting. The actual upper limit is shown in the ad group settings in TikTok Ads Manager. If you set and get the price range of [0, 250], it actually means [0, 300].
string
Schedule start time (UTC+0), in the format of YYYY-MM-DD HH:MM:SS. The time interval between schedule_start_time and schedule_end_time must not exceed 90 days. The value of this field must be at YYYY-MM-DD HH:00:00 for the time zone where the ad will be delivered. For instance, if an advertiser in the UTC-5 time zone wants to create an R&F ad group that starts delivery on November 1st, 2023, this field must be set to "2023-11-01 05:00:00".
integer
Impressions to be purchased, in the unit of 1,000. Please fill in this number based on the data returned via the ad inventory estimate API.
array
IDs of the audiences that you want to exclude. For an audience to be targeted or excluded in R&F ads, you must set audience_sub_type to REACH_FREQUENCY when creating or updating the audience. Note: You cannot use Lookalike Audience in R&F ads. Otherwise, an error will occur.
array
Interest classification. If the interest is specified, users that do not meet interest target will be excluded during delivery. Do not specify if you wish to target everyone. Use /tool/target_recommend_tags/ to get a list of recommended interest categories based on your targeting regions and your industries. Use /tool/interest_category/ endpoint to get the complete list of interest categories.
array
This field can only be updated when any of the following conditions is met: schedule_start_time of the ad group has not been reached. schedule_start_time of the ad group has been reached, but the operation_status is DISABLE and the cost is 0. To retrieve the schedule_start_time and operation_status of an ad group, use /adgroup/get/. Content exclusion category IDs. You can use /tool/content_exclusion/get/ to get a list of content category IDs (excluded_category_list) that can be excluded from being displayed next to your ads. Note: Updating Brand Safety settings, including brand_safety_type, category_exclusion_ids, and vertical_sensitivity_id, is currently an allowlist-only feature. If you would like to access it, please contact your TikTok representative.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_ADGROUP_STATUSEnable, disable, or permanently delete up to 20 ad groups. Enabling may resume ad delivery and spend; allow_partial_success can leave only some requested ad groups changed.

Input Parameters

array
required
The IDs of the ad groups to be operated on. Size range: 1-20.
string
required
Advertiser ID.
string ("DISABLE" | "ENABLE" | "DELETE")
required
The operation to be performed on the ad groups. Enum values: DISABLE (pause), ENABLE (enable), DELETE (delete). Note: The status of deleted ad groups or ad groups in deleted campaigns cannot be modified.ENABLE and DISABLE operations are not supported for R&F ad groups.
boolean
Whether to allow partial success for the operation. Enum values: true, false. Default value: false. If this field is set to true and you specify an operation for multiple ad groups, the operation can succeed for only some of the specified ad groups. In this case, the ineligible ad groups will be filtered out.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_AD_STATUSEnable, disable, or permanently delete regular or ACO ads. Enabling may resume ad delivery and spend.

Input Parameters

array
Regular ad IDs whose statuses to update.
array
Automated Creative Optimization ad IDs whose statuses to update.
string
required
Advertiser ID.
string ("ENABLE" | "DISABLE" | "DELETE")
required
Operation to apply: ENABLE may resume delivery and spend, DISABLE pauses delivery, and DELETE permanently deletes the ads.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_ADVERTISER_ACCOUNTUpdate one TikTok ad account’s name, contact, company, license, certificate, promotion-link, address, or billing tax-number metadata. This action cannot change budgets, funding, payment settings, or account status. Provide at least one metadata field to update.

Input Parameters

string
New business address shown on receipts.
string
New company name. First verify company_name_editable through advertiser information; otherwise TikTok requires representative support.
object
Billing and invoicing tax-number fields. Use vat for France or tax_id for Brazil; all keys and values are sent as strings.
string
New business license number. TikTok supports this field only for eligible account registration regions.
string
New name of the account contact person.
string
required
Ad account ID whose non-budget metadata will be updated. This action does not support Business Center budget updates.
string
New contact email for the ad account.
string
New contact phone number for the ad account.
New promotion link.
string
New ad account name.
string
TikTok image ID of the new business license image.
array
New additional business certificate images.
boolean
Whether to submit changed certificate information for review. Set true only when changing company, promotion_link, license_no, license_image_id, or qualification_images; otherwise omit it.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_ADVERTISER_BUDGETSConsequential financial action that updates, resets, increments, deducts, or sets minimum budgets for ad accounts in a Business Center. These changes can alter or reset spend controls and may be irreversible; verify the Business Center, ad accounts, operation, and amounts before execution.

Input Parameters

string
Idempotency request ID, valid only for INCREMENTAL_UPDATE. TikTok documents a 30-minute idempotency window and allowlist requirement.
array
required
Budget settings for one or more ad accounts. UPDATE and RESET accept at most 50 entries; INCREMENTAL_UPDATE and ONE_CLICK_SET accept exactly one.
string ("UPDATE" | "RESET" | "INCREMENTAL_UPDATE" | "ONE_CLICK_SET")
Budget operation: UPDATE settings, RESET consumption, add or deduct via INCREMENTAL_UPDATE, or set the provider minimum via ONE_CLICK_SET.
string
required
Business Center containing the ad accounts whose budgets will change.
string
Optional child Business Center ID associated with the budget update.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_APPUpdate a mobile app configured for an advertiser. The retargeting attribution setting defaults to NON_RETARGETING when omitted.

Input Parameters

string
required
Application ID.
string ("AdBrix" | "Adform" | "Adjust" | "Adobe" | "AdobeRTCDP" | "Adzcore" | "Amperity" | "AnyTrack" | "AppAdforce" | "AppLink" | "AppMetrica" | "AppsFlyer" | "Apptrian" | "Ayomakan" | "BASE" | "BigCommerce" | "Bird" | "Blip" | "Blotout" | "CTMDefault" | "Cafe24" | "Capico" | "Chatcone" | "Cheq" | "Cinarra" | "CommandersAct" | "ConversionLiftStudy" | "DataHash" | "Dentsu" | "Desty" | "DoubleClick" | "Driftrock" | "ECWID" | "ECWID_RESELLER" | "Elevar" | "Eventbrite" | "EventsAPIGateway" | "Fandango" | "FlashTalking" | "FutureShop" | "Gamesight" | "GoogleSheet" | "GoogleTagManagerClient" | "GoogleTagManagerServer" | "Grivy" | "Habu" | "Halosis" | "Haravan" | "HiPlatform" | "Hightouch" | "Huangbaoche" | "HubSpot" | "Journify" | "Kantar" | "Kargo" | "Kochava" | "KopiKenangan" | "Kyte" | "LadiPage" | "Lazada" | "LeadBolt" | "LeadCenterCSV" | "Lifesight" | "LiveRamp" | "MParticle" | "Macromil" | "Magento" | "ManyChat" | "Marketo" | "MercadoShops" | "Merkle" | "MetaRouter" | "Metaps" | "Nielsen" | "Nuvemshop" | "OhoChat" | "OneChatAi" | "OpenCart" | "Other" | "PMG" | "Pancake" | "Placed_powered_by_Foursquare" | "PrestaShop" | "Qiscus" | "Qontak" | "RespondIo" | "RudderStack" | "SHOPLINE" | "Salesforce" | "SalesforceMarketingCloud" | "Sapo" | "Segment" | "ServingsSys" | "Shift4Shop" | "Shopify" | "Shoplazza" | "Shopware" | "SignalSight" | "Singoo" | "SingooCloud" | "Singular" | "Square" | "Tealium" | "Tenjin" | "Testee" | "Ticketmaster" | "Tiendanube" | "TikTokAppAPI" | "TikTokBusinessSDK" | "TikTokCustomInstantPage" | "TikTokEC1PSeller" | "TikTokEC3PStore" | "TikTokLeadAd" | "TlnkIo" | "TomoroCoffee" | "Tray" | "TripleWhale" | "VTEX" | "Vidoadsplus" | "Weborama" | "Wix" | "WooCommerce" | "WordPress" | "ZZG" | "Zapier" | "Zoho" | "Zwiz" | "doubleverify" | "lojaintegrada" | "myTracker")
Third-party tracking partner enum value.
string ("ANDROID" | "IOS")
Application platform: ANDROID or IOS.
string
Application download URL.
object
Third-party tracking URLs.
string
required
Advertiser ID.
string ("RETARGETING" | "NON_RETARGETING")
Retargeting attribution setting; defaults to NON_RETARGETING.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_BC_ASSET_GROUPRename an Asset Group or add or remove its advertiser assets or members.

Input Parameters

string
required
Business Center ID.
string ("ADD" | "DELETE")
ADD or DELETE; required for ASSET and MEMBER updates.
array
Assets to add or delete; required for an ASSET update.
array
Members to add or delete; required for a MEMBER update.
string ("ASSET" | "MEMBER" | "NAME")
required
Entity to update: ASSET, MEMBER, or NAME.
string
required
Asset Group ID to update.
string
New name; required for a NAME update.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_BC_BILLING_GROUPUpdate Billing Group membership, name, email recipients, or default status. Providing new_billing_group_emails replaces the entire existing list, removing accounts changes invoice grouping, and is_primary changes the default group. Obtain explicit approval immediately before execution and verify every changed value.

Input Parameters

string
required
Business Center ID.
boolean
Whether to make this the default Billing Group.
string
required
Billing Group ID to update.
array
Ad account IDs to add to the Billing Group.
array
Ad account IDs to remove from the Billing Group.
string
New Billing Group name.
array
Replacement email list. Providing this overwrites all existing Billing Group emails.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_BC_MEMBERUpdate a Business Center member’s name or basic role, optionally including a finance role update. A name or basic role must be provided.

Input Parameters

string
required
Business Center ID.
string
required
Business Center member ID.
string
New member name, up to 250 characters.
string ("ADMIN" | "STANDARD")
New basic role: ADMIN or STANDARD.
string
Optional child Business Center ID.
object
Optional advanced finance role update.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_BLOCKEDWORDReplace one exact blocked word in an advertiser’s moderation list. Confirm both old and new values before calling because the moderation behavior changes immediately.

Input Parameters

string
required
Replacement blocked word.
string
required
Existing blocked word to replace.
string
required
Advertiser ID whose moderation list will change.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_CAMPAIGNUpdate the mutable fields of an existing campaign.

Input Parameters

number
New campaign budget.
string
Purchase order number.
string
required
Campaign ID.
string
required
Advertiser ID.
string
New campaign name, maximum 512 characters; emoji is unsupported.
array
Special ad categories.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_CAMPAIGN_STATUSEnable, disable, or permanently delete campaigns. Enabling may resume ad delivery and spend; postback_window_mode is accepted only while disabling.

Input Parameters

array
required
Campaign IDs whose statuses to update.
string
required
Advertiser ID.
string ("ENABLE" | "DISABLE" | "DELETE")
required
Operation to apply: ENABLE may resume delivery and spend, DISABLE pauses delivery, and DELETE permanently deletes the campaigns.
string ("POSTBACK_WINDOW_MODE1" | "POSTBACK_WINDOW_MODE2" | "POSTBACK_WINDOW_MODE3")
SKAN 4.0 postback window mode, valid only when disabling an iOS 14 campaign.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_CATALOGUpdate the name of a catalog owned by a TikTok Business Center.

Input Parameters

string
required
New catalog name (1-100 characters).
string
required
Business Center ID that owns the catalog.
string
required
ID of the catalog to update.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_CATALOG_FEEDUpdate a catalog feed or schedule. INCREMENTAL preserves products omitted from the next import; OVERWRITE permanently removes omitted products, so confirm the complete source file before using it.

Input Parameters

string
required
Business Center ID.
string
required
Feed ID.
string
required
Feed name.
string
required
Catalog ID.
string ("INCREMENTAL" | "OVERWRITE")
required
INCREMENTAL adds or updates products. OVERWRITE replaces the feed’s catalog data and permanently removes products omitted from the next feed import; confirm the complete source file before choosing OVERWRITE.
object
Optional remote-feed schedule.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_CATALOG_FEED_SCHEDULE_STATUSSet one catalog feed schedule to ON or OFF. Read the current status first because TikTok rejects an unchanged value; ON starts recurring ingestion.

Input Parameters

string
required
Business Center ID that owns the catalog feed.
string ("ON" | "OFF")
required
New schedule status, which must differ from the feed’s current status. ON requires uri, interval_type, and timezone to be configured already.
string
required
ID of the catalog feed whose schedule status to change.
string
required
Catalog ID containing the feed schedule.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_CATALOG_PRODUCTUpdate up to 5,000 products using the fields documented for each catalog type.

Input Parameters

string
required
Business Center ID.
string
Feed ID; omit to use the default catalog.
array
required
Products to update, at most 5,000 per request.
string
required
Catalog ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_CATALOG_SETUpdate a product set name, filter conditions, or both.

Input Parameters

string
required
Business Center ID.
string
required
Catalog ID.
object
Exactly one and or or list of replacement conditions.
string
required
Product set ID.
string
New product set name, up to 128 characters.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_COMMENT_STATUSChange the moderation visibility status of exact comments. Confirm the advertiser, every comment ID, and whether the operation hides or restores comments before calling; this affects public content.

Input Parameters

string ("BIDDING" | "BRAND")
Ad source type: BIDDING or BRAND.
string ("HIDDEN" | "PUBLIC")
required
New comment status: HIDDEN or PUBLIC.
array
required
Exact comment IDs whose visibility status will change.
string
required
Advertiser ID whose comments will change.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_CUSTOM_CONVERSIONUpdate the name or description of a Custom Conversion configuration.

Input Parameters

string
New unique name without emoji.
string
New description without emoji.
string
required
Advertiser ID.
string
required
Custom Conversion ID to update.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_DMP_CUSTOM_AUDIENCERename a custom audience, modify it using uploaded files, or update its audience enhancement setting.

Input Parameters

string ("REPLACE" | "APPEND" | "REMOVE")
File modification type, used only with file_paths.
array
Uploaded files used to modify the audience; fewer than 50 are recommended.
object
Optional operation context.
string
required
Advertiser ID.
string
Convert a NORMAL audience to REACH_FREQUENCY.
string
required
Custom audience ID.
boolean
Whether audience enhancement is enabled.
string
New audience name; required when file_paths is omitted.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_DMP_CUSTOM_AUDIENCE_LOOKALIKEManually refresh specified lookalike custom audiences.

Input Parameters

string
required
Advertiser ID.
array
required
Lookalike custom audience IDs to update.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_FILE_IMAGE_ADUpdate an advertiser image name.

Input Parameters

string
required
Image ID.
string
required
New image name, 1-100 characters.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_FILE_VIDEO_ADUpdate an advertiser video name.

Input Parameters

string
required
Video ID.
string
required
New video name, 1-100 characters.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_GMV_MAX_CAMPAIGNUpdate supported fields on an existing GMV Max campaign; at least one field to update must be provided. Perform mutation QA only on a disabled or draft campaign; this action does not enable or publish it.

Input Parameters

number
Optional new campaign budget.
number
Optional new ROAS bid.
array
Optional replacement shop items.
string
required
GMV Max campaign ID to update.
string
required
Authorized advertiser account ID.
string
Optional new campaign name.
string ("SCHEDULE_FROM_NOW" | "SCHEDULE_START_END")
Optional new campaign schedule type.
array
Optional replacement item group IDs.
object
Optional promotion-day schedule changes.
string
Optional campaign end time in the provider’s date-time string format.
boolean
Whether automatic budget management is enabled.
boolean
Whether affiliate posts are enabled.
array
Optional replacement custom anchor videos.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_GMV_MAX_CAMPAIGN_CREATIVESRemove creatives from a GMV Max campaign or add them back. Include spu_id_list for every item in a Product GMV Max campaign; campaign type is not part of this request.

Input Parameters

string ("REMOVE" | "ADD")
required
Whether to REMOVE creatives from the campaign or ADD them back.
array
required
Creative items to update, with at most 400 items per request.
string
required
Active GMV Max campaign ID. Product campaigns must use product_video_specific_type AUTO_SELECTION.
string
required
Authorized advertiser account ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_GMV_MAX_CAMPAIGN_SESSIONUpdate documented budget or schedule fields for a max delivery or creative boost session. schedule_start_time applies to max delivery sessions.

Input Parameters

object
required
Documented mutable session fields. The endpoint publishes no session-type discriminator.
string
required
TikTok Shop store ID.
string
required
GMV Max session ID to update.
string
required
Product GMV Max campaign ID.
string
required
Authorized advertiser account ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_OFFLINEUpdate an Offline Event Set configuration; this does not upload or ingest events.

Input Parameters

string
New unique event-set name.
string
required
Offline Event Set ID to update.
string
required
Advertiser ID.
boolean
Whether Auto Tracking is enabled.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_OPTIMIZER_RULEUpdate automated optimizer rules.

Input Parameters

string ("ZH" | "EN" | "JA")
Language of error messages.
array
required
Rules to update.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_OPTIMIZER_RULE_STATUSESTurn automated optimizer rules on or off, or permanently delete them.

Input Parameters

string ("ZH" | "EN" | "JA")
Language of error messages.
array
required
IDs of rules whose status will be updated.
string ("TURN_ON" | "TURN_OFF" | "DELETE")
required
Status operation to perform.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_PANGLE_BLOCK_LISTUpdate an advertiser’s Pangle app block list by adding apps, removing apps, or clearing the existing list before adding replacements. Provide at least one non-empty app list or set clear_old_app to true.

Input Parameters

array
Apps to add to the block list, using an iTunes ID for each iOS app and a package name for each Android app.
string
required
Advertiser ID whose Pangle app block list will be updated.
boolean
Whether to clear the existing block list before adding add_app_list. When false, TikTok applies additions and deletions to the existing list.
array
Apps to remove from the block list, using an iTunes ID for each iOS app and a package name for each Android app.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_PAYMENT_PORTFOLIO_CREDIT_LINEChange the credit-line percentages allocated to up to 10 Payment Portfolios. This directly changes available advertising credit now and whenever the total credit line changes; obtain explicit finance-owner approval immediately before execution and verify every portfolio, used minimum, percentage, and the intended total allocation.

Input Parameters

array
required
Credit line allocations for up to 10 Payment Portfolios.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_PIXELUpdate Pixel naming, matching, cookie, or expanded-data-sharing configuration.

Input Parameters

string
required
Pixel ID.
string
required
New Pixel name, or an empty string to keep it unchanged.
string
required
Advertiser ID.
object
Complete Manual Advanced Matching settings.
boolean
Whether first-party cookies are enabled.
boolean
Whether expanded data sharing is enabled.
object
Complete Automatic Advanced Matching settings.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_PIXEL_EVENTUpdate a Pixel Event configuration; this endpoint does not ingest event occurrences.

Input Parameters

string ("INR" | "JPY" | "USD")
Currency for currency_value.
string
required
Configured Pixel Event ID from LIST_PIXEL.
string
New event name without emoji.
string
required
Advertiser ID.
string
New event conversion value.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_SEARCH_AD_NEGATIVE_KEYWORDUpdate one negative keyword on a Search Ads campaign or ad group with a replacement name and match type. The match type defaults to broad match if omitted.

Input Parameters

object
required
Replacement negative-keyword name and match type.
string
required
Campaign ID or ad-group ID, according to object_type.
string ("CAMPAIGN" | "ADGROUP")
required
Whether object_id identifies a campaign or an ad group.
string
required
Advertiser ID that owns the negative keyword.
string
required
ID of the negative keyword to update.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_SEGMENTAdd or delete user and device mappings for explicitly selected disposable audiences.

Input Parameters

string ("add" | "delete")
Whether to add or delete mappings.
array
required
Identifier types corresponding to each batch row.
array
required
Batches of user or device audience mappings.
array
required
Advertiser IDs from the same business account.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_SMART_CREATIVE_MATERIALSUpdate current Smart Creative materials outside Smart+ campaigns. With patch_update=true, omitted top-level fields remain unchanged, but every provided array replaces the entire prior array; first read and resend all existing array items to avoid data loss. Automatically generated ad names cannot be updated. This does not target retired DYNAMIC ACO.

Input Parameters

array
Complete card list (maximum one).
array
Complete Instant Page ID list.
string
required
Ad group ID whose creative_material_mode is SMART_CREATIVE.
array
Complete replacement title list when changing any title.
boolean
Whether omitted top-level settings remain unchanged. Array fields still replace the complete array and must contain all existing items.
string
required
Advertiser account ID.
Complete replacement deep-link list.
object
Common material settings to update.
array
Complete replacement media list when changing any media item.
array
Avatar image list (maximum one).
array
Complete replacement display-name list.
array
Complete landing-page destination list.
array
Complete replacement call-to-action list.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_SMART_CREATIVE_MATERIAL_STATUSEnable or disable current Smart Creative materials. Enabling a material can make it eligible for delivery and spend. This does not target retired DYNAMIC ACO.

Input Parameters

string
required
Smart Creative ad group ID.
array
required
Smart Creative material IDs whose status will change.
string
required
Advertiser account ID.
string ("ENABLE" | "DISABLE")
required
Whether the materials can be used for ad delivery.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_SMART_PLUS_ADUpdate an existing Smart+ ad and its material configuration; at least one field to update must be provided.

Input Parameters

string
Updated ad name.
array
Instant Pages (maximum 3).
array
Ad text variants (maximum 5).
string
required
Advertiser ID that owns the ad.
array
Creative variants (1-31).
Deep-link destinations (maximum 1).
object
Common ad material configuration.
string
required
Smart+ ad ID to update.
array
Call-to-action variants (maximum 3).
array
Landing pages (maximum 1).
array
Interactive add-ons (maximum 2).

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_SMART_PLUS_ADGROUPUpdate an existing Smart+ ad group’s name, bid, budget, schedule, pacing, comment or sharing settings, and audience targeting. Omitted settings remain unchanged; at least one field to update must be provided.

Input Parameters

number
Updated budget.
string ("PACING_MODE_FAST" | "PACING_MODE_SMOOTH")
Pacing mode.
number
Updated ROAS bid.
number
Updated bid price.
string
required
Smart+ ad group ID to update.
string
Updated dayparting schedule.
number
Updated minimum budget.
string
Updated ad group name.
string
required
Advertiser ID that owns the ad group.
string ("SCHEDULE_FROM_NOW" | "SCHEDULE_START_END")
Schedule type.
boolean
Whether sharing is disabled.
object
Updated audience targeting.
boolean
Whether comments are disabled.
string
Schedule end time.
string
Updated movie premiere date.
string
Schedule start time.
number
Updated conversion bid price.
boolean
Whether suggested audience is enabled.
string ("AUTOMATIC" | "MANUAL")
Targeting optimization mode.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_SMART_PLUS_ADGROUP_BUDGETSUpdate immediate total budgets or next-day scheduled daily budgets for Upgraded Smart+ ad groups. Provide a non-empty budget or scheduled_budget list. For CBO campaigns where budget_optimize_on is true, a min_budget or max_budget or both must already be configured before a scheduled-budget update; non-CBO ad groups have no such prerequisite.

Input Parameters

array
Immediate total-budget updates for 1-20 Smart+ ad groups. Use this or scheduled_budget.
string
required
Advertiser ID that owns the Smart+ ad groups.
array
Next-day scheduled daily-budget updates for 1-20 Smart+ ad groups. Use this or budget. CBO prerequisites depend on provider-side campaign configuration and are not represented by a request discriminator.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_SMART_PLUS_AD_MATERIAL_STATUSEnable or disable up to 20 materials belonging to a Smart+ ad. Enabling materials can make them eligible for delivery and spend.

Input Parameters

string
required
Advertiser ID that owns the ad.
array
required
Ad material IDs to update (1-20).
string ("DISABLE" | "ENABLE")
required
Status operation to apply.
string
required
Smart+ ad ID whose materials to update.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_SMART_PLUS_CAMPAIGNUpdate an existing Smart+ campaign’s supported fields; at least one field to update must be provided. Perform mutation QA only on a disabled or draft campaign; this action does not enable or publish it.

Input Parameters

number
Optional new campaign budget.
string
Optional new purchase order number.
string
required
Smart+ campaign ID to update.
string
required
Authorized advertiser account ID.
string
Optional new campaign name.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_SPLIT_TESTUpdate the start and end time of a split test.

Input Parameters

string
required
New end time in YYYY-MM-DD HH:MM:SS UTC.
string
required
New start time in YYYY-MM-DD HH:MM:SS UTC; cannot be changed after the test starts.
string
required
Advertiser ID.
string
required
Split test group ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPDATE_TIKTOK_INVENTORY_FILTERSSet or update an advertiser account’s Brand Safety Hub settings. Setting cover_all_ad_objectives to true is irreversible and cannot be reverted.

Input Parameters

string
required
Advertiser ID.
string ("EXPANDED_INVENTORY" | "STANDARD_INVENTORY" | "LIMITED_INVENTORY")
Inventory filter tier to configure.
array
Content category IDs to exclude.
boolean
required
Whether the brand safety settings apply to all objectives. Once true, this cannot be reverted.
string
Sensitive vertical category ID to exclude.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPLOAD_ACCOUNT_VERIFICATIONUpload one or two verification document images.

Input Parameters

object
required
JPEG, JPG, or PNG verification document up to 10 MB.
object
Optional second JPEG, JPG, or PNG verification document up to 10 MB.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPLOAD_BUSINESS_CERTIFICATE_IMAGEUpload a business certificate image for an ad account through a Business Center where the connected user is an administrator.

Input Parameters

string
required
Business Center ID. The connected user must be an administrator.
object
required
JPG, JPEG, or PNG business certificate image, up to 10 MB.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPLOAD_CATALOG_PRODUCTUpload up to 5,000 products using the fields documented for each catalog type.

Input Parameters

string
required
Business Center ID.
string
Feed ID; omit to use the default catalog.
array
required
Products to upload, at most 5,000 per request.
string
required
Catalog ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPLOAD_CATALOG_PRODUCTS_BY_FILE_URLIngest a CSV catalog feed from a directly accessible HTTP or HTTPS URL. INCREMENTAL preserves omitted products; OVERWRITE permanently removes omitted products, so confirm the complete source file before using it.

Input Parameters

string
required
Business Center ID.
string
Optional feed ID.
string
required
Direct HTTP or HTTPS URL of a CSV catalog feed containing fewer than 20 million product rows.
string
required
Catalog ID.
string ("INCREMENTAL" | "OVERWRITE")
INCREMENTAL adds or updates products. OVERWRITE replaces the catalog data and permanently removes products omitted from this file; confirm the complete source file before choosing OVERWRITE.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPLOAD_CATALOG_VIDEOS_BY_FILE_URLUpload catalog videos from a file URL.

Input Parameters

string
required
Business Center ID that owns the E-commerce catalog.
string
required
URL of the file containing catalog video data.
string
required
E-commerce catalog ID receiving the videos.
array
Optional IDs of up to 100 advertiser accounts in the same Business Center whose Admin or Operator permissions authorize the upload.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPLOAD_DMP_CUSTOM_AUDIENCE_FILEUpload a CSV or TXT customer file after verifying its supplied MD5 signature.

Input Parameters

object
required
CSV or TXT audience data file.
string
Optional provider-side file name.
string
required
Advertiser ID.
string ("EMAIL_SHA256" | "FIRST_MD5" | "FIRST_SHA256" | "GAID_MD5" | "GAID_SHA256" | "IDFA_MD5" | "IDFA_SHA256" | "MAID_MD5" | "MAID_SHA256" | "MULTIPLE_TYPES" | "PHONE_SHA256")
required
Encryption type matching the file data.
string
required
Lowercase or uppercase MD5 digest of the file.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPLOAD_FILE_CHUNKEDUpload one image, video, or music file through TikTok’s start, ordered chunk-transfer, and finish workflow. Chunk signatures are computed internally.

Input Parameters

object
required
File to upload in chunks.
string
Optional file name, up to 100 characters.
integer
Chunk size in bytes, from 1 byte through 50 MiB. Defaults to 5 MiB.
string ("image" | "video" | "music")
required
File content category.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPLOAD_FILE_IMAGE_ADUpload an advertiser image by local file, URL, or temporary file ID.

Input Parameters

string
Temporary file ID required for file-ID upload.
string
Optional image name, 1-100 characters.
string
Image URL required for URL upload.
object
JPG, JPEG, or PNG image up to 50 MB for file upload.
string ("UPLOAD_BY_FILE" | "UPLOAD_BY_URL" | "UPLOAD_BY_FILE_ID")
required
Image upload method.
string
required
Advertiser ID.
string
Image MD5 digest required for file upload.
object
Pre-review details required when pre-review is enabled.
boolean
Whether to create a creative pre-review task.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPLOAD_FILE_MUSICUpload advertiser music or update a Carousel Ads music list.

Input Parameters

string
Temporary file ID required for file-ID upload.
string
Optional music name, 1-100 characters.
object
Music file; Carousel Ads music must be MP3 and at most 10 MB.
string
Material ID required for a material action.
string ("CREATIVE_ASSET" | "CAROUSEL_ADS" | "CATALOG_CAROUSEL")
Scenario where the music is used.
string ("UPLOAD_BY_FILE" | "UPLOAD_BY_FILE_ID")
Music upload method.
string
required
Advertiser ID.
string ("ADD_TO_LIKED" | "ADD_TO_HISTORY" | "REMOVE_FROM_LIKED")
Carousel music-list operation.
string
Music MD5 digest required for file upload.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPLOAD_FILE_TEMPORARILYUpload a temporary image, music, video, or playable file by file or URL.

Input Parameters

string
HTTP URL required for URL upload.
object
File to upload, up to 100 MB; Carousel Ads music must be MP3 and at most 10 MB.
string
Optional file name, up to 100 characters.
string
File MD5 digest required for FILE upload.
string ("FILE" | "URL")
required
Upload from a file or URL.
string ("image" | "music" | "video" | "playable")
required
Provider file category.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPLOAD_FILE_VIDEO_ADUpload an advertiser video by local file, URL, temporary file ID, or existing video ID.

Input Parameters

string
Temporary file ID required for file-ID upload.
string
Existing video ID required for video-ID upload.
string
Optional video name, 1-100 characters.
string
Playable video URL required for URL upload.
object
MP4, MOV, MPEG, or AVI video up to 500 MB for file upload.
boolean
Whether to detect video issues automatically.
string ("UPLOAD_BY_FILE" | "UPLOAD_BY_URL" | "UPLOAD_BY_FILE_ID" | "UPLOAD_BY_VIDEO_ID")
Video upload method.
string
required
Advertiser ID.
boolean
Whether this is a third-party video.
object
Pre-review details required when pre-review is enabled.
string
Video MD5 digest required for file upload.
boolean
Whether to fix supported detected issues automatically.
boolean
Whether to add an automatically fixed video to the creative library.
boolean
Whether to create a creative pre-review task.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_UPLOAD_PLAYABLEUpload a playable ZIP package or reference a file already in TikTok’s file repository. Direct packages must be 5 MB or smaller, contain index.html and config.json at the root, and must not load external network resources.

Input Parameters

string
Existing file repository ID; required for UPLOAD_BY_FILE_ID.
string ("UPLOAD_BY_FILE" | "UPLOAD_BY_FILE_ID")
Upload a ZIP directly or use an existing file repository ID.
string
required
Advertiser ID.
object
ZIP playable package, at most 5 MB; required for UPLOAD_BY_FILE.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_VALIDATE_LANDING_PAGE_URLGet TikTok verification results for a URL.

Input Parameters

string
required
URL to verify.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: TIKTOK_ADS_VALIDATE_PLAYABLECheck validation status and failure details for one playable asset.

Input Parameters

string
required
Playable asset ID.
string
required
Advertiser ID.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not