Create Ad Group - Markifact

Create TikTok ad groups for manual, Search, and Upgraded Smart+ campaigns, including native DM, phone-call, and instant-messaging lead routes. Use advanced_fields for additional native parameters. TikTok validates route eligibility; all groups default to paused.


App	TikTok Ads
Operation ID	`tiktok_ads_create_ad_group`
Type	Action
Connection	`tiktok_ads` (required)
Credits per run	1
Agent / MCP tool	Yes
Requires approval	Yes (write operation)

Inputs

Field	Type	Required	Default	Description
`account`	DynamicAccount	Yes	-	Select TikTok Ads account (advertiser) to create the ad group in.
`ad_group_mode`	string or SelectableOption	Yes	-	Ad group creation path. Match the parent campaign: manual, search, or upgraded_smart_plus. Upgraded Smart+ supports multiple ad groups, explicit status, and ad-group budgets when campaign budget optimization is disabled.
`campaign_id`	string or SelectItem	Yes	-	TikTok campaign ID to create the ad group under. Match ad_group_mode to the parent campaign type.
`adgroup_name`	string	Yes	-	Ad group name to create in TikTok. Keep it human-readable, 512 characters or less, and do not include emoji.
`operation_status`	string or SelectableOption	No	-	Initial ad-group status for manual, Search, and Upgraded Smart+. Use DISABLE to create paused or ENABLE to enable. Defaults to DISABLE.
`promotion_type`	string or SelectableOption	No	-	Native promotion type matching the campaign and destination. Website: WEBSITE. Apps: APP_ANDROID/APP_IOS. Lead forms: LEAD_GENERATION plus promotion_target_type; Smart+ also supports LEAD_GENERATION_MULTI_DESTINATION. Native leads: LEAD_GEN_CLICK_TO_TT_DIRECT_MESSAGE, LEAD_GEN_CLICK_TO_CALL, or LEAD_GEN_CLICK_TO_SOCIAL_MEDIA_APP_MESSAGE. Minis: MINI_APP/MINI_GAME; series: NATIVE_SERIES. Shopping: VIDEO_SHOPPING, LIVE_SHOPPING, PSA_PRODUCT, or TIKTOK_SHOP where supported. TikTok validates objective compatibility and regional/allowlist access; no substitute is inferred.
`optimization_goal`	string or SelectableOption	Yes	-	Match the objective and destination. Website traffic: CLICK or TRAFFIC_LANDING_PAGE_VIEW; PAGE_VISIT means TikTok profile/in-app page visits under ENGAGEMENT, not website visits. CONVERT: conversions; INSTALL/IN_APP_EVENT: apps; VALUE: value optimization; LEAD_GENERATION: forms; LEADS: lead optimization; WEBSITE_ENGAGEMENT: meaningful website actions; PREFERRED_LEAD: qualified leads where supported. SHOW/REACH: impressions/reach; FOLLOWERS: followers; ENGAGED_VIEW/ENGAGED_VIEW_FIFTEEN: 6-/15-second focused views; PRODUCT_CLICK_IN_LIVE/MT_LIVE_ROOM: live product clicks/views; DESTINATION_VISIT: in-app page with website fallback. Native calls use CLICK; DMs/messaging use CLICK or eligible CONVERSATION. Smart+ supports Zalo CONVERSATION as well as Messenger/WhatsApp. TikTok validates goal eligibility; do not substitute another goal to bypass access restrictions.
`billing_event`	string or SelectableOption	Yes	-	Match optimization_goal. CPC: CLICK or PAGE_VISIT. CPM: SHOW or REACH. CPV: ENGAGED_VIEW or ENGAGED_VIEW_FIFTEEN. OCPM: TRAFFIC_LANDING_PAGE_VIEW, CONVERT, INSTALL, IN_APP_EVENT, LEAD_GENERATION, CONVERSATION, VALUE, AUTOMATIC_VALUE_OPTIMIZATION, FOLLOWERS, PRODUCT_CLICK_IN_LIVE, MT_LIVE_ROOM, or DESTINATION_VISIT. Smart+ supports CPC for CLICK and OCPM for its other supported goals, including LEADS and WEBSITE_ENGAGEMENT. GD is Guaranteed Delivery for eligible reservation campaigns. TikTok validates compatibility.
`bid_type`	string or SelectableOption	No	-	Bid strategy. Use BID_TYPE_NO_BID for Maximum Delivery, or BID_TYPE_CUSTOM for Cost Cap. Required for Smart+ and most conversion/value flows.
`bid_price`	number	No	-	Cost Cap amount in account currency. Required when bid_type is BID_TYPE_CUSTOM and billing_event is CPC, CPM, or CPV, including native call/messaging CLICK. Omit for Maximum Delivery and OCPM; use conversion_bid_price for OCPM Cost Cap.
`conversion_bid_price`	number	No	-	Cost Cap amount in account currency. Required when bid_type is BID_TYPE_CUSTOM and billing_event is OCPM, including native DM/messaging CONVERSATION. Omit for Maximum Delivery and non-OCPM billing; use bid_price for CPC/CPM/CPV Cost Cap.
`deep_bid_type`	string or SelectableOption	No	-	Deep-event bidding strategy. For VALUE, use VO_HIGHEST_VALUE to maximize value or VO_MIN_ROAS with roas_bid for a minimum ROAS target. Smart+ also accepts DEFAULT and AEO where supported; TikTok validates compatibility.
`roas_bid`	number	No	-	Positive minimum ROAS target. Required when deep_bid_type is VO_MIN_ROAS; omit otherwise. TikTok applies different allowed ranges by promotion and optimization event.
`vbo_window`	string or SelectableOption	No	-	Value optimization attribution window. Provide only for VALUE/VBO flows when the user specifies a 0-day or 7-day window.
`budget_mode`	string or SelectableOption	No	-	Ad-group budget mode. For Smart+ with campaign CBO disabled, use BUDGET_MODE_DYNAMIC_DAILY_BUDGET or BUDGET_MODE_TOTAL. Omit when campaign CBO is enabled. Manual/search also support BUDGET_MODE_DAY and BUDGET_MODE_INFINITE where permitted.
`budget`	number	No	-	Ad-group budget in account currency, not cents. Required with a finite ad-group budget mode, including Smart+ when campaign CBO is disabled. Omit when campaign CBO controls the budget. Lifetime budgets need schedule_end_time; TikTok validates minimums and campaign compatibility.
`frequency`	integer	No	-	Manual/search Reach or Video Views only. Frequency cap count: the maximum number of times a person can see ads from this ad group during frequency_schedule days. Required for Reach. Omit it, or pass 0, for no cap on Video Views.
`frequency_schedule`	integer	No	-	Manual/search Reach or Video Views only. Frequency cap window in days. For example, frequency 2 with frequency_schedule 3 means no more than 2 impressions every 3 days. Omit it, or pass 0, for no cap on Video Views.
`schedule_start_time`	any	No	-	Optional ad group start time in UTC. Use YYYY-MM-DD HH:MM:SS or an ISO/timestamp value. If omitted, Markifact starts now.
`schedule_end_time`	any	No	-	Optional ad group end time in UTC. Required when budget_mode is BUDGET_MODE_TOTAL. When provided, Markifact sends SCHEDULE_START_END; otherwise it runs from start time onward.
`pacing`	string or SelectableOption	No	-	Manual/search only. Budget pacing mode for ad-group budget delivery. Omit for Smart+ and when no ad-group budget is set.
`placement_type`	string or SelectableOption	No	-	Placement selection mode. Use PLACEMENT_TYPE_AUTOMATIC to let TikTok choose placements, or PLACEMENT_TYPE_NORMAL when providing placements. Defaults to automatic.
`placements`	array of string or SelectableOption	No	-	Required when placement_type is PLACEMENT_TYPE_NORMAL. Provide TikTok placement values such as PLACEMENT_TIKTOK; omit for automatic placements.
`pixel_id`	string or SelectItem	No	-	TikTok Pixel ID. Required for WEBSITE ad groups using CONVERT or VALUE optimization, and whenever optimization_event is a pixel event. Do not add a website pixel just because a native DM or messaging route optimizes for CONVERSATION.
`app_id`	string or SelectItem	No	-	TikTok App ID. Required for app promotion ad groups; omit for website, lead, and shopping flows.
`optimization_event`	string or SelectableOption	No	-	Native TikTok conversion event, such as SHOPPING (website purchase), FORM (website lead), ON_WEB_DETAIL (website content view), ACTIVE (app install), or ACTIVE_PAY (app purchase). For TRAFFIC_LANDING_PAGE_VIEW, omit or use LANDING_PAGE_VIEW. PAGE_VISIT is a TikTok profile/in-app visit and is set automatically for that goal. For native messaging CLICK, omit; for CONVERSATION, omit or use MESSAGE. Use secondary_optimization_event in advanced_fields for secondary goals. TikTok validates which events your pixel/app supports.
`custom_conversion_id`	string or SelectItem	No	-	Optional TikTok custom conversion ID. Provide only when optimizing to a specific custom conversion instead of a standard pixel/app event.
`conversion_window`	string or SelectableOption	No	-	Legacy TikTok conversion_window; deprecated by TikTok. Use click_attribution_window and view_attribution_window for new ad groups.
`click_attribution_window`	string or SelectableOption	No	-	Optional click-through attribution window; specify view_attribution_window alongside it. OFF disables attribution. Smart+ Minis additionally support THIRTY_DAYS for MINI_GAME and THIRTY_TWO_DAYS/ONE_HUNDRED_EIGHTY_DAYS for MINI_APP with ACTIVE_PAY. TikTok validates allowed windows for the objective.
`view_attribution_window`	string or SelectableOption	No	-	Optional view-through attribution window: OFF, ONE_DAY, or SEVEN_DAYS. Specify click_attribution_window alongside it. TikTok validates allowed windows for the objective.
`location_ids`	any	No	-	TikTok location IDs to target, as a list or comma-separated IDs from Search Targeting. Required for most ad group flows, including Smart+ targeting_spec. A valid location ID does not guarantee eligibility: TikTok also checks advertiser region, destination, and account permissions. Do not replace the requested location to bypass a restriction.
`zipcode_ids`	any	No	-	Optional zipcode IDs for countries where TikTok supports ZIP targeting. Use IDs from Search Targeting; omit when targeting by location_ids only.
`languages`	any	No	-	Optional TikTok language codes, such as en or ar. Use language codes from Search Targeting, not numeric IDs.
`gender`	string or SelectableOption	No	-	Optional gender targeting. Use GENDER_UNLIMITED to avoid restricting gender, or a specific gender when requested.
`age_groups`	array of string or SelectableOption	No	-	Optional age groups to include. Provide TikTok age buckets such as AGE_18_24; omit for broad age targeting.
`audience_ids`	any	No	-	Optional custom audience IDs to include. Use comma-separated IDs or a list; omit unless the user selected specific audiences.
`excluded_audience_ids`	any	No	-	Optional custom audience IDs to exclude. Use comma-separated IDs or a list; omit unless the user selected exclusions.
`interest_category_ids`	any	No	-	Manual/search targeting. Interest category IDs from Search Targeting GENERAL_INTEREST results. Omit for Smart+ unless manually constraining targeting_spec.
`interest_keyword_ids`	any	No	-	Manual/search targeting. Additional interest IDs from Search Targeting. Use only when the user selected specific interests.
`purchase_intention_keyword_ids`	any	No	-	Manual/search targeting. Purchase-intention IDs from Search Targeting. Use only when the user selected purchase-intent audiences.
`smart_interest_behavior_enabled`	boolean	No	`False`	Manual/search only. Set true to let TikTok expand interest and behavior targeting. Defaults to false. Ignored for Smart+ because TikTok does not support this flag on Smart+ ad groups.
`video_interaction_category_ids`	any	No	-	Manual/search behavior targeting. Video interaction category IDs from Search Targeting; Markifact converts them to TikTok VIDEO_RELATED actions.
`creator_interaction_category_ids`	any	No	-	Manual/search behavior targeting. Creator interaction category IDs from Search Targeting; Markifact converts them to TikTok CREATOR_RELATED actions.
`hashtag_interaction_category_ids`	any	No	-	Manual/search behavior targeting. Hashtag interaction category IDs from Search Targeting; Markifact converts them to TikTok HASHTAG_RELATED actions.
`saved_audience_id`	string or SelectItem	No	-	Optional TikTok saved audience ID. Use when the user wants to target a saved audience instead of manually listing targeting dimensions.
`operating_systems`	array of string or SelectableOption	No	-	Optional device OS targeting. Use ANDROID or IOS values for app/device-specific ad groups; omit for broad targeting.
`min_ios_version`	string or SelectableOption	No	-	Optional minimum iOS version. Use only when targeting iOS devices or iOS app promotion.
`min_android_version`	string or SelectableOption	No	-	Optional minimum Android version. Use only when targeting Android devices or Android app promotion.
`shopping_ads_type`	string or SelectableOption	No	-	Manual/search PRODUCT_SALES campaigns only. Choose the shopping ad type for catalog, live, or video shopping flows; omit for website/app/lead ad groups.
`product_source`	string or SelectableOption	No	-	Product source: CATALOG, STORE (TikTok Shop), SHOWCASE, or UNSET where supported. Smart+ app O2O catalog groups use CATALOG. TikTok validates compatibility with the shopping type and campaign.
`catalog_id`	string or SelectItem	No	-	Catalog ID. Required when product_source is CATALOG, or for Smart+ catalog ad groups that reference a catalog.
`catalog_authorized_bc_id`	string or SelectItem	No	-	Business Center ID authorized for the catalog. Provide when TikTok requires catalog authorization; otherwise omit.
`store_id`	string or SelectItem	No	-	TikTok Shop or Showcase store ID. Required when product_source is STORE.
`store_authorized_bc_id`	string or SelectItem	No	-	Business Center ID authorized for the store. Provide when TikTok requires store authorization; otherwise omit.
`identity_id`	string or SelectItem	No	-	Optional TikTok identity ID, usually for LIVE shopping, showcase, or Spark/identity-based delivery flows. Omit unless the user provides an identity.
`identity_type`	string or SelectableOption	No	-	Identity type for identity_id. If using BC_AUTH_TT, also provide identity_authorized_bc_id.
`identity_authorized_bc_id`	string or SelectItem	No	-	Business Center ID authorized for BC_AUTH_TT identity use. Required when identity_type is BC_AUTH_TT.
`promotion_target_type`	string or SelectableOption	No	-	Lead Generation form destination: INSTANT_PAGE or EXTERNAL_WEBSITE. Omit for native DM, call, and instant messaging routes.
`promotion_website_type`	string or SelectableOption	No	-	Optional website page type; omit unless the flow needs it. LINK is only valid for lead generation ad groups collecting leads on an external website form; TIKTOK_NATIVE_PAGE means a TikTok Instant Form/Page. For website conversion or traffic flows TikTok accepts only UNSET or TIKTOK_NATIVE_PAGE and rejects LINK.
`search_result_enabled`	boolean	No	-	Automatic Search Placement. Use on eligible non-Search ad groups to let TikTok also show ads in Search results when the campaign objective is APP_PROMOTION, WEB_CONVERSIONS, TRAFFIC, or LEAD_GENERATION and placement_type is PLACEMENT_TYPE_AUTOMATIC, or placement_type is PLACEMENT_TYPE_NORMAL with PLACEMENT_TIKTOK included. Set false to explicitly disable Automatic Search Placement. Omit to let TikTok auto-default. For Search campaigns/ad_group_mode search, do not set true because Search Ads campaigns are incompatible with Automatic Search Placement; TikTok validates this setting; explicit values are forwarded unchanged. Smart+ supports this boolean where TikTok allows it.
`automated_keywords_enabled`	boolean	No	-	Optional TikTok keyword automation flag. TikTok determines whether keywords must be supplied for the campaign.
`search_keywords`	any	No	-	Native Search keyword objects; TikTok validates campaign compatibility and required fields. Provide a list of objects or a JSON array string. Each object must include keyword and match_type; match_type must be PRECISE_WORD, PHRASE_WORD, or BROAD_WORD. Optional per-keyword fields inside each object: keyword_bid_type FOLLOW_ADGROUP or CUSTOM, and keyword_bid when keyword_bid_type is CUSTOM. Max 1,000 keywords; each keyword max 80 characters and no emoji/special characters.
`request_id`	string	No	-	Optional numeric idempotency key. Smart+ requires one, and Markifact generates it if omitted. Provide a 64-bit integer string only when you need a stable retry key.
`targeting_optimization_mode`	string or SelectableOption	No	-	Smart+ targeting mode: AUTOMATIC for automatic audience targeting or MANUAL for manual targeting. Suggested audience settings can guide automatic targeting; TikTok validates available controls.
`suggestion_audience_enabled`	boolean	No	-	Smart+ only. Set true to use TikTok suggested audiences; omit or false when the user provides manual Smart+ targeting.
`min_budget`	number	No	-	Legacy input not forwarded by this operation. Use budget and budget_mode for ad-group budgets when campaign CBO is disabled, including Smart+.
`app_targeting_type`	string or SelectableOption	No	-	Smart+ app catalog targeting: PROSPECT to reach prospective customers or RETARGETING to reach people who already interacted. Eligibility depends on the parent campaign and catalog settings.
`minis_id`	string	No	-	Smart+ Minis asset ID for MINI_APP or MINI_GAME promotion; omit for other destinations.
`native_series_id`	string	No	-	Smart+ native series campaigns only. Provide when promoting a native series; otherwise omit.
`gaming_ad_compliance_agreement`	string or SelectableOption	No	-	Smart+ app install iOS14 gaming campaigns only. Set ON when the advertiser has agreed to TikTok’s gaming policy; omit for non-gaming campaigns.
`movie_premiere_date`	string	No	-	Smart+ entertainment campaigns only. Provide the movie premiere date when required by TikTok for movie promotion; otherwise omit.
`skip_learning_phase`	boolean	No	-	Optional allowlist-only setting. Set true only when TikTok has enabled skip learning phase for the advertiser; otherwise omit.
`messaging_app_type`	string or SelectableOption	No	-	For LEAD_GEN_CLICK_TO_SOCIAL_MEDIA_APP_MESSAGE. WHATSAPP/ZALO require phone_region_code, phone_region_calling_code, and phone_number. MESSENGER/LINE use messaging_app_account_id. IM_URL supplies its destination on the ad. Manual CONVERSATION supports Messenger/WhatsApp; Smart+ also supports Zalo. LINE and IM_URL use CLICK. TikTok validates advertiser access.
`messaging_app_account_id`	string	No	-	Required for MESSENGER (Facebook Page ID) or LINE (LINE Business ID). Omit for WHATSAPP, ZALO, and IM_URL; WhatsApp derives its account from the three phone fields.
`phone_region_code`	string	No	-	Required with phone_region_calling_code and phone_number for WHATSAPP/ZALO. Region code, for example NZ; obtain valid codes from TikTok /tool/phone_region_code/. Omit for other messaging apps. For Call Ads, all three phone destination fields belong on the ad creative instead.
`phone_region_calling_code`	string	No	-	Required with phone_region_code and phone_number for WHATSAPP/ZALO. Calling code including +, for example +64; use the value matching the phone region.
`phone_number`	string	No	-	Required with phone_region_code and phone_region_calling_code for WHATSAPP/ZALO. Phone number associated with the messaging account. For Call Ads, specify the phone destination on the ad creative instead.
`message_event_set_id`	string	No	-	Instant messaging CONVERSATION only. Required when TikTok cannot match the selected messaging account to an existing message event set. Check matched_event_set from /ctm/message_event_set/get/; if empty, select an available ID from message_event_set_list. Omit for CLICK or when TikTok matches the account automatically.
`advanced_fields`	object or string	No	-	Additional native fields for the selected TikTok ad-group create endpoint, as an object or JSON string. Merged over normal inputs and defaults; explicit advanced values win, nested objects merge, and arrays replace. Example: {“comment_disabled”: true, “share_disabled”: false}. For Smart+, use targeting_spec for nested targeting. Do not include advertiser_id, campaign_id, account, connection_id, or ad_group_mode; use normal inputs. TikTok validates native fields; this cannot bypass advertiser permissions or route eligibility. Omitted status defaults to DISABLE for all creation paths.

SelectItem

Field	Type	Required	Default	Description
`value`	string	Yes	-	The value of the selectable item.
`label`	string	Yes	-	The label of the selectable item, used for display purposes. If not provided, defaults to the value.

SelectableOption

Field	Type	Required	Default	Description
`value`	string	Yes	-
`label`	string	Yes	-

Output

Type: Dict Returns created TikTok ad group details. Fields: adgroup_id, adgroup_name, campaign_id, ad_group_mode