> ## Documentation Index > Fetch the complete documentation index at: https://docs.markifact.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Ad Group > Create TikTok Ads ad groups for manual, Search, and Upgraded Smart+ campaign types Create TikTok Ads ad groups for manual, Search, and Upgraded Smart+ campaign types. | | | | --------------------- | ---------------------------- | | **App** | TikTok Ads | | **Operation ID** | `tiktok_ads_create_ad_group` | | **Type** | Action | | **Connection** | `tiktok_ads` (required) | | **Credits per run** | 2 | | **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. Use upgraded\_smart\_plus only for a Smart+ campaign; Smart+ campaigns can have one ad group, and TikTok manages its status and budget from the campaign. Use manual for regular ad groups and search for Search Ads ad groups. | | `campaign_id` | string or SelectItem | Yes | - | TikTok campaign ID to create the ad group under. For Smart+, use the Smart+ campaign ID; TikTok allows only one Smart+ ad group per Smart+ campaign. | | `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 | - | Manual/search only. Set ENABLE or DISABLE when creating regular/search ad groups. Omit for Smart+: TikTok rejects status changes because Smart+ campaigns have one TikTok-managed ad group. | | `promotion_type` | string or SelectableOption | No | - | What the ad group promotes. Required by TikTok for app, website, lead, and shopping flows. For Reach, Video Views, and Engagement-style goals, Markifact defaults this to WEBSITE if omitted. | | `optimization_goal` | string or SelectableOption | Yes | - | Delivery goal for the ad group. Choose the goal that matches the objective, such as CONVERT for website conversions, VALUE for value optimization, INSTALL for app installs, CLICK/PAGE\_VISIT for traffic, or LEAD\_GENERATION for leads, ENGAGED\_VIEW/ENGAGED\_VIEW\_FIFTEEN for video views, and so on. | | `billing_event` | string or SelectableOption | Yes | - | Billing event required by the optimization goal. Use CPC for CLICK/PAGE\_VISIT, CPM for SHOW/REACH, CPV for ENGAGED\_VIEW goals, and OCPM for conversion, install, lead, value, follower, live, and destination-visit goals. | | `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 for CPC, CPM, or CPV billing. Required only when bid\_type is BID\_TYPE\_CUSTOM and billing\_event is CPC, CPM, or CPV; omit for Maximum Delivery and OCPM. | | `conversion_bid_price` | number | No | - | Cost Cap amount for OCPM conversion-style bidding. Required only when bid\_type is BID\_TYPE\_CUSTOM and billing\_event is OCPM; omit for Maximum Delivery and non-OCPM billing. | | `deep_bid_type` | string or SelectableOption | No | - | Value optimization only. Use VO\_HIGHEST\_VALUE to maximize value or VO\_MIN\_ROAS when the user provides a minimum ROAS target. | | `roas_bid` | number | No | - | Minimum ROAS target. Required when deep\_bid\_type is VO\_MIN\_ROAS; omit otherwise. | | `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 | - | Manual/search only. Set when this ad group should have its own daily/lifetime budget. Omit for Smart+: budget is set on the campaign. | | `budget` | number | No | - | Manual/search only. Ad group budget amount in account currency; required when budget\_mode is daily, lifetime, or dynamic daily. Do not set for Smart+: use campaign budget instead. | | `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. | | `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. | | `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. | | `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 | - | TikTok optimization event for conversion, app, lead, or shopping flows. Required with pixel\_id and for CONVERT/VALUE goals. Use TikTok event names such as PAY\_ACTION, ADD\_BILLING, SHOPPING, PAGE\_VIEW, FORM, or INSTALL\_FINISH; do not use Meta-style names like PURCHASE. | | `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 | - | Optional conversion attribution window. Use only when the advertiser needs a non-default conversion window. | | `click_attribution_window` | string or SelectableOption | No | - | Optional click attribution window. Use only when overriding TikTok's default click attribution setting. | | `view_attribution_window` | string or SelectableOption | No | - | Optional view attribution window. Use only when overriding TikTok's default view attribution setting. | | `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. | | `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\_SHOPPING 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 | - | Manual/search shopping only. Use CATALOG when products come from a catalog and STORE when using TikTok Shop/showcase; catalog\_id or store\_id is then required. | | `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 | - | Optional website promotion target type. Use when TikTok needs the website destination category; omit for app, lead, and shopping flows. | | `promotion_website_type` | string or SelectableOption | No | - | Optional website page type. Use with website promotion flows when distinguishing landing page/site behavior; otherwise omit. | | `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; Markifact sends false for Search ad groups. Smart+ supports this boolean where TikTok allows it. | | `automated_keywords_enabled` | boolean | No | - | Search only. Optional TikTok automation flag where supported, but it does not replace search\_keywords. Always provide search\_keywords for Search ad groups. | | `search_keywords` | any | No | - | Search only and required for every Search ad group. 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+ only. Choose targeting expansion or manual targeting mode when the user wants to control Smart+ audience expansion; otherwise omit. | | `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 | - | Do not use for Smart+ ad group creation. Smart+ budget is set on the campaign, and Markifact ignores this field before calling TikTok. | | `app_targeting_type` | string or SelectableOption | No | - | Smart+ app campaigns only. Use when TikTok requires an app targeting type for APP\_ANDROID or APP\_IOS promotion. | | `minis_id` | string | No | - | Smart+ Mini Program campaigns only. Provide the minis ID when promotion\_type is MINI\_PROGRAM or TikTok requires a minis asset. | | `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. | ### 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`