--- canonical_url: "https://docs.composio.dev/toolkits/tiktok_ads" markdown_url: "https://docs.composio.dev/toolkits/tiktok_ads.md" product: "platform" version: null last_updated: null --- # TikTok Ads Use TikTok API for Business actions to read advertisers, campaigns, ad groups, ads, audiences, creatives, catalogs, Business Centers, balances, billing, and transactions; manage advertiser settings, Asset Groups, disabled-by-default Smart+ and GMV Max resources, catalog feeds and videos, creative sharing, Pangle block lists, and selected compliance workflows; and retrieve MMM, GMV Max, and Smart+ reports. - **Category:** marketing - **Auth:** OAUTH2 - **Composio-managed OAuth available?** Yes - **Tools:** 403 - **Triggers:** 0 - **Slug:** `TIKTOK_ADS` - **Version:** 20261001_00 ## Tools ### Add a partner to a BC **Slug:** `TIKTOK_ADS_ADD_BC_PARTNER` Add another Business Center as a partner and optionally share advertiser or catalog assets with it. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID adding the partner. | | `asset_ids` | array | No | Up to 50 asset IDs to share. | | `asset_type` | string ("ADVERTISER" | "CATALOG") | No | Type of assets to share: `ADVERTISER` or `CATALOG`. | | `partner_id` | string | Yes | Business Center ID to add as a partner. | | `catalog_role` | string ("ADMIN" | "AD_PROMOTE") | No | Catalog role for shared catalog assets. TikTok defaults to `AD_PROMOTE` when applicable. | | `advertiser_role` | string ("ADMIN" | "ANALYST" | "OPERATOR") | No | Advertiser role for shared advertiser assets. TikTok defaults to `ANALYST` when applicable. | | `source_child_bc_id` | string | No | Optional source child Business Center ID. | | `target_child_bc_id` | string | No | Optional target child Business Center ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Appeal a rejection **Slug:** `TIKTOK_ADS_APPEAL_ADGROUP` Submit 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `ad_id` | string | No | Ad ID. Optional. | | `adgroup_id` | string | Yes | Ad group ID. | | `advertiser_id` | string | Yes | Advertiser ID. | | `appeal_reason` | string | No | The reason for the appeal. | | `attachment_list` | array | No | List of attachment links. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Appeal Smart+ Ad **Slug:** `TIKTOK_ADS_APPEAL_SMART_PLUS_AD` Submit an appeal for a Smart+ ad review decision. Once submitted, the appeal cannot be withdrawn through this tool. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_id` | string | Yes | Advertiser ID that owns the ad. | | `appeal_reason` | string | No | Appeal reason, up to 512 characters. | | `attachment_list` | array | No | Provider attachment references supporting the appeal. | | `smart_plus_ad_id` | string | Yes | Smart+ ad ID to appeal. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Apply or Disconnect a Custom Audience **Slug:** `TIKTOK_ADS_APPLY_DMP_CUSTOM_AUDIENCE` Apply a custom audience to ad groups or disconnect it from them. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `usage_mode` | string ("Include" | "Exclude") | No | Required for Apply; include or exclude the audience. | | `action_mode` | string ("Apply" | "Disconnect") | Yes | Operation to perform on the audience. | | `adgroup_ids` | array | Yes | Ad group IDs under the same advertiser account. | | `advertiser_id` | string | Yes | Advertiser ID. | | `custom_audience_id` | string | Yes | Custom audience ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Assign an asset **Slug:** `TIKTOK_ADS_ASSIGN_BC_ASSET` Assign a Business Center asset and its asset-specific role to a member. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `user_id` | string | Yes | Business Center user ID receiving access. | | `asset_id` | string | Yes | Asset ID to assign. | | `asset_type` | string ("ADVERTISER" | "CATALOG" | "TIKTOK_SHOP" | "LEAD" | "TT_ACCOUNT" | "MANAGED_BUSINESS_ACCOUNT") | Yes | Type of the asset to assign. | | `store_role` | string ("ADMIN" | "AD_PROMOTION") | No | Shop role; required for TikTok Shop assets. | | `catalog_role` | string ("ADMIN" | "AD_PROMOTE") | No | Catalog role; required for catalog assets. | | `advertiser_role` | string ("ADMIN" | "OPERATOR" | "ANALYST") | No | Advertiser role; required for advertiser assets. | | `tt_account_roles` | array | No | Ad-delivery roles; required for TikTok account assets. | | `form_library_role` | string | No | Form library role; required for lead assets. | | `business_account_roles` | array | No | One Business Account management role; required for managed business account assets. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Assign Members to a Child Business Center **Slug:** `TIKTOK_ADS_ASSIGN_BC_MEMBER` Assign one or more existing members from source child Business Centers to a target child Business Center, optionally setting basic and finance roles. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | ID of the Business Center performing the assignment. | | `users` | array | Yes | Members to assign to the target child Business Center (1-100). | | `target_child_bc_id` | string | Yes | ID of the child Business Center to which to assign the members. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Assign TikTok Account To Advertiser **Slug:** `TIKTOK_ADS_ASSIGN_TIKTOK_ACCOUNT_TO_ADVERTISER` Link a TikTok account to an ad account in the same Business Center. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID that owns the TikTok account asset. | | `asset_id` | string | Yes | TikTok account asset ID to link to the advertiser. | | `asset_type` | string ("TT_ACCOUNT" | "MANAGED_BUSINESS_ACCOUNT") | No | TikTok account asset type: TT_ACCOUNT or MANAGED_BUSINESS_ACCOUNT. | | `advertiser_id` | string | Yes | ID of an ad account in the same Business Center to which to link the TikTok account. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Music Authorization Info of a Video **Slug:** `TIKTOK_ADS_AUTHORIZE_IDENTITY_MUSIC` Check 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `end_time` | string | Yes | Ad deployment end time in UTC, YYYY-MM-DD HH:MM:SS. | | `video_id` | string | Yes | TikTok post ID. Sent to TikTok as `item_id`. | | `locations` | array | Yes | Targeting locations, exactly matching the intended ad. | | `start_time` | string | Yes | Ad deployment start time in UTC, YYYY-MM-DD HH:MM:SS. | | `identity_id` | string | Yes | Identity ID authorized to use the post. | | `advertiser_id` | string | Yes | Ad account ID. | | `identity_type` | string ("AUTH_CODE" | "TT_USER" | "BC_AUTH_TT") | Yes | Identity type: AUTH_CODE, TT_USER, or BC_AUTH_TT. | | `identity_authorized_bc_id` | string | No | Business Center ID; required for BC_AUTH_TT. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Apply a Spark Post Authorization Code **Slug:** `TIKTOK_ADS_AUTHORIZE_TT_VIDEO` Apply 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `auth_code` | string | Yes | Creator-issued Spark post authorization code. Per TikTok's contract, replace every plus sign (+) in the code with %2B before calling. | | `advertiser_id` | string | Yes | Advertiser ID receiving the Spark post authorization. | | `original_post_auth_code` | string | No | Creator-issued authorization code for an original post referenced by a duet, stitch, or mention; at most one mentioned post is supported. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Bind an event source to a catalog **Slug:** `TIKTOK_ADS_BIND_CATALOG_EVENTSOURCE` Bind a mobile app, website Pixel, or both to a catalog. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `app_id` | string | No | Mobile app ID; at least app_id or pixel_code is required. | | `catalog_id` | string | Yes | Catalog ID. | | `pixel_code` | string | No | Website Pixel code; at least app_id or pixel_code is required. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Bind/Unbind rules **Slug:** `TIKTOK_ADS_BIND_OPTIMIZER_RULE_BATCH` Bind or unbind optimizer rules from existing advertising objects. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `lang` | string ("ZH" | "EN" | "JA") | No | Language of returned messages. | | `bind_info` | array | Yes | Rule binding operations. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Cancel Custom Audience Sharing **Slug:** `TIKTOK_ADS_CANCEL_DMP_CUSTOM_AUDIENCE_SHARE` Stop sharing a custom audience with an advertiser. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_id` | string | Yes | Advertiser ID performing the operation. | | `custom_audience_id` | string | Yes | Audience ID to stop sharing. | | `shared_advertiser_id` | string | Yes | Advertiser ID to stop sharing the audience with. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Cancel asynchronous report task **Slug:** `TIKTOK_ADS_CANCEL_REPORT_TASK` Cancel a queued or processing asynchronous TikTok report task. Confirm the advertiser and disposable task ID before calling because cancellation is irreversible. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `task_id` | string | Yes | Queued or processing asynchronous report task ID to cancel. | | `advertiser_id` | string | Yes | Advertiser ID associated with the report task. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Cancel the R&F ad order **Slug:** `TIKTOK_ADS_CANCEL_RF_ORDER` Cancel 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `adgroup_ids` | array | Yes | ID of the ad group to be withdrawn (ID must correspond to R&F ad group). | | `advertiser_id` | string | Yes | Advertiser ID | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Change Log Download Task Result **Slug:** `TIKTOK_ADS_CHANGELOG_TASK_DOWNLOAD` Read the status and change-log content returned for an advertiser's change-log task. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `task_id` | string | Yes | Change-log download task ID to retrieve. | | `advertiser_id` | string | Yes | Advertiser ID that owns the change-log task. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Check Advertiser Term Status **Slug:** `TIKTOK_ADS_CHECK_ADVERTISER_TERM_STATUS` Check whether a TikTok advertiser has signed a specified agreement. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `term_type` | string ("InstantPage" | "LeadAds" | "Pixel" | "ReachFrequency") | Yes | Type of TikTok agreement to check. | | `advertiser_id` | string | Yes | Advertiser ID whose agreement status to check. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Check the statuses of words **Slug:** `TIKTOK_ADS_CHECK_BLOCKEDWORD` Check whether specified words are blocked for an advertiser without changing moderation settings. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_id` | string | Yes | Advertiser ID. | | `blocked_words` | array | Yes | List of words whose blocked status to check. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Check the status of a blocked-word export task **Slug:** `TIKTOK_ADS_CHECK_BLOCKEDWORD_TASK` Check whether a blocked-word export task is running, succeeded, or failed. Call the download action only after SUCCEED. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `task_id` | string | Yes | Blocked-word export task ID. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Manual Campaign Copy Task Results **Slug:** `TIKTOK_ADS_CHECK_CAMPAIGN_COPY_TASK` Get the results of an asynchronous copy task for a Manual Campaign. Availability may depend on account entitlement. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `task_id` | string | Yes | Asynchronous campaign copy task ID. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Check Change Log Download Task **Slug:** `TIKTOK_ADS_CHECK_CHANGELOG_TASK` Check whether an advertiser change-log download task is processing, successful, or failed. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `task_id` | string | Yes | Change-log download task ID to check. | | `advertiser_id` | string | Yes | Advertiser ID that owns the change-log task. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get the status of a comment export task **Slug:** `TIKTOK_ADS_CHECK_COMMENT_TASK` Check whether a comment export task is running, succeeded, or failed. Call the download action only after SUCCEED. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `source` | string ("BIDDING" | "BRAND") | No | Comment source: `BIDDING` or `BRAND`. | | `task_id` | string | Yes | Comment export task ID. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Check File Names **Slug:** `TIKTOK_ADS_CHECK_FILE_NAMES` Check whether one or more image or video file names are already used in an advertiser account. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `files` | array | No | File names to check in one batch (maximum 20). | | `file_name` | string | No | Single image or video file name to check. | | `file_type` | string ("VIDEO" | "IMAGE") | No | Type of the single file. Required with file_name even though TikTok documents VIDEO as the provider default. | | `advertiser_id` | string | Yes | Advertiser account ID that owns the files. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Check TikTok Shop GMV Max Availability **Slug:** `TIKTOK_ADS_CHECK_GMV_MAX_STORE_AVAILABILITY` Check a TikTok Shop's availability for Product GMV Max campaigns. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `store_id` | string | Yes | TikTok Shop store ID to check for Product GMV Max availability. | | `advertiser_id` | string | Yes | Advertiser account ID for which to check TikTok Shop availability. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Check MMM Data Request **Slug:** `TIKTOK_ADS_CHECK_MMM_DATA_REQUEST` Check one MMM export job. Poll conservatively because TikTok documents up to 24 hours of processing but no polling-rate contract. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `mmm_request_id` | string | Yes | MMM request ID returned by create or history. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Check a lead download task **Slug:** `TIKTOK_ADS_CHECK_PAGE_LEAD_TASK` Poll 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `task_id` | string | Yes | Lead download task ID returned by task creation. | | `library_id` | string | No | Form library ID after leads have migrated to a Business Center. | | `lead_region` | string ("eu" | "us") | No | Use eu for EEA/Switzerland/UK leads, us for US leads, or omit for other regions. | | `advertiser_id` | string | No | Advertiser ID when leads remain under an ad account. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Check asynchronous report task **Slug:** `TIKTOK_ADS_CHECK_REPORT_TASK` Check, without polling, whether an asynchronous report task is queued, processing, successful, failed, or canceled. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `task_id` | string | Yes | Asynchronous report task ID. | | `advertiser_id` | string | Yes | Advertiser ID associated with the task. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Check Smart+ Campaign Copy Task **Slug:** `TIKTOK_ADS_CHECK_SMART_PLUS_CAMPAIGN_COPY_TASK` Get the results of an asynchronous Upgraded Smart+ campaign copy task. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `task_id` | string | Yes | ID of the asynchronous Upgraded Smart+ campaign copy task. | | `advertiser_id` | string | Yes | Advertiser account ID that owns the campaign copy task. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Check UnionPay Verification Requirement **Slug:** `TIKTOK_ADS_CHECK_UNIONPAY_VERIFICATION_REQUIREMENT` Check whether a business license requires UnionPay verification before submitting advertiser verification details. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `license_no` | string | Yes | Business license number to check for a UnionPay verification requirement. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Check Value-Based Optimization eligibility **Slug:** `TIKTOK_ADS_CHECK_VBO_ELIGIBILITY` Check VBO bidding eligibility for a proposed campaign configuration; some options require allowlisting. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `app_id` | string | No | Promoted application ID. | | `pixel_id` | string | No | Pixel ID; use with optimization_event where supported. | | `store_id` | string | No | TikTok Shop ID for Product Sales. | | `placements` | array | Yes | Apps where ads will be delivered. | | `advertiser_id` | string | Yes | Advertiser ID. | | `campaign_type` | string ("REGULAR_CAMPAIGN" | "IOS14_CAMPAIGN") | No | Regular or iOS 14 Dedicated Campaign type. | | `bid_align_type` | string ("SAN" | "SKAN") | No | Dedicated Campaign attribution type: SAN or SKAN. | | `objective_type` | string ("APP_PROMOTION" | "WEB_CONVERSIONS" | "PRODUCT_SALES") | Yes | VBO-capable advertising objective. | | `promotion_type` | 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") | Yes | Promotion type. | | `ios14_quota_type` | string ("OCCUPIED" | "UNOCCUPIED") | No | Whether the campaign occupies the iOS 14 campaign quota. | | `app_promotion_type` | string ("APP_INSTALL" | "APP_RETARGETING") | No | App promotion type. | | `budget_optimize_on` | boolean | No | Whether Campaign Budget Optimization is enabled. | | `optimization_event` | string | No | Conversion-event code required with pixel_id. | | `disable_skan_campaign` | boolean | No | Whether SKAdNetwork attribution is disabled. | | `campaign_automation_type` | string ("MANUAL" | "SMART_PLUS" | "UPGRADED_SMART_PLUS") | No | Campaign automation type. | | `is_smart_performance_campaign` | boolean | No | Whether this is a Smart+ Campaign. | | `is_advanced_dedicated_campaign` | boolean | No | Whether this is an Advanced Dedicated Campaign. | | `campaign_app_profile_page_state` | string ("ON" | "OFF") | No | Whether to use App Profile Page delivery optimization. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Sign Terms **Slug:** `TIKTOK_ADS_CONFIRM_TERM` Sign the selected advertiser agreement. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `term_type` | string ("InstantPage" | "LeadAds" | "Pixel" | "ReachFrequency") | Yes | Agreement type to sign. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get a TikTok in-app link **Slug:** `TIKTOK_ADS_CONVERT_TIKTOK_LINK` Convert an open TikTok URL to an internal TikTok link; availability may require allowlisting. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `url` | string | Yes | Open TikTok URL to convert to an internal link. | | `url_type` | string ("USER_PROFILE" | "VIDEO" | "HASHTAG_CHALLENGE" | "MUSIC" | "STICKER" | "STICKER_SHOOTER") | Yes | Type of TikTok URL. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create ads **Slug:** `TIKTOK_ADS_CREATE_AD` Create 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `creatives` | array | Yes | Ads to create. | | `adgroup_id` | string | Yes | Ad group ID. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create an ad group **Slug:** `TIKTOK_ADS_CREATE_ADGROUP` Create an ad group. New ad groups default to DISABLE so they do not start delivery or spend unless operation_status is explicitly set to ENABLE. Availability may depend on TikTok allowlisting or account entitlement. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `app_id` | string | No | 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. | | `budget` | number | Yes | 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. | | `gender` | string ("GENDER_FEMALE" | "GENDER_MALE" | "GENDER_UNLIMITED") | No | Gender that you want to target. Enum values: `GENDER_FEMALE`,`GENDER_MALE`,`GENDER_UNLIMITED`. | | `pacing` | string | Yes | 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. | | `actions` | array | No | A list of targeting behavioral category objects. | | `is_hfss` | boolean | No | 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`. | | `isp_ids` | array | No | 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`). | | `bid_type` | string | No | 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. | | `pixel_id` | string | No | 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/. | | `roas_bid` | number | No | 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. | | `store_id` | string | No | 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. | | `bid_price` | number | No | 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. | | `frequency` | integer | No | 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". | | `languages` | array | No | 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. | | `age_groups` | array | No | 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. | | `app_config` | array | No | 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 | | `catalog_id` | string | No | 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. | | `dayparting` | string | No | 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. | | `placements` | array | No | 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`. | | `request_id` | string | No | 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` | | `vbo_window` | string ("SEVEN_DAYS" | "ZERO_DAY") | No | 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. | | `budget_mode` | string ("BUDGET_MODE_TOTAL" | "BUDGET_MODE_DAY" | "BUDGET_MODE_DYNAMIC_DAILY_BUDGET") | Yes | 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`. | | `campaign_id` | string | Yes | The ID of the campaign that the ad group belongs to. | | `carrier_ids` | array | No | 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`. | | `identity_id` | string | No | Required and valid only when `shopping_ads_type` is `VIDEO` and `product_source` is `SHOWCASE` or `shopping_ads_type` is `LIVE`. Identity ID. | | `zipcode_ids` | array | No | 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. | | `adgroup_name` | string | Yes | Ad group name. Length limit: 512 characters and cannot contain emoji. | | `audience_ids` | array | No | List of audience IDs. You can get audience IDs by using the /dmp/custom_audience/list/ endpoint. | | `deep_cpa_bid` | number | No | Bid price for the selected in-app event bidding strategy. Required when `next_day_retention` is specified. | | `location_ids` | array | No | 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. | | `phone_number` | string | No | 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. | | `advertiser_id` | string | Yes | Advertiser ID. | | `audience_rule` | object | No | Rules that specify your audience, valid if `objective_type` is `TRAFFIC` or `APP_PROMOTION`. For details, see Audience Rules. | | `audience_type` | string | No | 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. | | `billing_event` | string | Yes | 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. | | `deep_bid_type` | string ("VO_MIN_ROAS" | "VO_HIGHEST_VALUE") | No | 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. | | `identity_type` | string ("AUTH_CODE" | "TT_USER" | "BC_AUTH_TT") | No | 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. | | `network_types` | array | No | Device connection types that you want to target. For enum values, see Enumeration - Connection Type. | | `schedule_type` | string | Yes | 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`. | | `placement_type` | string ("PLACEMENT_TYPE_AUTOMATIC" | "PLACEMENT_TYPE_NORMAL") | No | 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`. | | `product_source` | string ("UNSET" | "CATALOG" | "STORE" | "SHOWCASE") | No | 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. | | `promotion_type` | string | No | 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. | | `share_disabled` | boolean | No | Whether to disable sharing of ads in this ad group to third-party platforms. Default value: `false`. The value `true`is 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` or`placement_type`= `PLACEMENT_TYPE_NORMAL`, and `placements` = `PLACEMENT_TIKTOK` | | `spending_power` | string ("ALL" | "HIGH") | No | 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`. | | `statistic_type` | string | No | 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. | | `ios14_targeting` | string ("UNSET" | "IOS14_MINUS" | "IOS14_PLUS" | "ALL") | No | 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`. | | `min_ios_version` | string | No | Required when `ios14_targeting` is specified. Minimum iOS version. For enum values, see Enumeration - Minimum iOS Version. | | `search_keywords` | array | No | 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. | | `bid_display_mode` | string | No | 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. | | `comment_disabled` | boolean | No | Whether to allow comments on your ads on TikTok. | | `device_model_ids` | array | No | 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. | | `household_income` | array | No | 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. | | `operation_status` | string ("ENABLE" | "DISABLE") | No | 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/. | | `brand_safety_type` | string ("NO_BRAND_SAFETY" | "EXPANDED_INVENTORY" | "STANDARD_INVENTORY" | "LIMITED_INVENTORY" | "THIRD_PARTY") | No | 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. | | `conversion_window` | string | No | 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. | | `is_lhf_compliance` | boolean | No | 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`. | | `operating_systems` | array | No | 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` | | `optimization_goal` | string | Yes | 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. | | `phone_region_code` | string | No | 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. | | `saved_audience_id` | string | No | 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. | | `schedule_end_time` | string | No | 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"`. | | `shopping_ads_type` | string ("VIDEO" | "LIVE" | "PRODUCT_SHOPPING_ADS") | No | 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. | | `contextual_tag_ids` | array | No | 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`. | | `frequency_schedule` | integer | No | Frequency schedule, together with `frequency`, controls how often people see your ad (only available for `REACH` ads). See `frequency` fields for more. | | `messaging_app_type` | string ("MESSENGER" | "WHATSAPP" | "ZALO" | "LINE" | "IM_URL") | No | 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. | | `next_day_retention` | number | No | 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. | | `optimization_event` | string | No | 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`. | | `device_price_ranges` | array | No | 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]. | | `min_android_version` | string | No | Minimum device Android version. For enum values, see Enumeration - Minimum Android Version. | | `schedule_start_time` | string | Yes | 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"`. | | `targeting_expansion` | object | No | 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. | | `brand_safety_partner` | string ("IAS" | "OPEN_SLATE") | No | Required only when `brand_safety_type` is `THIRD_PARTY`, and `placements` needs to be set to `["PLACEMENT_TIKTOK"]`. 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. | | `conversion_bid_price` | number | No | 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. | | `custom_conversion_id` | string | No | 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`. | | `interest_keyword_ids` | array | No | 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/. | | `message_event_set_id` | string | No | 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. | | `tiktok_subplacements` | array | No | 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. | | `excluded_audience_ids` | array | No | List of audience ID to be excluded. You can get audience IDs by using the /dmp/custom_audience/list/ endpoint. | | `interest_category_ids` | array | No | 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/. | | `promotion_target_type` | string ("INSTANT_PAGE" | "EXTERNAL_WEBSITE") | No | 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`. | | `search_result_enabled` | boolean | No | 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`. | | `auto_targeting_enabled` | boolean | No | 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. | | `blocked_pangle_app_ids` | array | No | 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. | | `category_exclusion_ids` | array | No | 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 `["PLACEMENT_TIKTOK"]`. `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. | | `creative_material_mode` | string | No | 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. | | `promotion_website_type` | string ("UNSET" | "TIKTOK_NATIVE_PAGE") | No | 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. | | `smart_audience_enabled` | boolean | No | 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. | | `store_authorized_bc_id` | string | No | Required when `store_id` is passed. ID of the Business Center that is authorized to access the store (`store_id`). | | `attribution_event_count` | string ("UNSET" | "EVERY" | "ONCE") | No | 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. | | `excluded_custom_actions` | array | No | 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. | | `included_custom_actions` | array | No | 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. | | `vertical_sensitivity_id` | string | No | 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 `["PLACEMENT_TIKTOK"]`.`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. | | `video_download_disabled` | boolean | No | Whether users can download your video ads on TikTok(cannot be updated once created). | | `view_attribution_window` | string ("OFF" | "ONE_DAY" | "SEVEN_DAYS") | No | 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. | | `catalog_authorized_bc_id` | string | No | 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. | | `click_attribution_window` | string ("OFF" | "ONE_DAY" | "SEVEN_DAYS" | "FOURTEEN_DAYS" | "TWENTY_EIGHT_DAYS") | No | 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. | | `deep_funnel_event_source` | string ("PIXEL" | "OFFLINE" | "CRM") | No | Required when `deep_funnel_optimization_status` is `ON`. The event source type. Enum values: `PIXEL`: Pixel. `OFFLINE`: Offline Event Set.`CRM`: CRM Event Set. | | `messaging_app_account_id` | string | No | 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. | | `identity_authorized_bc_id` | string | No | 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. | | `phone_region_calling_code` | string | No | 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. | | `automated_keywords_enabled` | boolean | No | 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. | | `deep_funnel_event_source_id` | string | No | 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/. | | `secondary_optimization_event` | string | No | 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. | | `shopping_ads_retargeting_type` | string ("LAB1" | "LAB2" | "LAB3" | "OFF") | No | 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. | | `adgroup_app_profile_page_state` | string ("ON" | "OFF") | No | 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` | | `deep_funnel_optimization_event` | string | No | 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`. | | `purchase_intention_keyword_ids` | array | No | 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`). | | `deep_funnel_optimization_status` | string ("ON" | "OFF") | No | 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. | | `engaged_view_attribution_window` | string ("ONE_DAY" | "SEVEN_DAYS") | No | 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. | | `smart_interest_behavior_enabled` | boolean | No | 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. | | `excluded_pangle_audience_package_ids` | array | No | 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`. | | `included_pangle_audience_package_ids` | array | No | 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`. | | `shopping_ads_retargeting_actions_days` | integer | No | 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. | | `shopping_ads_retargeting_custom_audience_relation` | string ("OR" | "AND") | No | 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create an R&F ad group **Slug:** `TIKTOK_ADS_CREATE_ADGROUP_RF` Create an R&F ad group. Availability may depend on TikTok allowlisting or account entitlement. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `app_id` | string | No | ID of the promoted mobile application. | | `budget` | number | No | Budget. Required only when `rf_purchased_type` is `FIXED_BUDGET`. Use the value returned by the ad inventory estimate API. | | `gender` | string | No | Audience gender. For more details, see Enumeration - Audience Gender. | | `is_hfss` | boolean | No | 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. | | `feed_type` | string ("STANDARD_FEED" | "TOP_FEED") | No | Feed type option. Enum values: `STANDARD_FEED`, `TOP_FEED`. `STANDARD_FEED` refers to large inventory with normal CPM price while `TOP_FEED`refers to limited inventory with higher CPM price. | | `frequency` | integer | Yes | `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. | | `languages` | array | No | Codes of the languages that you want to target. For the list of languages codes supported, see Enumeration - Language Code. | | `age_groups` | array | No | 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. | | `request_id` | string | Yes | 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"` | | `campaign_id` | string | Yes | The campaign the ad group belongs to. | | `carrier_ids` | array | No | 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. | | `adgroup_name` | string | Yes | Name of the ad group. It must not exceed 100 characters or contain any emojis. | | `audience_ids` | array | No | 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. | | `location_ids` | array | Yes | 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. | | `advertiser_id` | string | Yes | Advertiser ID. | | `delivery_mode` | string ("STANDARD" | "SCHEDULE" | "SEQUENCE" | "VIEW_OPTIMIZE" | "OPTIMIZE") | No | 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. | | `network_types` | array | No | Device connection types that you want to target. Default value: `unlimited`. For enum values, see Enumeration - Connection Type. | | `promotion_type` | string ("APP_ANDROID" | "APP_IOS" | "WEBSITE" | "WEBSITE_OR_DISPLAY") | Yes | 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`. | | `schedule_infos` | array | No | 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. | | `share_disabled` | boolean | No | Whether sharing to third-party platforms is disabled for ads in this ad group. Default value: `False`. | | `purchased_reach` | integer | No | 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. | | `comment_disabled` | boolean | No | Whether to prohibit users from commenting on your ads on TikTok. Default value: `False`. | | `device_model_ids` | array | No | 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. | | `brand_safety_type` | string ("NO_BRAND_SAFETY" | "EXPANDED_INVENTORY" | "STANDARD_INVENTORY" | "LIMITED_INVENTORY" | "THIRD_PARTY") | No | 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. | | `operating_systems` | array | No | Device operating systems that you want to target. Enum values: `ANDROID`, `IOS`, `PC`. | | `optimization_goal` | string ("REACH" | "VIDEO_VIEW" | "CLICK" | "POST_ENGAGEMENT" | "INSTALL") | Yes | 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. | | `rf_purchased_type` | string ("FIXED_SHOW" | "FIXED_REACH" | "FIXED_BUDGET") | Yes | 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. | | `schedule_end_time` | string | Yes | 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"`. | | `contextual_tag_ids` | array | No | 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. | | `cpv_video_duration` | string | No | 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`. | | `frequency_schedule` | integer | Yes | `frequency_schedule`, together with `frequency`, controls how often people see your ad (only available for `REACH` ads). See `frequency` field for more. | | `optimization_event` | string | No | 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. | | `device_price_ranges` | array | No | 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]. | | `schedule_start_time` | string | Yes | 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"`. | | `brand_safety_partner` | string ("IAS" | "OPEN_SLATE") | No | 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. | | `purchased_impression` | integer | No | 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. | | `excluded_audience_ids` | array | No | 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. | | `interest_category_ids` | array | No | List of interest categories that you want to target. Use /tool/interest_category/ endpoint to get the complete list of interest categories. | | `category_exclusion_ids` | array | No | 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. | | `video_download_disabled` | boolean | No | Whether users can download your video ads on TikTok(cannot be updated once created). Default value: `false`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create an app **Slug:** `TIKTOK_ADS_CREATE_APP` Create a mobile app for an advertiser. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `partner` | 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") | No | Third-party tracking partner enum value. | | `download_url` | string | Yes | Application download URL. | | `tracking_url` | object | No | Third-party tracking URLs. | | `advertiser_id` | string | Yes | Advertiser ID. | | `enable_retargeting` | string ("RETARGETING" | "NON_RETARGETING") | No | Retargeting attribution setting; defaults to NON_RETARGETING. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create a Business Center **Slug:** `TIKTOK_ADS_CREATE_BC` Create 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `type` | string | No | Business Center type. The SDK contract enumerates codes 1, 5, and 6 and defaults to NORMAL. | | `bc_name` | string | Yes | Business Center name. | | `currency` | string | No | Business Center currency. | | `timezone` | string | Yes | Business Center timezone code. | | `company_name` | string | No | Company name. | | `contact_info` | object | No | Business Center contact information. | | `plugin_partner` | string | No | Plugin partner identifier. | | `registered_area` | string | No | Registration area code. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create an ad account **Slug:** `TIKTOK_ADS_CREATE_BC_ADVERTISER` Create 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `billing_info` | object | No | Billing information required for applicable France, Brazil, or Mexico registrations. | | `contact_info` | object | No | Contact information. | | `payment_info` | object | No | Payment Portfolio and initial budget settings. | | `customer_info` | object | Yes | Business information. | | `advertiser_info` | object | Yes | Ad account information. | | `billing_group_info` | object | No | Billing Group and invoice grouping settings. | | `qualification_info` | object | No | Qualification information required for AGENCY or SELF_SERVICE_AGENCY Business Centers; do not provide it for DIRECT Business Centers. | | `tied_to_billing_group` | boolean | No | Whether to add the account to a Billing Group; this is allowlist-only. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create a Billing Group **Slug:** `TIKTOK_ADS_CREATE_BC_BILLING_GROUP` Create 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `is_primary` | boolean | No | Whether this becomes the default Billing Group. | | `advertiser_ids` | array | Yes | 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. | | `billing_group_name` | string | Yes | Billing Group name. | | `billing_group_type` | string ("AUCTION" | "RESERVATION") | No | Advertising type for all accounts in the group; this cannot be edited later. | | `billing_group_emails` | array | No | Email addresses associated with the Billing Group. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create an asynchronous invoice download task **Slug:** `TIKTOK_ADS_CREATE_BC_INVOICE_TASK` Create 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `filtering` | object | No | Invoice filters for the generated file. | | `invoice_id` | string | No | Invoice ID; required for BILLING_REPORT and optional as a filter for other types. | | `download_type` | string ("INVOICE_LIST" | "INVOICE_BATCH" | "BILLING_REPORT") | Yes | INVOICE_LIST creates XLSX, INVOICE_BATCH creates ZIP of PDFs, and BILLING_REPORT creates XLSX. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create blocked words **Slug:** `TIKTOK_ADS_CREATE_BLOCKEDWORD` Add 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_id` | string | Yes | Advertiser ID whose moderation list will change. | | `blocked_words` | array | Yes | Words to add to the advertiser's blocked-word list. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create a blocked-word export task **Slug:** `TIKTOK_ADS_CREATE_BLOCKEDWORD_TASK` Create 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `lang` | string ("EN" | "JA" | "ZH") | No | Export language: EN, JA, or ZH. | | `advertiser_id` | string | Yes | Advertiser ID whose blocked words to export. | | `blocked_words` | array | No | Optional blocked words to include in the export. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create Business Center Asset Group **Slug:** `TIKTOK_ADS_CREATE_BUSINESS_CENTER_ASSET_GROUP` Create an Asset Group in a TikTok Business Center, add advertiser assets and members, and optionally assign each member an advertiser access role. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID in which to create the Asset Group. | | `assets` | array | Yes | Advertiser assets to include (1-200). | | `members` | array | Yes | Business Center members to include (1-50). | | `asset_group_name` | string | Yes | Name of the Asset Group to create. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create Business Center Organization Account **Slug:** `TIKTOK_ADS_CREATE_BUSINESS_CENTER_ORGANIZATION_ACCOUNT` Create an Organization Account in an authorized Business Center. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID in which to create the Organization Account. | | `handle` | string | No | Optional Organization Account handle, up to 24 characters. It cannot consist solely of numbers. | | `display_name` | string | Yes | Display name for the Organization Account, up to 30 characters. | | `profile_image` | object | No | Optional profile image file for the Organization Account. | | `qualification_info` | object | No | 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. | | `operating_region_code` | 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") | Yes | Operating region for the Organization Account. Businesses based in Chinese mainland must select a region other than China; CN is not available. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create Business Spark Ad **Slug:** `TIKTOK_ADS_CREATE_BUSINESS_SPARK_AD` Create 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `budget` | number | No | Campaign budget. | | `gender` | string ("GENDER_FEMALE" | "GENDER_MALE" | "GENDER_UNLIMITED") | No | Audience gender targeting. | | `ad_name` | string | No | Optional Spark Ad name, up to 512 characters; emojis are unsupported. | | `bid_type` | string ("BID_TYPE_CUSTOM" | "BID_TYPE_NO_BID") | No | Custom bidding or maximum delivery without a bid. | | `bid_price` | number | No | Custom standard bid price. | | `frequency` | number | No | Maximum impressions per user in the frequency schedule (1-1,000). | | `age_groups` | array | No | Audience age groups. | | `budget_mode` | string ("BUDGET_MODE_TOTAL" | "BUDGET_MODE_DAY") | No | Total or daily budget mode. | | `identity_id` | string | No | Authorized identity ID. | | `adgroup_name` | string | No | Optional ad group name, up to 512 characters; emojis are unsupported. | | `location_ids` | array | No | Location IDs, maximum 3,000. Either this field or saved_audience_id must be supplied. | | `advertiser_id` | string | Yes | Authorized advertiser account ID. | | `campaign_name` | string | No | Optional campaign name, up to 512 characters; emojis are unsupported. | | `identity_type` | string ("AUTH_CODE" | "TT_USER" | "BC_AUTH_TT") | No | TikTok identity authorization type. | | `schedule_type` | string ("SCHEDULE_START_END" | "SCHEDULE_FROM_NOW") | No | Finite or continuous delivery schedule. | | `call_to_action` | 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") | No | Call to action shown on the Spark Ad. | | `objective_type` | string ("REACH" | "TRAFFIC" | "VIDEO_VIEWS" | "ENGAGEMENT") | No | Campaign objective that determines valid optimization goals. | | `tiktok_item_id` | string | No | Authorized TikTok post ID. | | `landing_page_url` | string | No | Landing page URL when supported by the optimization goal. | | `optimization_goal` | string ("REACH" | "CLICK" | "TRAFFIC_LANDING_PAGE_VIEW" | "ENGAGED_VIEW" | "FOLLOWERS" | "PAGE_VISIT") | No | Optimization goal compatible with objective_type. | | `saved_audience_id` | string | No | Saved Audience ID. Either this field or location_ids must be supplied. | | `schedule_end_time` | string | No | UTC+0 end time in YYYY-MM-DD HH:MM:SS format. | | `frequency_schedule` | number | No | Frequency-cap period in days (1-30). | | `schedule_start_time` | string | No | UTC+0 start time in YYYY-MM-DD HH:MM:SS format. | | `conversion_bid_price` | number | No | Custom conversion bid price. | | `identity_authorized_bc_id` | string | No | Authorizing Business Center ID, required for BC_AUTH_TT identities. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create a campaign **Slug:** `TIKTOK_ADS_CREATE_CAMPAIGN` Create a Manual Campaign with documented campaign, objective, budget, RTA, and iOS settings. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `app_id` | string | No | Promoted app ID required for applicable iOS 14 campaigns. | | `budget` | number | No | Budget required for finite budget modes. | | `rta_id` | string | No | Realtime API strategy ID. | | `po_number` | string | No | Purchase order number. | | `request_id` | string | No | 64-bit integer represented as a string for idempotency and duplicate names. | | `budget_mode` | string ("BUDGET_MODE_TOTAL" | "BUDGET_MODE_DYNAMIC_DAILY_BUDGET" | "BUDGET_MODE_DAY" | "BUDGET_MODE_INFINITE") | No | Campaign budget mode; required unless objective_type is RF_REACH. | | `advertiser_id` | string | Yes | Advertiser ID. | | `campaign_name` | string | Yes | Campaign name, maximum 512 characters; emoji is unsupported. | | `campaign_type` | string ("REGULAR_CAMPAIGN" | "IOS14_CAMPAIGN") | No | Campaign type. | | `objective_type` | string | Yes | Advertising objective code. | | `catalog_enabled` | boolean | No | Whether catalog-based advertising is enabled. | | `rta_bid_enabled` | boolean | No | Whether RTA bidding is enabled. | | `operation_status` | string ("ENABLE" | "DISABLE") | No | Initial campaign status. | | `rf_campaign_type` | string ("STANDARD" | "PULSE") | No | Reach and Frequency campaign type. | | `sales_destination` | string ("TIKTOK_SHOP" | "WEBSITE" | "APP" | "WEB_AND_APP") | No | Sales destination; required with virtual_objective_type. | | `app_promotion_type` | string ("APP_INSTALL" | "APP_RETARGETING" | "APP_PREREGISTRATION") | No | App promotion type; required for APP_PROMOTION. | | `budget_optimize_on` | boolean | No | Whether Campaign Budget Optimization is enabled. | | `is_search_campaign` | boolean | No | Whether to create an allowlisted Search Ads Campaign. | | `special_industries` | array | No | Special ad categories. | | `postback_window_mode` | string ("POSTBACK_WINDOW_MODE1" | "POSTBACK_WINDOW_MODE2" | "POSTBACK_WINDOW_MODE3") | No | SKAN 4.0 postback window for a disabled iOS 14 campaign. | | `disable_skan_campaign` | boolean | No | Whether to disable SKAN attribution for an eligible campaign. | | `virtual_objective_type` | string | No | Combined Sales objective. | | `campaign_product_source` | string ("CATALOG" | "STORE") | No | Product source required for PRODUCT_SALES. | | `rta_product_selection_enabled` | boolean | No | Whether RTA product selection is enabled. | | `is_advanced_dedicated_campaign` | boolean | No | Whether this is an Advanced Dedicated Campaign. | | `campaign_app_profile_page_state` | string ("ON" | "OFF") | No | Whether to optimize using an app profile page. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create an asynchronous copy task for a Manual Campaign **Slug:** `TIKTOK_ADS_CREATE_CAMPAIGN_COPY_TASK` Create an asynchronous Manual Campaign copy task. Copied nested resources may default to enabled unless explicitly disabled. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `budget` | number | No | Copied campaign budget. | | `rta_id` | string | No | Realtime API strategy ID. | | `po_number` | string | No | Purchase order number. | | `request_id` | string | Yes | Idempotency request ID cached for 10 seconds. | | `campaign_id` | string | Yes | Source Manual Campaign ID. | | `adgroup_list` | array | No | Ad groups to customize, maximum ten. | | `advertiser_id` | string | Yes | Advertiser ID. | | `campaign_name` | string | No | Copied campaign name. | | `schedule_type` | string ("SCHEDULE_START_END" | "SCHEDULE_FROM_NOW") | No | Schedule mode for copied ad groups. | | `deep_copy_mode` | string ("DEFAULT" | "CUSTOM") | No | Copy mode. | | `operation_status` | string ("ENABLE" | "DISABLE") | No | Copied campaign status. | | `sales_destination` | string ("TIKTOK_SHOP" | "WEBSITE" | "APP" | "WEB_AND_APP") | No | Copied campaign sales destination. | | `schedule_end_time` | string | No | UTC schedule end. | | `schedule_start_time` | string | No | UTC schedule start. | | `virtual_objective_type` | string | No | Combined Sales objective. | | `is_advanced_dedicated_campaign` | boolean | No | Whether the copy is an Advanced Dedicated Campaign. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create a campaign through the shared SPC route **Slug:** `TIKTOK_ADS_CREATE_CAMPAIGN_SPC` Create a current Smart+ Catalog or Advanced Dedicated Campaign through TikTok's shared SPC route; legacy Smart+ modes are deprecated. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `app_id` | string | No | Promoted app ID. | | `budget` | number | Yes | Campaign budget. | | `gender` | string ("GENDER_FEMALE" | "GENDER_MALE" | "GENDER_UNLIMITED") | No | Target gender. | | `bid_type` | string ("BID_TYPE_NO_BID" | "BID_TYPE_CUSTOM") | No | Bidding strategy. | | `deeplink` | string | No | App deeplink. | | `pixel_id` | string | No | Pixel ID. | | `roas_bid` | number | No | Target ROAS. | | `spc_type` | string ("WEB_ALL_IN_ONE" | "UNSET") | No | Web campaign type. | | `bid_price` | number | No | Target click cost. | | `card_list` | array | No | Creative portfolio IDs, maximum one. | | `languages` | array | No | Target languages. | | `page_list` | array | No | Page IDs, maximum one. | | `app_config` | array | No | Apps promoted for WEB_AND_APP, maximum two. | | `catalog_id` | string | No | Catalog ID. | | `dayparting` | string | No | 336-character weekly delivery grid. | | `placements` | array | No | Selected placements. | | `title_list` | array | No | Ad title objects. | | `utm_params` | array | No | URL parameters, maximum 14. | | `vbo_window` | string ("SEVEN_DAYS" | "ZERO_DAY") | No | Value optimization window. | | `budget_mode` | string ("BUDGET_MODE_DAY" | "BUDGET_MODE_DYNAMIC_DAILY_BUDGET") | No | Budget mode. | | `identity_id` | string | No | Non-Spark identity ID. | | `product_ids` | array | No | Customized product IDs, maximum 20. | | `location_ids` | array | Yes | Target location IDs. | | `product_info` | object | No | Product promotion information. | | `advertiser_id` | string | Yes | Advertiser ID. | | `billing_event` | string ("OCPM" | "CPC") | Yes | Billing event. | | `campaign_name` | string | Yes | Campaign name. | | `campaign_type` | string ("REGULAR_CAMPAIGN" | "IOS14_CAMPAIGN") | No | Campaign type. | | `deep_bid_type` | string ("DEFAULT" | "AEO" | "VO_MIN_ROAS" | "VO_HIGHEST_VALUE") | No | Deep-event bidding strategy. | | `deeplink_type` | string | No | Deeplink type. | | `identity_type` | string | No | Non-Spark identity type. | | `schedule_type` | string ("SCHEDULE_START_END" | "SCHEDULE_FROM_NOW") | Yes | Schedule type. | | `objective_type` | string ("APP_PROMOTION" | "WEB_CONVERSIONS" | "LEAD_GENERATION") | Yes | Advertising objective. | | `placement_type` | string ("PLACEMENT_TYPE_NORMAL" | "PLACEMENT_TYPE_AUTOMATIC") | No | Placement strategy. | | `product_set_id` | string | No | Product set ID. | | `product_source` | string | No | Catalog product source. | | `promotion_type` | string ("APP_ANDROID" | "APP_IOS" | "WEBSITE" | "LEAD_GENERATION") | Yes | Optimization location. | | `share_disabled` | boolean | No | Whether sharing is disabled. | | `disclaimer_info` | object | No | WEB_AND_APP disclaimer details. | | `media_info_list` | array | Yes | Documented media information, maximum 30. | | `tracking_app_id` | string | No | Tracking app ID. | | `comment_disabled` | boolean | No | Whether comments are disabled. | | `dark_post_status` | string ("ON" | "OFF") | No | Spark Ads-only mode. | | `operation_status` | string ("ENABLE" | "DISABLE") | No | Initial campaign status. | | `spc_audience_age` | string ("18+" | "25+") | No | Target age floor. | | `call_to_action_id` | string | No | CTA portfolio ID. | | `landing_page_urls` | array | No | Landing-page mappings, maximum 30. | | `optimization_goal` | string ("CLICK" | "INSTALL" | "IN_APP_EVENT" | "VALUE" | "CONVERT" | "TRAFFIC_LANDING_PAGE_VIEW" | "LEAD_GENERATION") | Yes | Optimization goal. | | `sales_destination` | string ("WEBSITE" | "WEB_AND_APP") | No | Sales destination required with virtual_objective_type. | | `schedule_end_time` | string | No | UTC schedule end. | | `app_promotion_type` | string | No | App promotion type required for APP_PROMOTION. | | `click_tracking_url` | string | No | Click tracking URL. | | `optimization_event` | string | No | Conversion event. | | `special_industries` | array | No | Special ad categories. | | `call_to_action_list` | array | No | Call-to-action objects. | | `schedule_start_time` | string | Yes | UTC schedule start. | | `conversion_bid_price` | number | No | Target conversion or landing-page-view cost. | | `disable_skan_campaign` | boolean | No | Whether to disable SKAN attribution. | | `excluded_audience_ids` | array | No | Excluded audience IDs. | | `product_specific_type` | string ("ALL" | "PRODUCT_SET" | "CUSTOMIZED_PRODUCTS") | No | Product selection type. | | `promotion_target_type` | string ("INSTANT_PAGE" | "EXTERNAL_WEBSITE") | No | Lead generation optimization location. | | `app_tracking_info_list` | array | No | Third-party app tracking settings, maximum four. | | `blocked_pangle_app_ids` | array | No | Blocked Pangle app IDs. | | `promotion_website_type` | string | No | TikTok Instant Page type. | | `virtual_objective_type` | string | No | Combined Sales objective. | | `attribution_event_count` | string ("UNSET" | "EVERY" | "ONCE") | No | Attribution event count mode. | | `catalog_creative_toggle` | boolean | No | Catalog creative auto-selection. | | `impression_tracking_url` | string | No | Impression tracking URL. | | `video_download_disabled` | boolean | No | Whether video download is disabled. | | `view_attribution_window` | string | No | View attribution window. | | `automatic_add_on_enabled` | boolean | No | Automatic interactive add-ons. | | `catalog_authorized_bc_id` | string | No | Catalog Business Center ID. | | `click_attribution_window` | string | No | Click attribution window. | | `deep_funnel_event_source` | string ("PIXEL" | "OFFLINE" | "CRM") | No | Deep-funnel event source. | | `exclude_age_under_eighteen` | boolean | No | Exclude users under 18; only true is supported. | | `budget_auto_adjust_strategy` | string | No | Automatic budget adjustment strategy. | | `deep_funnel_event_source_id` | string | No | Deep-funnel source ID. | | `web_all_in_one_catalog_status` | string ("OPEN" | "UNSET") | No | Smart+ Web catalog status. | | `deep_funnel_optimization_event` | string | No | Deep-funnel event. | | `is_advanced_dedicated_campaign` | boolean | No | Advanced Dedicated Campaign status. | | `campaign_app_profile_page_state` | string ("ON" | "OFF") | No | App profile page optimization state. | | `deep_funnel_optimization_status` | string ("ON" | "OFF") | No | Deep-funnel optimization status. | | `engaged_view_attribution_window` | string | No | Engaged-view attribution window. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create a catalog **Slug:** `TIKTOK_ADS_CREATE_CATALOG` Create a catalog in a TikTok Business Center; some catalog types require allowlisting. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | Yes | Catalog name, up to 128 characters. | | `bc_id` | string | Yes | Business Center ID. | | `catalog_conf` | object | Yes | Catalog region and currency configuration. | | `catalog_type` | string ("ECOM" | "GENERIC" | "HOTEL" | "FLIGHT" | "DESTINATION" | "ENTERTAINMENT" | "AUTO_VEHICLE" | "AUTO_MODEL" | "ONLINE_TO_OFFLINE" | "MINI_SERIES") | Yes | TikTok catalog type. | | `creative_asset_type` | string | No | Creative asset type, when supported. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create a feed **Slug:** `TIKTOK_ADS_CREATE_CATALOG_FEED` Create 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `feed_name` | string | Yes | Feed name. | | `catalog_id` | string | Yes | Catalog ID. | | `update_mode` | string ("INCREMENTAL" | "OVERWRITE") | Yes | 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. | | `schedule_param` | object | No | Optional remote-feed schedule. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create Catalog Product Diagnostic Task **Slug:** `TIKTOK_ADS_CREATE_CATALOG_PRODUCT_DIAGNOSTIC_TASK` Create an asynchronous download task for catalog product diagnostic information. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `lang` | string ("ar" | "cs-CZ" | "de" | "en" | "es" | "fil" | "fr" | "id" | "it" | "ja" | "ko" | "ms" | "pl-PL" | "pt" | "ru" | "sv-SE" | "th" | "tr" | "vi" | "zh") | No | Language for the downloaded diagnostic information. | | `bc_id` | string | Yes | Business Center ID that owns the catalog. | | `feed_id` | string | No | Optional catalog feed ID to diagnose. | | `issue_id` | string | No | Optional diagnostic issue ID to include. | | `catalog_id` | string | Yes | E-commerce catalog ID to diagnose. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create Catalog Product Set by File **Slug:** `TIKTOK_ADS_CREATE_CATALOG_PRODUCT_SET` Create an E-commerce catalog product set from an uploaded CSV file. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file` | object | Yes | CSV defining the product set, with at most 5,000 rows. | | `bc_id` | string | Yes | Business Center ID that owns the E-commerce catalog. | | `catalog_id` | string | Yes | E-commerce catalog ID in which to create the product set. | | `file_signature` | string | Yes | MD5 hash of the uploaded file for integrity verification. | | `product_set_name` | string | Yes | Unique product set name, up to 28 characters. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create a product set by conditions **Slug:** `TIKTOK_ADS_CREATE_CATALOG_SET` Create a catalog product set using one AND or OR condition group. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `catalog_id` | string | Yes | Catalog ID. | | `conditions` | object | Yes | Exactly one `and` or `or` list of filter conditions. | | `product_set_name` | string | Yes | Product set name, up to 128 characters. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create Change Log Download Task **Slug:** `TIKTOK_ADS_CREATE_CHANGELOG_TASK` Create an asynchronous download task for an advertiser's change log. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `module` | string ("BIDDING_AND_OPTIMIZATION" | "BUDGET" | "STATUS" | "TARGETING") | No | Change-log module to query. | | `end_time` | string | No | Query end time, no more than 30 days after start_time. | | `timezone` | string | No | 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. | | `object_ids` | array | No | Object IDs to include in the change-log query. | | `start_time` | string | No | Inclusive query start time in YYYY-MM-DD HH:MM:SS format. | | `object_type` | string ("AD" | "ADGROUP" | "ADVERTISER" | "CAMPAIGN" | "INSTANT_FORM") | No | Type of object IDs being queried. | | `order_fields` | array | No | 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. | | `advertiser_id` | string | Yes | Advertiser ID whose change log to export. | | `operation_types` | array | No | Change-log operation types to include. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create a comment export task **Slug:** `TIKTOK_ADS_CREATE_COMMENT_TASK` Create 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `lang` | string ("EN" | "JA" | "ZH") | No | Export language: `EN`, `JA`, or `ZH`. | | `end_time` | string | Yes | End date of the export range in YYYY-MM-DD format. | | `sort_type` | string ("ASC" | "DESC") | No | Ascending or descending sort order. | | `sort_field` | string ("CREATE_TIME" | "LIKES" | "REPLIES") | No | Field used to sort exported comments. | | `start_time` | string | Yes | Start date of the export range in YYYY-MM-DD format. | | `comment_ids` | array | No | Optional comment IDs to export. | | `comment_type` | array | No | Comment type filters: `ALL`, `COMMENT`, or `REPLY`. | | `search_field` | string | Yes | Field to search by; only `ADGROUP_ID` is supported. | | `search_value` | string | Yes | Ad group ID used as the search value. | | `advertiser_id` | string | Yes | Advertiser ID whose comments to export. | | `comment_status` | array | No | Comment status filters: `ALL`, `PUBLIC`, or `HIDDEN`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create Creative Welcome Message **Slug:** `TIKTOK_ADS_CREATE_CREATIVE_AUTO_MESSAGE` Create a welcome message within a TikTok advertiser account. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_id` | string | Yes | Advertiser account ID. | | `welcome_message` | object | Yes | Welcome message required for WELCOME_MESSAGE. | | `auto_message_type` | string | Yes | Automatic-message type. The documented value is WELCOME_MESSAGE. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create a portfolio **Slug:** `TIKTOK_ADS_CREATE_CREATIVE_PORTFOLIO` Create a typed creative portfolio. Availability may depend on TikTok entitlement. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_id` | string | Yes | Advertiser ID. | | `portfolio_content` | array | Yes | Portfolio content objects. | | `creative_portfolio_type` | string | No | TikTok creative portfolio type. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create Creative Pre-Review Task **Slug:** `TIKTOK_ADS_CREATE_CREATIVE_PRE_REVIEW_TASK` Create a task to pre-review creative materials for one location. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `is_ecommerce` | boolean | No | Whether the materials are for e-commerce. | | `advertiser_id` | string | Yes | Advertiser account ID. | | `material_list` | array | Yes | Materials to pre-review (1-5). | | `location_codes` | array | Yes | Exactly one target location code. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create a creative shareable link **Slug:** `TIKTOK_ADS_CREATE_CREATIVE_SHAREABLE_LINK` Create a link for sharing up to 20 named creative assets. TikTok does not document the link lifetime or revocation behavior. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sharer` | string | Yes | Name of the person or organization sharing the creative assets. | | `shared_assets` | array | Yes | Creative assets to include in the shareable link, maximum 20. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create a CRM Event Set **Slug:** `TIKTOK_ADS_CREATE_CRM` Create 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | Yes | Unique CRM Event Set name, from 1 to 40 characters after trimming. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create a Custom Conversion **Slug:** `TIKTOK_ADS_CREATE_CUSTOM_CONVERSION` Create a Custom Conversion configuration; this does not ingest conversion events. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | Yes | Unique Custom Conversion name; starts with a letter and contains no emoji. | | `rules` | array | Yes | One to ten conversion rules. | | `description` | string | No | Optional description without emoji. | | `advertiser_id` | string | Yes | Advertiser ID. | | `event_source_id` | string | Yes | Pixel ID or SAN app platform ID. | | `custom_event_type` | string | No | Configured custom event to associate, when applicable. | | `event_source_type` | string ("PIXEL" | "APP") | Yes | PIXEL or APP event source. | | `optimization_event` | string | No | Standard event associated with the conversion; required for PIXEL sources. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create a Customer File Audience **Slug:** `TIKTOK_ADS_CREATE_DMP_CUSTOM_AUDIENCE` Create a custom audience from previously uploaded encrypted customer files. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file_paths` | array | Yes | Uploaded audience file paths; fewer than 50 are recommended. | | `advertiser_id` | string | Yes | Advertiser ID. | | `calculate_type` | string ("EMAIL_SHA256" | "FIRST_MD5" | "FIRST_SHA256" | "GAID_MD5" | "GAID_SHA256" | "IDFA_MD5" | "IDFA_SHA256" | "MULTIPLE_TYPES" | "PHONE_SHA256") | Yes | Encryption type shared by every uploaded file. | | `audience_sub_type` | string ("NORMAL" | "REACH_FREQUENCY") | No | Audience subtype: NORMAL or REACH_FREQUENCY. | | `retention_in_days` | integer | No | Audience retention period in days (1-365). | | `audience_enhancement` | boolean | No | Whether to enable audience enhancement. | | `custom_audience_name` | string | Yes | Audience name (maximum 128 characters). | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create a Lookalike Audience **Slug:** `TIKTOK_ADS_CREATE_DMP_CUSTOM_AUDIENCE_LOOKALIKE` Create a lookalike custom audience from an eligible source audience. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_id` | string | Yes | Advertiser ID. | | `lookalike_spec` | object | Yes | Lookalike audience settings. | | `custom_audience_name` | string | Yes | Audience name (maximum 128 characters). | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create a Rule-Based Custom Audience **Slug:** `TIKTOK_ADS_CREATE_DMP_CUSTOM_AUDIENCE_RULE` Create a custom audience from conditional inclusion and exclusion event rules. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `rule_spec` | object | Yes | Inclusion and optional exclusion rule sets. | | `identity_id` | string | No | Identity ID required for organic-video and live-video audiences. | | `advertiser_id` | string | Yes | Advertiser ID. | | `audience_type` | string ("ENGAGEMENT" | "ENGAGEMENT_ORGANIC_VIDEO" | "ENGAGEMENT_LIVE_VIDEO" | "APP" | "PIXEL" | "LEAD_GENERATION" | "BUSINESS_ACCOUNT" | "TIKTOK_SHOP" | "OFFLINE") | Yes | Provider audience type. | | `identity_type` | string ("TT_USER" | "BC_AUTH_TT") | No | Identity type required for organic-video and live-video audiences. | | `is_auto_refresh` | boolean | No | Whether to refresh the audience automatically. | | `audience_sub_type` | string ("NORMAL" | "REACH_FREQUENCY") | No | Audience subtype for standard or Reach & Frequency ads. | | `retention_in_days` | integer | No | Audience retention period (1-365 days). | | `audience_enhancement` | boolean | No | Whether to enable audience enhancement. | | `custom_audience_name` | string | Yes | Audience name (maximum 128 characters). | | `identity_authorized_bc_id` | string | No | Business Center ID required for a Business Center-authorized TikTok identity. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create a Saved Audience **Slug:** `TIKTOK_ADS_CREATE_DMP_SAVED_AUDIENCE` Create a reusable Saved Audience from targeting criteria. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `gender` | string ("GENDER_FEMALE" | "GENDER_MALE" | "GENDER_UNLIMITED") | No | Target gender. | | `actions` | array | No | Action targeting objects. | | `languages` | array | No | Target language codes. | | `age_groups` | array | No | Target age groups. | | `carrier_ids` | array | No | Target carrier IDs. | | `audience_ids` | array | No | Included audience IDs. | | `location_ids` | array | Yes | Non-overlapping target location IDs. | | `advertiser_id` | string | Yes | Advertiser ID. | | `network_types` | array | No | Target connection types. | | `min_ios_version` | string | No | Minimum iOS version. | | `device_model_ids` | array | No | Target device model IDs. | | `operating_systems` | array | No | Target device operating system. | | `device_price_ranges` | array | No | Target device price ranges. | | `min_android_version` | string | No | Minimum Android version. | | `saved_audience_name` | string | Yes | Saved Audience name without emoji (maximum 512 characters). | | `interest_keyword_ids` | array | No | Interest keyword IDs. | | `excluded_audience_ids` | array | No | Excluded audience IDs. | | `interest_category_ids` | array | No | Interest category IDs. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create GMV Max Campaign **Slug:** `TIKTOK_ADS_CREATE_GMV_MAX_CAMPAIGN` Create a GMV Max campaign from TikTok's official campaign model. Mutation QA must use owned test resources and remain disabled or draft; this action does not add an enabling or publishing status. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `budget` | number | No | Optional campaign budget. | | `roas_bid` | number | No | Optional ROAS bid. | | `store_id` | string | Yes | TikTok Shop store ID. | | `item_list` | array | No | Optional shop items for the campaign. | | `request_id` | string | Yes | Client deduplication request ID. | | `advertiser_id` | string | Yes | Authorized advertiser account ID. | | `campaign_name` | string | Yes | Name for the new GMV Max campaign. | | `deep_bid_type` | string | Yes | Deep bid type; the official contract supports VO_MIN_ROAS. | | `identity_list` | array | No | Optional identities available to the campaign. | | `schedule_type` | string ("SCHEDULE_FROM_NOW" | "SCHEDULE_START_END") | Yes | Campaign schedule type. | | `item_group_ids` | array | No | Optional item group IDs (1-50). | | `promotion_days` | object | No | Optional promotion-day schedule configuration. | | `optimization_goal` | string | Yes | Optimization goal; the official contract supports VALUE. | | `schedule_end_time` | string | No | Required for SCHEDULE_START_END, in the provider's date-time string format. | | `shopping_ads_type` | string ("LIVE" | "PRODUCT") | Yes | GMV Max shopping ads type: LIVE or PRODUCT. | | `auto_budget_enabled` | boolean | No | Whether automatic budget management is enabled. | | `schedule_start_time` | string | Yes | Campaign start time in the provider's date-time string format. | | `product_specific_type` | string ("ALL" | "CUSTOMIZED_PRODUCTS") | No | Optional product selection type. | | `store_authorized_bc_id` | string | Yes | Business Center ID authorizing the store. | | `affiliate_posts_enabled` | boolean | No | Whether affiliate posts are enabled. | | `custom_anchor_video_list` | array | No | Optional custom anchor videos (maximum 2000). | | `product_video_specific_type` | string ("AUTO_SELECTION" | "CUSTOM_SELECTION") | No | Optional product video selection type. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create GMV Max Session **Slug:** `TIKTOK_ADS_CREATE_GMV_MAX_CAMPAIGN_SESSION` Create 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `session` | string | Yes | Max delivery or creative boost session configuration. | | `store_id` | string | Yes | TikTok Shop store ID. | | `campaign_id` | string | Yes | Product GMV Max campaign ID. | | `advertiser_id` | string | Yes | Authorized advertiser account ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create shop-level customized TikTok posts **Slug:** `TIKTOK_ADS_CREATE_GMV_MAX_CUSTOMIZED_POSTS` Create shop-level customized TikTok posts. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `store_id` | string | Yes | TikTok Shop ID. | | `advertiser_id` | string | Yes | Advertiser ID. | | `store_authorized_bc_id` | string | Yes | Business Center ID authorized to access the TikTok Shop. | | `custom_anchor_video_list` | array | Yes | Videos and products to link (maximum 200). | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Grant an ad account exclusive authorization for a TikTok Shop **Slug:** `TIKTOK_ADS_CREATE_GMV_MAX_EXCLUSIVE_AUTHORIZATION` Grant an ad account exclusive authorization for a TikTok Shop. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `store_id` | string | Yes | TikTok Shop ID. | | `advertiser_id` | string | Yes | Ad account to authorize exclusively for the TikTok Shop. | | `store_authorized_bc_id` | string | Yes | Business Center ID that owns the TikTok Shop. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create an Identity **Slug:** `TIKTOK_ADS_CREATE_IDENTITY` Create 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `image_uri` | string | No | Uploaded square avatar image ID; omit to use TikTok's default image. | | `display_name` | string | Yes | Identity display name, at most 100 characters. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create MMM Data Request **Slug:** `TIKTOK_ADS_CREATE_MMM_DATA_REQUEST` Create 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `email` | string | No | Optional email address to notify when processing changes state. | | `confirmed` | boolean | Yes | 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. | | `request_info` | object | Yes | MMM export selection and date range. | | `advertiser_ids` | array | Yes | Authorized advertiser IDs for this export; five or fewer are recommended. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create an Offline Event Set **Slug:** `TIKTOK_ADS_CREATE_OFFLINE` Create an Offline Event Set configuration; this does not upload or ingest offline events. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | Yes | Unique Offline Event Set name. | | `description` | string | Yes | Offline Event Set description. | | `advertiser_id` | string | Yes | Advertiser ID. | | `auto_tracking` | boolean | No | Enable Auto Tracking for future campaigns. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create rules **Slug:** `TIKTOK_ADS_CREATE_OPTIMIZER_RULE` Create automated optimizer rules. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `lang` | string ("ZH" | "EN" | "JA") | No | Language of error messages. | | `rules` | array | Yes | Rules to create. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create a test lead **Slug:** `TIKTOK_ADS_CREATE_PAGE_LEAD_MOCK` Create a disposable test lead for an Instant Form or direct-message source; remove it after testing. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page_id` | string | No | Instant Form ID; required for INSTANT_FORM and unsupported for DIRECT_MESSAGE. | | `library_id` | string | No | Form library ID when creating under a Business Center. | | `lead_source` | string ("INSTANT_FORM" | "DIRECT_MESSAGE") | No | Test-lead source. | | `advertiser_id` | string | No | Advertiser ID when creating under an ad account. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create a lead download task **Slug:** `TIKTOK_ADS_CREATE_PAGE_LEAD_TASK` Create 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `ad_id` | string | No | Ad ID to export leads for; mutually exclusive with page_id. | | `page_id` | string | No | Instant Form ID to export leads for; mutually exclusive with ad_id. | | `library_id` | string | No | Form library ID after leads have migrated to a Business Center. | | `lead_region` | string ("eu" | "us") | No | Use eu for EEA/Switzerland/UK leads, us for US leads, or omit for other regions. | | `advertiser_id` | string | No | Advertiser ID when leads remain under an ad account. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create a Payment Portfolio **Slug:** `TIKTOK_ADS_CREATE_PAYMENT_PORTFOLIO` Create 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_ids` | array | Yes | Ad account IDs to link (maximum 20). All must belong to the same client; one invalid ID causes the entire call to fail. | | `payment_portfolio_name` | string | Yes | Payment Portfolio name. | | `payment_portfolio_type` | string | No | Portfolio type. SHARED centrally manages funds across linked accounts. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create a Pixel **Slug:** `TIKTOK_ADS_CREATE_PIXEL` Create a TikTok Pixel configuration; this does not ingest web events. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `pixel_name` | string | Yes | Unique Pixel name without emoji. | | `partner_name` | string | No | Merchant partner name, when applicable. | | `advertiser_id` | string | Yes | Advertiser ID. | | `pixel_category` | string ("ONLINE_STORE" | "FILLING_FORM" | "CONTACTS" | "LANDING_PAGE" | "CUSTOMIZE_EVENTS") | No | Deprecated Pixel category; omit for new Pixels. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create Pixel Events **Slug:** `TIKTOK_ADS_CREATE_PIXEL_EVENT` Create standard Pixel Event configurations and rules; this endpoint does not ingest event occurrences. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `pixel_id` | string | Yes | Pixel ID. | | `pixel_events` | array | Yes | Pixel Event configurations to create. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create asynchronous report task **Slug:** `TIKTOK_ADS_CREATE_REPORT_TASK` Create 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `metrics` | array | No | Metric names; defaults upstream to spend and impressions. | | `end_date` | string | No | Inclusive end date. | | `file_name` | string | No | Custom download file name. | | `filtering` | array | No | Asynchronous report filters. | | `data_level` | string ("AUCTION_AD" | "AUCTION_ADGROUP" | "AUCTION_ADVERTISER" | "AUCTION_CAMPAIGN" | "RESERVATION_AD" | "RESERVATION_ADGROUP" | "RESERVATION_ADVERTISER" | "RESERVATION_CAMPAIGN") | No | Report data level. | | `dimensions` | array | Yes | Asynchronous report dimensions. | | `order_type` | string ("ASC" | "DESC") | No | Sort order. | | `start_date` | string | No | Inclusive start date. | | `order_field` | string | No | Metric used for sorting. | | `report_type` | string ("BASIC" | "AUDIENCE" | "CATALOG") | Yes | Asynchronous report type. | | `service_type` | string ("AUCTION" | "RESERVATION") | No | Ad service type. | | `advertiser_id` | string | No | Single advertiser ID; ignored when advertiser_ids is supplied. | | `output_format` | string ("CSV_DOWNLOAD" | "CSV_STRING" | "XLSX_DOWNLOAD") | No | Asynchronous report output format. | | `advertiser_ids` | array | No | One to five advertiser IDs belonging to the same user. | | `query_lifetime` | boolean | No | Request lifetime metrics. | | `enable_report_title_translation` | boolean | No | Translate dimension and metric titles in the output. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create Smart Creative Ads **Slug:** `TIKTOK_ADS_CREATE_SMART_CREATIVE_ADS` Create 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `card_list` | array | No | Card or sticker ID (maximum one). | | `page_list` | array | No | Instant Page IDs (1-3). | | `adgroup_id` | string | Yes | Ad group ID whose creative_material_mode is SMART_CREATIVE. | | `title_list` | array | No | Distinct ad titles (1-5). | | `advertiser_id` | string | Yes | Advertiser account ID. | | `deeplink_list` | array | No | Optional app deep link (maximum one). | | `common_material` | object | No | Settings shared by generated ads. | | `media_info_list` | array | Yes | Distinct image, video, or Spark materials. | | `display_name_list` | array | No | Displayed app or landing-page names. | | `landing_page_urls` | array | No | Landing-page destinations. | | `call_to_action_list` | array | No | Distinct call-to-action texts (1-3). | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create Smart+ Ad **Slug:** `TIKTOK_ADS_CREATE_SMART_PLUS_AD` Create a Smart+ ad disabled for review in an existing Smart+ ad group. Use the separate Smart+ ad status tool to enable it. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `ad_name` | string | Yes | Smart+ ad name. | | `page_list` | array | No | Instant Pages (maximum 3). | | `adgroup_id` | string | Yes | Ad group ID in which to create the ad. | | `ad_text_list` | array | No | Ad text variants (maximum 5). | | `advertiser_id` | string | Yes | Advertiser ID that owns the ad group. | | `creative_list` | array | No | Creative variants (1-31). | | `deeplink_list` | array | No | Deep-link destinations (maximum 1). | | `ad_configuration` | object | No | Common ad material configuration. | | `operation_status` | string | No | Initial status. Only DISABLE is accepted so the ad is created disabled for review. | | `auto_message_list` | array | No | Auto-message configuration (maximum 1). | | `call_to_action_list` | array | No | Call-to-action variants (maximum 3). | | `landing_page_url_list` | array | No | Landing pages (maximum 1). | | `interactive_add_on_list` | array | No | Interactive add-ons (maximum 1). | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create Smart+ Ad Group **Slug:** `TIKTOK_ADS_CREATE_SMART_PLUS_ADGROUP` Create 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `app_id` | string | No | Promoted app ID. | | `budget` | number | No | Budget. | | `bid_type` | string ("BID_TYPE_CUSTOM" | "BID_TYPE_MAX_CONVERSION" | "BID_TYPE_NO_BID") | No | Bid type. | | `pixel_id` | string | No | Pixel ID. | | `roas_bid` | number | No | ROAS bid. | | `bid_price` | number | No | Bid price. | | `catalog_id` | string | No | Catalog ID. | | `dayparting` | string | No | Dayparting schedule. | | `min_budget` | number | No | Minimum budget. | | `phone_info` | object | No | Phone information. | | `placements` | array | No | Placements. | | `request_id` | string | Yes | Caller-provided deduplication token. | | `vbo_window` | string ("SEVEN_DAYS" | "ZERO_DAY") | No | Value-based optimization window. | | `budget_mode` | string ("BUDGET_MODE_DAY" | "BUDGET_MODE_DYNAMIC_DAILY_BUDGET" | "BUDGET_MODE_INFINITE" | "BUDGET_MODE_TOTAL") | No | Budget mode. | | `campaign_id` | string | Yes | Campaign ID in which to create the ad group. | | `deep_cpabid` | number | No | Deep conversion CPA bid. | | `identity_id` | string | No | Identity ID. | | `adgroup_name` | string | Yes | Ad group name. | | `zalo_id_type` | string ("ZALO_OFFICIAL_ACCOUNT" | "ZALO_PHONE_ACCOUNT") | No | Zalo account ID type. | | `advertiser_id` | string | Yes | Advertiser ID that owns the campaign. | | `billing_event` | string ("CPA" | "CPC" | "CPM" | "CPV" | "GD" | "OCPM") | Yes | Billing event. | | `deep_bid_type` | string ("AEO" | "DEFAULT" | "MIN" | "PACING" | "VO_HIGHEST_VALUE" | "VO_MIN" | "VO_MIN_ROAS") | No | Deep bid type. | | `identity_type` | string ("BC_AUTH_TT" | "TT_USER") | No | Identity type. | | `schedule_type` | string ("SCHEDULE_FROM_NOW" | "SCHEDULE_START_END") | Yes | Schedule type. | | `placement_type` | string ("PLACEMENT_TYPE_AUTOMATIC" | "PLACEMENT_TYPE_NORMAL") | No | Placement type. | | `product_source` | string ("CATALOG" | "SHOWCASE" | "STORE" | "UNSET") | No | Product source. | | `promotion_type` | 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") | Yes | Promotion type. | | `share_disabled` | boolean | No | Whether sharing is disabled. | | `targeting_spec` | object | Yes | Audience targeting specification. | | `comment_disabled` | boolean | No | Whether comments are disabled. | | `open_api_partner` | string | No | Open API partner. | | `operation_status` | string | No | Initial status. Only DISABLE is accepted so the ad group is created disabled for review. | | `optimization_goal` | 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") | Yes | Optimization goal. | | `schedule_end_time` | string | No | Schedule end time. | | `messaging_app_type` | string ("IM_URL" | "LINE" | "MESSENGER" | "WHATSAPP" | "ZALO") | No | Messaging app type. | | `optimization_event` | 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") | No | Optimization event. | | `movie_premiere_date` | string | No | Movie premiere date. | | `schedule_start_time` | string | Yes | Schedule start time. | | `conversion_bid_price` | number | No | Conversion bid price. | | `custom_conversion_id` | string | No | Custom conversion ID. | | `message_event_set_id` | string | No | Message event set ID. | | `promotion_target_type` | string ("EXTERNAL_WEBSITE" | "INSTANT_PAGE" | "UNSET") | No | Promotion target type. | | `promotion_website_type` | string ("TIKTOK_NATIVE_PAGE" | "UNSET") | No | Promotion website type. | | `attribution_event_count` | string ("EVERY" | "ONCE" | "UNSET") | No | Attribution event counting mode. | | `video_download_disabled` | boolean | No | Whether video download is disabled. | | `view_attribution_window` | string ("FOURTEEN_DAYS" | "OFF" | "ONE_DAY" | "SEVEN_DAYS" | "TWENTY_EIGHT_DAYS" | "UNSET") | No | View attribution window. | | `catalog_authorized_bc_id` | string | No | Catalog-authorizing Business Center ID. | | `click_attribution_window` | string ("FOURTEEN_DAYS" | "OFF" | "ONE_DAY" | "SEVEN_DAYS" | "TWENTY_EIGHT_DAYS" | "UNSET") | No | Click attribution window. | | `deep_funnel_event_source` | string ("CRM" | "OFFLINE" | "PIXEL") | No | Deep-funnel event source. | | `messaging_app_account_id` | string | No | Messaging app account ID. | | `identity_authorized_bc_id` | string | No | Identity-authorizing Business Center ID. | | `deep_funnel_event_source_id` | string | No | Deep-funnel event source ID. | | `suggestion_audience_enabled` | boolean | No | Whether suggested audience is enabled. | | `targeting_optimization_mode` | string ("AUTOMATIC" | "MANUAL") | No | Targeting optimization mode. | | `deep_funnel_optimization_event` | 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") | No | Deep-funnel optimization event. | | `deep_funnel_optimization_status` | string ("OFF" | "ON" | "UNSET") | No | Deep-funnel optimization status. | | `engaged_view_attribution_window` | string ("FOURTEEN_DAYS" | "OFF" | "ONE_DAY" | "SEVEN_DAYS" | "TWENTY_EIGHT_DAYS" | "UNSET") | No | Engaged-view attribution window. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create Smart+ Campaign **Slug:** `TIKTOK_ADS_CREATE_SMART_PLUS_CAMPAIGN` Create a Smart+ campaign disabled for review. Use the separate Smart+ campaign status tool to enable it after review. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `app_id` | string | No | Optional promoted application ID. | | `budget` | number | No | Optional campaign budget. | | `po_number` | string | No | Optional purchase order number. | | `request_id` | string | Yes | Client deduplication request ID. | | `budget_mode` | string ("BUDGET_MODE_DYNAMIC_DAILY_BUDGET" | "BUDGET_MODE_TOTAL") | No | Optional campaign budget mode. | | `catalog_type` | string ("ECOMMERCE" | "MINI_SERIES" | "TRAVEL_ENTERTAINMENT") | No | Optional Smart+ catalog type. | | `advertiser_id` | string | Yes | Authorized advertiser account ID. | | `campaign_name` | string | Yes | Name for the new Smart+ campaign. | | `campaign_type` | string ("IOS14_CAMPAIGN" | "REGULAR_CAMPAIGN") | No | Optional dedicated campaign type: regular or iOS 14 campaign. | | `bid_align_type` | string ("SAN" | "SKAN" | "UNSET") | No | Optional bid attribution alignment type. | | `objective_type` | string ("APP_PROMOTION" | "LEAD_GENERATION" | "WEB_CONVERSIONS") | Yes | Campaign objective type. | | `catalog_enabled` | boolean | No | Whether catalog use is enabled for the campaign. | | `open_api_partner` | string | No | Optional Open API partner identifier. | | `operation_status` | string | No | Initial campaign status. Only DISABLE is accepted so the campaign is created paused for review. | | `sales_destination` | string | No | Optional campaign sales destination. | | `app_promotion_type` | string | No | Optional application promotion type. | | `budget_optimize_on` | boolean | No | Whether campaign budget optimization is on. | | `special_industries` | array | No | Optional regulated-industry categories: CREDIT, EMPLOYMENT, or HOUSING. | | `postback_window_mode` | string ("POSTBACK_WINDOW_MODE1" | "POSTBACK_WINDOW_MODE2" | "POSTBACK_WINDOW_MODE3") | No | 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. | | `disable_skan_campaign` | boolean | No | Whether SKAdNetwork campaign behavior is disabled. | | `is_promotional_campaign` | boolean | No | Whether this is a promotional campaign. | | `is_advanced_dedicated_campaign` | boolean | No | Whether this is an advanced dedicated campaign; TikTok defaults this to true. | | `campaign_app_profile_page_state` | string ("OFF" | "ON") | No | Whether the promoted app's profile page is ON or OFF for this campaign. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create Smart+ Campaign Copy Task **Slug:** `TIKTOK_ADS_CREATE_SMART_PLUS_CAMPAIGN_COPY_TASK` Create 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `budget` | number | No | Copied campaign budget. | | `dayparting` | string | No | Seven-day delivery grid containing exactly 48 x 7 characters. | | `request_id` | string | Yes | Idempotency request ID cached for 10 seconds. | | `campaign_id` | string | Yes | Source Upgraded Smart+ campaign ID. | | `adgroup_list` | array | No | Ad groups to customize (maximum 10). | | `advertiser_id` | string | Yes | Advertiser account ID. | | `campaign_name` | string | No | Copied campaign name (maximum 512 characters). | | `schedule_type` | string ("SCHEDULE_START_END" | "SCHEDULE_FROM_NOW") | No | Schedule mode for all copied ad groups. | | `deep_copy_mode` | string ("DEFAULT" | "CUSTOM") | No | DEFAULT or CUSTOM deep-copy mode. | | `operation_status` | string ("ENABLE" | "DISABLE") | No | Copied campaign status. | | `schedule_end_time` | string | No | UTC schedule end in YYYY-MM-DD HH:MM:SS format. | | `schedule_start_time` | string | No | UTC schedule start in YYYY-MM-DD HH:MM:SS format. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create a split test **Slug:** `TIKTOK_ADS_CREATE_SPLIT_TEST` Create an ad-group or campaign-level split test. Campaign-level tests may require allowlisting. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `cells` | array | No | Exactly two split-test cells; required for CAMPAIGN tests. | | `budget` | number | No | Total test budget; required for ADGROUP and forbidden for CAMPAIGN tests. | | `end_time` | string | Yes | End time in YYYY-MM-DD HH:MM:SS UTC. | | `key_metric` | string | No | Key metric to monitor from TikTok's documented metric enumeration. | | `object_ids` | array | No | Ad group IDs; for ADGROUP tests provide this or cells. | | `start_time` | string | Yes | Start time in YYYY-MM-DD HH:MM:SS UTC. | | `advertiser_id` | string | Yes | Advertiser ID. | | `test_variable` | string ("BIDDING_OPTIMIZATION" | "TARGTING" | "CREATIVE" | "CUSTOM") | No | Test variable; defaults provider-side by split-test level. | | `split_test_level` | string ("ADGROUP" | "CAMPAIGN") | No | ADGROUP or CAMPAIGN split-test level. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create Video Fix Tasks **Slug:** `TIKTOK_ADS_CREATE_VIDEO_FIX_TASKS` Create up to 10 Smart Fix tasks for advertiser-owned videos. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `tasks` | array | Yes | Smart Fix tasks (1-10). | | `advertiser_id` | string | Yes | Advertiser account ID that owns the videos. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete assets from a BC **Slug:** `TIKTOK_ADS_DELETE_BC_ASSET_ADMIN` Remove the specified asset from the Business Center. This revokes the Business Center relationship and can move a lead asset back to its prior ad account. Confirm the exact Business Center, asset type, and disposable asset ID before calling. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `asset_ids` | array | Yes | Single asset ID to remove from the Business Center. | | `asset_type` | string ("LEAD" | "TT_ACCOUNT") | Yes | Type of the asset being removed. | | `child_bc_id` | string | No | Optional child Business Center ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete a member or revoke an invitation **Slug:** `TIKTOK_ADS_DELETE_BC_MEMBER` Remove 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `user_id` | string | No | Existing member's user ID when removing a member. | | `user_email` | string | No | Invited user's email when revoking an invitation. | | `child_bc_id` | string | No | Optional child Business Center ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete a partner from a BC **Slug:** `TIKTOK_ADS_DELETE_BC_PARTNER` Remove 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `partner_id` | string | Yes | Partner Business Center ID to remove. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Cancel the sharing of assets **Slug:** `TIKTOK_ADS_DELETE_BC_PARTNER_ASSET` Cancel 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `asset_ids` | array | Yes | Asset IDs whose sharing relationship will be cancelled. | | `asset_type` | string ("ADVERTISER" | "CATALOG" | "LEAD" | "PIXEL" | "TIKTOK_SHOP" | "TT_ACCOUNT") | Yes | Type shared by all specified assets. | | `partner_id` | string | Yes | Partner Business Center ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete blocked words **Slug:** `TIKTOK_ADS_DELETE_BLOCKEDWORD` Destructively 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_id` | string | Yes | Advertiser ID whose moderation list will change. | | `blocked_words` | array | Yes | Exact words to remove from the blocked-word list. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete Business Center Asset Group **Slug:** `TIKTOK_ADS_DELETE_BUSINESS_CENTER_ASSET_GROUP` Delete 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID containing the Asset Group to delete. | | `asset_group_ids` | array | Yes | Exactly one Asset Group ID to delete. This revokes members' access to the grouped assets without deleting the members or assets. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete a catalog **Slug:** `TIKTOK_ADS_DELETE_CATALOG` Permanently delete a catalog from a Business Center. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | ID of the Business Center that owns the catalog. | | `catalog_id` | string | Yes | ID of the catalog to delete. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete a feed **Slug:** `TIKTOK_ADS_DELETE_CATALOG_FEED` Permanently delete a catalog feed. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `feed_id` | string | Yes | Feed ID to delete. | | `catalog_id` | string | Yes | Catalog ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Remove products **Slug:** `TIKTOK_ADS_DELETE_CATALOG_PRODUCT` Remove products from a catalog using the ID list for that catalog type. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `feed_id` | string | No | Feed ID; omit to process the default catalog. | | `sku_ids` | array | No | E-commerce SKU IDs to delete, at most 1,000. | | `item_ids` | array | No | Generic catalog item IDs to delete, at most 10,000. | | `hotel_ids` | array | No | Hotel IDs to delete, at most 1,000. | | `catalog_id` | string | Yes | Catalog ID. | | `flight_ids` | array | No | Flight IDs to delete, at most 1,000. | | `series_ids` | array | No | Mini-series IDs to delete, at most 1,000. | | `listing_ids` | array | No | Online-to-offline listing IDs to delete, at most 10,000. | | `vehicle_ids` | array | No | Vehicle IDs to delete, at most 1,000. | | `destination_ids` | array | No | Destination IDs to delete, at most 1,000. | | `media_title_ids` | array | No | Entertainment media-title IDs to delete. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete product sets **Slug:** `TIKTOK_ADS_DELETE_CATALOG_SET` Permanently delete one to ten catalog product sets. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `catalog_id` | string | Yes | Catalog ID. | | `product_set_ids` | array | Yes | One to ten product set IDs to delete. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete Catalog Video **Slug:** `TIKTOK_ADS_DELETE_CATALOG_VIDEO` Permanently delete one uploaded video from an E-commerce catalog. This does not remove copies already synchronized to advertiser creative libraries. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID that owns the E-commerce catalog. | | `catalog_id` | string | Yes | E-commerce catalog ID containing the uploaded video. | | `catalog_video_ids` | array | Yes | Exactly one uploaded catalog video ID to delete. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete a comment **Slug:** `TIKTOK_ADS_DELETE_COMMENT` Permanently delete one TikTok comment. Before calling, confirm the exact advertiser, ad, video, identity, and disposable comment IDs; deletion cannot be undone. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `ad_id` | string | Yes | Ad ID associated with the comment. | | `comment_id` | string | Yes | Exact comment ID to delete. | | `identity_id` | string | Yes | Identity ID authorized to manage the comment. | | `advertiser_id` | string | Yes | Advertiser ID that owns the ad. | | `identity_type` | string ("CUSTOMIZED_USER" | "TT_USER") | Yes | Managing identity type: `CUSTOMIZED_USER` or `TT_USER`. | | `tiktok_item_id` | string | Yes | TikTok video ID containing the comment. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete Creative Assets **Slug:** `TIKTOK_ADS_DELETE_CREATIVE_ASSETS` Delete video or image assets owned by a TikTok advertiser account. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `image_ids` | array | No | Image IDs to delete (1-50 when supplied). | | `video_ids` | array | No | Video IDs to delete (1-50 when supplied). | | `advertiser_id` | string | Yes | Advertiser account ID that owns the assets. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete creative portfolios **Slug:** `TIKTOK_ADS_DELETE_CREATIVE_PORTFOLIO` Permanently delete up to 100 eligible creative portfolios. Use only explicitly confirmed disposable targets; one invalid ID fails the batch. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_id` | string | Yes | Advertiser ID that owns the portfolios. | | `creative_portfolio_ids` | array | Yes | 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete a Custom Conversion **Slug:** `TIKTOK_ADS_DELETE_CUSTOM_CONVERSION` Delete a Custom Conversion configuration; this does not delete ingested events. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_id` | string | Yes | Advertiser ID. | | `custom_conversion_id` | string | Yes | Custom Conversion ID to delete. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete Custom Audiences **Slug:** `TIKTOK_ADS_DELETE_DMP_CUSTOM_AUDIENCE` Delete between one and 100 custom audiences. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_id` | string | Yes | Advertiser ID. | | `custom_audience_ids` | array | Yes | Audience IDs to delete (1-100). | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete Saved Audiences **Slug:** `TIKTOK_ADS_DELETE_DMP_SAVED_AUDIENCE` Delete up to 100 Saved Audiences. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_id` | string | Yes | Advertiser ID. | | `saved_audience_ids` | array | Yes | Saved Audience IDs to delete (maximum 100). | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete GMV Max Session **Slug:** `TIKTOK_ADS_DELETE_GMV_MAX_CAMPAIGN_SESSION` Permanently delete a GMV Max session from an advertiser account. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `session_id` | string | Yes | GMV Max session ID to delete. | | `advertiser_id` | string | Yes | Authorized advertiser account ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete Customized TikTok Posts **Slug:** `TIKTOK_ADS_DELETE_GMV_MAX_CUSTOMIZED_POSTS` Permanently delete shop-level customized TikTok posts. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `store_id` | string | Yes | TikTok Shop store ID. | | `campaign_id` | string | No | 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. | | `advertiser_id` | string | Yes | Authorized advertiser account ID. | | `store_authorized_bc_id` | string | Yes | Business Center ID authorized for the TikTok Shop. | | `custom_anchor_video_list` | array | Yes | Customized TikTok posts to delete (maximum 200). | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete Customized Identity **Slug:** `TIKTOK_ADS_DELETE_IDENTITY` Permanently delete a customized user identity from an advertiser account. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `identity_id` | string | Yes | Customized user identity ID to delete. | | `advertiser_id` | string | Yes | Advertiser ID that owns the identity. | | `identity_type` | string | Yes | Identity type; TikTok supports only CUSTOMIZED_USER for deletion. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete an Offline Event Set **Slug:** `TIKTOK_ADS_DELETE_OFFLINE` Delete an Offline Event Set configuration; this is not an event-ingestion operation. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `event_set_id` | string | Yes | Offline Event Set ID to delete. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete a test lead **Slug:** `TIKTOK_ADS_DELETE_PAGE_LEAD_MOCK` Permanently delete one exact disposable TikTok test lead. Confirm the owner and lead ID before calling. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `lead_id` | string | Yes | Exact disposable test-lead ID to delete. | | `library_id` | string | No | Form library ID when the test lead belongs to a Business Center. | | `advertiser_id` | string | No | Advertiser ID when the test lead belongs to an ad account. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete a Pixel Event **Slug:** `TIKTOK_ADS_DELETE_PIXEL_EVENT` Delete a Pixel Event configuration; this does not delete ingested event occurrences. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `event_id` | string | Yes | Configured Pixel Event ID from LIST_PIXEL. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete a playable asset **Slug:** `TIKTOK_ADS_DELETE_PLAYABLE` Permanently delete one exact playable asset. Confirm the advertiser and a disposable playable ID before calling. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `playable_id` | string | Yes | Exact disposable playable asset ID to delete. | | `advertiser_id` | string | Yes | Advertiser ID that owns the playable asset. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete Search Ad Negative Keywords **Slug:** `TIKTOK_ADS_DELETE_SEARCH_AD_NEGATIVE_KEYWORDS` Delete negative keywords from one Search Ads campaign or ad group in an authorized advertiser account. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `object_id` | string | Yes | Campaign or ad-group ID that owns the keywords. | | `keyword_ids` | array | Yes | Negative-keyword IDs to delete. | | `object_type` | string ("CAMPAIGN" | "ADGROUP") | Yes | Whether object_id identifies a campaign or ad group. | | `advertiser_id` | string | Yes | Authorized advertiser account ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete Smart+ Resources **Slug:** `TIKTOK_ADS_DELETE_SMART_PLUS_RESOURCES` Permanently delete up to 20 Smart+ campaigns, ad groups, or ads. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `resource_ids` | array | Yes | Smart+ campaign, ad group, or ad IDs to delete (1-20). | | `advertiser_id` | string | Yes | Advertiser ID that owns the resources. | | `resource_type` | string ("CAMPAIGN" | "ADGROUP" | "AD") | Yes | Type of Smart+ resource identified by resource_ids. | | `postback_window_mode` | string ("POSTBACK_WINDOW_MODE1" | "POSTBACK_WINDOW_MODE2" | "POSTBACK_WINDOW_MODE3" | "UNSET") | No | Optional campaign postback window mode; valid only for CAMPAIGN. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Disable Business Center Advertiser **Slug:** `TIKTOK_ADS_DISABLE_BUSINESS_CENTER_ADVERTISER` Irreversibly 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID that contains the ad account. | | `advertiser_ids` | array | Yes | Ad account ID to disable. TikTok requires exactly one ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Discover new keywords **Slug:** `TIKTOK_ADS_DISCOVER_SEARCH_KEYWORD_IDEAS` Discover search keyword ideas and historical search metrics. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `keywords` | array | Yes | One to ten English seed keywords. | | `brand_type` | string ("BRAND" | "NON_BRAND" | "ALL") | No | Brand classification filter. | | `order_type` | string ("ASC" | "DESC") | No | Keyword idea sorting order. | | `order_field` | string ("AVG_MONTHLY_SEARCHES" | "THREE_MONTH_CHANGE" | "YEAR_OVER_YEAR_CHANGE" | "COMPETITION") | No | Field used to sort keyword ideas. | | `advertiser_id` | string | Yes | Advertiser ID. | | `country_codes` | array | No | Single target country or region code. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Download an invoice synchronously **Slug:** `TIKTOK_ADS_DOWNLOAD_BC_INVOICE` Download 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `invoice_id` | string | Yes | Invoice ID to download. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Download exported blocked words **Slug:** `TIKTOK_ADS_DOWNLOAD_BLOCKEDWORD_TASK` Download 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `task_id` | string | Yes | Succeeded blocked-word export task ID. | | `advertiser_id` | string | Yes | Advertiser ID that owns the export task. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Download exported comments **Slug:** `TIKTOK_ADS_DOWNLOAD_COMMENT_TASK` Download 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `task_id` | string | Yes | Succeeded comment export task ID. | | `advertiser_id` | string | Yes | Advertiser ID that owns the export task. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Download leads from a completed export task **Slug:** `TIKTOK_ADS_DOWNLOAD_PAGE_LEAD_TASK` Download 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `task_id` | string | Yes | Completed lead download task ID. | | `library_id` | string | No | Form library ID when leads are under a Business Center. | | `lead_region` | string ("eu" | "us") | No | Use eu for EEA/Switzerland/UK leads, us for US leads, or omit for other regions. | | `advertiser_id` | string | No | Advertiser ID when leads are under an ad account. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get asynchronous report download **Slug:** `TIKTOK_ADS_DOWNLOAD_REPORT_TASK` Retrieve output for a successful asynchronous report task. Returns temporary download URL metadata for CSV_DOWNLOAD or XLSX_DOWNLOAD tasks, or inline UTF-8 CSV content for CSV_STRING tasks. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `task_id` | string | Yes | Successful asynchronous report task ID. | | `advertiser_id` | string | Yes | Advertiser ID associated with the task. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Download negative keywords **Slug:** `TIKTOK_ADS_DOWNLOAD_SEARCH_AD_NEGATIVE_KEYWORD` Download negative keywords for a campaign or ad group as a spreadsheet file. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `object_id` | string | Yes | Campaign or ad-group ID whose negative keywords to download. | | `object_type` | string ("CAMPAIGN" | "ADGROUP") | Yes | Whether object_id identifies a campaign or ad group. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Edit an image **Slug:** `TIKTOK_ADS_EDIT_CREATIVE_IMAGE` Resize or Gaussian-pad an advertiser image. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `width` | integer | Yes | Edited image width, at least 3 pixels. | | `height` | integer | Yes | Edited image height, at least 3 pixels. | | `image_id` | string | Yes | Image ID. | | `image_name` | string | No | Edited image name; TikTok generates one when omitted. | | `edit_method` | string ("fix_size" | "only_gauss_pad" | "gauss_padding_reserve_score") | No | Image editing method. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### End a split test **Slug:** `TIKTOK_ADS_END_SPLIT_TEST` End an in-progress split test. This transition is irreversible. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_id` | string | Yes | Advertiser ID. | | `split_test_group_id` | string | Yes | Split test group ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Estimate audience size **Slug:** `TIKTOK_ADS_ESTIMATE_AD_AUDIENCE_SIZE` Estimate audience size for documented placement, promotion, and targeting settings. Availability may depend on account entitlement. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `app_id` | string | No | Promoted app ID; required for APP_PROMOTION. | | `gender` | string ("GENDER_FEMALE" | "GENDER_MALE" | "GENDER_UNLIMITED") | No | Target gender. | | `actions` | array | No | Behavior targeting objects. | | `isp_ids` | array | No | Internet service provider IDs. | | `pixel_id` | string | No | Pixel ID; provide with external_action when applicable. | | `languages` | array | No | Target language codes. | | `age_groups` | array | No | Target age groups. | | `catalog_id` | string | No | Catalog ID; required for PRODUCT_SALES. | | `placements` | array | No | Placements; required for selected placement. | | `carrier_ids` | array | No | Target carrier IDs. | | `zipcode_ids` | array | No | Target ZIP or postal code IDs. | | `audience_ids` | array | No | Included custom audience IDs. | | `location_ids` | array | No | Target location IDs. | | `advertiser_id` | string | Yes | Advertiser ID. | | `audience_rule` | object | No | Audience rule for TRAFFIC or WEB_CONVERSIONS. | | `audience_type` | string | No | App-retargeting audience type. | | `network_types` | array | No | Target connection types. | | `objective_type` | string | Yes | Advertising objective code. | | `placement_type` | string ("PLACEMENT_TYPE_AUTOMATIC" | "PLACEMENT_TYPE_NORMAL") | No | Placement type. | | `product_set_id` | string | No | Product set ID; 0 selects all product sets. | | `product_source` | string ("UNSET" | "CATALOG" | "STORE") | No | Product source; required for PRODUCT_SALES. | | `promotion_type` | string | No | Promotion type; required for PRODUCT_SALES. | | `spending_power` | string ("ALL" | "HIGH") | No | Target spending power. | | `ios14_targeting` | string ("UNSET" | "IOS14_MINUS" | "IOS14_PLUS") | No | iOS targeting mode. | | `min_ios_version` | string | No | Minimum iOS version. | | `device_model_ids` | array | No | Target device model IDs. | | `household_income` | array | No | Target household-income bands. | | `operating_systems` | array | No | Target operating system; at most one. | | `optimization_goal` | string | Yes | Optimization goal code. | | `contextual_tag_ids` | array | No | Contextual tag IDs. | | `device_price_ranges` | array | No | Device price range boundaries in multiples of 50. | | `min_android_version` | string | No | Minimum Android version. | | `targeting_expansion` | object | No | Deprecated targeting-expansion settings. | | `interest_keyword_ids` | array | No | Interest keyword IDs. | | `excluded_audience_ids` | array | No | Excluded custom audience IDs. | | `interest_category_ids` | array | No | Interest category IDs. | | `auto_targeting_enabled` | boolean | No | Deprecated automated-targeting switch. | | `blocked_pangle_app_ids` | array | No | Blocked Pangle app IDs. | | `excluded_custom_actions` | array | No | Excluded LAB3 audience actions. | | `included_custom_actions` | array | No | Included LAB3 audience actions. | | `catalog_authorized_bc_id` | string | No | Business Center ID for a Business Center catalog. | | `shopping_ads_retargeting_type` | string ("LAB1" | "LAB2" | "LAB3" | "OFF") | No | Shopping Ads retargeting type. | | `purchase_intention_keyword_ids` | array | No | Purchase-intention keyword IDs. | | `excluded_pangle_audience_package_ids` | array | No | Excluded Pangle audience package IDs. | | `included_pangle_audience_package_ids` | array | No | Included Pangle audience package IDs. | | `shopping_ads_retargeting_actions_days` | integer ("1" | "2" | "3" | "7" | "14" | "30" | "60" | "90" | "180") | No | Shopping retargeting lookback days. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get inventory estimates **Slug:** `TIKTOK_ADS_ESTIMATE_RF_INVENTORY` Get inventory estimates. Availability may depend on TikTok allowlisting or account entitlement. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `budget` | number | No | 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. | | `feed_type` | string ("STANDARD_FEED" | "TOP_FEED") | No | Feed type option. Enum values: `STANDARD_FEED`, `TOP_FEED`. `STANDARD_FEED` refers to large inventory with normal CPM price while `TOP_FEED`refers to limited inventory with higher CPM price. | | `frequency` | integer | Yes | 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_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. | | `advertiser_id` | string | Yes | Advertiser ID | | `audience_info` | object | Yes | Audience targeting rules | | `objective_type` | string | Yes | The advertising objective. Enum values: `RF_REACH`. | | `purchased_reach` | integer | No | 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. | | `rf_campaign_type` | string ("STANDARD" | "PULSE") | No | 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. | | `rf_purchased_type` | string ("FIXED_SHOW" | "FIXED_REACH" | "FIXED_BUDGET") | No | 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. | | `schedule_end_time` | string | Yes | 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`. | | `cpv_video_duration` | string ("SIX_SECONDS" | "TWO_SECONDS") | No | The target video view duration. Enum values: `SIX_SECONDS`, `TWO_SECONDS`. | | `frequency_schedule` | integer | Yes | 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. | | `schedule_start_time` | string | Yes | 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`. | | `purchased_impression` | integer | No | 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Generate Smart Text recommendations **Slug:** `TIKTOK_ADS_GENERATE_CREATIVE_SMART_TEXT` Generate Smart Text recommendations for an ad group. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Number of generated texts (1-20). | | `keywords` | array | No | Non-empty keywords; required for CUSTOMIZED parameters. | | `language` | string ("EN" | "JA" | "RU" | "VI") | No | Language; required for CUSTOMIZED parameters. | | `adgroup_id` | string | Yes | Ad group ID. | | `param_type` | string ("RECOMMENDED" | "CUSTOMIZED") | No | Whether TikTok predicts or the caller supplies parameters. | | `industry_id` | string | No | Industry ID. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Check the verification status of your account **Slug:** `TIKTOK_ADS_GET_ACCOUNT_VERIFICATION` Check the verification status of an ad account or Business Center. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | No | Business Center ID. Provide this or advertiser_id, but not both. | | `advertiser_id` | string | No | Ad account ID. Provide this or bc_id, but not both. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get available verification document types for a region **Slug:** `TIKTOK_ADS_GET_ACCOUNT_VERIFICATION_FILETYPE` Get available verification document types for a region. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `business_type` | string ("BUSINESS" | "INDIVIDUAL") | Yes | The verification type: BUSINESS or INDIVIDUAL. | | `region_iso_code` | string | Yes | Country or region code in ISO 3166 format, such as US. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Ad Benchmarks **Slug:** `TIKTOK_ADS_GET_AD_BENCHMARK_REPORT` Get one page of ad benchmark dimensions and dynamic numeric metrics, scoped by exactly one ad_ids, adgroup_ids, or campaign_ids filter. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Result page number. | | `filtering` | object | Yes | Exactly one ad, ad group, or campaign ID filter. | | `page_size` | integer | No | Results per page. | | `sort_type` | string | No | Provider-supported benchmark sort type; no fixed enum is verified. | | `dimensions` | array | Yes | Benchmark dimensions to return. Retained, provider-reported accepted examples are AD_CATEGORY, EXTERNAL_ACTION, LOCATION, and PLACEMENT; no complete enum has been independently verified. | | `sort_field` | string | No | Provider field name to sort by. No sort-field vocabulary is independently verified. | | `advertiser_id` | string | Yes | Advertiser account ID. | | `metrics_fields` | array | No | Provider field names for benchmark metrics to return as dynamic numeric values. No complete metric vocabulary is verified. | | `compare_time_window` | string | No | 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get additional interest categories by ID **Slug:** `TIKTOK_ADS_GET_ADDITIONAL_INTEREST_CATEGORIES` Get up to 50 additional interest categories by ID and language. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `filtering` | object | No | Audience-type filtering conditions. | | `advertiser_id` | string | Yes | Advertiser ID. | | `keyword_query` | array | Yes | Additional interest categories to retrieve (1-50). | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get diagnoses for ad groups **Slug:** `TIKTOK_ADS_GET_ADGROUP_DIAGNOSES` Get issue diagnoses and suggestions for selected ad groups. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `filtering` | object | No | Diagnosis filtering conditions. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get the dynamic quota on active ad groups **Slug:** `TIKTOK_ADS_GET_ADGROUP_QUOTA` Get the dynamic quota on active ad groups. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get review info of ad groups **Slug:** `TIKTOK_ADS_GET_ADGROUP_REVIEW` Get review info of ad groups. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `lang` | string | No | Language. | | `adgroup_ids` | array | Yes | The list of ad group IDs. Currently, we support a maximum of 20 ad group IDs in the request. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get estimated info of R&F ad groups **Slug:** `TIKTOK_ADS_GET_ADGROUP_RF_ESTIMATED` Get estimated info of R&F ad groups. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `adgroup_ids` | array | Yes | Ad group ids | | `advertiser_id` | string | Yes | Advertiser id | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get review info of ads **Slug:** `TIKTOK_ADS_GET_AD_REVIEW` Get review information for one to 100 ads. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `lang` | string | No | Language. | | `ad_ids` | array | Yes | Ad IDs to review (1-100). | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Advertiser Accounts **Slug:** `TIKTOK_ADS_GET_ADVERTISER_ACCOUNTS` Discover every advertiser account authorized for this connection when no IDs are supplied, or return full profile, status, timezone, and currency details for specified authorized advertiser IDs. Discovery first uses advertiser IDs stored with the OAuth token and only falls back to securely injected app credentials. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `fields` | array | No | Advertiser information fields to return; omit for TikTok's default field set. | | `advertiser_ids` | array | No | Authorized advertiser account IDs whose full profiles to retrieve. Omit to discover every advertiser account authorized for this connection. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get info of an app **Slug:** `TIKTOK_ADS_GET_APP` Get information about a mobile app configured for an advertiser. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `app_id` | string | Yes | App ID. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get App Conversion Events **Slug:** `TIKTOK_ADS_GET_APP_OPTIMIZATION_EVENT` Get app conversion events available for advertising optimization. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `app_id` | string | Yes | App ID. | | `is_skan` | boolean | No | Whether the app uses SKAdNetwork features. | | `objective` | string | No | Advertising objective. | | `placement` | array | No | Apps where ads will be delivered; conditionally required for normal placement. | | `advertiser_id` | string | Yes | Advertiser ID. | | `available_only` | boolean | No | Whether to return only available conversion events. | | `placement_type` | string | No | Placement strategy: PLACEMENT_TYPE_AUTOMATIC or PLACEMENT_TYPE_NORMAL. | | `optimization_goal` | string | Yes | Optimization goal. | | `app_promotion_type` | string | No | App promotion type, conditionally required for app-promotion objectives. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get App Retargeting Events **Slug:** `TIKTOK_ADS_GET_APP_OPTIMIZATION_EVENT_RETARGETING` Get app retargeting events available for audience rules. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `app_id` | string | Yes | App ID. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Asset Binding Quota **Slug:** `TIKTOK_ADS_GET_ASSET_BINDING_QUOTA` Get advertiser binding quota usage for a TikTok identity asset. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `asset_id` | string | Yes | Identity asset ID whose binding quota to retrieve. | | `asset_type` | string | Yes | Asset type. TikTok currently supports only IDENTITY. | | `advertiser_id` | string | Yes | Advertiser ID whose asset binding quota to retrieve. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Details of Audience Overlap **Slug:** `TIKTOK_ADS_GET_AUDIENCE_INSIGHT` Get overlap details for a benchmark custom audience and up to four comparison audiences. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_id` | string | Yes | Advertiser ID. | | `benchmark_custom_audience_id` | string | Yes | Accessible custom audience ID used as the benchmark. | | `comparison_custom_audience_ids` | array | No | Accessible comparison audience IDs (maximum 4). | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Audience Insights **Slug:** `TIKTOK_ADS_GET_AUDIENCE_INSIGHTS` Get one audience insight dimension for locations or a custom audience. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `locations` | array | No | Locations (maximum 5); mutually exclusive with custom_audience_id. | | `dimensions` | array | Yes | Single response dimension. | | `advertiser_id` | string | Yes | Advertiser ID. | | `selected_audience` | object | No | Audience targeting filters. | | `custom_audience_id` | string | No | Custom audience ID; mutually exclusive with locations and selected_audience. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get assets as admin **Slug:** `TIKTOK_ADS_GET_BC_ASSET_ADMIN` Get one page of assets administered by a Business Center. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial page number. | | `bc_id` | string | Yes | Business Center ID. | | `filtering` | object | No | Optional structured asset filtering conditions. | | `page_size` | integer | No | Assets per page (1-50). | | `asset_type` | string ("ADVERTISER" | "CATALOG" | "TIKTOK_SHOP" | "PIXEL" | "LEAD" | "TT_ACCOUNT" | "MANAGED_BUSINESS_ACCOUNT") | Yes | Asset type: ADVERTISER, CATALOG, TIKTOK_SHOP, PIXEL, LEAD, TT_ACCOUNT, or MANAGED_BUSINESS_ACCOUNT. | | `child_bc_id` | string | No | Optional child Business Center ID. | | `next_cursor` | string | No | Opaque continuation token from a previous response; resend the same filtering object when continuing a filtered listing. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get members by an asset **Slug:** `TIKTOK_ADS_GET_BC_ASSET_MEMBER` Get one page of Business Center members assigned to an asset. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial page number. | | `bc_id` | string | Yes | Business Center ID. | | `asset_id` | string | Yes | Asset ID whose assigned members to return. | | `filtering` | object | No | Optional member filtering conditions. | | `page_size` | integer | No | Members per page (1-20). | | `asset_type` | string ("ADVERTISER" | "CATALOG" | "LEAD" | "MANAGED_BUSINESS_ACCOUNT") | Yes | Asset type for advertiser, catalog, lead, or managed business account. | | `next_cursor` | string | No | Opaque continuation token from a previous response; resend the same filtering object when continuing a filtered listing. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get the invoices of a Business Center **Slug:** `TIKTOK_ADS_GET_BC_INVOICE` Return one page of Business Center invoices using documented type, payment, title, ID, and issuance-time filters. This exposes finance-sensitive invoice, tax, address, and balance data; confirm the Business Center and restrict the result to authorized recipients. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial page number. | | `bc_id` | string | Yes | Business Center ID. | | `end_time` | string | No | Invoice issuance range end in YYYY-MM-DD HH:MM:SS format; provide with start_time. | | `page_size` | integer | No | Invoices per page (1-50). | | `invoice_id` | string | No | Invoice ID filter. | | `start_time` | string | No | Invoice issuance range start in YYYY-MM-DD HH:MM:SS format; provide with end_time. | | `next_cursor` | string | No | Opaque continuation token returned by a previous call. | | `pay_statuses` | array | No | Payment statuses to include. | | `invoice_title` | string | No | Invoice title filter. | | `invoice_types` | array | Yes | Invoice types to return. AUTO_PAY must be the only value when used; other supported values are RECON and CREDIT. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get an asynchronous invoice download task **Slug:** `TIKTOK_ADS_GET_BC_INVOICE_TASK` Get one asynchronous invoice download task and return its documented status and download URL. Use DOWNLOAD_BC_INVOICE for the synchronous invoice file. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `task_id` | string | Yes | Asynchronous invoice download task ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get the unpaid amount of a Business Center **Slug:** `TIKTOK_ADS_GET_BC_INVOICE_UNPAID` Read 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `invoice_type` | string | Yes | Invoice type. TikTok supports RECON for reconciliation invoices. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get the assets of a partner **Slug:** `TIKTOK_ADS_GET_BC_PARTNER_ASSET` Get one page of assets shared with or by a partner Business Center. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial page number. | | `bc_id` | string | Yes | Business Center ID. | | `filtering` | object | No | Optional partner-asset filtering conditions. | | `page_size` | integer | No | Assets per page (1-50). | | `asset_type` | string ("ADVERTISER" | "CATALOG") | Yes | Partner asset type. | | `partner_id` | string | Yes | Partner Business Center ID. | | `share_type` | string ("SHARED" | "SHARING") | Yes | Share direction: shared with this BC or shared by this BC. | | `next_cursor` | string | No | Opaque continuation token from a previous response; resend the same filtering object when continuing a filtered listing. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Bid Protection Details **Slug:** `TIKTOK_ADS_GET_BID_PROTECTION_DETAILS` Get bid protection history for campaigns or ad groups over a date range. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `end_date` | string | Yes | Inclusive end date in YYYY-MM-DD format. | | `query_ids` | array | Yes | 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. | | `data_level` | string ("CAMPAIGN" | "ADGROUP") | Yes | Level of the requested bid protection history. | | `start_date` | string | Yes | Inclusive start date in YYYY-MM-DD format. | | `advertiser_id` | string | Yes | Authorized advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Bid Protection Statuses **Slug:** `TIKTOK_ADS_GET_BID_PROTECTION_STATUSES` Get bid protection statuses for up to 200 campaigns or ad groups. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `query_ids` | array | Yes | One to 200 campaign or ad group IDs belonging to advertiser_id. | | `data_level` | string ("CAMPAIGN" | "ADGROUP") | Yes | Level of the requested bid protection statuses. | | `advertiser_id` | string | Yes | Authorized advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get the authorization status of a Brand Safety partner **Slug:** `TIKTOK_ADS_GET_BRAND_SAFETY_PARTNER_AUTHORIZATION_STATUS` Get a Brand Safety measurement partner's authorization status. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `partner` | string | No | Brand Safety post-bid measurement partner. The supported value is `Zefr`. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Business Center Advertiser Attributes **Slug:** `TIKTOK_ADS_GET_BUSINESS_CENTER_ADVERTISER_ATTRIBUTES` Get currencies and registration regions available when creating ad accounts in a Business Center. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `business_center_id` | string | Yes | Business Center ID whose supported advertiser attributes to retrieve. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Business Center Asset Group **Slug:** `TIKTOK_ADS_GET_BUSINESS_CENTER_ASSET_GROUP` Get the assets or members of an Asset Group in a Business Center. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial result page to retrieve (1 or greater). | | `bc_id` | string | Yes | Business Center ID containing the Asset Group. | | `keyword` | string | No | Optional keyword passed in TikTok's structured filtering object for the requested ASSET or MEMBER collection. | | `page_size` | integer | No | Number of assets or members to return in this page (1 or greater). | | `next_cursor` | string | No | Opaque continuation token returned by a previous call; omit for the first page and pass it back unchanged for the next page. | | `query_entity` | string ("ASSET" | "MEMBER") | Yes | Entity collection to retrieve: ASSET or MEMBER. | | `asset_group_id` | string | Yes | Asset Group ID whose assets or members to retrieve. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Business Center Balance **Slug:** `TIKTOK_ADS_GET_BUSINESS_CENTER_BALANCE` Read the balance of a TikTok Business Center or Payment Portfolio. This action only retrieves financial information and never funds an account. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID whose balance to retrieve. | | `payment_portfolio_id` | string | No | 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. | | `child_business_center_id` | string | No | 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Campaign Quota Information **Slug:** `TIKTOK_ADS_GET_CAMPAIGN_QUOTA_INFO` Get SKAN Dedicated Campaign quota information by ad network. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `app_id` | string | Yes | SKAN 4.0 app ID whose campaign quota to retrieve. | | `adgroup_id` | string | No | Optional ID of an ad group within a SKAN 4 campaign. | | `campaign_id` | string | No | Optional SKAN campaign ID for campaign-specific quota information. | | `advertiser_id` | string | Yes | Advertiser account ID whose SKAN campaign quota to retrieve. | | `has_advertiser_quota` | boolean | No | Whether to include advertiser-level campaign quota information. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get available regions **Slug:** `TIKTOK_ADS_GET_CATALOG_AVAILABLE_COUNTRY` Get regions where ads for catalogs in a Business Center can be delivered. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Catalog Category Insights **Slug:** `TIKTOK_ADS_GET_CATALOG_CATEGORY_INSIGHTS` Get up to 50 top trending product categories and availability metrics for an eligible E-commerce catalog, optionally filtered by category IDs. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `filtering` | object | No | Optional category filter. Obtain category IDs from the filter endpoint. | | `catalog_id` | string | Yes | Eligible E-commerce catalog ID containing at least 20 products. | | `business_center_id` | string | Yes | Business Center ID that owns the eligible E-commerce catalog. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get event source binding info of a catalog **Slug:** `TIKTOK_ADS_GET_CATALOG_EVENTSOURCE_BIND` Get apps and pixels bound as event sources to a catalog. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `catalog_id` | string | Yes | Catalog ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get feeds **Slug:** `TIKTOK_ADS_GET_CATALOG_FEED` Get all feeds in a catalog or one feed by ID. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `feed_id` | string | No | Feed ID to return. Omit to return every feed in the catalog. | | `catalog_id` | string | Yes | Catalog ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get the log of a feed **Slug:** `TIKTOK_ADS_GET_CATALOG_FEED_LOG` Get processing log entries for a catalog feed. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `feed_id` | string | Yes | Feed ID whose log to return. | | `catalog_id` | string | Yes | Catalog ID. | | `context_info` | string | No | Optional provider context value. Pass the provider-issued string unchanged. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Catalog Insight Filters **Slug:** `TIKTOK_ADS_GET_CATALOG_INSIGHT_FILTERS` Get 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Result page to request. TikTok returns no pagination metadata. | | `page_size` | integer | No | Filter values to request (1-200); TikTok suggests 50 for a complete set. | | `catalog_id` | string | Yes | Eligible E-commerce catalog ID containing at least 20 products. | | `filter_type` | string ("CATEGORY_ID" | "BRAND" | "AVAILABILITY") | Yes | Filter values to retrieve: category IDs, brands, or availability values. | | `business_center_id` | string | Yes | Business Center ID that owns the eligible E-commerce catalog. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get the lexicon list for a catalog **Slug:** `TIKTOK_ADS_GET_CATALOG_LEXICON` Get the provider-defined lexicon list for a catalog. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `catalog_id` | string | Yes | Catalog ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get locations and currencies **Slug:** `TIKTOK_ADS_GET_CATALOG_LOCATION_CURRENCY` Get supported country or region and currency combinations for catalogs. #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get the overview of a catalog **Slug:** `TIKTOK_ADS_GET_CATALOG_OVERVIEW` Get product audit totals for a catalog. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `catalog_id` | string | Yes | Catalog ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get products **Slug:** `TIKTOK_ADS_GET_CATALOG_PRODUCT` Get one page of catalog products with optional IDs, filters, and ordering. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial provider page number. | | `bc_id` | string | Yes | Business Center ID. | | `order` | object | No | Product ordering settings. Encoded as TikTok's JSON query object. | | `sku_ids` | array | No | SKU IDs to retrieve (up to 1,000). | | `page_size` | integer | No | Products per page (1-500). | | `catalog_id` | string | Yes | Catalog ID. | | `conditions` | object | No | Product filtering conditions. Encoded as TikTok's JSON query object. | | `series_ids` | array | No | Short-drama series IDs to retrieve (up to 1,000). | | `next_cursor` | string | No | Opaque continuation token from a previous call; omit for the first page. | | `product_ids` | array | No | Product IDs to retrieve (up to 1,000). | | `product_set_ids` | array | No | Product set IDs to retrieve (up to 100). | | `product_available_type` | string ("AVAILABLE" | "ALL") | No | Return ad-available products or all products. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Catalog Product Diagnostic Task **Slug:** `TIKTOK_ADS_GET_CATALOG_PRODUCT_DIAGNOSTIC_TASK` Get an asynchronous catalog product diagnostic task result. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID that owns the catalog. | | `task_id` | string | Yes | Catalog product diagnostic task ID. | | `catalog_id` | string | Yes | Catalog ID associated with the task. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get the product handling log **Slug:** `TIKTOK_ADS_GET_CATALOG_PRODUCT_LOG` Get processing counts, errors, warnings, and downloads for a product handling task. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `language` | string ("en" | "zh-CN" | "ja-JP" | "de" | "es" | "fr" | "hi-IN" | "id" | "it" | "ko" | "ms" | "ru" | "th" | "tr" | "vi") | No | Language for log messages. | | `catalog_id` | string | Yes | Catalog ID. | | `feed_log_id` | string | Yes | Product handling log ID. | | `context_info` | string | No | Optional provider context value; pass it unchanged. | | `advertiser_id` | string | No | Optional advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get product sets **Slug:** `TIKTOK_ADS_GET_CATALOG_SET` Get all product sets in a catalog or one product set by ID. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `catalog_id` | string | Yes | Catalog ID whose product sets to return. | | `product_set_id` | string | No | Optional product set ID. | | `return_product_count` | boolean | No | Whether to calculate and return each set's product count. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get products in a product set **Slug:** `TIKTOK_ADS_GET_CATALOG_SET_PRODUCT` Get one page of products in a catalog product set. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial provider page number. | | `bc_id` | string | Yes | Business Center ID. | | `page_size` | integer | No | Products per page (1-100). | | `catalog_id` | string | Yes | Catalog ID. | | `next_cursor` | string | No | Opaque continuation token; omit for the first page. | | `product_set_id` | string | Yes | Product set ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get the catalog video handling log **Slug:** `TIKTOK_ADS_GET_CATALOG_VIDEO_LOG` Get processing counts, errors, warnings, and downloads for a catalog video task. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `language` | string ("en" | "zh-CN" | "ja-JP" | "de" | "es" | "fr" | "hi-IN" | "id" | "it" | "ko" | "ms" | "ru" | "th" | "tr" | "vi") | No | Language for log messages. | | `catalog_id` | string | Yes | Catalog ID. | | `feed_log_id` | string | Yes | Catalog video handling log ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get video packages **Slug:** `TIKTOK_ADS_GET_CATALOG_VIDEO_PACKAGE` Get catalog video packages, optionally restricted to one package ID. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `catalog_id` | string | Yes | Catalog ID. | | `shopping_ads_video_package_id` | string | No | Optional catalog video package ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get related comments **Slug:** `TIKTOK_ADS_GET_COMMENT_REFERENCE` Read one page of comments related to a specific TikTok comment and return an opaque continuation cursor. This action does not alter moderation state. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `app` | string | No | App source; only `TIKTOK` is supported. | | `page` | integer | No | Initial page number. | | `page_size` | integer | No | Page size (1-100). | | `comment_id` | string | Yes | Comment ID whose related comments to read. | | `next_cursor` | string | No | Opaque continuation token; omit for the first page. | | `comment_type` | string ("COMMENT" | "REPLY") | Yes | Comment type: `COMMENT` or `REPLY`. | | `advertiser_id` | string | Yes | Advertiser ID. | | `original_comment_id` | string | No | Original comment ID, used for replies. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get details of content exclusion categories **Slug:** `TIKTOK_ADS_GET_CONTENT_EXCLUSION_CATEGORY_DETAILS` Get details for content exclusion or vertical sensitivity category IDs. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `category_ids` | array | Yes | Content exclusion or vertical sensitivity category IDs. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get details of contextual tags **Slug:** `TIKTOK_ADS_GET_CONTEXTUAL_TAG_DETAILS` Get details for specified contextual tag IDs. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_id` | string | Yes | Advertiser ID. | | `contextual_tag_ids` | array | Yes | Contextual tag IDs to retrieve. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Creative Assets **Slug:** `TIKTOK_ADS_GET_CREATIVE_ASSETS` Return metadata for specified video or image assets in an authorized advertiser's Ads Asset Library. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `asset_ids` | array | Yes | Video or image asset IDs to retrieve. Video requests support at most 60 IDs; image requests support at most 100 IDs. | | `asset_type` | string ("VIDEO" | "IMAGE") | Yes | Type of Ads Asset Library asset to retrieve. | | `advertiser_id` | string | Yes | Authorized advertiser account ID that owns or can access the assets. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get a portfolio by ID **Slug:** `TIKTOK_ADS_GET_CREATIVE_PORTFOLIO` Get a creative portfolio by ID. Availability may depend on TikTok entitlement. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_id` | string | Yes | Advertiser ID. | | `creative_portfolio_id` | string | Yes | Creative portfolio ID returned by portfolio creation. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Creative Pre-Review Task **Slug:** `TIKTOK_ADS_GET_CREATIVE_PRE_REVIEW_TASK` Get the result of a creative pre-review task. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `task_id` | string | Yes | Creative pre-review task ID to retrieve. | | `advertiser_id` | string | Yes | Advertiser account ID that owns the creative pre-review task. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get creative report **Slug:** `TIKTOK_ADS_GET_CREATIVE_REPORT` Return one page of creative material performance with exact JSON-encoded filter and field-selection query parameters. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial provider page. | | `end_date` | string | No | Inclusive end date in advertiser time zone. | | `lifetime` | boolean | No | Query lifetime data instead of a date range. | | `filtering` | object | No | Creative filtering object, JSON-encoded into the query. | | `page_size` | integer | No | Rows per page (1-1000). | | `sort_type` | string ("ASC" | "DESC") | No | Sort order. | | `sort_field` | string | No | Creation-time or metric field used for sorting. | | `start_date` | string | No | Inclusive start date in advertiser time zone. | | `info_fields` | array | No | Documented creative information field names. | | `next_cursor` | string | No | Opaque continuation token from a previous response. | | `advertiser_id` | string | Yes | Advertiser ID. | | `material_type` | string ("VIDEO" | "IMAGE" | "INSTANT_PAGE") | Yes | Creative material type. | | `metrics_fields` | array | No | Documented creative metric or dimension field names. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get the message event sets for ad creation **Slug:** `TIKTOK_ADS_GET_CTM_MESSAGE_EVENT_SET` Get message event sets available for instant-messaging ad creation. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_id` | string | Yes | Advertiser ID. | | `message_event_name` | string | No | Exact message event set name to filter by. | | `messaging_app_type` | string ("MESSENGER" | "WHATSAPP" | "ZALO") | Yes | Instant messaging app type. | | `message_event_set_ids` | array | No | Message event set IDs to filter by, with at most 10 IDs. | | `messaging_app_account_id` | string | Yes | Messaging account ID, phone number, Facebook Page ID, or Zalo account ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Custom Audience Details **Slug:** `TIKTOK_ADS_GET_CUSTOM_AUDIENCE_DETAILS` Get current status and modification history for specified owned or shared custom audiences. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `history_size` | integer | No | Maximum number of modification-history entries to request (1-100). | | `advertiser_id` | string | Yes | Authorized advertiser account ID whose audiences to read. | | `custom_audience_ids` | array | Yes | Audience IDs whose details to return (1-100). | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Custom Audience Sharing Log **Slug:** `TIKTOK_ADS_GET_CUSTOM_AUDIENCE_SHARING_LOG` Get the advertisers with which a specific TikTok custom audience has been shared, including each sharing status. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_id` | string | Yes | Advertiser ID that owns the custom audience. | | `custom_audience_id` | string | Yes | Custom audience ID whose sharing log to retrieve. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get the details of a Custom Conversion **Slug:** `TIKTOK_ADS_GET_CUSTOM_CONVERSION` Get one Custom Conversion configured for a Pixel or app event source. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_id` | string | Yes | Advertiser ID. | | `event_source_id` | string | Yes | Pixel ID or SAN app platform ID matching event_source_type. | | `event_source_type` | string ("PIXEL" | "APP") | Yes | PIXEL or APP event source. | | `custom_conversion_id` | string | Yes | Custom Conversion ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get catalog event source diagnostic information **Slug:** `TIKTOK_ADS_GET_DIAGNOSTIC_CATALOG_EVENTSOURCE_ISSUE` Get detected catalog app or pixel event source issues and suggested solutions. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `app_id` | string | No | Required for an APP event source. | | `catalog_id` | string | Yes | Catalog ID. | | `event_type` | string ("VIEW_CONTENT" | "ADD_TO_CART" | "PURCHASE") | No | Event type to diagnose. | | `pixel_code` | string | No | Required for a PIXEL event source. | | `time_range` | string ("YESTERDAY" | "LAST_7_DAYS" | "LAST_30_DAYS") | No | Diagnostic time range. | | `event_source_type` | string ("PIXEL" | "APP") | Yes | App or pixel event source. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get catalog event trends and match rate **Slug:** `TIKTOK_ADS_GET_DIAGNOSTIC_CATALOG_EVENTSOURCE_METRIC` Get daily app or pixel event trends and catalog content-ID match rates. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `app_id` | string | No | Required for an APP event source. | | `catalog_id` | string | Yes | Catalog ID. | | `event_type` | string ("VIEW_CONTENT" | "ADD_TO_CART" | "PURCHASE") | No | Event type to measure. | | `pixel_code` | string | No | Required for a PIXEL event source. | | `time_range` | string ("YESTERDAY" | "LAST_7_DAYS" | "LAST_30_DAYS") | No | Metric time range. | | `event_source_type` | string ("PIXEL" | "APP") | Yes | App or pixel event source. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get the Application Log of Audiences **Slug:** `TIKTOK_ADS_GET_DMP_CUSTOM_AUDIENCE_APPLY_LOG` Return one page of audience application history. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial page number. | | `timezone` | string | No | Timezone for returned timestamps; defaults to UTC. | | `page_size` | integer | No | Results per page. | | `next_cursor` | string | No | Opaque cursor from the previous page. | | `advertiser_id` | string | Yes | Advertiser ID that owns the audiences. | | `custom_audience_ids` | array | Yes | Owned custom audience IDs. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get the music list **Slug:** `TIKTOK_ADS_GET_FILE_MUSIC` Get one page of advertiser music and return a continuation cursor. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial provider page. | | `filtering` | object | No | Music search filters. Resubmit this value with a continuation cursor. | | `page_size` | integer | No | Music entries per page; some search modes allow at most 200. | | `music_scene` | string ("CREATIVE_ASSET" | "CAROUSEL_ADS" | "CATALOG_CAROUSEL") | No | Scenario where the music will be used. | | `next_cursor` | string | No | Opaque continuation token from a previous call. | | `search_type` | string ("SEARCH_BY_KEYWORD" | "SEARCH_BY_RECOMMEND" | "SEARCH_BY_LIKED" | "SEARCH_BY_HISTORY" | "SEARCH_BY_MUSIC_ID" | "SEARCH_BY_SOURCE") | No | Music search mode for Carousel Ads or catalog carousel music. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get suggested thumbnails for a video **Slug:** `TIKTOK_ADS_GET_FILE_VIDEO_SUGGESTCOVER` Get up to ten suggested thumbnail images for an advertiser video. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `video_id` | string | Yes | Video ID. | | `advertiser_id` | string | Yes | Advertiser ID. | | `poster_number` | integer | No | Number of cover candidates (1-10). | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get GMV Max Bid Recommendation **Slug:** `TIKTOK_ADS_GET_GMV_MAX_BID_RECOMMENDATION` Get TikTok's recommended GMV Max bid for an eligible advertiser and shop. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `store_id` | string | Yes | TikTok Shop store ID used for the recommendation. | | `identity_id` | string | No | Optional TikTok identity ID used for the recommendation. | | `advertiser_id` | string | Yes | Authorized advertiser account ID. | | `item_group_ids` | array | No | Optional item group IDs included in the recommendation (1-50). | | `optimization_goal` | string | Yes | Optimization goal; the official contract supports VALUE. | | `shopping_ads_type` | string ("LIVE" | "PRODUCT") | Yes | GMV Max shopping ads type: LIVE or PRODUCT. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get GMV Max Campaigns **Slug:** `TIKTOK_ADS_GET_GMV_MAX_CAMPAIGN` Get one page of GMV Max campaigns. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial page number. | | `fields` | array | No | Campaign fields to return; omit to return all fields. | | `filtering` | object | Yes | Filters on the GMV Max campaigns. | | `page_size` | integer | No | Page size (1-100). | | `next_cursor` | string | No | Opaque continuation token from a previous response. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get GMV Max Campaign Info **Slug:** `TIKTOK_ADS_GET_GMV_MAX_CAMPAIGN_INFO` Get information for one GMV Max campaign owned by an authorized advertiser. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `campaign_id` | string | Yes | GMV Max campaign ID to retrieve. | | `advertiser_id` | string | Yes | Authorized advertiser account ID that owns the GMV Max campaign. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get GMV Max Sessions **Slug:** `TIKTOK_ADS_GET_GMV_MAX_CAMPAIGN_SESSIONS` Get 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `session_ids` | array | Yes | 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. | | `advertiser_id` | string | Yes | Authorized advertiser account ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get GMV Max Exclusive Authorization **Slug:** `TIKTOK_ADS_GET_GMV_MAX_EXCLUSIVE_AUTHORIZATION` Get an advertiser account's exclusive authorization status for a TikTok Shop. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `store_id` | string | Yes | TikTok Shop store ID to check. | | `advertiser_id` | string | Yes | Advertiser account ID whose exclusive authorization to check. | | `store_authorized_bc_id` | string | Yes | Business Center ID authorized for the TikTok Shop. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get GMV Max Report **Slug:** `TIKTOK_ADS_GET_GMV_MAX_REPORT` Run one paginated Product or LIVE GMV Max campaign report. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial result page. | | `metrics` | array | Yes | Current official GMV Max metric identifiers. Compatibility varies for all, Product, creative, duration, and LIVE report families. | | `end_date` | string | Yes | Inclusive end date in YYYY-MM-DD, in the ad-account time zone. | | `filtering` | object | No | Documented GMV Max report filters. | | `page_size` | integer | No | Rows in this page (1-1000). | | `sort_type` | string ("ASC" | "DESC") | No | Sort order. | | `store_ids` | array | Yes | Exactly one GMV-Max-eligible TikTok Shop ID. | | `dimensions` | array | Yes | One to three GMV Max report dimensions. | | `sort_field` | 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") | No | Supported Product or LIVE report metric to sort by. | | `start_date` | string | Yes | Inclusive start date in YYYY-MM-DD, in the ad-account time zone. | | `next_cursor` | string | No | Opaque continuation token from a previous response; omit for the first page. | | `advertiser_id` | string | Yes | Authorized advertiser ID. | | `enable_total_metrics` | boolean | No | Return aggregate metrics across all matching pages. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get product linkage details of videos in customized posts **Slug:** `TIKTOK_ADS_GET_GMV_MAX_VIDEO_PRODUCT_LINKS` Get product linkage details of videos in customized posts. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `item_ids` | array | Yes | TikTok video IDs (maximum 20). | | `store_id` | string | Yes | TikTok Shop ID. | | `campaign_id` | string | No | Product GMV Max campaign ID when videos are used in campaign-level posts. | | `advertiser_id` | string | Yes | Advertiser ID. | | `store_authorized_bc_id` | string | Yes | Business Center ID authorized to access the TikTok Shop. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get the Identity List **Slug:** `TIKTOK_ADS_GET_IDENTITY_GET` Return 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial provider page number. | | `filtering` | object | No | Customized-identity filtering, valid only when identity_type is CUSTOMIZED_USER or omitted. | | `page_size` | integer | No | Identities to return per page (1-100). | | `next_cursor` | string | No | Opaque continuation cursor from a previous response; omit for the first page and repeat the same filtering value when continuing. | | `advertiser_id` | string | Yes | Advertiser ID. | | `identity_type` | string ("CUSTOMIZED_USER" | "AUTH_CODE" | "TT_USER" | "BC_AUTH_TT") | No | Identity type; omit to return all identity types. | | `identity_authorized_bc_id` | string | No | Business Center ID; required when identity_type is BC_AUTH_TT. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Info About an Identity **Slug:** `TIKTOK_ADS_GET_IDENTITY_INFO` Get 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `identity_id` | string | Yes | Identity ID. | | `advertiser_id` | string | Yes | Advertiser ID. | | `identity_type` | string ("CUSTOMIZED_USER" | "AUTH_CODE" | "TT_USER" | "BC_AUTH_TT") | Yes | Identity type. | | `identity_authorized_bc_id` | string | No | Business Center ID; required when identity_type is BC_AUTH_TT. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Live Videos Under an Identity **Slug:** `TIKTOK_ADS_GET_IDENTITY_LIVE` Return 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `identity_id` | string | Yes | TikTok account identity ID. | | `next_cursor` | string | No | Opaque timestamp cursor from the previous response; omit for the first page. | | `advertiser_id` | string | Yes | Advertiser ID. | | `identity_type` | string ("TT_USER" | "BC_AUTH_TT") | Yes | Identity type: TT_USER or BC_AUTH_TT. | | `identity_authorized_bc_id` | string | No | Business Center ID; required for BC_AUTH_TT. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List Available TikTok Series **Slug:** `TIKTOK_ADS_GET_IDENTITY_NATIVE_SERIES` Return 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `count` | integer | No | Maximum Series to return on this page (1-100). | | `identity_id` | string | Yes | TikTok account identity ID whose promotable Series to retrieve. | | `next_cursor` | string | No | Opaque continuation cursor from the previous page; omit for the first page. | | `advertiser_id` | string | Yes | Advertiser ID. | | `identity_type` | string ("TT_USER" | "BC_AUTH_TT") | Yes | Identity type: TT_USER or BC_AUTH_TT. | | `identity_authorized_bc_id` | string | No | Business Center ID; required when identity_type is BC_AUTH_TT. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Posts Under an Identity **Slug:** `TIKTOK_ADS_GET_IDENTITY_VIDEO_GET` Return 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `count` | integer | No | Posts to return (1-20). | | `keyword` | string | No | Post text or exact post ID search; valid only for AUTH_CODE identities. | | `item_type` | string ("VIDEO" | "CAROUSEL") | No | Post type: VIDEO or CAROUSEL. | | `identity_id` | string | Yes | Authorized identity ID. | | `next_cursor` | string | No | Opaque provider cursor from the previous page; omit for the first page. | | `advertiser_id` | string | Yes | Advertiser ID. | | `identity_type` | string ("AUTH_CODE" | "TT_USER" | "BC_AUTH_TT") | Yes | Identity type: AUTH_CODE, TT_USER, or BC_AUTH_TT. | | `exclude_adsonly` | boolean | No | Exclude ads-only posts; true returns at most the 500 most recent organic posts. | | `identity_authorized_bc_id` | string | No | Business Center ID; required for BC_AUTH_TT. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Info About TikTok Posts **Slug:** `TIKTOK_ADS_GET_IDENTITY_VIDEO_INFO` Get 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `item_id` | string | No | One post ID; mutually exclusive with item_ids. | | `item_ids` | array | No | One to 20 post IDs; mutually exclusive with item_id. | | `identity_id` | string | Yes | Identity ID associated with the requested posts. | | `advertiser_id` | string | Yes | Advertiser ID. | | `identity_type` | string ("AUTH_CODE" | "TT_USER" | "BC_AUTH_TT") | Yes | Identity type: AUTH_CODE, TT_USER, or BC_AUTH_TT. | | `identity_authorized_bc_id` | string | No | Business Center ID; required for BC_AUTH_TT. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get an Instant Form or Direct-Message Lead **Slug:** `TIKTOK_ADS_GET_LEAD` Retrieve 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page_id` | string | No | Instant Form page ID; required for INSTANT_FORM and unsupported for DIRECT_MESSAGE. | | `library_id` | string | No | Form-library ID when the lead belongs to a Business Center library. | | `lead_source` | string ("INSTANT_FORM" | "DIRECT_MESSAGE") | Yes | Lead source: INSTANT_FORM or DIRECT_MESSAGE. | | `advertiser_id` | string | No | Advertiser ID when the lead belongs to an ad account. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Lead Fields **Slug:** `TIKTOK_ADS_GET_LEAD_FIELD` Retrieve 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page_id` | string | No | Instant Form page ID; required for INSTANT_FORM and unsupported for DIRECT_MESSAGE. | | `library_id` | string | No | Form-library ID when leads belong to a Business Center library. | | `lead_source` | string ("INSTANT_FORM" | "DIRECT_MESSAGE") | Yes | Lead source: INSTANT_FORM or DIRECT_MESSAGE. | | `advertiser_id` | string | No | Advertiser ID when leads belong to an ad account. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get the TikTok Minis within an ad account **Slug:** `TIKTOK_ADS_GET_MINIS` Get one page of TikTok Minis within an ad account. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial page number. | | `page_size` | integer | No | Page size (1-50). | | `next_cursor` | string | No | Opaque continuation token from a previous response. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get MMM Download URL **Slug:** `TIKTOK_ADS_GET_MMM_DOWNLOAD_URL` Obtain 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `mmm_request_id` | string | Yes | Completed MMM request ID whose compressed CSV URL to obtain. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get MMM Request History **Slug:** `TIKTOK_ADS_GET_MMM_REQUEST_HISTORY` Retrieve 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `end_date` | string | Yes | Inclusive history end date in YYYY-MM-DD format, interpreted in UTC+0. | | `from_date` | string | Yes | Inclusive history start date in YYYY-MM-DD format, interpreted in UTC+0. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Offline Event Sets **Slug:** `TIKTOK_ADS_GET_OFFLINE` List Offline Event Set configurations; this management endpoint does not ingest offline events. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | No | Offline Event Set name to match. | | `advertiser_id` | string | No | Advertiser ID. | | `event_set_ids` | array | No | Offline Event Set IDs to match. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get rules by ID **Slug:** `TIKTOK_ADS_GET_OPTIMIZER_RULE` Get automated optimizer rules by ID. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `rule_ids` | array | Yes | IDs of the rules to retrieve. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get result details **Slug:** `TIKTOK_ADS_GET_OPTIMIZER_RULE_RESULT` Get automated optimizer rule result details. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `lang` | string ("ZH" | "EN" | "JA") | No | Language of execution results. | | `advertiser_id` | string | Yes | Advertiser ID. | | `result_detail` | array | Yes | Result references containing rule execution IDs and rule IDs. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Instant Pages **Slug:** `TIKTOK_ADS_GET_PAGE` Return one page of Instant Forms and other TikTok Instant Page types. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial provider page number. | | `title` | string | No | Exact page-title filter. | | `status` | string ("EDITED" | "PUBLISHED") | No | Instant Page status filter. | | `page_size` | integer | No | Results per page (1-100). | | `library_id` | string | No | Form library ID; mutually exclusive with advertiser_id. | | `next_cursor` | string | No | Opaque continuation token from a previous response. | | `advertiser_id` | string | No | Advertiser ID; mutually exclusive with library_id. | | `business_type` | string ("LEAD_GEN" | "STORE_FRONT" | "APP_PROFILE_PAGE" | "TIKTOK_INSTANT_PAGE" | "SHOP_ADS_PLP" | "SHOP_ADS_PDP" | "POP_UP_FORM") | No | Single page type; ignored when business_types is set. | | `business_types` | array | No | Page types to include. | | `update_time_range` | object | No | Page update-time range filter. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get the fields of an Instant Form **Slug:** `TIKTOK_ADS_GET_PAGE_FIELD` Get the field definitions and metadata for one TikTok Instant Form. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page_id` | string | Yes | ID of the Instant Form. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get a test lead **Slug:** `TIKTOK_ADS_GET_PAGE_LEAD_MOCK` Get the current test lead for an Instant Form or direct-message lead source. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page_id` | string | No | Instant Form ID; required for INSTANT_FORM and unsupported for DIRECT_MESSAGE. | | `library_id` | string | No | Form library ID when the lead belongs to a Business Center. | | `lead_source` | string ("INSTANT_FORM" | "DIRECT_MESSAGE") | No | Test-lead source. | | `advertiser_id` | string | No | Advertiser ID when the lead belongs to an ad account. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get form libraries **Slug:** `TIKTOK_ADS_GET_PAGE_LIBRARY` Return one page of Business Center form libraries accessible to the connected user. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial provider page number. | | `page_size` | integer | No | Records per page. | | `next_cursor` | string | No | Opaque continuation token from a previous response. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get the Pangle Block List **Slug:** `TIKTOK_ADS_GET_PANGLE_BLOCK_LIST` Get an advertiser's Pangle app block list and its last modification time. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Payment Portfolios **Slug:** `TIKTOK_ADS_GET_PAYMENT_PORTFOLIO` Return 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial page number. | | `bc_id` | string | Yes | Business Center ID. By default TikTok can return portfolios belonging to the same client even when they are not linked to this Business Center. | | `filtering` | object | No | Optional Payment Portfolio filters. | | `page_size` | integer | No | Portfolios per page (1-50). | | `next_cursor` | string | No | Opaque continuation token returned by a previous call. Repeat filtering with the cursor so later pages use the same filter. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get ad accounts linked to a Payment Portfolio **Slug:** `TIKTOK_ADS_GET_PAYMENT_PORTFOLIO_ADVERTISER` Return 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial page number. | | `page_size` | integer | No | Ad accounts per page (1-50). | | `next_cursor` | string | No | Opaque continuation token returned by a previous call. | | `payment_portfolio_id` | string | Yes | Payment Portfolio ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get authorized users for a Payment Portfolio **Slug:** `TIKTOK_ADS_GET_PAYMENT_PORTFOLIO_USER` Return 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial page number. | | `page_size` | integer | No | Users per page (1-50). | | `next_cursor` | string | No | Opaque continuation token returned by a previous call. | | `payment_portfolio_id` | string | Yes | Payment Portfolio ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Pixel Event statistics **Slug:** `TIKTOK_ADS_GET_PIXEL_EVENT_STATS` Get UTC Pixel Event statistics; this reporting endpoint does not ingest events. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `pixel_ids` | array | Yes | One to ten Pixel IDs. | | `date_range` | object | Yes | UTC reporting range of at most 30 days. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Instant Page events **Slug:** `TIKTOK_ADS_GET_PIXEL_INSTANT_PAGE_EVENT` Get supported TikTok Instant Page event options for an optimization goal. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_id` | string | Yes | Advertiser ID. | | `is_retargeting` | boolean | No | Whether the use case is retargeting. | | `objective_type` | string ("CONVERSIONS" | "APP_PROMOTION") | Yes | CONVERSIONS or APP_PROMOTION. | | `optimization_goal` | string | Yes | Optimization goal. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get playable assets **Slug:** `TIKTOK_ADS_GET_PLAYABLE` Return one page of playable assets for an advertiser. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial provider page number. | | `status` | string ("AUDIT_FAIL" | "AUDIT_SUCCESS" | "VALIDATE_FAIL" | "VALIDATE_SUCCESS" | "VALIDATING") | No | Playable validation or audit status. | | `page_size` | integer | No | Results per page (1-100). | | `next_cursor` | string | No | Opaque continuation token from a previous response. | | `playable_id` | string | No | Playable asset ID filter. | | `playable_url` | string | No | Playable URL filter. | | `advertiser_id` | string | Yes | Advertiser ID. | | `playable_name` | string | No | Playable asset name filter. | | `operation_status` | string ("UPLOADED" | "SAVED" | "DELETED") | No | Playable operation status. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get recommended CTAs **Slug:** `TIKTOK_ADS_GET_RECOMMENDED_CREATIVE_CTA` Get standard or Dynamic CTA recommendations for an advertiser. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `app_id` | string | No | Promoted application ID. | | `ad_texts` | array | No | Ad texts used to customize recommendations. | | `language` | string | No | Recommendation language code; valid for the new request. | | `asset_type` | string | No | CTA_NORMAL or CTA_AUTO_OPTIMIZED for the legacy request. | | `placements` | array | No | Delivery placements for the new request. | | `new_version` | boolean | No | Use Dynamic CTA recommendations. | | `content_type` | string | No | Ads content type for the legacy request. | | `region_codes` | array | No | Target region codes for the new request. | | `advertiser_id` | string | Yes | Advertiser ID. | | `objective_type` | string | No | Advertising objective for the new request. | | `promotion_type` | string | No | Promotion type for the new request. | | `landing_page_url` | string | No | Landing page used to customize recommendations. | | `optimization_goal` | string | No | Optimization goal for the new request. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Run synchronous integrated report **Slug:** `TIKTOK_ADS_GET_REPORT_INTEGRATED` Return one page of a synchronous TikTok report with dimensions, metrics, advertiser lists, and filters encoded as provider JSON query values. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial provider page. | | `bc_id` | string | No | Business Center ID for BC reports. | | `metrics` | array | No | Metric names, JSON-encoded in the query. | | `end_date` | string | No | Inclusive query end date. | | `filtering` | array | No | Filtering conditions, JSON-encoded in the query. | | `page_size` | integer | No | Rows per page (1-1000). | | `data_level` | string | No | Report data level. | | `dimensions` | array | No | Dimension names, JSON-encoded in the query. | | `order_type` | string ("ASC" | "DESC") | No | Sort order. | | `query_mode` | string ("REGULAR" | "CHUNK") | No | Deprecated query mode; CHUNK disables pagination. | | `start_date` | string | No | Inclusive query start date. | | `next_cursor` | string | No | Opaque continuation token from a previous response. | | `order_field` | string | No | Metric used for sorting. | | `report_type` | string ("BASIC" | "AUDIENCE" | "PLAYABLE_MATERIAL" | "CATALOG" | "BC" | "TT_SHOP") | Yes | Report family. | | `service_type` | string ("AUCTION" | "RESERVATION") | No | Ad service type. | | `advertiser_id` | string | No | Single advertiser ID. | | `advertiser_ids` | array | No | Up to five advertiser IDs, JSON-encoded in the query. | | `query_lifetime` | boolean | No | Request lifetime metrics where supported. | | `enable_total_metrics` | boolean | No | Return aggregate metrics when supported. | | `multi_adv_report_in_utc_time` | boolean | No | Normalize multi-advertiser metrics to UTC. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get R&F time zones **Slug:** `TIKTOK_ADS_GET_RF_DELIVERY_TIMEZONE` Get R&F time zones. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `region_codes` | array | Yes | Country codes to be queried. Example:`US` . See Appendix - Location Code | | `advertiser_id` | string | Yes | Advertiser ID | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Search Ads Campaign Health diagnoses **Slug:** `TIKTOK_ADS_GET_SEARCH_AD_HEALTH_DIAGNOSES` Get Search Ads Campaign Health diagnoses for an ad group or ads. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `ad_ids` | array | No | Ad IDs from one Search Ads ad group (maximum 50). | | `adgroup_id` | string | No | Existing Search Ads ad-group ID; ignored when ad_ids is set. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get available locations by advertiser ID **Slug:** `TIKTOK_ADS_GET_SEARCH_REGION` Get all locations available to an advertiser, with translated names. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `language` | string ("zh" | "fr" | "es" | "ko" | "vi" | "en" | "hi" | "it" | "tr" | "ru" | "ja" | "id" | "de" | "ms" | "ar" | "th") | No | Language for returned region names. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Showcase Identity **Slug:** `TIKTOK_ADS_GET_SHOWCASE_IDENTITY` Get the identity with Showcase permission under an ad account. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_id` | string | Yes | Advertiser account ID whose Showcase identity to retrieve. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Smart Creative Materials **Slug:** `TIKTOK_ADS_GET_SMART_CREATIVE_MATERIALS` Get 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `adgroup_ids` | array | Yes | Smart Creative ad group IDs to read (1-100). | | `advertiser_id` | string | Yes | Advertiser account ID. | | `exclude_field_types_in_response` | array | No | Use NULL_FIELD to omit null-valued response fields. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Smart+ Material Report **Slug:** `TIKTOK_ADS_GET_SMART_PLUS_MATERIAL_REPORT` Get one page of Smart+ material overview or breakdown reporting. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial result page. | | `metrics` | array | No | Metrics supported by the selected report type. | | `end_date` | string | No | Report end date in YYYY-MM-DD format. | | `page_size` | integer | No | Rows in this page (1-100). | | `sort_type` | string ("ASC" | "DESC") | No | Sort order. | | `dimensions` | array | Yes | Dimensions supported by the selected report type. | | `sort_field` | 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") | No | Metric supported for sorting by the selected report type. | | `start_date` | string | No | Report start date in YYYY-MM-DD format. | | `adgroup_ids` | array | No | Ad group IDs (1-200). | | `next_cursor` | string | No | 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. | | `report_type` | string ("OVERVIEW" | "BREAKDOWN") | Yes | Select the overview or breakdown report endpoint. | | `campaign_ids` | array | No | Campaign IDs (1-200). | | `advertiser_id` | string | Yes | Authorized advertiser ID. | | `query_lifetime` | boolean | No | Query lifetime performance; available only for OVERVIEW. | | `main_material_ids` | array | No | Main material IDs (1-400). | | `smart_plus_ad_ids` | array | No | Smart+ ad IDs (1-200). | | `ad_text_entity_ids` | array | No | Ad text entity IDs (1-400). | | `main_material_types` | array | No | Main material type filters. | | `call_to_action_entity_ids` | array | No | Call-to-action entity IDs (1-400). | | `interactive_add_on_entity_ids` | array | No | Interactive add-on entity IDs (1-400). | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Smart+ Review Info **Slug:** `TIKTOK_ADS_GET_SMART_PLUS_REVIEW_INFO` Get review information for Smart+ ads or ad materials. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `lang` | string | No | Response language selector. | | `resource_ids` | array | Yes | Smart+ ad or ad material IDs to inspect (1-100). | | `advertiser_id` | string | Yes | Advertiser ID that owns the resources. | | `resource_type` | string ("AD" | "AD_MATERIAL") | Yes | Whether resource_ids contains Smart+ ad or ad material IDs. | | `extra_info_setting` | object | No | Optional review details to include. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get the results of a split test **Slug:** `TIKTOK_ADS_GET_SPLIT_TEST_RESULT` Get the current status and statistical results of a split test. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_id` | string | Yes | Advertiser ID. | | `split_test_group_id` | string | Yes | Split test group ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get products within a TikTok Shop **Slug:** `TIKTOK_ADS_GET_STORE_PRODUCT` Get one page of products within a TikTok Shop. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial page number. | | `bc_id` | string | Yes | Business Center ID. | | `store_id` | string | Yes | TikTok Shop ID. | | `filtering` | object | No | Product filtering conditions. | | `page_size` | integer | No | Page size (1-100). | | `sort_type` | string ("ASC" | "DESC") | No | Sort direction. | | `sort_field` | string ("min_price" | "historical_sales") | No | Field to sort by. | | `next_cursor` | string | No | Opaque continuation token from a previous response. | | `advertiser_id` | string | No | Advertiser ID, required when ad_creation_eligible is specified. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get subscription details of a developer app **Slug:** `TIKTOK_ADS_GET_SUBSCRIPTION` Return one page of webhook subscriptions configured for a developer application. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial provider page number. | | `app_id` | string | Yes | Developer application ID from My Apps. | | `secret` | string | Yes | Developer application secret from My Apps. | | `page_size` | integer | No | Subscriptions per page (1-1000). | | `next_cursor` | string | No | Opaque continuation token from a previous response. Resend secret with the token; secrets are never stored in continuation cursors. | | `subscribe_entity` | string ("REPORT_DATA_CHANGE" | "AD_ACCOUNT_SUSPENSION" | "LEAD" | "AD_GROUP" | "AD" | "TCM_VIDEOS" | "CREATIVE_FATIGUE" | "API_SERVICE_STATUS") | No | Optional subscribed object type to filter by. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get targeting hashtags by ID **Slug:** `TIKTOK_ADS_GET_TARGETING_HASHTAGS` Get targeting hashtag names and availability by keyword ID. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `keyword_ids` | array | Yes | Hashtag keyword IDs to retrieve. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get targeting information **Slug:** `TIKTOK_ADS_GET_TARGETING_TAG_DETAILS` Get geographical or ISP targeting tag details by targeting ID. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `scene` | string ("GEO" | "ISP") | No | Targeting scene for the supplied IDs. | | `placements` | array | No | Required placements for the GEO scene. | | `advertiser_id` | string | Yes | Advertiser ID. | | `targeting_ids` | array | Yes | Location, postal-code, or ISP targeting IDs (maximum 1,000). | | `objective_type` | string ("REACH" | "TRAFFIC" | "VIDEO_VIEWS" | "LEAD_GENERATION" | "ENGAGEMENT" | "APP_PROMOTION" | "WEB_CONVERSIONS" | "PRODUCT_SALES") | No | Required for the GEO scene. | | `promotion_type` | string | No | Promotion type required for applicable GEO objectives. | | `operating_system` | string ("ANDROID" | "IOS") | No | Device operating system for GEO targeting. | | `brand_safety_type` | string ("NO_BRAND_SAFETY" | "EXPANDED_INVENTORY" | "STANDARD_INVENTORY" | "LIMITED_INVENTORY" | "THIRD_PARTY") | No | Brand safety type for GEO targeting on TikTok placement. | | `brand_safety_partner` | string ("IAS" | "OPEN_SLATE") | No | Required with THIRD_PARTY brand safety. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Terms **Slug:** `TIKTOK_ADS_GET_TERM` Get an advertiser agreement in the requested language. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `lang` | string ("EN" | "JA" | "ZH") | No | Language of the agreement. | | `term_type` | string ("InstantPage" | "LeadAds" | "Pixel" | "ReachFrequency") | Yes | Type of agreement to retrieve. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get the Brand Safety Hub settings of an ad account **Slug:** `TIKTOK_ADS_GET_TIKTOK_INVENTORY_FILTERS` Get the Brand Safety Hub settings configured for an advertiser account. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Info About a Spark Ad Post **Slug:** `TIKTOK_ADS_GET_TT_VIDEO` Resolve 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `auth_code` | string | Yes | 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. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Video Fix Task **Slug:** `TIKTOK_ADS_GET_VIDEO_FIX_TASK` Get the results of a Smart Fix task. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `task_id` | string | Yes | Smart Fix task ID to retrieve. | | `advertiser_id` | string | Yes | Advertiser account ID that owns the Smart Fix task. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get In-Second Video Performance **Slug:** `TIKTOK_ADS_GET_VIDEO_PERFORMANCE_REPORT` Get 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Result page number. | | `filtering` | object | Yes | Report filters and optional VIDEO time window. | | `page_size` | integer | No | Results per page (1-500). | | `sort_type` | string ("ASC" | "DES") | No | ASC or provider-documented DES sort order (not DESC). | | `sort_field` | string | No | Provider field to sort by. Retained, provider-reported examples are AD_ID and CREATE_TIME; no complete enum has been independently verified. | | `report_type` | string ("AD" | "VIDEO") | No | AD (default) or VIDEO report mode. Only VIDEO mode accepts start_time, end_time, and lifetime filters. | | `advertiser_id` | string | Yes | Advertiser account ID. | | `metrics_fields` | array | No | Provider field names for in-second performance metrics to return as numeric arrays. No complete metric vocabulary is verified. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Invite members to a BC **Slug:** `TIKTOK_ADS_INVITE_BC_MEMBER` Invite users to a Business Center and optionally assign advertiser and finance roles. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `emails` | array | Yes | One to 50 user email addresses to invite. | | `asset_ids` | array | No | Up to 50 advertiser IDs assigned to invited users. | | `user_role` | string ("ADMIN" | "STANDARD") | No | Basic Business Center role: `ADMIN` or `STANDARD`. | | `asset_type` | string | No | Asset type; only `ADVERTISER` is supported. | | `ext_user_role` | object | No | Optional advanced finance role. | | `advertiser_role` | string ("ADMIN" | "ANALYST" | "OPERATOR") | No | Advertiser role assigned to invited users; defaults to analyst. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List Ad Groups **Slug:** `TIKTOK_ADS_LIST_AD_GROUPS` List 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial ad group result page to retrieve. | | `fields` | array | No | Generic ad group fields to return. Verified selections include adgroup_id and adgroup_name; other provider-supported field names remain free-form. | | `page_size` | integer | No | Maximum ad groups to return in this page (1-1000). | | `next_cursor` | string | No | Continuation token returned by a previous call; omit for the first page. | | `ad_group_ids` | array | No | Ad group IDs to return from this list endpoint. | | `bid_strategy` | string | No | TikTok bid-strategy code to filter by. Use a strategy supported for the advertiser's objective and buying type. | | `buying_types` | array | No | Ad group buying-type filters. | | `campaign_ids` | array | No | Campaign IDs whose ad groups to return. | | `ad_group_name` | string | No | Ad group name filter. | | `advertiser_id` | string | Yes | Authorized advertiser account ID whose ad groups to read. | | `billing_events` | array | No | TikTok billing-event codes to filter by. The supported set depends on the objective and is not restricted to an unverified fixed enum. | | `objective_type` | string | No | TikTok objective-type code to filter by for this advertiser. | | `primary_status` | string | No | Primary-status code from TikTok's Ad Management status enumeration. Defaults to STATUS_NOT_DELETE. | | `promotion_type` | string | No | TikTok promoted-destination or promoted-object type code to filter by. | | `secondary_status` | string | No | Detailed TikTok ad-group delivery or review status code. The provider-maintained set is not exposed here as an exhaustive enum. | | `optimization_goal` | string | No | TikTok optimization-goal code to filter by for the selected objective. | | `split_test_enabled` | boolean | No | Filter by split-test status. | | `creative_material_mode` | string ("CUSTOM" | "SMART_CREATIVE" | "DYNAMIC") | No | Creative material-mode filter. | | `campaign_system_origins` | array | No | Campaign system-origin filters. | | `campaign_automation_type` | string ("MANUAL" | "SMART_PLUS" | "UPGRADED_SMART_PLUS") | No | Campaign automation type to filter by. | | `creation_filter_end_time` | string | No | Inclusive ad group creation-time filter end. | | `creation_filter_start_time` | string | No | Inclusive ad group creation-time filter start. | | `exclude_field_types_in_response` | array | No | Field types to omit from the response. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List Ads **Slug:** `TIKTOK_ADS_LIST_ADS` List 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial ad result page to retrieve. | | `ad_ids` | array | No | Legacy creative IDs to return. For Upgraded Smart+ ad-level IDs, use current_ad_ids instead; do not provide both ID filters. | | `fields` | array | No | Generic ad fields to return. Verified selections include ad_id and ad_name; other provider-supported field names remain free-form. | | `page_size` | integer | No | Maximum ads to return in this page (1-1000). | | `destination` | string ("APP" | "TIKTOK_INSTANT_PAGE" | "WEBSITE" | "SOCIAL_MEDIA_APP" | "PHONE_CALL") | No | Ad destination filter. | | `next_cursor` | string | No | Opaque continuation cursor from a previous call; omit for the first page. | | `ad_group_ids` | array | No | Ad group IDs whose ads to return. | | `buying_types` | array | No | Ad buying-type filters. | | `campaign_ids` | array | No | Campaign IDs whose ads to return. | | `advertiser_id` | string | Yes | Authorized advertiser account ID whose ads to read. | | `current_ad_ids` | array | No | 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. | | `modified_after` | string | No | Return ads modified after this time. | | `objective_type` | string | No | 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. | | `primary_status` | string | No | Primary-status code from TikTok's Ad Management status enumeration. Defaults to STATUS_NOT_DELETE. | | `secondary_status` | string | No | Detailed TikTok ad delivery or review status code. This provider-maintained set is not exposed here as an exhaustive enum. | | `optimization_goal` | string | No | TikTok optimization-goal code to filter by. Use a value supported for the advertiser and campaign objective. | | `creative_material_mode` | string ("CUSTOM" | "SMART_CREATIVE" | "DYNAMIC") | No | Creative material-mode filter. | | `campaign_system_origins` | array | No | Campaign system-origin filters. | | `campaign_automation_type` | string ("MANUAL" | "SMART_PLUS" | "UPGRADED_SMART_PLUS") | No | Campaign automation type to filter by. | | `creation_filter_end_time` | string | No | Inclusive ad creation-time filter end. | | `creation_filter_start_time` | string | No | Inclusive ad creation-time filter start. | | `exclude_field_types_in_response` | array | No | Field types to omit from the response. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Advertiser Balance **Slug:** `TIKTOK_ADS_LIST_ADVERTISER_BALANCES` Get one page of ad account balances and budgets for a TikTok Business Center, with optional account filters and detailed balance fields. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial result page to retrieve (1 or greater). | | `bc_id` | string | Yes | Business Center ID whose ad account balances to retrieve. | | `fields` | array | No | Additional balance and budget fields to return. TikTok omits these fields by default; requesting all additional fields together requires page_size=1. | | `keyword` | string | No | Ad account name or ad account ID keyword used in TikTok's filtering object. | | `page_size` | integer | No | Maximum ad account balances to return in this page (1-50). | | `child_bc_id` | string | No | Child Business Center ID when retrieving balances for a child center. | | `next_cursor` | string | No | Opaque continuation token returned by a previous call; omit for the first page. | | `advertiser_status` | array | No | Ad account display statuses included in TikTok's filtering object. | | `payment_portfolio_id` | string | No | Payment Portfolio ID used in TikTok's filtering object. This filter requires the allowlisted multiple Payment Portfolios feature. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List Advertiser Budget Changes **Slug:** `TIKTOK_ADS_LIST_ADVERTISER_BUDGET_CHANGES` Get one page of budget change audit records for an ad account. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial result page to retrieve. | | `end_date` | string | No | UTC end date in YYYY-MM-DD; must be supplied with start_date. | | `page_size` | integer | No | Maximum budget changes to return in this page (1-50). | | `start_date` | string | No | UTC start date in YYYY-MM-DD; must be supplied with end_date. | | `next_cursor` | string | No | Opaque continuation token from a previous call; omit for the first page. | | `advertiser_id` | string | Yes | Ad account ID whose budget change history to retrieve. | | `business_center_id` | string | Yes | Business Center ID that owns the ad account. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List Advertiser Qualifications **Slug:** `TIKTOK_ADS_LIST_ADVERTISER_QUALIFICATIONS` List one page of reusable advertiser qualification records in a Business Center, optionally filtered by verification status. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial result page to retrieve. | | `verified` | boolean | No | Filter by whether TikTok has verified the qualification. | | `page_size` | integer | No | Maximum qualifications to return in this page (1-100). | | `next_cursor` | string | No | Opaque continuation token from a previous call; omit for the first page. | | `business_center_id` | string | Yes | Business Center ID whose reusable advertiser qualifications to retrieve. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get time zones **Slug:** `TIKTOK_ADS_LIST_ADVERTISER_TIMEZONES` Get time zones available to advertisers. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List Advertiser Transactions **Slug:** `TIKTOK_ADS_LIST_ADVERTISER_TRANSACTIONS` List one page of advertiser billing transactions accessible through a Business Center, with optional transaction type, fund type, account, and UTC date filters. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial result page to retrieve. | | `bc_id` | string | Yes | Business Center ID. The Business Center must not have type NORMAL and the connected user must have finance access. | | `keyword` | string | No | Ad account name or ad account ID to search for. | | `end_date` | string | No | 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. | | `page_size` | integer | No | Maximum transaction records to return in this page (1-50). | | `funds_type` | array | No | Fund types to include. Omit to include both cash and grant transactions. | | `start_date` | string | No | Transaction search start date in UTC, formatted YYYY-MM-DD. TikTok defaults to 90 days ago. | | `next_cursor` | string | No | Opaque continuation token returned by a previous call; omit for the first page. | | `transfer_type` | string ("TRANS_TYPE_TRANSFER" | "TRANS_TYPE_TAX" | "TRANS_TYPE_COST" | "TRANS_TYPE_PAYMENT") | No | Billing type: transfer, tax, consumption, or payment. Tax and consumption transactions do not return a funds_type. | | `summary_by_account` | boolean | No | Whether TikTok should summarize transaction records by ad account. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get the app list **Slug:** `TIKTOK_ADS_LIST_APP` Get the mobile apps configured for an advertiser. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_id` | string | Yes | Advertiser ID. | | `app_platform_ids` | array | No | List of app platform IDs used to filter results. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get available attribution sources and data sources for an app **Slug:** `TIKTOK_ADS_LIST_APP_ATTRIBUTION_SOURCES` Get attribution sources and data sources available for a mobile app. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `app_id` | string | Yes | Mobile app ID returned by the app list endpoint. | | `advertiser_id` | string | Yes | Advertiser ID. | | `campaign_type` | string ("REGULAR_CAMPAIGN" | "IOS14_CAMPAIGN") | No | Campaign type. | | `optimization_event` | string | No | Optimization event used to filter attribution sources. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get the advertiser list of a Billing Group **Slug:** `TIKTOK_ADS_LIST_BC_BILLING_GROUP_ADVERTISER` Return 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial page number. | | `bc_id` | string | Yes | Business Center ID. | | `page_size` | integer | No | Advertisers to return per page (1-50). | | `next_cursor` | string | No | Opaque continuation token returned by a previous call. | | `billing_group_id` | string | Yes | Billing Group ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get asynchronous invoice download task list **Slug:** `TIKTOK_ADS_LIST_BC_INVOICE_TASK` Return one page of asynchronous invoice download tasks and their download URLs. These references expose finance-sensitive billing files; confirm the Business Center and share or download them only to approved destinations. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial page number. | | `bc_id` | string | Yes | Business Center ID. | | `page_size` | integer | No | Tasks to return per page (1-50). | | `next_cursor` | string | No | Opaque continuation token returned by a previous call. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get blocked words **Slug:** `TIKTOK_ADS_LIST_BLOCKEDWORD` Return one page of an advertiser's blocked-word moderation list and an opaque continuation cursor when more results exist. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page_info` | object | No | Pagination information sent in TikTok's page_info query object. | | `next_cursor` | string | No | Opaque continuation token from a previous response; omit for the first page. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List Business Center Account Costs **Slug:** `TIKTOK_ADS_LIST_BUSINESS_CENTER_ACCOUNT_COSTS` Get one page of aggregate Business Center costs and itemized advertiser cost records. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial result page to retrieve. | | `keyword` | string | No | Advertiser ID or name to fuzzy-match. | | `end_date` | string | No | End date in YYYY-MM-DD in the ad account time zone. | | `page_size` | integer | No | Maximum cost records to return in this page (1-50). | | `start_date` | string | No | Start date in YYYY-MM-DD in the ad account time zone. | | `next_cursor` | string | No | Opaque continuation token from a previous call; omit for the first page. | | `business_center_id` | string | Yes | Business Center ID whose Business Center and ad-account costs to retrieve. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List Business Center Account Transactions **Slug:** `TIKTOK_ADS_LIST_BUSINESS_CENTER_ACCOUNT_TRANSACTIONS` Get 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial result page to retrieve. | | `end_time` | string | No | Closed-interval end in YYYY-MM-DD HH:MM:SS. | | `page_size` | integer | No | Maximum transaction records to return in this page (1-50). | | `start_time` | string | No | Closed-interval start in YYYY-MM-DD HH:MM:SS. | | `account_ids` | array | No | Ad account IDs to include (1-100); valid at ADVERTISER level. | | `next_cursor` | string | No | Opaque continuation token from a previous call; omit for the first page. | | `account_name` | string | No | Ad account name to fuzzy-match; valid at ADVERTISER level. | | `billing_types` | array | No | Billing types to include: CASH or CREDIT. | | `owner_of_account` | array | No | Ad account ownership categories to include; valid at ADVERTISER level. | | `transaction_level` | string ("BC" | "ADVERTISER" | "PAYMENT_PORTFOLIO") | No | Level at which to retrieve transactions. | | `transaction_types` | array | No | Provider transaction-type codes to include, such as ORDER_CREATION_PAYMENT. TikTok does not publish a closed enum. | | `business_center_id` | string | Yes | Business Center ID whose account transactions to retrieve. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Business Center Activity Log **Slug:** `TIKTOK_ADS_LIST_BUSINESS_CENTER_ACTIVITY_LOG_ENTRIES` Get one page of activity-log records for a Business Center. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `lang` | string ("ar" | "cs-CZ" | "de" | "en" | "es" | "fil" | "fr" | "id" | "it" | "ja" | "ko" | "ms" | "pl-PL" | "pt" | "ru" | "sv-SE" | "th" | "tr" | "vi" | "zh") | No | Activity-log language. | | `page` | integer | No | Initial result page to retrieve. | | `bc_id` | string | Yes | Business Center ID whose activity log to retrieve. | | `filtering` | object | No | Optional date and activity filters. | | `page_size` | integer | No | Maximum activity records in this page (1-50). | | `sort_type` | string ("DESC" | "ASC") | No | Activity-log sort direction. | | `sort_field` | string | No | Sort by the activity time represented by each entry's time field. | | `next_cursor` | string | No | Opaque continuation token from a previous call; omit for the first page. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List Business Center Advertisers **Slug:** `TIKTOK_ADS_LIST_BUSINESS_CENTER_ADVERTISERS` List one page of advertiser-account assets assigned to the authorized user in a specified TikTok Business Center. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial result page to retrieve. | | `keyword` | string | No | Asset name or ID keyword. | | `user_id` | string | No | Bound user's TikTok for Business ID. | | `page_size` | integer | No | Maximum advertiser assets in this page (1-50). | | `user_email` | string | No | Pending Business Center user's email. | | `next_cursor` | string | No | Opaque continuation token returned by a previous call; omit for the first page. | | `business_center_id` | string | Yes | Authorized Business Center ID whose assigned advertiser accounts to list. | | `child_business_center_id` | string | No | Child Business Center ID when reading tiered assets. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List Business Center Asset Groups **Slug:** `TIKTOK_ADS_LIST_BUSINESS_CENTER_ASSET_GROUPS` Get one page of Asset Groups in a TikTok Business Center. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial result page to retrieve. | | `bc_id` | string | Yes | Business Center ID whose Asset Groups to list. | | `keyword` | string | No | Keyword used to filter Asset Groups. | | `page_size` | integer | No | Maximum Asset Groups to return in this page; must be at least 1. | | `next_cursor` | string | No | Opaque continuation token returned by a previous call; omit for the first page and pass it back unchanged for the next page. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List Business Center Asset Partners **Slug:** `TIKTOK_ADS_LIST_BUSINESS_CENTER_ASSET_PARTNERS` Get one page of Business Center partners associated with an asset. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial result page to retrieve. | | `keyword` | string | No | Partner name keyword to filter by. | | `asset_id` | string | Yes | ID of the asset identified by asset_type: an ad account, catalog, domain, lead, pixel, storefront, TikTok Shop, or TikTok account ID. | | `page_size` | integer | No | Maximum partners to return in this page (1-50). | | `asset_type` | string ("ADVERTISER" | "CATALOG" | "DOMAIN" | "LEAD" | "PIXEL" | "STOREFRONT" | "TIKTOK_SHOP" | "TT_ACCOUNT") | Yes | Asset type: ADVERTISER, CATALOG, DOMAIN, LEAD, PIXEL, STOREFRONT, TIKTOK_SHOP, or TT_ACCOUNT. | | `next_cursor` | string | No | Opaque continuation token returned by a previous call; omit for the first page and pass it back unchanged for the next page. | | `business_center_id` | string | Yes | Business Center ID that owns the asset. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List Business Center Billing Groups **Slug:** `TIKTOK_ADS_LIST_BUSINESS_CENTER_BILLING_GROUPS` Get one page of billing groups in a TikTok Business Center. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial result page to retrieve (1 or greater). | | `bc_id` | string | Yes | Business Center ID whose billing groups to retrieve. | | `status` | string ("VALID" | "INVALID") | No | Billing Group status to include: VALID or INVALID. | | `page_size` | integer | No | Maximum billing groups to return in this page (1-50). | | `next_cursor` | string | No | Opaque continuation token returned by a previous call; omit for the first page and pass it back unchanged for the next page. | | `billed_to_type` | string ("ACCOUNT" | "ADVERTISER") | No | Party billed on invoices: ACCOUNT bills agencies, while ADVERTISER bills advertisers. | | `billing_group_id` | string | No | Billing Group ID to match. | | `invoice_group_by` | string ("ACCOUNT" | "ADVERTISER") | No | How invoices are handled: ACCOUNT combines invoices, while ADVERTISER handles each advertiser's invoices separately. | | `billing_group_name` | string | No | Billing group name to match (1-256 characters). | | `billing_group_type` | string ("AUCTION" | "RESERVATION") | No | Advertising type of the billing group's ad accounts: AUCTION or RESERVATION. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List Business Center Members **Slug:** `TIKTOK_ADS_LIST_BUSINESS_CENTER_MEMBERS` Get one page of members in a TikTok Business Center. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial result page to retrieve. | | `keyword` | string | No | Keyword to filter members by. | | `page_size` | integer | No | Maximum members to return in this page (1-20). | | `user_role` | string ("ADMIN" | "STANDARD") | No | Basic Business Center role to filter by: ADMIN or STANDARD. | | `next_cursor` | string | No | Opaque continuation token returned by a previous call; omit for the first page and pass it back unchanged for the next page. | | `relation_status` | string ("BOUND" | "PENDING" | "REJECTED" | "UNBOUND") | No | Business Center relation status to filter by: BOUND, PENDING, REJECTED, or UNBOUND. | | `business_center_id` | string | Yes | Business Center ID whose members to list. | | `child_business_center_id` | string | No | Child Business Center ID when listing members in a tiered structure. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List Business Center Partners **Slug:** `TIKTOK_ADS_LIST_BUSINESS_CENTER_PARTNERS` Get one page of partners for a TikTok Business Center. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | No | Partner name keyword to filter the results by. | | `page` | integer | No | Initial result page to retrieve (1 or greater). | | `bc_id` | string | Yes | Business Center ID whose partners to retrieve. | | `page_size` | integer | No | Maximum partners to return in this page (1-50). | | `next_cursor` | string | No | Opaque continuation token returned by a previous call; omit for the first page and pass it back unchanged for the next page. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List Business Center Pixel Links **Slug:** `TIKTOK_ADS_LIST_BUSINESS_CENTER_PIXEL_LINKS` Get one page of ad accounts linked to a TikTok Business Center pixel. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial result page to retrieve (1 or greater). | | `bc_id` | string | Yes | Business Center ID that owns the pixel. | | `page_size` | integer | No | Maximum linked ad accounts to return in this page (1 or greater). | | `pixel_code` | string | Yes | Pixel code whose linked ad accounts to list. | | `next_cursor` | string | No | Opaque continuation token returned by a previous call; omit for the first page and pass it back unchanged for the next page. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List Business Centers **Slug:** `TIKTOK_ADS_LIST_BUSINESS_CENTERS` List one page of Business Centers accessible to the connected TikTok authorization, optionally restricted to one Business Center ID. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial result page to retrieve. | | `scene` | string ("SINGLE_ACCOUNT" | "TIERED_ACCOUNT") | No | Business Center account scene. | | `keyword` | string | No | Business Center filter keyword. | | `page_size` | integer | No | Maximum Business Centers in this page (1-50). | | `next_cursor` | string | No | Opaque continuation token returned by a previous call; omit for the first page and pass it back unchanged for the next page. | | `keyword_type` | string ("ASSET" | "MEMBER" | "PARTNER" | "TIER") | No | Resource type searched by the keyword. | | `relation_type` | string ("CHILD" | "PARENT") | No | Tiered Business Center relationship to return. | | `business_center_id` | string | No | Business Center ID to return; omit to discover all accessible Business Centers. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List Business Center Transactions **Slug:** `TIKTOK_ADS_LIST_BUSINESS_CENTER_TRANSACTIONS` Get 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial result page to retrieve. | | `bc_id` | string | Yes | Business Center ID whose transaction records to retrieve. | | `end_date` | string | No | Latest transaction date to include, formatted YYYY-MM-DD. TikTok defaults to today. | | `page_size` | integer | No | Maximum transaction records to return in this page (1-50). | | `funds_type` | array | No | Fund types to include: cash or non-cash grant funds. Omit to include both fund types. | | `start_date` | string | No | Earliest transaction date to include, formatted YYYY-MM-DD. TikTok defaults to 90 days ago. | | `next_cursor` | string | No | Opaque continuation token returned by a previous call; omit for the first page and pass it back unchanged for the next page. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List Campaign Labels **Slug:** `TIKTOK_ADS_LIST_CAMPAIGN_LABELS` List one page of campaign labels for an authorized advertiser. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial result page to retrieve. | | `page_size` | integer | No | Maximum campaign labels to return in this page (1-1000). | | `next_cursor` | string | No | Opaque continuation token from a previous call; omit for the first page. | | `advertiser_id` | string | Yes | Authorized advertiser account ID. | | `campaign_label_ids` | array | No | Campaign label IDs to include (maximum 50, each exactly 19 digits). | | `campaign_label_names` | array | No | Campaign label names to include (maximum 10). | | `campaign_label_types` | array | No | Campaign label types to include. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List Campaigns **Slug:** `TIKTOK_ADS_LIST_CAMPAIGNS` List 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial campaign result page to retrieve. | | `fields` | array | No | Generic campaign fields to return. Verified selections include campaign_id and campaign_name; other provider-supported field names remain free-form. | | `page_size` | integer | No | Maximum campaigns to return in this page (1-1000). | | `store_ids` | array | No | TikTok Shop store IDs to filter by (maximum 10). Provide gmv_max_promotion_types in the same request when using this filter. | | `next_cursor` | string | No | Opaque continuation token returned by a previous call; omit for the first page. | | `buying_types` | array | No | Campaign buying-type filters. | | `campaign_ids` | array | No | Campaign IDs to return from this list endpoint. | | `advertiser_id` | string | Yes | Authorized advertiser account ID whose campaigns to read. | | `campaign_name` | string | No | Campaign name filter supported by the campaign list endpoint. | | `campaign_type` | string ("REGULAR_CAMPAIGN" | "IOS14_CAMPAIGN") | No | Regular or iOS 14 campaign type filter. | | `objective_type` | string | No | TikTok campaign objective code to filter by. The provider's supported set varies by advertiser features and is not restricted to a fixed enum. | | `primary_status` | string | No | Primary-status code from TikTok's Campaign Status enumeration. | | `secondary_status` | string | No | Detailed TikTok campaign delivery or review status code. The provider-maintained set is not exposed here as an exhaustive enum. | | `optimization_goal` | string | No | TikTok optimization-goal code to filter by for the campaign objective. | | `sales_destination` | string ("TIKTOK_SHOP" | "WEBSITE" | "APP" | "WEB_AND_APP") | No | Campaign sales-destination filter. | | `split_test_enabled` | boolean | No | Filter by split-test status. | | `creative_campaign_type` | array | No | Creative campaign-type filters. | | `campaign_product_source` | string ("CATALOG" | "STORE") | No | Campaign product-source filter. | | `campaign_system_origins` | array | No | Campaign system-origin filters. | | `gmv_max_promotion_types` | array | No | Deprecated GMV Max promotion-type filters; use only for legacy queries. | | `campaign_automation_type` | string ("MANUAL" | "SMART_PLUS" | "UPGRADED_SMART_PLUS") | No | Campaign automation type to filter by. | | `creation_filter_end_time` | string | No | Inclusive campaign creation-time filter end. | | `creation_filter_start_time` | string | No | Inclusive campaign creation-time filter start. | | `is_smart_performance_campaign` | boolean | No | Filter by Smart Performance Campaign status. | | `exclude_field_types_in_response` | array | No | Field types to omit from the response. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Catalog Diagnostics **Slug:** `TIKTOK_ADS_LIST_CATALOG_PRODUCT_DIAGNOSTICS` Get one page of synchronous catalog product diagnostic information. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `lang` | string ("ar" | "cs-CZ" | "de" | "en" | "es" | "fil" | "fr" | "id" | "it" | "ja" | "ko" | "ms" | "pl-PL" | "pt" | "ru" | "sv-SE" | "th" | "tr" | "vi" | "zh") | No | Language for diagnostic text. | | `page` | integer | No | Result page number. | | `bc_id` | string | Yes | Business Center ID that owns the catalog. | | `feed_id` | string | No | Optional catalog feed ID to diagnose. | | `filtering` | object | No | Optional issue severity and category filters. | | `page_size` | integer | No | Issues per page (1-20). | | `catalog_id` | string | Yes | Catalog ID to diagnose. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List Catalogs **Slug:** `TIKTOK_ADS_LIST_CATALOGS` List catalogs in a specified TikTok Business Center, optionally restricted to one catalog ID. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial catalog result page to retrieve. | | `page_size` | integer | No | Maximum catalogs to request in this page (1-1000). | | `catalog_id` | string | No | Catalog ID to return from this list endpoint. | | `next_cursor` | string | No | Continuation token returned by a previous call. Omit it for the first page and pass it back unchanged to fetch the next page. | | `business_center_id` | string | Yes | Authorized Business Center ID whose catalogs to read. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Catalog Videos **Slug:** `TIKTOK_ADS_LIST_CATALOG_VIDEOS` Get one page of uploaded videos from a catalog. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Result page number. | | `bc_id` | string | Yes | Business Center ID that owns the catalog. | | `page_size` | integer | No | Videos per page (1-50). | | `catalog_id` | string | Yes | Catalog ID whose uploaded videos to retrieve. | | `catalog_video_ids` | array | No | Up to 50 catalog video IDs to retrieve. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get comments **Slug:** `TIKTOK_ADS_LIST_COMMENT` Read 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial page number. | | `end_time` | string | Yes | End date in YYYY-MM-DD format. | | `page_size` | integer | No | Page size (1-100). | | `sort_type` | string ("ASC" | "DESC") | No | Sort order. | | `sort_field` | string ("CREATE_TIME" | "LIKES" | "REPLIES") | No | Field to sort by: `CREATE_TIME`, `LIKES`, or `REPLIES`. | | `start_time` | string | Yes | Start date in YYYY-MM-DD format. | | `next_cursor` | string | No | Opaque continuation token from a previous response; omit for the first page. | | `comment_type` | array | No | Comment types: `ALL`, `COMMENT`, or `REPLY`. | | `search_field` | string | Yes | Field to search by; only `ADGROUP_ID` is supported. | | `search_value` | string | Yes | Ad group ID to search for. | | `advertiser_id` | string | Yes | Advertiser ID. | | `comment_status` | array | No | Comment statuses: `ALL`, `HIDDEN`, or `PUBLIC`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get available content exclusion categories **Slug:** `TIKTOK_ADS_LIST_CONTENT_EXCLUSION_CATEGORIES` Get content exclusion and vertical sensitivity categories for an objective. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_id` | string | Yes | Advertiser ID. | | `objective_type` | string ("REACH" | "VIDEO_VIEWS" | "ENGAGEMENT") | Yes | Advertising objective. | | `brand_safety_type` | string ("NO_BRAND_SAFETY" | "EXPANDED_INVENTORY" | "STANDARD_INVENTORY" | "LIMITED_INVENTORY") | No | Brand safety inventory tier. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get available contextual tags **Slug:** `TIKTOK_ADS_LIST_CONTEXTUAL_TAGS` Get contextual tags available for an objective and optional regions. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `region_codes` | array | No | Country or region codes. | | `advertiser_id` | string | Yes | Advertiser ID. | | `objective_type` | string ("REACH" | "VIDEO_VIEWS" | "RF_REACH") | Yes | Advertising objective. | | `rf_campaign_type` | string ("PULSE" | "STANDARD") | No | Reach and Frequency campaign type; only valid for RF_REACH. | | `brand_safety_type` | string ("EXPANDED_INVENTORY" | "LIMITED_INVENTORY" | "NO_BRAND_SAFETY" | "STANDARD_INVENTORY" | "THIRD_PARTY") | No | Brand safety inventory type. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Creative Welcome Messages **Slug:** `TIKTOK_ADS_LIST_CREATIVE_AUTO_MESSAGES` Get one page of welcome messages within a TikTok advertiser account. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | string | No | Initial provider page number (at least 1). | | `page_size` | string | No | Number of welcome messages per page (1-100). | | `next_cursor` | string | No | Opaque continuation token returned by a previous call. | | `advertiser_id` | string | Yes | Advertiser account ID whose welcome messages will be returned. | | `auto_message_id` | string | No | Optional automatic-message ID to retrieve. | | `auto_message_type` | string | Yes | Automatic-message type. The documented value is WELCOME_MESSAGE. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Creative Fatigue Results **Slug:** `TIKTOK_ADS_LIST_CREATIVE_FATIGUE_RESULTS` Get one page of Creative Fatigue Detection results for an ad. This API is available only to allowlisted advertisers. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Result page number. | | `ad_id` | string | Yes | Ad ID whose fatigue results to retrieve. | | `end_date` | string | Yes | Open-interval end date in YYYY-MM-DD in the advertiser time zone. | | `page_size` | integer | No | Results per page (1-500). | | `start_date` | string | Yes | Closed-interval start date in YYYY-MM-DD in the advertiser time zone. | | `advertiser_id` | string | Yes | Advertiser account ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List Creative Portfolios **Slug:** `TIKTOK_ADS_LIST_CREATIVE_PORTFOLIOS` List one provider page of interactive creative portfolios for an advertiser. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial provider page to retrieve. | | `page_size` | integer | No | Maximum portfolios to return in this page (1-100; defaults to 10). | | `next_cursor` | string | No | Opaque continuation token from a previous response; omit for the first page. | | `advertiser_id` | string | Yes | Advertiser ID whose portfolios to list. | | `creative_portfolio_ids` | array | No | Portfolio IDs to include in the filtering object. | | `creative_portfolio_types` | array | No | Valid portfolio types to include in the filtering object. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get CRM Event Sets **Slug:** `TIKTOK_ADS_LIST_CRM` Get CRM Event Sets for an advertiser, optionally filtered by name or ID. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | No | Exact CRM Event Set name to filter by, from 1 to 40 characters. | | `advertiser_id` | string | Yes | Advertiser ID. | | `event_set_ids` | array | No | CRM Event Set IDs to filter by, with at most 50 IDs. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List Custom Audiences **Slug:** `TIKTOK_ADS_LIST_CUSTOM_AUDIENCES` List one page of owned and shared custom audiences for an authorized advertiser, optionally restricted to specified audience IDs. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial custom-audience result page to retrieve. | | `page_size` | integer | No | Maximum audiences to return in this page (1-100). | | `next_cursor` | string | No | Continuation cursor from a previous response. Omit for the first page; pass it back unchanged to fetch the next page. | | `advertiser_id` | string | Yes | Authorized advertiser account ID whose audiences to read. | | `custom_audience_ids` | array | No | Audience IDs to return from this list endpoint (1-100 when supplied). | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Custom Conversions associated with an event source **Slug:** `TIKTOK_ADS_LIST_CUSTOM_CONVERSION` Return one page of Custom Conversions configured for a Pixel or app event source. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial provider page. | | `page_size` | integer | No | Results per page (1-1000). | | `sort_type` | string ("DESC" | "ASC") | No | Ascending or descending order. | | `sort_field` | string ("CREATE_TIME" | "TOTAL_COUNT") | No | Result sorting field. | | `next_cursor` | string | No | Opaque token returned by a previous call. | | `advertiser_id` | string | Yes | Advertiser ID. | | `search_keyword` | string | No | Name fuzzy match or exact ID. | | `event_source_id` | string | Yes | Pixel ID or SAN app platform ID. | | `event_source_type` | string ("PIXEL" | "APP") | Yes | PIXEL or APP event source. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Details of Saved Audiences **Slug:** `TIKTOK_ADS_LIST_DMP_SAVED_AUDIENCE` Return one page of Saved Audience details. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial page number. | | `page_size` | integer | No | Results per page (1-100). | | `next_cursor` | string | No | Opaque cursor from the previous page. | | `advertiser_id` | string | Yes | Advertiser ID. | | `saved_audience_ids` | array | No | Saved Audience IDs to return (maximum 100). | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List GMV Max Campaign Sessions **Slug:** `TIKTOK_ADS_LIST_GMV_MAX_CAMPAIGN_SESSIONS` List 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `campaign_id` | string | Yes | 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. | | `advertiser_id` | string | Yes | Authorized advertiser account ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List GMV Max Customized Posts **Slug:** `TIKTOK_ADS_LIST_GMV_MAX_CUSTOMIZED_POSTS` List one page of shop-level customized TikTok posts for GMV Max. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial result page (at least 1). | | `keyword` | string | No | Post search keyword. To search by item_id, provide a numeric string of at least 19 characters; ordinary text remains a keyword search. | | `store_id` | string | Yes | TikTok Shop store ID. | | `page_size` | integer | No | Number of posts in this page (1-50). | | `sort_type` | string ("ASC" | "DESC") | No | Optional ascending or descending sort direction. | | `sort_field` | string ("GMV" | "POST_TIME" | "VIDEO_VIEWS" | "VIDEO_LIKES" | "CLICK_THROUGH_RATE" | "PRODUCT_CLICKS") | No | Field by which to sort customized posts. | | `campaign_id` | string | No | 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. | | `next_cursor` | string | No | Opaque continuation token from a previous response. | | `spu_id_list` | array | No | Product SPU IDs by which to filter customized posts. | | `advertiser_id` | string | Yes | Authorized advertiser account ID. | | `identity_list` | array | No | Identity filters (maximum 20). | | `creative_source` | string | Yes | Creative source; this endpoint accepts CUSTOMIZED. | | `need_auth_code_video` | boolean | No | Whether to include videos authorized by authorization code. | | `store_authorized_bc_id` | string | Yes | Business Center ID authorized for the TikTok Shop. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List GMV Max Identities **Slug:** `TIKTOK_ADS_LIST_GMV_MAX_IDENTITIES` List identities available to an advertiser for GMV Max campaigns. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `store_id` | string | Yes | TikTok Shop store ID for which to get GMV Max identities. | | `advertiser_id` | string | Yes | Advertiser account ID for which to get GMV Max identities. | | `store_authorized_bc_id` | string | Yes | Business Center ID authorized for the TikTok Shop. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Check GMV Max Occupied Custom Shop Ads **Slug:** `TIKTOK_ADS_LIST_GMV_MAX_OCCUPYING_ADS` Check which Shopping Ads occupy one TikTok Shop identity or product asset. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `store_id` | string | Yes | TikTok Shop store ID containing the identity or product. | | `asset_ids` | array | Yes | Exactly one asset ID to check. For SPU, use a product SPU ID from the specified TikTok Shop. | | `advertiser_id` | string | Yes | Advertiser account ID whose Shopping Ads occupancy to check. | | `occupied_asset_type` | string ("IDENTITY_TT_USER" | "IDENTITY_BC_AUTH_TT" | "IDENTITY_TTS_TT" | "SPU") | Yes | Type of occupied identity or product: IDENTITY_TT_USER, IDENTITY_BC_AUTH_TT, IDENTITY_TTS_TT, or SPU. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List TikTok Shops for GMV Max **Slug:** `TIKTOK_ADS_LIST_GMV_MAX_STORES` List TikTok Shops available to an advertiser for GMV Max campaigns. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_id` | string | Yes | Advertiser account ID for which to list available TikTok Shops. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List GMV Max Videos **Slug:** `TIKTOK_ADS_LIST_GMV_MAX_VIDEOS` List one page of authorized or custom-post-eligible TikTok posts for a Product GMV Max campaign. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial result page (at least 1). | | `keyword` | string | No | 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. | | `store_id` | string | Yes | TikTok Shop store ID. | | `page_size` | integer | No | Number of posts in this page (1-50). | | `sort_type` | string ("ASC" | "DESC") | No | Authorized-post sort direction. Sent together with sort_field when custom_posts_eligible is false or omitted. | | `sort_field` | string ("GMV" | "POST_TIME" | "VIDEO_VIEWS" | "VIDEO_LIKES" | "CLICK_THROUGH_RATE" | "PRODUCT_CLICKS") | No | Authorized-post sort field. Valid only when custom_posts_eligible is false or omitted. | | `next_cursor` | string | No | Opaque continuation token from a previous response. | | `spu_id_list` | array | No | Product SPU IDs. Up to 50 are allowed normally; exactly one is required when custom_posts_eligible is true. | | `advertiser_id` | string | Yes | Authorized advertiser account ID. | | `identity_list` | array | No | Identity filters (maximum 20). | | `need_auth_code_video` | boolean | No | Whether to include videos authorized by authorization code. | | `custom_posts_eligible` | boolean | No | Whether to return only posts eligible for customized-post creation. | | `store_authorized_bc_id` | string | Yes | Business Center ID authorized for the store. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get rules by filters **Slug:** `TIKTOK_ADS_LIST_OPTIMIZER_RULE` Get one page of automated optimizer rules by filters. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial page number. | | `tzone` | string | No | Timezone used for returned date and time fields. | | `filtering` | object | No | Rule filters. | | `page_size` | integer | No | Page size. | | `next_cursor` | string | No | Opaque continuation token from a previous response. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get rule results **Slug:** `TIKTOK_ADS_LIST_OPTIMIZER_RULE_RESULT` Get one page of automated optimizer rule results. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `lang` | string ("EN" | "ZH" | "JA") | No | Language of error messages. | | `page` | integer | No | Initial page number. | | `filtering` | object | No | Rule-result filters. | | `page_size` | integer | No | Page size. | | `next_cursor` | string | No | Opaque continuation token from a previous response. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List Pangle Audience Packages **Slug:** `TIKTOK_ADS_LIST_PANGLE_AUDIENCE_PACKAGES` List the include and exclude audience packages available for an advertiser's Pangle targeting configuration. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_id` | string | Yes | Advertiser ID whose Pangle audience packages to retrieve. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get phone region codes **Slug:** `TIKTOK_ADS_LIST_PHONE_REGION_CODES` Get region names, region codes, and calling codes for phone numbers. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Pixels **Slug:** `TIKTOK_ADS_LIST_PIXEL` Return one page of Pixels and their configured Pixel Events. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `code` | string | No | Exact Pixel Code filter. | | `name` | string | No | Fuzzy Pixel name filter. | | `page` | integer | No | Initial provider page. | | `order_by` | string ("EARLIEST_CREATE" | "LATEST_CREATE") | No | Creation-time sorting order. | | `pixel_id` | string | No | Exact Pixel ID filter. | | `filtering` | object | No | Additional Pixel filters. | | `page_size` | integer | No | Pixels per page (1-20). | | `next_cursor` | string | No | Opaque token returned by a previous call. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Recommended Search Keywords **Slug:** `TIKTOK_ADS_LIST_RECOMMENDED_SEARCH_KEYWORDS` Requires a TikTok Business Account token issued by /tt_user/oauth2/token/. The advertiser OAuth connection used by this toolkit cannot call this endpoint. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `query` | string | Yes | Product, service, or brand query used to recommend search keywords. | | `business_id` | string | Yes | Application-specific Business Account identifier (open_id). | | `is_personalized` | boolean | No | Whether to personalize the recommended keywords for the Business Account. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List Search Ad Negative Keywords **Slug:** `TIKTOK_ADS_LIST_SEARCH_AD_NEGATIVE_KEYWORDS` List one page of negative keywords for a campaign or ad group in an authorized advertiser account. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial result page to retrieve. | | `object_id` | string | Yes | Campaign or ad-group ID whose keywords to read. | | `page_size` | integer | No | Maximum negative keywords to return in this page (1-50). | | `next_cursor` | string | No | Opaque continuation token from a previous call; omit for the first page. | | `object_type` | string ("CAMPAIGN" | "ADGROUP") | Yes | Whether object_id identifies a campaign or ad group. | | `advertiser_id` | string | Yes | Authorized advertiser account ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Showcase Products **Slug:** `TIKTOK_ADS_LIST_SHOWCASE_PRODUCTS` Get one page of products available in a Showcase. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial result page to retrieve. | | `filtering` | object | No | Optional product SPU filter. | | `page_size` | integer | No | Products in this page (1-1000). | | `identity_id` | string | Yes | ID of the identity bound to the Showcase. | | `next_cursor` | string | No | Opaque continuation token from a previous call; omit for the first page. | | `region_codes` | array | Yes | Country or region codes in which the products will be targeted. | | `advertiser_id` | string | Yes | Authorized advertiser account ID. | | `identity_type` | string ("TT_USER" | "BC_AUTH_TT") | Yes | Showcase identity type: TT_USER or BC_AUTH_TT. | | `identity_authorized_bc_id` | string | No | Business Center ID; required when identity_type is BC_AUTH_TT. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Showcase Regions **Slug:** `TIKTOK_ADS_LIST_SHOWCASE_REGIONS` Get the regions targetable by a Showcase-bound identity. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `identity_id` | string | Yes | ID of the identity bound to the Showcase. | | `advertiser_id` | string | Yes | Authorized advertiser account ID. | | `identity_type` | string ("TT_USER" | "BC_AUTH_TT") | Yes | Showcase identity type: TT_USER or BC_AUTH_TT. | | `identity_authorized_bc_id` | string | No | Business Center ID; required when identity_type is BC_AUTH_TT. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Smart+ Ad Groups **Slug:** `TIKTOK_ADS_LIST_SMART_PLUS_ADGROUPS` List 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial result page. | | `fields` | array | No | 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. | | `page_size` | integer | No | Page size (1-1000). | | `adgroup_ids` | array | No | Ad group ID filter. | | `next_cursor` | string | No | Continuation token from a prior call. | | `adgroup_name` | string | No | Ad group name filter. | | `campaign_ids` | array | No | Campaign ID filter. | | `advertiser_id` | string | Yes | Advertiser ID whose Smart+ ad groups to read. | | `objective_type` | string ("APP_PROMOTION" | "LEAD_GENERATION" | "WEB_CONVERSIONS") | No | Objective filter. | | `primary_status` | string ("STATUS_ALL" | "STATUS_DELETE" | "STATUS_DELIVERY_OK" | "STATUS_DISABLE" | "STATUS_FROZEN" | "STATUS_NOT_DELETE" | "STATUS_NOT_DELIVERY" | "STATUS_RF_CLOSED" | "STATUS_TIME_DONE") | No | Primary status filter. | | `promotion_type` | 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") | No | Promotion type filter. | | `secondary_status` | 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") | No | Secondary delivery-status filter. | | `optimization_goal` | 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") | No | Optimization goal filter. | | `creation_filter_end_time` | string | No | Creation-time filter end. | | `creation_filter_start_time` | string | No | Creation-time filter start. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Smart+ Ads **Slug:** `TIKTOK_ADS_LIST_SMART_PLUS_ADS` List Smart+ ad details through TikTok's dedicated /smart_plus/ad/get/ endpoint. Select this instead of LIST_ADS for an exact Smart+ endpoint read; use LIST_ADS for regular or mixed-automation inventory. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial result page. | | `fields` | array | No | 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. | | `page_size` | integer | No | Page size (1-100). | | `adgroup_ids` | array | No | Ad group ID filter. | | `next_cursor` | string | No | Continuation token from a prior call. | | `campaign_ids` | array | No | Campaign ID filter. | | `advertiser_id` | string | Yes | Advertiser ID whose Smart+ ads to read. | | `modified_after` | string | No | Modification-time lower bound. | | `objective_type` | string ("APP_PROMOTION" | "LEAD_GENERATION" | "WEB_CONVERSIONS") | No | Objective filter. | | `primary_status` | 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") | No | Primary status filter. | | `secondary_status` | 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") | No | Secondary status filter. | | `optimization_goal` | 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") | No | Optimization goal filter. | | `smart_plus_ad_ids` | array | No | Smart+ ad ID filter. | | `creation_filter_end_time` | string | No | Creation-time filter end. | | `creation_filter_start_time` | string | No | Creation-time filter start. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Smart+ Campaigns **Slug:** `TIKTOK_ADS_LIST_SMART_PLUS_CAMPAIGNS` List 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Result page number. | | `fields` | array | No | 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. | | `filtering` | object | No | Optional Smart+ campaign filters. | | `page_size` | integer | No | Maximum results on this page (1-1000). | | `next_cursor` | string | No | Opaque continuation token from a previous response; omit for the first page. | | `advertiser_id` | string | Yes | Authorized advertiser account ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get available stores under an ad account **Slug:** `TIKTOK_ADS_LIST_STORE` Get available TikTok Shops under an ad account. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `store_id` | string | No | TikTok Shop ID by which to filter. | | `store_type` | string | No | Store type; the documented value is TIKTOK_SHOP. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get carriers **Slug:** `TIKTOK_ADS_LIST_TARGETABLE_CARRIERS` Get carriers available for ad targeting by country or region. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get device models **Slug:** `TIKTOK_ADS_LIST_TARGETABLE_DEVICE_MODELS` Get device models available for ad targeting. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get internet service providers **Slug:** `TIKTOK_ADS_LIST_TARGETABLE_ISPS` Get ISP targeting tags supported for specified country- or region-level locations. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `scene` | string | Yes | Targeting scene; this endpoint supports ISP targeting. | | `location_ids` | array | Yes | Country- or region-level location IDs whose supported ISPs to return (maximum 1,000). | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get languages **Slug:** `TIKTOK_ADS_LIST_TARGETABLE_LANGUAGES` Get languages available for ad targeting. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get OS versions **Slug:** `TIKTOK_ADS_LIST_TARGETABLE_OS_VERSIONS` Get operating-system versions available for targeting. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `os_type` | string ("ANDROID" | "IOS") | Yes | Operating system type. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get targeting regions **Slug:** `TIKTOK_ADS_LIST_TARGETABLE_REGIONS` Get locations available for an advertiser's placement, objective, and campaign settings. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `language` | string | No | Language for returned location names. | | `placements` | array | Yes | Apps where ads will be delivered. | | `level_range` | string ("ALL" | "TO_COUNTRY" | "TO_PROVINCE" | "TO_CITY" | "TO_DISTRICT") | No | Deepest administrative location level to return. | | `advertiser_id` | string | Yes | Advertiser ID. | | `objective_type` | string | Yes | Campaign objective type. | | `promotion_type` | string | No | Promotion type or optimization location. | | `operating_system` | string ("ANDROID" | "IOS") | No | Target device operating system. | | `rf_campaign_type` | string ("STANDARD" | "PULSE") | No | Reach-and-frequency campaign type when objective_type is RF_REACH. | | `brand_safety_type` | string ("NO_BRAND_SAFETY" | "EXPANDED_INVENTORY" | "STANDARD_INVENTORY" | "LIMITED_INVENTORY" | "THIRD_PARTY") | No | Brand safety inventory type for TikTok placement. | | `shopping_ads_type` | string ("VIDEO" | "LIVE" | "PRODUCT_SHOPPING_ADS") | No | Shopping ads type for PRODUCT_SALES objectives. | | `app_promotion_type` | string ("APP_INSTALL" | "APP_RETARGETING" | "APP_PREREGISTRATION" | "MINIS") | No | Required for APP_PROMOTION objectives. | | `brand_safety_partner` | string ("IAS" | "OPEN_SLATE") | No | Required when brand_safety_type is THIRD_PARTY. | | `promotion_target_type` | string ("INSTANT_PAGE" | "EXTERNAL_WEBSITE") | No | Lead-generation promotion target type. | | `search_campaign_enabled` | boolean | No | Whether this is an upgraded Smart+ Search Ads campaign. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get action categories **Slug:** `TIKTOK_ADS_LIST_TARGETING_ACTION_CATEGORIES` Get targeting action categories available to an advertiser. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `language` | string ("en" | "zh" | "ja" | "de" | "es" | "fr" | "id" | "it" | "ko" | "ru" | "th" | "tr" | "vi" | "ar" | "pt" | "ms") | No | Language for category names. | | `advertiser_id` | string | Yes | Advertiser ID. | | `special_industries` | array | No | Special ad categories to filter for. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get interest categories **Slug:** `TIKTOK_ADS_LIST_TARGETING_INTEREST_CATEGORIES` Get advertiser interest categories, optionally filtered by placement and special industry. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `version` | integer ("1" | "2") | No | Interest category version: 1 for interest_category or 2 for interest_category_v2. | | `language` | string ("en" | "zh" | "ja" | "de" | "es" | "fr" | "id" | "it" | "ko" | "ru" | "th" | "tr" | "vi" | "ar" | "pt" | "ms") | No | Language for returned category names. | | `placements` | array | No | Placements whose version-2 interest categories to return. | | `advertiser_id` | string | Yes | Advertiser ID. | | `special_industries` | array | No | Special ad categories to filter for. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List Ad Accounts Linked to TikTok Account **Slug:** `TIKTOK_ADS_LIST_TIKTOK_LINKED_AD_ACCOUNTS` List one page of ad accounts linked to one TikTok account asset in a Business Center. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial result page to retrieve. | | `asset_id` | string | Yes | TikTok account asset ID whose linked ad accounts to list. | | `page_size` | integer | No | Maximum assigned TikTok accounts to return in this page (1-50). | | `asset_type` | string ("TT_ACCOUNT" | "MANAGED_BUSINESS_ACCOUNT") | Yes | TikTok account asset type: TT_ACCOUNT or MANAGED_BUSINESS_ACCOUNT. | | `next_cursor` | string | No | Opaque continuation token returned by a previous call; omit for the first page and pass it back unchanged for the next page. | | `business_center_id` | string | Yes | Business Center ID that owns the TikTok account asset. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Trending Catalog Products **Slug:** `TIKTOK_ADS_LIST_TRENDING_CATALOG_PRODUCTS` Get up to 50 trending products from an eligible E-commerce catalog. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID that owns the catalog. | | `filtering` | object | No | Optional category, brand, or availability filters. | | `catalog_id` | string | Yes | E-commerce catalog ID containing at least 20 products. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List Trending Videos for Commercial Music **Slug:** `TIKTOK_ADS_LIST_TRENDING_CML_VIDEOS` Requires a TikTok Business Account token issued by /tt_user/oauth2/token/. The advertiser OAuth connection used by this toolkit cannot call this endpoint. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `business_id` | string | Yes | Application-specific TikTok Business Account ID (OAuth open_id). | | `country_code` | string | No | Location code used to select regional trends. | | `commercial_music_id` | string | Yes | Commercial Music Library track ID whose trending videos to retrieve. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List Trending Commercial Music **Slug:** `TIKTOK_ADS_LIST_TRENDING_COMMERCIAL_MUSIC` Requires a TikTok Business Account token issued by /tt_user/oauth2/token/. The advertiser OAuth connection used by this toolkit cannot call this endpoint. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `genre` | string ("ALL" | "ROCK" | "POP" | "LATIN" | "METAL" | "ELECTRONIC" | "HIP_HOP/RAP" | "ALTERNATIVE/INDIE" | "FOLK" | "R&B/SOUL" | "COUNTRY" | "CLASSICAL" | "JAZZ" | "REGGAE" | "CHILDHOOD" | "BLUES" | "EASY_LISTENING" | "NEW_AGE" | "WORLD_MUSIC" | "EXPERIMENTAL" | "DEVOTIONAL" | "CHINESE_TRADITION" | "8_BIT" | "A_CAPPELLA" | "AFRO-POP" | "ALTERNATIVE_HIP_HOP" | "ALTERNATIVE_ROCK" | "AMBIENT" | "ARABIC_POP" | "BASS_HOUSE" | "BGM" | "BOOMBAP" | "BOSSA_NOVA" | "BRAZILIAN_FUNK_STYLE" | "BUDDHIST_MUSIC" | "CANTOPOP" | "CELTIC_POP" | "CHAMBER_MUSIC" | "CHILL_BEATS" | "CHILLOUT" | "CHINESE_FOLK" | "CHINESE_OPERA" | "CHINESE_POP" | "CHINESE_STYLE" | "CHINOISERIE_ELECTRONIC" | "CHINOISERIE_RAP" | "CHRISTIAN_MUSIC" | "CONTEMPORARY_R&B" | "COUNTRY_POP" | "DANCE_POP" | "DISCO" | "DJ" | "DRUM&BASS" | "DUBSTEP" | "EDM" | "EDM_TRAP" | "ELECTRO_POP" | "EPIC" | "FOLK_POP" | "FUNK" | "FUTURE_BASS" | "GOSPEL" | "GUFENG_MUSIC" | "HARD_ROCK" | "HIP_HOUSE" | "HOLIDAY_MUSIC" | "HOUSE" | "INDIAN_POP" | "INDIE_FOLK" | "INDIE_POP" | "INDIE_ROCK" | "INSTRUMENTAL_HIP_HOP" | "INSTRUMENTAL_ROCK" | "IRISH_FOLK" | "J_ROCK" | "JAPANESE_TRADITIONAL_MUSIC" | "JAZZ_FUSION" | "JAZZ_HIP_HOP" | "JAZZ_POP" | "J-POP" | "K-POP" | "LATIN_POP" | "LO-FI" | "MC" | "NOISE" | "OLD_SCHOOL" | "OTHERS" | "POP_RAP" | "POP_ROCK" | "POP_SOUL" | "PSYCHEDELIC_ROCK" | "PUNK" | "R&B_RAP" | "REGGAETON" | "RUSSIAN_POP" | "SERTANEJO" | "SON_CUBANO" | "SOUL" | "SOUNDTRACK" | "SYMPHONY" | "SYNTH_POP" | "TANGO" | "TECHNO" | "TEEN_POP" | "TRADITIONAL_CHINESE_FOLK" | "TRANCE" | "TRAP_RAP" | "TRIP_HOP" | "TROPICAL_HOUSE" | "TURKISH_POP") | No | Commercial Music Library genre to return. | | `date_range` | string ("1DAY" | "7DAY" | "30DAY" | "90DAY") | No | Timeframe in which tracks were popular. | | `business_id` | string | Yes | Application-specific TikTok Business Account ID (OAuth open_id). | | `country_code` | string | No | Location code used to select regional trends. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Trending Search Keywords **Slug:** `TIKTOK_ADS_LIST_TRENDING_SEARCH_KEYWORDS` Requires a TikTok Business Account token issued by /tt_user/oauth2/token/. The advertiser OAuth connection used by this toolkit cannot call this endpoint. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `business_id` | string | Yes | Application-specific Business Account identifier (open_id). | | `is_personalized` | boolean | No | Whether to personalize the trending keywords for the Business Account. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Spark Ad Posts **Slug:** `TIKTOK_ADS_LIST_TT_VIDEO` Return 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial provider page number. | | `keyword` | string | No | Fuzzy post-text search or exact post ID search. | | `page_size` | integer | No | Posts per page (1-50). | | `item_types` | array | No | Post types to include; defaults upstream to VIDEO and CAROUSEL. | | `next_cursor` | string | No | Opaque continuation cursor from the previous response; omit for the first page. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Migrate a catalog to a BC **Slug:** `TIKTOK_ADS_MIGRATE_CATALOG` Migrate a catalog from an ad account to a Business Center. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | ID of the Business Center to migrate the catalog to. | | `catalog_id` | string | Yes | ID of the catalog to migrate. | | `advertiser_id` | string | Yes | ID of the ad account that owns the catalog. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Run the winning ad group **Slug:** `TIKTOK_ADS_PROMOTE_SPLIT_TEST` End a split test by promoting its selected winning ad group and starting that ad group's delivery, which may incur spend. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_id` | string | Yes | Advertiser ID. | | `winning_object_id` | string | Yes | Winning ad group ID to run. | | `split_test_group_id` | string | Yes | Split test group ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Query contracts **Slug:** `TIKTOK_ADS_QUERY_RF_CONTRACT` Read 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_id` | string | Yes | Advertiser ID | | `included_date` | string | Yes | A certain date within the contract validity, or the start/end time of an ad group. Format: "2020-09-18". | | `rf_campaign_type` | string ("STANDARD" | "PULSE") | No | 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get a suggested bid **Slug:** `TIKTOK_ADS_RECOMMEND_BID` Get a suggested bid for an objective and target locations. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `campaign_id` | string | No | Campaign ID; use 0 when no campaign exists yet. | | `location_ids` | array | Yes | IDs of locations to target. | | `advertiser_id` | string | Yes | Advertiser ID. | | `objective_type` | string ("APP_PROMOTION" | "ENGAGEMENT" | "LEAD_GENERATION" | "PRODUCT_SALES" | "REACH" | "RF_REACH" | "TRAFFIC" | "VIDEO_VIEWS" | "WEB_CONVERSIONS") | Yes | TikTok campaign objective. | | `external_action` | 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") | No | TikTok conversion-event code for the ad group. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Recommend additional interest categories **Slug:** `TIKTOK_ADS_RECOMMEND_INTEREST_CATEGORIES` Recommend additional interest categories from one or more seed keywords. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `mode` | string ("FUZZ_MATCH" | "SEMANTIC_RECOMMEND") | No | Recommendation search mode. | | `limit` | integer | No | Maximum recommendations to return (1-50). | | `keyword` | string | No | Single seed keyword; ignored upstream when keywords is supplied. | | `keywords` | array | No | Seed keywords processed separately (maximum 10). | | `language` | string ("fr" | "id" | "it" | "ja" | "ms" | "ar" | "vi" | "en" | "ru" | "es" | "th" | "tr" | "hi" | "zh" | "de" | "ko") | No | Seed keyword language. | | `advertiser_id` | string | Yes | Advertiser ID. | | `audience_type` | string ("GENERAL_INTEREST" | "PURCHASE_INTENTION") | No | Audience type; PURCHASE_INTENTION is deprecated. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get recommended search keywords **Slug:** `TIKTOK_ADS_RECOMMEND_SEARCH_KEYWORDS` Get one page of recommended search keywords from exactly one seed type. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial provider page number. | | `ad_ids` | array | No | Single ad ID seed. | | `regions` | array | Yes | Target regions; currently only US is supported. | | `page_size` | integer | No | Maximum recommendations in this page. | | `order_type` | string ("ASC" | "DESC") | No | Sorting order when ordering by monthly searches. | | `total_size` | integer | No | Maximum total recommendation pool size. | | `next_cursor` | string | No | Opaque continuation token from a previous call; omit for the first page. | | `order_field` | string ("RELEVANCE" | "MONTHLY_SEARCHES") | No | Field used to sort recommendations. | | `advertiser_id` | string | Yes | Advertiser ID. | | `search_queries` | array | No | One to five search-query seeds. | | `landing_page_urls` | array | No | One to five landing-page URL seeds. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Recommend targeting categories **Slug:** `TIKTOK_ADS_RECOMMEND_TARGETING_CATEGORIES` Recommend interest and action targeting categories for specified regions and an optional app. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `app_id` | string | No | Optional mobile app ID when promoting an app. | | `region_codes` | array | Yes | Country or region codes for recommendations. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Search for targeting hashtags **Slug:** `TIKTOK_ADS_RECOMMEND_TARGETING_HASHTAGS` Generate targeting hashtag recommendations from up to ten seed keywords. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `keywords` | array | Yes | Seed keywords for hashtag recommendations (maximum 10). | | `operator` | string ("AND" | "OR") | No | Whether recommendations combine all keywords or process each separately. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Reply to a comment **Slug:** `TIKTOK_ADS_REPLY_TO_COMMENT` Publish a public reply as the specified TikTok identity. Confirm the account, target comment, identity, and final text before calling; the reply is externally visible. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `text` | string | Yes | Public reply text to publish. | | `ad_id` | string | Yes | Ad ID associated with the target comment. | | `comment_id` | string | Yes | Comment ID to reply to. | | `identity_id` | string | Yes | Identity ID that will publish the reply. | | `comment_type` | string | Yes | Comment-post type. TikTok currently supports only `REPLY`. | | `advertiser_id` | string | Yes | Advertiser ID that owns the ad. | | `identity_type` | string ("CUSTOMIZED_USER" | "TT_USER") | Yes | Publishing identity type: `CUSTOMIZED_USER` or `TT_USER`. | | `tiktok_item_id` | string | Yes | TikTok video ID containing the target comment. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Save a playable asset **Slug:** `TIKTOK_ADS_SAVE_PLAYABLE` Save and name a previously uploaded playable asset for an advertiser. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `playable_id` | string | Yes | Uploaded playable asset ID to save. | | `advertiser_id` | string | Yes | Advertiser ID that owns the uploaded playable. | | `playable_name` | string | Yes | Playable asset name (1-20 characters). | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Search for images **Slug:** `TIKTOK_ADS_SEARCH_FILE_IMAGE_AD` Search for one page of advertiser images and return a continuation cursor. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial provider page. | | `filtering` | object | No | Image filters. Resubmit this value with a continuation cursor. | | `page_size` | integer | No | Images per page (1-100). | | `next_cursor` | string | No | Opaque continuation token from a previous call. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Search for videos **Slug:** `TIKTOK_ADS_SEARCH_FILE_VIDEO_AD` Search for one page of advertiser videos and return a continuation cursor. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | integer | No | Initial provider page. | | `filtering` | object | No | Video filters. Resubmit this value with a continuation cursor. | | `page_size` | integer | No | Videos per page (1-100). | | `sort_field` | string ("CREATE_TIME" | "MODIFY_TIME") | No | Descending sort field. | | `next_cursor` | string | No | Opaque continuation token from a previous call. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Search or list interest and behavior targeting **Slug:** `TIKTOK_ADS_SEARCH_TARGETING` Search for or list targeting categories and hashtags for interests and behaviors. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `language` | string | No | Language of the seed keywords; defaults upstream to en. | | `filtering` | object | No | Optional special-industry filters. | | `advertiser_id` | string | Yes | Advertiser ID. | | `targeting_type` | string | Yes | Primary targeting type; only INTEREST_AND_BEHAVIOR is supported. | | `search_keywords` | array | No | Seed keywords, each at most 100 characters. | | `sub_targeting_types` | array | No | Secondary interest and behavior targeting types to return. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Search targeting tags **Slug:** `TIKTOK_ADS_SEARCH_TARGETING_LOCATIONS` Search geographical targeting tags by location, ZIP-code, or postal-code keywords. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `keywords` | array | Yes | Location, ZIP-code, or postal-code search terms. | | `geo_types` | array | No | Location types to include in search results. | | `placements` | array | Yes | Apps where ads will be delivered. | | `search_type` | string ("FUZZY_SEARCH" | "BATCH_REGION_SEARCH" | "BATCH_ZIPCODE_SEARCH") | Yes | Fuzzy single search or batch region/ZIP-code search mode. | | `region_codes` | array | No | Country or region codes used to constrain results. | | `advertiser_id` | string | Yes | Advertiser ID. | | `objective_type` | string ("REACH" | "TRAFFIC" | "VIDEO_VIEWS" | "LEAD_GENERATION" | "ENGAGEMENT" | "APP_PROMOTION" | "WEB_CONVERSIONS" | "PRODUCT_SALES") | Yes | Campaign objective. | | `promotion_type` | string | No | Promotion type required for applicable objectives. | | `operating_system` | string ("ANDROID" | "IOS") | No | Target device operating system. | | `brand_safety_type` | string ("NO_BRAND_SAFETY" | "EXPANDED_INVENTORY" | "STANDARD_INVENTORY" | "LIMITED_INVENTORY" | "THIRD_PARTY") | No | Brand safety type for TikTok placement. | | `brand_safety_partner` | string ("IAS" | "OPEN_SLATE") | No | Required with THIRD_PARTY brand safety. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create or Delete an Audience Segment **Slug:** `TIKTOK_ADS_SET_AUDIENCE_SEGMENT` Create a named audience segment or delete one by audience ID. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `action` | string ("create" | "delete") | Yes | Create or delete an audience segment. | | `advertiser_id` | string | Yes | Advertiser ID. | | `delete_audience_id` | string | No | Audience ID, required for delete. | | `custom_audience_name` | string | No | Audience name, required for create. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Set Search Ad Negative Keywords **Slug:** `TIKTOK_ADS_SET_SEARCH_AD_NEGATIVE_KEYWORDS` Set 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `replace` | boolean | No | 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. | | `keywords` | array | Yes | Negative keywords to add. | | `object_ids` | array | Yes | Campaign or ad-group IDs to receive the keywords. | | `object_type` | string ("CAMPAIGN" | "ADGROUP") | Yes | Whether object_ids identify campaigns or ad groups. | | `advertiser_id` | string | Yes | Authorized advertiser account ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Set Smart+ Delivery Status **Slug:** `TIKTOK_ADS_SET_SMART_PLUS_DELIVERY_STATUS` Enable or disable up to 20 Smart+ campaigns, ad groups, or ads. Enabling resources may start ad delivery and spend. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `resource_ids` | array | Yes | Smart+ campaign, ad group, or ad IDs to update (1-20). | | `advertiser_id` | string | Yes | Advertiser ID that owns the resources. | | `resource_type` | string ("CAMPAIGN" | "ADGROUP" | "AD") | Yes | Type of Smart+ resource identified by resource_ids. | | `operation_status` | string ("DISABLE" | "ENABLE") | Yes | Delivery operation to apply: ENABLE or DISABLE. | | `postback_window_mode` | string ("POSTBACK_WINDOW_MODE1" | "POSTBACK_WINDOW_MODE2" | "POSTBACK_WINDOW_MODE3" | "UNSET") | No | Optional campaign postback window mode; valid only for CAMPAIGN. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Share Creative Assets **Slug:** `TIKTOK_ADS_SHARE_CREATIVE_ASSETS` Share controlled creative assets from one advertiser with specified target advertiser accounts. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `asset_type` | string ("VIDEO" | "IMAGE" | "MUSIC") | No | Type of creative assets being shared. | | `material_ids` | array | Yes | Material IDs to share (1-20). | | `advertiser_id` | string | Yes | Source advertiser ID that controls the assets. | | `shared_advertiser_ids` | array | Yes | Target advertiser IDs that will receive the assets (1-10). | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Share Custom Audiences **Slug:** `TIKTOK_ADS_SHARE_CUSTOM_AUDIENCES` Share up to ten custom audiences with up to ten advertisers in the same Business Center. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `context_info` | object | No | Optional operation context. | | `advertiser_id` | string | Yes | Operator advertiser ID. | | `custom_audience_ids` | array | Yes | Custom audience IDs to share (1-10). | | `shared_advertiser_ids` | array | Yes | Recipient advertisers in the same Business Center (1-10). | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Submit a verification request for your account **Slug:** `TIKTOK_ADS_SUBMIT_ACCOUNT_VERIFICATION` Submit 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | No | Business Center ID. Provide this or advertiser_id, but not both. | | `advertiser_id` | string | No | Ad account ID. Provide this or bc_id, but not both. | | `business_form` | object | No | Business verification details. Provide one form only. | | `individual_form` | object | No | Individual identity verification details. Provide one form only. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Submit Smart Text feedback **Slug:** `TIKTOK_ADS_SUBMIT_CREATIVE_SMART_TEXT` Submit 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Number of texts to generate (1-20). | | `keywords` | array | No | Keywords; required for CUSTOMIZED parameters. | | `language` | string ("EN" | "JA" | "RU" | "VI") | No | Language; required for CUSTOMIZED parameters. | | `adgroup_id` | string | Yes | Ad group ID. | | `param_type` | string ("RECOMMENDED" | "CUSTOMIZED") | No | Whether TikTok predicts or the caller supplies recommendation parameters. | | `industry_id` | string | No | Industry ID. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Submit UnionPay Verification **Slug:** `TIKTOK_ADS_SUBMIT_UNIONPAY_VERIFICATION` Submit identity and UnionPay account details to verify an eligible business license. This starts a sensitive review with no documented rollback. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_id` | string | Yes | Ad account ID created with the business license being verified. | | `unionpay_account` | string | Yes | UnionPay account number containing 12-19 digits. | | `representative_id` | string | Yes | Identity document number in the format required for its document type. | | `business_center_id` | string | Yes | Business Center ID that owns the ad account being verified. | | `representative_name` | string | Yes | Legal representative name on the identity document. | | `representative_phone_number` | string | Yes | Legal representative's phone number containing exactly 11 digits. | | `representative_document_type` | string ("ID_CARD" | "PASSPORT" | "HK_MACAO_EXIT_ENTRY_PERMIT" | "TAIWAN_MAINLAND_TRAVEL_PERMIT" | "HK_MACAO_MAINLAND_TRAVEL_PERMIT") | No | Type of the legal representative's identity document. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create a subscription **Slug:** `TIKTOK_ADS_SUBSCRIBE_SUBSCRIPTION` Create a webhook subscription for a developer application and external callback URL. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `app_id` | string | Yes | Developer application ID from My Apps. | | `secret` | string | Yes | Developer application secret from My Apps. | | `callback_url` | string | Yes | Public webhook callback URL. | | `subscribe_entity` | string ("REPORT_DATA_CHANGE" | "AD_ACCOUNT_SUSPENSION" | "LEAD" | "AD_GROUP" | "AD" | "TCM_VIDEOS" | "CREATIVE_FATIGUE" | "API_SERVICE_STATUS") | Yes | Object whose events will be delivered. | | `subscription_detail` | object | Yes | Entity-specific subscription details. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Process a payment **Slug:** `TIKTOK_ADS_TRANSFER_BC` Irreversibly 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `request_id` | string | No | Idempotency request ID. Reusing it prevents duplicate processing; ad-account idempotency is allowlist-only and guaranteed for 30 minutes. | | `amount_info` | object | No | Detailed cash, voucher, or credit amounts, valid only at ADVERTISER level. | | `cash_amount` | number | No | Positive cash or credit amount, rounded to two decimal places. | | `child_bc_id` | string | No | Child Business Center ID supported by the SDK request contract. | | `grant_amount` | number | No | Positive voucher amount, rounded to two decimal places; unsupported at BC level. | | `advertiser_id` | string | No | Ad account ID, required at ADVERTISER level. | | `transfer_type` | string ("RECHARGE" | "REFUND") | Yes | Payment operation. `RECHARGE` adds funds or credit; `REFUND` deducts funds or credit. | | `transfer_level` | string ("ADVERTISER" | "BC") | No | ADVERTISER moves funds for an ad account; BC changes Business Center credit balance. | | `payment_portfolio_id` | string | No | Payment Portfolio ID, required when the client has multiple portfolios. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Transfer a pixel from advertiser to BC **Slug:** `TIKTOK_ADS_TRANSFER_BC_PIXEL` Permanently 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Destination Business Center ID. | | `pixel_code` | string | Yes | Pixel code to transfer. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Migrate leads to a Business Center **Slug:** `TIKTOK_ADS_TRANSFER_PAGE_LIBRARY` Migrate an advertiser's leads into a newly created Business Center form library. Confirm both account IDs before changing lead ownership location. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID to migrate the advertiser's leads to. | | `advertiser_id` | string | Yes | ID of the advertiser that owns the leads. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Unassign an asset **Slug:** `TIKTOK_ADS_UNASSIGN_BC_ASSET` Revoke 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `user_id` | string | Yes | Business Center user ID losing access. | | `asset_id` | string | Yes | Asset ID whose member access will be revoked. | | `asset_type` | string ("ADVERTISER" | "CATALOG" | "LEAD" | "TT_ACCOUNT" | "MANAGED_BUSINESS_ACCOUNT") | Yes | Type of the asset. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Unassign TikTok Account From Advertiser **Slug:** `TIKTOK_ADS_UNASSIGN_TIKTOK_ACCOUNT_FROM_ADVERTISER` Unlink a TikTok account from an ad account in the same Business Center. This destructively removes the existing account association. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID that owns the TikTok account asset. | | `asset_id` | string | Yes | TikTok account asset ID to unlink from the advertiser. | | `asset_type` | string ("TT_ACCOUNT" | "MANAGED_BUSINESS_ACCOUNT") | Yes | TikTok account asset type: TT_ACCOUNT or MANAGED_BUSINESS_ACCOUNT. | | `advertiser_id` | string | Yes | ID of an ad account in the same Business Center from which to unlink the TikTok account. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Unbind an event source from a catalog **Slug:** `TIKTOK_ADS_UNBIND_CATALOG_EVENTSOURCE` Unbind a mobile app, website Pixel, or both from a catalog. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `app_id` | string | No | Mobile app ID to unbind. | | `catalog_id` | string | Yes | Catalog ID. | | `pixel_code` | string | No | Website Pixel code to unbind. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Unbind a Spark Ad Post **Slug:** `TIKTOK_ADS_UNBIND_TT_VIDEO` Irreversibly 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `item_id` | string | Yes | Exact Spark post ID to unbind. | | `advertiser_id` | string | Yes | Advertiser ID currently bound to the Spark post. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Cancel a subscription **Slug:** `TIKTOK_ADS_UNSUBSCRIBE_SUBSCRIPTION` Irreversibly cancel a developer-app webhook subscription. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `app_id` | string | Yes | Developer application ID from My Apps. | | `secret` | string | Yes | Developer application secret from My Apps. | | `subscription_id` | string | Yes | Subscription ID returned by the subscription endpoints. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update ads **Slug:** `TIKTOK_ADS_UPDATE_AD` Update ordinary ads and their documented creative fields. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `creatives` | array | Yes | Ads and creative fields to update; each object requires ad_id. | | `adgroup_id` | string | Yes | Ad group ID. | | `patch_update` | boolean | No | Whether to apply a patch-style update. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update an ad group **Slug:** `TIKTOK_ADS_UPDATE_ADGROUP` Update an ad group. Some changes are irreversible: FROZEN permanently terminates the ad group, and is_hfss can change from false to true but not back to false. Availability may depend on TikTok allowlisting or account entitlement. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `budget` | number | No | 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` . | | `gender` | string | No | Gender that you want to target. Enum: `GENDER_FEMALE`,`GENDER_MALE`,`GENDER_UNLIMITED` | | `pacing` | string | No | 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. | | `actions` | array | No | A list of targeting behavioral category objects. | | `is_hfss` | boolean | No | 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. | | `isp_ids` | array | No | 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`). | | `bid_type` | string | No | 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`). | | `roas_bid` | number | No | 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. | | `bid_price` | number | No | 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. | | `frequency` | integer | No | 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". | | `languages` | array | No | 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. | | `adgroup_id` | string | Yes | Ad group ID. | | `age_groups` | array | No | 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. | | `dayparting` | string | No | 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. | | `carrier_ids` | array | No | 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. | | `zipcode_ids` | array | No | 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. | | `adgroup_name` | string | No | Ad group name, maximum character allowed is 512 and it cannot contain emoji. | | `audience_ids` | array | No | An list of audience IDs. You can get audience IDs by using the /dmp/custom_audience/list/ endpoint. | | `deep_cpa_bid` | number | No | Specify bid price in this field after you've chosen a bidding strategy for in-app events, for example VO_MIN. | | `location_ids` | array | No | 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. | | `advertiser_id` | string | Yes | Advertiser ID. | | `audience_rule` | object | No | Rules that specify your audience. Valid if objective_type is `TRAFFIC` or `APP_PROMOTION`. For details, see Audience Rules. | | `audience_type` | string | No | 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. | | `deep_bid_type` | string | No | 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. | | `network_types` | array | No | Device connection types that you want to target. For enum values, see Enumeration - Connection Type. | | `schedule_type` | string | No | 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. | | `share_disabled` | boolean | No | Whether to disable sharing of ads in this ad group to third-party platforms. The value `True`is 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` or`placement_type`= `PLACEMENT_TYPE_NORMAL`, and `placements` = `PLACEMENT_TIKTOK` Note: This field supports incremental updates. | | `spending_power` | string ("ALL" | "HIGH") | No | 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`. | | `ios14_targeting` | string ("UNSET" | "IOS14_MINUS" | "IOS14_PLUS" | "ALL") | No | 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`. | | `min_ios_version` | string | No | Required when `ios14_targeting` is specified. Minimum iOS version. For enum values, see Enumeration - Minimum iOS Version. | | `search_keywords` | array | No | 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. | | `comment_disabled` | boolean | No | 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`. | | `device_model_ids` | array | No | 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. | | `household_income` | array | No | 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. | | `brand_safety_type` | string ("EXPANDED_INVENTORY" | "STANDARD_INVENTORY" | "LIMITED_INVENTORY") | No | 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. | | `is_lhf_compliance` | boolean | No | 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`. | | `operating_systems` | array | No | 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` | | `saved_audience_id` | string | No | 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. | | `schedule_end_time` | string | No | 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"`. | | `contextual_tag_ids` | array | No | 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`. | | `frequency_schedule` | integer | No | Frequency schedule, together with `frequency`, controls how often people see your ad (only available for `REACH` ads). See `frequency` fields for more. | | `next_day_retention` | number | No | 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. | | `device_price_ranges` | array | No | 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]. | | `min_android_version` | string | No | Minimum Android version. For enum values, see Enumeration - Minimum Android Version. | | `schedule_start_time` | string | No | 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. | | `targeting_expansion` | object | No | 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. | | `conversion_bid_price` | number | No | 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. | | `interest_keyword_ids` | array | No | 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/. | | `excluded_audience_ids` | array | No | A list of audience IDs to be excluded. You can get audience IDs by using the /dmp/custom_audience/list/ endpoint. | | `interest_category_ids` | array | No | 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/. | | `search_result_enabled` | boolean | No | 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. | | `auto_targeting_enabled` | boolean | No | 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. | | `blocked_pangle_app_ids` | array | No | 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. | | `category_exclusion_ids` | array | No | 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. | | `smart_audience_enabled` | boolean | No | 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. | | `excluded_custom_actions` | array | No | 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`. | | `included_custom_actions` | array | No | 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`. | | `vertical_sensitivity_id` | string | No | 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. | | `catalog_authorized_bc_id` | string | No | 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. | | `deep_funnel_event_source` | string ("PIXEL" | "OFFLINE" | "CRM") | No | 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`. | | `automated_keywords_enabled` | boolean | No | 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. | | `exclude_age_under_eighteen` | boolean | No | 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`. | | `deep_funnel_event_source_id` | string | No | 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`. | | `secondary_optimization_event` | string | No | 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. | | `shopping_ads_retargeting_type` | string ("LAB1" | "LAB2" | "LAB3" | "OFF") | No | 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. | | `deep_funnel_optimization_event` | string | No | 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`. | | `purchase_intention_keyword_ids` | array | No | 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`. | | `deep_funnel_optimization_status` | string ("ON" | "OFF") | No | 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. | | `smart_interest_behavior_enabled` | boolean | No | 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. | | `excluded_pangle_audience_package_ids` | array | No | 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. | | `included_pangle_audience_package_ids` | array | No | 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. | | `shopping_ads_retargeting_actions_days` | integer | No | 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. | | `shopping_ads_retargeting_custom_audience_relation` | string ("OR" | "AND") | No | 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update the budgets of ad groups **Slug:** `TIKTOK_ADS_UPDATE_ADGROUP_BUDGET` Update 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `budget` | array | No | 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. | | `advertiser_id` | string | Yes | Advertiser ID. | | `scheduled_budget` | array | No | 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update an R&F ad group **Slug:** `TIKTOK_ADS_UPDATE_ADGROUP_RF` Update an R&F ad group. Availability may depend on TikTok allowlisting or account entitlement. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `budget` | number | No | Budget. Please fill in this number based on the data returned via the ad inventory estimate API. | | `gender` | string | No | Target gender. For enum values, see Appendix - Enumeration - Audience Gender. | | `is_hfss` | boolean | No | 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. | | `feed_type` | string | No | Feed type option. Enum: `STANDARD_FEED`, `TOP_FEED`. `STANDARD_FEED` refers to large inventory with normal CPM price while `TOP_FEED`refers to limited inventory with higher CPM price. | | `frequency` | integer | No | `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. | | `languages` | array | No | Audience language. Available values: see Appendix - Enumeration - Audience Language. | | `adgroup_id` | string | Yes | ID of the ad group to be modified. The `objective_type` of the campaign it belongs to must be `RF_REACH`. | | `age_groups` | array | No | 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. | | `carrier_ids` | array | No | 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. | | `adgroup_name` | string | No | Name of the ad group. It must not exceed 100 characters or contain any emojis. | | `audience_ids` | array | No | 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. | | `location_ids` | array | No | 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. | | `advertiser_id` | string | Yes | Advertiser ID | | `delivery_mode` | string ("STANDARD" | "SCHEDULE" | "SEQUENCE" | "VIEW_OPTIMIZE" | "OPTIMIZE") | No | 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. | | `network_types` | array | No | Device connection types that you want to target. Default value: `unlimited`. For enum values, see Enumeration - Connection Type. | | `schedule_infos` | array | No | 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. | | `share_disabled` | boolean | No | Whether sharing to third-party platforms is disabled for ads in this ad group | | `purchased_reach` | integer | No | 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. | | `comment_disabled` | boolean | No | Whether to prohibit users from posting comments to your ads on TikTok. | | `device_model_ids` | array | No | 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. | | `brand_safety_type` | string ("EXPANDED_INVENTORY" | "STANDARD_INVENTORY" | "LIMITED_INVENTORY") | No | 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. | | `operating_systems` | array | No | Operating system. See Appendix - Enumeration - Audience Operating System. | | `rf_purchased_type` | string | No | 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. | | `schedule_end_time` | string | No | 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"`. | | `contextual_tag_ids` | array | No | 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. | | `frequency_schedule` | integer | No | `frequency_schedule`, together with `frequency`, controls how often people see your ad (only available for `REACH` ads). See `frequency` field for more. | | `device_price_ranges` | array | No | 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]. | | `schedule_start_time` | string | No | 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"`. | | `purchased_impression` | integer | No | 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. | | `excluded_audience_ids` | array | No | 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. | | `interest_category_ids` | array | No | 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. | | `category_exclusion_ids` | array | No | 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update the statuses of ad groups **Slug:** `TIKTOK_ADS_UPDATE_ADGROUP_STATUS` Enable, 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `adgroup_ids` | array | Yes | The IDs of the ad groups to be operated on. Size range: 1-20. | | `advertiser_id` | string | Yes | Advertiser ID. | | `operation_status` | string ("DISABLE" | "ENABLE" | "DELETE") | Yes | 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. | | `allow_partial_success` | boolean | No | 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update the statuses of ads **Slug:** `TIKTOK_ADS_UPDATE_AD_STATUS` Enable, disable, or permanently delete regular or ACO ads. Enabling may resume ad delivery and spend. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `ad_ids` | array | No | Regular ad IDs whose statuses to update. | | `aco_ad_ids` | array | No | Automated Creative Optimization ad IDs whose statuses to update. | | `advertiser_id` | string | Yes | Advertiser ID. | | `operation_status` | string ("ENABLE" | "DISABLE" | "DELETE") | Yes | Operation to apply: ENABLE may resume delivery and spend, DISABLE pauses delivery, and DELETE permanently deletes the ads. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update Advertiser Account **Slug:** `TIKTOK_ADS_UPDATE_ADVERTISER_ACCOUNT` Update 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `address` | string | No | New business address shown on receipts. | | `company` | string | No | New company name. First verify `company_name_editable` through advertiser information; otherwise TikTok requires representative support. | | `tax_map` | object | No | Billing and invoicing tax-number fields. Use vat for France or tax_id for Brazil; all keys and values are sent as strings. | | `license_no` | string | No | New business license number. TikTok supports this field only for eligible account registration regions. | | `contact_name` | string | No | New name of the account contact person. | | `advertiser_id` | string | Yes | Ad account ID whose non-budget metadata will be updated. This action does not support Business Center budget updates. | | `contact_email` | string | No | New contact email for the ad account. | | `contact_number` | string | No | New contact phone number for the ad account. | | `promotion_link` | string | No | New promotion link. | | `advertiser_name` | string | No | New ad account name. | | `license_image_id` | string | No | TikTok image ID of the new business license image. | | `qualification_images` | array | No | New additional business certificate images. | | `need_submit_certificate` | boolean | No | 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update Advertiser Budgets **Slug:** `TIKTOK_ADS_UPDATE_ADVERTISER_BUDGETS` Consequential 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `request_id` | string | No | Idempotency request ID, valid only for INCREMENTAL_UPDATE. TikTok documents a 30-minute idempotency window and allowlist requirement. | | `advertiser_budgets` | array | Yes | 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. | | `budget_update_type` | string ("UPDATE" | "RESET" | "INCREMENTAL_UPDATE" | "ONE_CLICK_SET") | No | Budget operation: UPDATE settings, RESET consumption, add or deduct via INCREMENTAL_UPDATE, or set the provider minimum via ONE_CLICK_SET. | | `business_center_id` | string | Yes | Business Center containing the ad accounts whose budgets will change. | | `child_business_center_id` | string | No | Optional child Business Center ID associated with the budget update. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update an app **Slug:** `TIKTOK_ADS_UPDATE_APP` Update a mobile app configured for an advertiser. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `app_id` | string | Yes | Application ID. | | `partner` | 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") | No | Third-party tracking partner enum value. | | `platform` | string ("ANDROID" | "IOS") | No | Application platform: `ANDROID` or `IOS`. | | `download_url` | string | No | Application download URL. | | `tracking_url` | object | No | Third-party tracking URLs. | | `advertiser_id` | string | Yes | Advertiser ID. | | `enable_retargeting` | string ("RETARGETING" | "NON_RETARGETING") | No | Retargeting attribution setting; defaults to NON_RETARGETING. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update an Asset Group **Slug:** `TIKTOK_ADS_UPDATE_BC_ASSET_GROUP` Rename an Asset Group or add or remove its advertiser assets or members. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `action` | string ("ADD" | "DELETE") | No | ADD or DELETE; required for ASSET and MEMBER updates. | | `assets` | array | No | Assets to add or delete; required for an ASSET update. | | `members` | array | No | Members to add or delete; required for a MEMBER update. | | `update_entity` | string ("ASSET" | "MEMBER" | "NAME") | Yes | Entity to update: ASSET, MEMBER, or NAME. | | `asset_group_id` | string | Yes | Asset Group ID to update. | | `asset_group_name` | string | No | New name; required for a NAME update. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update a Billing Group **Slug:** `TIKTOK_ADS_UPDATE_BC_BILLING_GROUP` Update 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `is_primary` | boolean | No | Whether to make this the default Billing Group. | | `billing_group_id` | string | Yes | Billing Group ID to update. | | `add_advertiser_ids` | array | No | Ad account IDs to add to the Billing Group. | | `delete_advertiser_ids` | array | No | Ad account IDs to remove from the Billing Group. | | `new_billing_group_name` | string | No | New Billing Group name. | | `new_billing_group_emails` | array | No | Replacement email list. Providing this overwrites all existing Billing Group emails. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update info of a BC member **Slug:** `TIKTOK_ADS_UPDATE_BC_MEMBER` Update a Business Center member's name, basic role, or finance role. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `user_id` | string | Yes | Business Center member ID. | | `user_name` | string | No | New member name, up to 250 characters. | | `user_role` | string ("ADMIN" | "STANDARD") | No | New basic role: `ADMIN` or `STANDARD`. | | `child_bc_id` | string | No | Optional child Business Center ID. | | `ext_user_role` | object | No | Optional advanced finance role update. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Link or unlink a pixel and ad accounts **Slug:** `TIKTOK_ADS_UPDATE_BC_PIXEL_LINK` Ensure the requested link or unlink relationship between a Business Center pixel and advertiser accounts. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `pixel_code` | string | Yes | Pixel code. | | `advertiser_ids` | array | Yes | Advertiser IDs to link to or unlink from the pixel. | | `relation_status` | string ("LINK" | "UNLINK") | Yes | Relationship operation: LINK or UNLINK. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update a blocked word **Slug:** `TIKTOK_ADS_UPDATE_BLOCKEDWORD` Replace 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `new_word` | string | Yes | Replacement blocked word. | | `old_word` | string | Yes | Existing blocked word to replace. | | `advertiser_id` | string | Yes | Advertiser ID whose moderation list will change. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update a campaign **Slug:** `TIKTOK_ADS_UPDATE_CAMPAIGN` Update the mutable fields of an existing campaign. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `budget` | number | No | New campaign budget. | | `po_number` | string | No | Purchase order number. | | `campaign_id` | string | Yes | Campaign ID. | | `advertiser_id` | string | Yes | Advertiser ID. | | `campaign_name` | string | No | New campaign name, maximum 512 characters; emoji is unsupported. | | `special_industries` | array | No | Special ad categories. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update the operation statuses of campaigns **Slug:** `TIKTOK_ADS_UPDATE_CAMPAIGN_STATUS` Enable, disable, or permanently delete campaigns. Enabling may resume ad delivery and spend; postback_window_mode is accepted only while disabling. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `campaign_ids` | array | Yes | Campaign IDs whose statuses to update. | | `advertiser_id` | string | Yes | Advertiser ID. | | `operation_status` | string ("ENABLE" | "DISABLE" | "DELETE") | Yes | Operation to apply: ENABLE may resume delivery and spend, DISABLE pauses delivery, and DELETE permanently deletes the campaigns. | | `postback_window_mode` | string ("POSTBACK_WINDOW_MODE1" | "POSTBACK_WINDOW_MODE2" | "POSTBACK_WINDOW_MODE3") | No | SKAN 4.0 postback window mode, valid only when disabling an iOS 14 campaign. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update Catalog **Slug:** `TIKTOK_ADS_UPDATE_CATALOG` Update the name of a catalog owned by a TikTok Business Center. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | Yes | New catalog name (1-100 characters). | | `bc_id` | string | Yes | Business Center ID that owns the catalog. | | `catalog_id` | string | Yes | ID of the catalog to update. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update a feed **Slug:** `TIKTOK_ADS_UPDATE_CATALOG_FEED` Update 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `feed_id` | string | Yes | Feed ID. | | `feed_name` | string | Yes | Feed name. | | `catalog_id` | string | Yes | Catalog ID. | | `update_mode` | string ("INCREMENTAL" | "OVERWRITE") | Yes | 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. | | `schedule_param` | object | No | Optional remote-feed schedule. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update Catalog Feed Schedule Status **Slug:** `TIKTOK_ADS_UPDATE_CATALOG_FEED_SCHEDULE_STATUS` Set 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID that owns the catalog feed. | | `status` | string ("ON" | "OFF") | Yes | New schedule status, which must differ from the feed's current status. ON requires uri, interval_type, and timezone to be configured already. | | `feed_id` | string | Yes | ID of the catalog feed whose schedule status to change. | | `catalog_id` | string | Yes | Catalog ID containing the feed schedule. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update catalog products **Slug:** `TIKTOK_ADS_UPDATE_CATALOG_PRODUCT` Update up to 5,000 products using the fields documented for each catalog type. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `feed_id` | string | No | Feed ID; omit to use the default catalog. | | `products` | array | Yes | Products to update, at most 5,000 per request. | | `catalog_id` | string | Yes | Catalog ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update a product set **Slug:** `TIKTOK_ADS_UPDATE_CATALOG_SET` Update a product set name, filter conditions, or both. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `catalog_id` | string | Yes | Catalog ID. | | `conditions` | object | No | Exactly one `and` or `or` list of replacement conditions. | | `product_set_id` | string | Yes | Product set ID. | | `product_set_name` | string | No | New product set name, up to 128 characters. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update the statuses of comments **Slug:** `TIKTOK_ADS_UPDATE_COMMENT_STATUS` Change 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `ad_type` | string ("BIDDING" | "BRAND") | No | Ad source type: `BIDDING` or `BRAND`. | | `operation` | string ("HIDDEN" | "PUBLIC") | Yes | New comment status: `HIDDEN` or `PUBLIC`. | | `comment_ids` | array | Yes | Exact comment IDs whose visibility status will change. | | `advertiser_id` | string | Yes | Advertiser ID whose comments will change. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update a Custom Conversion **Slug:** `TIKTOK_ADS_UPDATE_CUSTOM_CONVERSION` Update the name or description of a Custom Conversion configuration. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | No | New unique name without emoji. | | `description` | string | No | New description without emoji. | | `advertiser_id` | string | Yes | Advertiser ID. | | `custom_conversion_id` | string | Yes | Custom Conversion ID to update. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update a Custom Audience **Slug:** `TIKTOK_ADS_UPDATE_DMP_CUSTOM_AUDIENCE` Rename, refresh from files, enhance, or convert a custom audience subtype. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `action` | string ("REPLACE" | "APPEND" | "REMOVE") | No | File modification type, used only with file_paths. | | `file_paths` | array | No | Uploaded files used to modify the audience; fewer than 50 are recommended. | | `context_info` | object | No | Optional operation context. | | `advertiser_id` | string | Yes | Advertiser ID. | | `audience_sub_type` | string | No | Convert a NORMAL audience to REACH_FREQUENCY. | | `custom_audience_id` | string | Yes | Custom audience ID. | | `audience_enhancement` | boolean | No | Whether audience enhancement is enabled. | | `custom_audience_name` | string | No | New audience name; required when file_paths is omitted. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update Lookalike Audiences **Slug:** `TIKTOK_ADS_UPDATE_DMP_CUSTOM_AUDIENCE_LOOKALIKE` Update specified lookalike custom audiences. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_id` | string | Yes | Advertiser ID. | | `custom_audience_ids` | array | Yes | Lookalike custom audience IDs to update. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update the name of an image **Slug:** `TIKTOK_ADS_UPDATE_FILE_IMAGE_AD` Update an advertiser image name. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `image_id` | string | Yes | Image ID. | | `file_name` | string | Yes | New image name, 1-100 characters. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update the name of a video **Slug:** `TIKTOK_ADS_UPDATE_FILE_VIDEO_AD` Update an advertiser video name. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `video_id` | string | Yes | Video ID. | | `file_name` | string | Yes | New video name, 1-100 characters. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update GMV Max Campaign **Slug:** `TIKTOK_ADS_UPDATE_GMV_MAX_CAMPAIGN` Update 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `budget` | number | No | Optional new campaign budget. | | `roas_bid` | number | No | Optional new ROAS bid. | | `item_list` | array | No | Optional replacement shop items. | | `campaign_id` | string | Yes | GMV Max campaign ID to update. | | `advertiser_id` | string | Yes | Authorized advertiser account ID. | | `campaign_name` | string | No | Optional new campaign name. | | `schedule_type` | string ("SCHEDULE_FROM_NOW" | "SCHEDULE_START_END") | No | Optional new campaign schedule type. | | `item_group_ids` | array | No | Optional replacement item group IDs. | | `promotion_days` | object | No | Optional promotion-day schedule changes. | | `schedule_end_time` | string | No | Optional campaign end time in the provider's date-time string format. | | `auto_budget_enabled` | boolean | No | Whether automatic budget management is enabled. | | `affiliate_posts_enabled` | boolean | No | Whether affiliate posts are enabled. | | `custom_anchor_video_list` | array | No | Optional replacement custom anchor videos. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update GMV Max Campaign Creatives **Slug:** `TIKTOK_ADS_UPDATE_GMV_MAX_CAMPAIGN_CREATIVES` Remove 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `action` | string ("REMOVE" | "ADD") | Yes | Whether to REMOVE creatives from the campaign or ADD them back. | | `item_list` | array | Yes | Creative items to update, with at most 400 items per request. | | `campaign_id` | string | Yes | Active GMV Max campaign ID. Product campaigns must use product_video_specific_type AUTO_SELECTION. | | `advertiser_id` | string | Yes | Authorized advertiser account ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update GMV Max Session **Slug:** `TIKTOK_ADS_UPDATE_GMV_MAX_CAMPAIGN_SESSION` Update documented budget or schedule fields for a max delivery or creative boost session. schedule_start_time applies to max delivery sessions. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `session` | object | Yes | Documented mutable session fields. The endpoint publishes no session-type discriminator. | | `store_id` | string | Yes | TikTok Shop store ID. | | `session_id` | string | Yes | GMV Max session ID to update. | | `campaign_id` | string | Yes | Product GMV Max campaign ID. | | `advertiser_id` | string | Yes | Authorized advertiser account ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update an Offline Event Set **Slug:** `TIKTOK_ADS_UPDATE_OFFLINE` Update an Offline Event Set configuration; this does not upload or ingest events. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | No | New unique event-set name. | | `event_set_id` | string | Yes | Offline Event Set ID to update. | | `advertiser_id` | string | Yes | Advertiser ID. | | `auto_tracking` | boolean | No | Whether Auto Tracking is enabled. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update rules **Slug:** `TIKTOK_ADS_UPDATE_OPTIMIZER_RULE` Update automated optimizer rules. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `lang` | string ("ZH" | "EN" | "JA") | No | Language of error messages. | | `rules` | array | Yes | Rules to update. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update the statuses of rules **Slug:** `TIKTOK_ADS_UPDATE_OPTIMIZER_RULE_STATUSES` Turn automated optimizer rules on or off, or permanently delete them. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `lang` | string ("ZH" | "EN" | "JA") | No | Language of error messages. | | `rule_ids` | array | Yes | IDs of rules whose status will be updated. | | `operate_type` | string ("TURN_ON" | "TURN_OFF" | "DELETE") | Yes | Status operation to perform. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update Pangle Block List **Slug:** `TIKTOK_ADS_UPDATE_PANGLE_BLOCK_LIST` Update 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `add_app_list` | array | No | Apps to add to the block list, using an iTunes ID for each iOS app and a package name for each Android app. | | `advertiser_id` | string | Yes | Advertiser ID whose Pangle app block list will be updated. | | `clear_old_app` | boolean | No | Whether to clear the existing block list before adding add_app_list. When false, TikTok applies additions and deletions to the existing list. | | `delete_app_list` | array | No | Apps to remove from the block list, using an iTunes ID for each iOS app and a package name for each Android app. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Link ad accounts to a Payment Portfolio **Slug:** `TIKTOK_ADS_UPDATE_PAYMENT_PORTFOLIO_ADVERTISER` Link up to 20 ad accounts to an Advanced Payment Portfolio, changing which centrally managed funds those accounts can use. Obtain explicit finance-owner approval immediately before execution and verify the portfolio, every ad account, same-client eligibility, and administrator access; the whole call fails for one invalid ID. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_ids` | array | Yes | Ad account IDs to link (maximum 20). All must belong to the same client as the portfolio; one invalid ID causes the entire call to fail. | | `payment_portfolio_id` | string | Yes | Advanced Payment Portfolio ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Allocate the credit line to Payment Portfolios **Slug:** `TIKTOK_ADS_UPDATE_PAYMENT_PORTFOLIO_CREDIT_LINE` Change 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `allocation_details` | array | Yes | Credit line allocations for up to 10 Payment Portfolios. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update a Pixel **Slug:** `TIKTOK_ADS_UPDATE_PIXEL` Update Pixel naming, matching, cookie, or expanded-data-sharing configuration. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `pixel_id` | string | Yes | Pixel ID. | | `pixel_name` | string | Yes | New Pixel name, or an empty string to keep it unchanged. | | `advertiser_id` | string | Yes | Advertiser ID. | | `advanced_matching_fields` | object | No | Complete Manual Advanced Matching settings. | | `enable_first_party_cookies` | boolean | No | Whether first-party cookies are enabled. | | `enable_expanded_data_sharing` | boolean | No | Whether expanded data sharing is enabled. | | `automatic_advanced_matching_fields` | object | No | Complete Automatic Advanced Matching settings. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update a Pixel Event **Slug:** `TIKTOK_ADS_UPDATE_PIXEL_EVENT` Update a Pixel Event configuration; this endpoint does not ingest event occurrences. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `currency` | string ("INR" | "JPY" | "USD") | No | Currency for currency_value. | | `event_id` | string | Yes | Configured Pixel Event ID from LIST_PIXEL. | | `event_name` | string | No | New event name without emoji. | | `advertiser_id` | string | Yes | Advertiser ID. | | `currency_value` | string | No | New event conversion value. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update Search Ad Negative Keyword **Slug:** `TIKTOK_ADS_UPDATE_SEARCH_AD_NEGATIVE_KEYWORD` Update the name or match type of one negative keyword attached to a Search Ads campaign or ad group. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `keyword` | object | Yes | Replacement negative-keyword name and match type. | | `object_id` | string | Yes | Campaign ID or ad-group ID, according to object_type. | | `object_type` | string ("CAMPAIGN" | "ADGROUP") | Yes | Whether object_id identifies a campaign or an ad group. | | `advertiser_id` | string | Yes | Advertiser ID that owns the negative keyword. | | `old_keyword_id` | string | Yes | ID of the negative keyword to update. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Add or delete audience segment mappings **Slug:** `TIKTOK_ADS_UPDATE_SEGMENT` Add or delete user and device mappings for explicitly selected disposable audiences. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `action` | string ("add" | "delete") | No | Whether to add or delete mappings. | | `id_schema` | array | Yes | Identifier types corresponding to each batch row. | | `batch_data` | array | Yes | Batches of user or device audience mappings. | | `advertiser_ids` | array | Yes | Advertiser IDs from the same business account. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update Smart Creative Materials **Slug:** `TIKTOK_ADS_UPDATE_SMART_CREATIVE_MATERIALS` Update 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `card_list` | array | No | Complete card list (maximum one). | | `page_list` | array | No | Complete Instant Page ID list. | | `adgroup_id` | string | Yes | Ad group ID whose creative_material_mode is SMART_CREATIVE. | | `title_list` | array | No | Complete replacement title list when changing any title. | | `patch_update` | boolean | No | Whether omitted top-level settings remain unchanged. Array fields still replace the complete array and must contain all existing items. | | `advertiser_id` | string | Yes | Advertiser account ID. | | `deeplink_list` | array | No | Complete replacement deep-link list. | | `common_material` | object | No | Common material settings to update. | | `media_info_list` | array | No | Complete replacement media list when changing any media item. | | `avatar_icon_list` | array | No | Avatar image list (maximum one). | | `display_name_list` | array | No | Complete replacement display-name list. | | `landing_page_urls` | array | No | Complete landing-page destination list. | | `call_to_action_list` | array | No | Complete replacement call-to-action list. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update Smart Creative Material Status **Slug:** `TIKTOK_ADS_UPDATE_SMART_CREATIVE_MATERIAL_STATUS` Enable 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `ad_group_id` | string | Yes | Smart Creative ad group ID. | | `material_ids` | array | Yes | Smart Creative material IDs whose status will change. | | `advertiser_id` | string | Yes | Advertiser account ID. | | `material_status` | string ("ENABLE" | "DISABLE") | Yes | Whether the materials can be used for ad delivery. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update Smart+ Ad **Slug:** `TIKTOK_ADS_UPDATE_SMART_PLUS_AD` Update an existing Smart+ ad and its material configuration; at least one field to update must be provided. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `ad_name` | string | No | Updated ad name. | | `page_list` | array | No | Instant Pages (maximum 3). | | `ad_text_list` | array | No | Ad text variants (maximum 5). | | `advertiser_id` | string | Yes | Advertiser ID that owns the ad. | | `creative_list` | array | No | Creative variants (1-31). | | `deeplink_list` | array | No | Deep-link destinations (maximum 1). | | `ad_configuration` | object | No | Common ad material configuration. | | `smart_plus_ad_id` | string | Yes | Smart+ ad ID to update. | | `call_to_action_list` | array | No | Call-to-action variants (maximum 3). | | `landing_page_url_list` | array | No | Landing pages (maximum 1). | | `interactive_add_on_list` | array | No | Interactive add-ons (maximum 2). | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update Smart+ Ad Group **Slug:** `TIKTOK_ADS_UPDATE_SMART_PLUS_ADGROUP` Update 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `budget` | number | No | Updated budget. | | `pacing` | string ("PACING_MODE_FAST" | "PACING_MODE_SMOOTH") | No | Pacing mode. | | `roas_bid` | number | No | Updated ROAS bid. | | `bid_price` | number | No | Updated bid price. | | `adgroup_id` | string | Yes | Smart+ ad group ID to update. | | `dayparting` | string | No | Updated dayparting schedule. | | `min_budget` | number | No | Updated minimum budget. | | `adgroup_name` | string | No | Updated ad group name. | | `advertiser_id` | string | Yes | Advertiser ID that owns the ad group. | | `schedule_type` | string ("SCHEDULE_FROM_NOW" | "SCHEDULE_START_END") | No | Schedule type. | | `share_disabled` | boolean | No | Whether sharing is disabled. | | `targeting_spec` | object | No | Updated audience targeting. | | `comment_disabled` | boolean | No | Whether comments are disabled. | | `schedule_end_time` | string | No | Schedule end time. | | `movie_premiere_date` | string | No | Updated movie premiere date. | | `schedule_start_time` | string | No | Schedule start time. | | `conversion_bid_price` | number | No | Updated conversion bid price. | | `suggestion_audience_enabled` | boolean | No | Whether suggested audience is enabled. | | `targeting_optimization_mode` | string ("AUTOMATIC" | "MANUAL") | No | Targeting optimization mode. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update Smart+ Ad Group Budgets **Slug:** `TIKTOK_ADS_UPDATE_SMART_PLUS_ADGROUP_BUDGETS` Update 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `budget` | array | No | Immediate total-budget updates for 1-20 Smart+ ad groups. Use this or scheduled_budget. | | `advertiser_id` | string | Yes | Advertiser ID that owns the Smart+ ad groups. | | `scheduled_budget` | array | No | 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update Smart+ Ad Material Status **Slug:** `TIKTOK_ADS_UPDATE_SMART_PLUS_AD_MATERIAL_STATUS` Enable or disable up to 20 materials belonging to a Smart+ ad. Enabling materials can make them eligible for delivery and spend. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_id` | string | Yes | Advertiser ID that owns the ad. | | `ad_material_ids` | array | Yes | Ad material IDs to update (1-20). | | `operation_status` | string ("DISABLE" | "ENABLE") | Yes | Status operation to apply. | | `smart_plus_ad_id` | string | Yes | Smart+ ad ID whose materials to update. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update Smart+ Campaign **Slug:** `TIKTOK_ADS_UPDATE_SMART_PLUS_CAMPAIGN` Update 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `budget` | number | No | Optional new campaign budget. | | `po_number` | string | No | Optional new purchase order number. | | `campaign_id` | string | Yes | Smart+ campaign ID to update. | | `advertiser_id` | string | Yes | Authorized advertiser account ID. | | `campaign_name` | string | No | Optional new campaign name. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update the time of a split test **Slug:** `TIKTOK_ADS_UPDATE_SPLIT_TEST` Update the start and end time of a split test. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `end_time` | string | Yes | New end time in YYYY-MM-DD HH:MM:SS UTC. | | `start_time` | string | Yes | New start time in YYYY-MM-DD HH:MM:SS UTC; cannot be changed after the test starts. | | `advertiser_id` | string | Yes | Advertiser ID. | | `split_test_group_id` | string | Yes | Split test group ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Set or update the Brand Safety Hub settings of an ad account **Slug:** `TIKTOK_ADS_UPDATE_TIKTOK_INVENTORY_FILTERS` Set 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `advertiser_id` | string | Yes | Advertiser ID. | | `brand_safety_type` | string ("EXPANDED_INVENTORY" | "STANDARD_INVENTORY" | "LIMITED_INVENTORY") | No | Inventory filter tier to configure. | | `category_exclusion_ids` | array | No | Content category IDs to exclude. | | `cover_all_ad_objectives` | boolean | Yes | Whether the brand safety settings apply to all objectives. Once true, this cannot be reverted. | | `vertical_sensitivity_id` | string | No | Sensitive vertical category ID to exclude. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Upload verification documents **Slug:** `TIKTOK_ADS_UPLOAD_ACCOUNT_VERIFICATION` Upload one or two verification document images. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `image_file1` | object | Yes | JPEG, JPG, or PNG verification document up to 10 MB. | | `image_file2` | object | No | Optional second JPEG, JPG, or PNG verification document up to 10 MB. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Upload Business Certificate Image **Slug:** `TIKTOK_ADS_UPLOAD_BUSINESS_CERTIFICATE_IMAGE` Upload a business certificate image for an ad account through a Business Center where the connected user is an administrator. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. The connected user must be an administrator. | | `image_file` | object | Yes | JPG, JPEG, or PNG business certificate image, up to 10 MB. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Upload catalog products **Slug:** `TIKTOK_ADS_UPLOAD_CATALOG_PRODUCT` Upload up to 5,000 products using the fields documented for each catalog type. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `feed_id` | string | No | Feed ID; omit to use the default catalog. | | `products` | array | Yes | Products to upload, at most 5,000 per request. | | `catalog_id` | string | Yes | Catalog ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Upload products via a file URL **Slug:** `TIKTOK_ADS_UPLOAD_CATALOG_PRODUCTS_BY_FILE_URL` Ingest 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID. | | `feed_id` | string | No | Optional feed ID. | | `file_url` | string | Yes | Direct HTTP or HTTPS URL of a CSV catalog feed containing fewer than 20 million product rows. | | `catalog_id` | string | Yes | Catalog ID. | | `update_mode` | string ("INCREMENTAL" | "OVERWRITE") | No | 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Upload Catalog Videos by File URL **Slug:** `TIKTOK_ADS_UPLOAD_CATALOG_VIDEOS_BY_FILE_URL` Upload catalog videos from a file URL. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `bc_id` | string | Yes | Business Center ID that owns the E-commerce catalog. | | `file_url` | string | Yes | URL of the file containing catalog video data. | | `catalog_id` | string | Yes | E-commerce catalog ID receiving the videos. | | `advertiser_ids` | array | No | Optional IDs of up to 100 advertiser accounts in the same Business Center whose Admin or Operator permissions authorize the upload. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Upload an Audience File **Slug:** `TIKTOK_ADS_UPLOAD_DMP_CUSTOM_AUDIENCE_FILE` Upload a CSV or TXT customer file after verifying its supplied MD5 signature. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file` | object | Yes | CSV or TXT audience data file. | | `name` | string | No | Optional provider-side file name. | | `advertiser_id` | string | Yes | Advertiser ID. | | `calculate_type` | string ("EMAIL_SHA256" | "FIRST_MD5" | "FIRST_SHA256" | "GAID_MD5" | "GAID_SHA256" | "IDFA_MD5" | "IDFA_SHA256" | "MAID_MD5" | "MAID_SHA256" | "MULTIPLE_TYPES" | "PHONE_SHA256") | Yes | Encryption type matching the file data. | | `file_signature` | string | Yes | Lowercase or uppercase MD5 digest of the file. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Upload a file in chunks **Slug:** `TIKTOK_ADS_UPLOAD_FILE_CHUNKED` Upload one image, video, or music file through TikTok's start, ordered chunk-transfer, and finish workflow. Chunk signatures are computed internally. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file` | object | Yes | File to upload in chunks. | | `name` | string | No | Optional file name, up to 100 characters. | | `chunk_size` | integer | No | Chunk size in bytes, from 1 byte through 50 MiB. Defaults to 5 MiB. | | `content_type` | string ("image" | "video" | "music") | Yes | File content category. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Upload an image **Slug:** `TIKTOK_ADS_UPLOAD_FILE_IMAGE_AD` Upload an advertiser image by local file, URL, or temporary file ID. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file_id` | string | No | Temporary file ID required for file-ID upload. | | `file_name` | string | No | Optional image name, 1-100 characters. | | `image_url` | string | No | Image URL required for URL upload. | | `image_file` | object | No | JPG, JPEG, or PNG image up to 50 MB for file upload. | | `upload_type` | string ("UPLOAD_BY_FILE" | "UPLOAD_BY_URL" | "UPLOAD_BY_FILE_ID") | Yes | Image upload method. | | `advertiser_id` | string | Yes | Advertiser ID. | | `image_signature` | string | No | Image MD5 digest required for file upload. | | `pre_review_info` | object | No | Pre-review details required when pre-review is enabled. | | `pre_review_enabled` | boolean | No | Whether to create a creative pre-review task. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Upload a piece of music **Slug:** `TIKTOK_ADS_UPLOAD_FILE_MUSIC` Upload advertiser music or update a Carousel Ads music list. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file_id` | string | No | Temporary file ID required for file-ID upload. | | `file_name` | string | No | Optional music name, 1-100 characters. | | `music_file` | object | No | Music file; Carousel Ads music must be MP3 and at most 10 MB. | | `material_id` | string | No | Material ID required for a material action. | | `music_scene` | string ("CREATIVE_ASSET" | "CAROUSEL_ADS" | "CATALOG_CAROUSEL") | No | Scenario where the music is used. | | `upload_type` | string ("UPLOAD_BY_FILE" | "UPLOAD_BY_FILE_ID") | No | Music upload method. | | `advertiser_id` | string | Yes | Advertiser ID. | | `material_action` | string ("ADD_TO_LIKED" | "ADD_TO_HISTORY" | "REMOVE_FROM_LIKED") | No | Carousel music-list operation. | | `music_signature` | string | No | Music MD5 digest required for file upload. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Upload a file **Slug:** `TIKTOK_ADS_UPLOAD_FILE_TEMPORARILY` Upload a temporary image, music, video, or playable file by file or URL. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `url` | string | No | HTTP URL required for URL upload. | | `file` | object | No | File to upload, up to 100 MB; Carousel Ads music must be MP3 and at most 10 MB. | | `name` | string | No | Optional file name, up to 100 characters. | | `signature` | string | No | File MD5 digest required for FILE upload. | | `upload_type` | string ("FILE" | "URL") | Yes | Upload from a file or URL. | | `content_type` | string ("image" | "music" | "video" | "playable") | Yes | Provider file category. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Upload a video **Slug:** `TIKTOK_ADS_UPLOAD_FILE_VIDEO_AD` Upload an advertiser video by local file, URL, temporary file ID, or existing video ID. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file_id` | string | No | Temporary file ID required for file-ID upload. | | `video_id` | string | No | Existing video ID required for video-ID upload. | | `file_name` | string | No | Optional video name, 1-100 characters. | | `video_url` | string | No | Playable video URL required for URL upload. | | `video_file` | object | No | MP4, MOV, MPEG, or AVI video up to 500 MB for file upload. | | `flaw_detect` | boolean | No | Whether to detect video issues automatically. | | `upload_type` | string ("UPLOAD_BY_FILE" | "UPLOAD_BY_URL" | "UPLOAD_BY_FILE_ID" | "UPLOAD_BY_VIDEO_ID") | No | Video upload method. | | `advertiser_id` | string | Yes | Advertiser ID. | | `is_third_party` | boolean | No | Whether this is a third-party video. | | `pre_review_info` | object | No | Pre-review details required when pre-review is enabled. | | `video_signature` | string | No | Video MD5 digest required for file upload. | | `auto_fix_enabled` | boolean | No | Whether to fix supported detected issues automatically. | | `auto_bind_enabled` | boolean | No | Whether to add an automatically fixed video to the creative library. | | `pre_review_enabled` | boolean | No | Whether to create a creative pre-review task. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Upload a playable asset **Slug:** `TIKTOK_ADS_UPLOAD_PLAYABLE` Upload 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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file_id` | string | No | Existing file repository ID; required for UPLOAD_BY_FILE_ID. | | `upload_type` | string ("UPLOAD_BY_FILE" | "UPLOAD_BY_FILE_ID") | No | Upload a ZIP directly or use an existing file repository ID. | | `advertiser_id` | string | Yes | Advertiser ID. | | `playable_package` | object | No | ZIP playable package, at most 5 MB; required for UPLOAD_BY_FILE. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Validate a URL **Slug:** `TIKTOK_ADS_VALIDATE_LANDING_PAGE_URL` Get TikTok verification results for a URL. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `url` | string | Yes | URL to verify. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Check the status of a playable asset **Slug:** `TIKTOK_ADS_VALIDATE_PLAYABLE` Check validation status and failure details for one playable asset. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `playable_id` | string | Yes | Playable asset ID. | | `advertiser_id` | string | Yes | Advertiser ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not |