> ## 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 ad groups for manual, Search, and Upgraded Smart+ campaigns, including native DM, phone-call, and instant-messaging lead routes

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`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.