smart_plus_adgroup_create

Ad group name. Maximum 512 characters. Emojis are not supported.

Advertiser ID.

Required when campaign `sales_destination` is `WEB_AND_APP`. App configuration for up to 2 apps. You can provide an Android app, an iOS app, or one of each. Maximum size: 2.

Required when both conditions are met: at the campaign level, (`objective_type` is `APP_PROMOTION` and `app_promotion_type` is `APP_INSTALL` or `APP_RETARGETING`) or (`objective_type` is `WEB_CONVERSIONS` and `sales_destination` is `APP`); and `campaign_type` is `REGULAR_CAMPAIGN`. App ID of the app to promote. You cannot use an app that has not activated the SAN module on your MMP.

Event count / statistic type. If you omit `click_attribution_window`, `engaged_view_attribution_window`, `view_attribution_window`, and `attribution_event_count`, default settings, if any, are used; you can confirm defaults via `/smart_plus/adgroup/get/`. Once set, this field cannot be updated.

Required when `optimization_goal` is `CLICK` and `bid_type` is `BID_TYPE_CUSTOM`. Target cost per click. Must be lower than budget. When CBO is enabled (`budget_optimize_on=true`) at the campaign level, this setting, if specified, must be the same across all ad groups in the same campaign.

Bidding strategy. `BID_TYPE_NO_BID` is Maximum Delivery. `BID_TYPE_CUSTOM` is Cost Cap / Target CPA and can only be used when campaign-level or ad-group-level `budget_mode` is `BUDGET_MODE_DYNAMIC_DAILY_BUDGET`. This setting, if specified, must be the same across all ad groups in the same campaign.

Billing event. Currently only `OCPM` and `CPC` are supported. When `optimization_goal` is `CLICK`, set this to `CPC`. When `optimization_goal` is not `CLICK`, set this to `OCPM`. When CBO is enabled (`budget_optimize_on=true`) at the campaign level, this setting must be the same across all ad groups in the same campaign.

Required when campaign CBO is disabled (`budget_optimize_on=false`) and ignored when CBO is enabled (`budget_optimize_on=true`). If `budget_auto_adjust_strategy=UNSET`, this is the fixed ad-group budget. If `budget_auto_adjust_strategy=AUTO_BUDGET_INCREASE`, this is the initial ad-group budget.

Valid only when campaign `budget_optimize_on` is `false` and, at the ad group level, either: for `APP_PROMOTION`, `budget_mode` is `BUDGET_MODE_DYNAMIC_DAILY_BUDGET`, `optimization_goal` is `VALUE`, `deep_bid_type` is `VO_MIN_ROAS`, and `vbo_window` is `ZERO_DAY`; or for `LEAD_GENERATION`, `budget_mode` is `BUDGET_MODE_DYNAMIC_DAILY_BUDGET` and `bid_type` is `BID_TYPE_CUSTOM`. `AUTO_BUDGET_INCREASE` enables Goal-based budget increase: the provided `budget` becomes the initial daily budget, and it may automatically increase by 20%, up to 10 times per day, when utilization reaches 90% or more, then reset to the original daily budget each day. `UNSET` disables this behavior. This feature is allowlist-only.

Required when campaign CBO is disabled (`budget_optimize_on=false`) and ignored when CBO is enabled (`budget_optimize_on=true`). Ad-group budget mode. If `BUDGET_MODE_TOTAL`, then `schedule_type` must be `SCHEDULE_START_END`, which requires `schedule_end_time`. When campaign-level `budget_optimize_on` is `false` and campaign `budget_mode` is `BUDGET_MODE_DAY`, you can only set this field to `BUDGET_MODE_DYNAMIC_DAILY_BUDGET`. This setting, if specified, must be the same across all ad groups in the same campaign.

ID of the campaign that this ad group belongs to.

Required when `catalog_enabled` is `true`. Business Center ID that owns `catalog_id`.

Required when `catalog_enabled` is `true` at the campaign level. Catalog ID to use in the ad group.

Click-through attribution window. If you manually configure attribution windows, you must pass at least `click_attribution_window` and `view_attribution_window` together, and may optionally include `engaged_view_attribution_window`; if `engaged_view_attribution_window` is passed, it must be accompanied by both `click_attribution_window` and `view_attribution_window`. `THIRTY_DAYS` is valid only when `promotion_type` is `MINI_GAME`. `THIRTY_TWO_DAYS` and `ONE_HUNDRED_EIGHTY_DAYS` are valid only when `promotion_type` is `MINI_APP` and `optimization_event` is `ACTIVE_PAY`. If you omit `click_attribution_window`, `engaged_view_attribution_window`, `view_attribution_window`, and `attribution_event_count`, default settings, if any, are used; you can confirm defaults via `/smart_plus/adgroup/get/`. Once set, this field cannot be updated.

Whether to disable comments on TikTok. Default is `false`.

Required when `optimization_goal` is `CONVERT`, `TRAFFIC_LANDING_PAGE_VIEW`, `INSTALL`, or `IN_APP_EVENT`, and `bid_type` is `BID_TYPE_CUSTOM`. Target cost per conversion or landing page view. Must be lower than budget. When CBO is enabled (`budget_optimize_on=true`) at the campaign level, this setting, if specified, must be the same across all ad groups in the same campaign.

Custom Conversion ID to use in the ad group. Valid only when either `pixel_id` or `app_id` is specified, a Custom Conversion exists for that source, `optimization_goal` is `CONVERT` or `IN_APP_EVENT`, `optimization_event` is specified and matches the Standard Event associated with the Custom Conversion, and the Custom Conversion status is Active or No recent activity.

Delivery schedule string of 48 × 7 characters, one per 30-minute slot from Monday through Sunday. `1` means deliver and `0` means do not deliver. An all-1 value or omitting this field means full-time delivery.

Required when `optimization_goal` is `VALUE`. Bidding strategy for in-app events. `VO_MIN_ROAS` can only be used when campaign-level or ad-group-level `budget_mode` is `BUDGET_MODE_DYNAMIC_DAILY_BUDGET`. This setting, if specified, must be the same across all ad groups in the same campaign.

Required when `deep_funnel_optimization_status` is `ON`. Event source type for deep funnel optimization.

Required when `deep_funnel_optimization_status` is `ON`. Source ID corresponding to `deep_funnel_event_source`: when `PIXEL`, provide a Pixel ID; when `OFFLINE`, provide an Offline Event Set ID; when `CRM`, provide a CRM Event Set ID.

Required when `deep_funnel_optimization_status` is `ON`. Deep funnel optimization event, for example `SHOPPING`.

Valid only when `promotion_type` is `LEAD_GENERATION`. Enables or disables deep funnel optimization, which optimizes both primary and deeper-funnel events. Default is `OFF`. Deep funnel optimization with CRM events is allowlist-only; Pixel and Offline event sources are generally available.

Engaged view-through attribution window. Default is `OFF`. If you manually configure attribution windows, you must pass at least `click_attribution_window` and `view_attribution_window` together, and may optionally include this field; if this field is passed, it must be accompanied by both `click_attribution_window` and `view_attribution_window`. `FOURTEEN_DAYS` and `TWENTY_EIGHT_DAYS` are valid only in Upgraded Smart+ Ads with Website and App Optimization. If you omit `click_attribution_window`, `engaged_view_attribution_window`, `view_attribution_window`, and `attribution_event_count`, default settings, if any, are used; you can confirm defaults via `/smart_plus/adgroup/get/`. Once set, this field cannot be updated.

Valid when campaign `objective_type` is `APP_PROMOTION` and either `app_promotion_type` is `APP_RETARGETING`, or `app_promotion_type` is `APP_INSTALL` with `campaign_type` `REGULAR_CAMPAIGN`. Whether to agree to the Compliance Assurance Policy for Gaming Advertisers on TikTok. Default is `OFF`. This is currently an allowlist-only feature.

Required when `identity_type` is `BC_AUTH_TT`. Business Center ID associated with the TikTok Account User in Business Center identity. Once set, this field cannot be updated.

Valid only when `promotion_type` is `NATIVE_SERIES`, or when `promotion_type` is `LEAD_GEN_CLICK_TO_TT_DIRECT_MESSAGE` and the ad account is allowlisted for ad-group-level TikTok account selection in TikTok Direct Messaging Ads. TikTok account identity ID used for the Series host/manager or for direct messaging ads. Selecting a TikTok account at the ad group level for direct messaging ads is allowlist-only. Once set, this field cannot be updated.

Valid only when `promotion_type` is `NATIVE_SERIES`, or when `promotion_type` is `LEAD_GEN_CLICK_TO_TT_DIRECT_MESSAGE` and the ad account is allowlisted for ad-group-level TikTok account selection in TikTok Direct Messaging Ads. Identity type for the TikTok account. Selecting a TikTok account at the ad group level for direct messaging ads is allowlist-only. Once set, this field cannot be updated.

Valid only when `targeting_optimization_mode` is `MANUAL`. Whether the promoted content is HFSS (High Fat, Salt, Sugar). In regulated regions, HFSS ads must target users aged 18 or over. Can be set to `true` when targeting includes the UK, Australia, New Zealand, or the European Union. Default is `false`.

Required and must be `true` when targeted locations include the UK and `is_hfss` is `true`. Confirms compliance with UK Less Healthy Foods regulations. Default is `false`.

Required when `promotion_type` is `LEAD_GEN_CLICK_TO_SOCIAL_MEDIA_APP_MESSAGE`, `optimization_goal` is `CONVERSATION`, and the messaging account configured in the ad group does not match any existing message event set. If the messaging account selected via `messaging_app_account_id` or derived from `phone_info` already matches a unique existing event set, this field is ignored and automatically populated. If `/ctm/message_event_set/get/` returns an empty `matched_event_set`, use that endpoint's `message_event_set_list` to choose a value. Once set, this field cannot be updated.

Required when `messaging_app_type` is `MESSENGER` or `LINE`, or when `messaging_app_type` is `ZALO` and `zalo_id_type` is `ZALO_OFFICIAL_ACCOUNT`. For `MESSENGER`, provide a Facebook Page ID. For `LINE`, provide a LINE Business ID. For `ZALO` with `ZALO_OFFICIAL_ACCOUNT`, provide the Zalo Official Account ID. If `messaging_app_type` is `WHATSAPP` or `zalo_id_type` is `ZALO_PHONE_ACCOUNT`, this field is ignored and automatically set from `phone_info`. Once set, this field cannot be updated.

Valid only when `promotion_type` is `LEAD_GEN_CLICK_TO_SOCIAL_MEDIA_APP_MESSAGE`. Required when `optimization_goal` is `CONVERSATION`. If `optimization_goal` is `CLICK`, default is `IM_URL`. Companion fields depend on the value: `MESSENGER` requires `messaging_app_account_id` with a Facebook Page ID; `WHATSAPP` requires `phone_info`; `ZALO` requires `zalo_id_type`, and then `messaging_app_account_id` if `zalo_id_type=ZALO_OFFICIAL_ACCOUNT` or `phone_info` if `zalo_id_type=ZALO_PHONE_ACCOUNT`; `LINE` requires `messaging_app_account_id` with a LINE Business ID; `IM_URL` requires no companion account field. When `optimization_goal` is `CONVERSATION`, you cannot set this field to `LINE` or `IM_URL`. Once set, this field cannot be updated.

Valid only when campaign `budget_optimize_on` is `true`, campaign `budget_mode` is `BUDGET_MODE_DYNAMIC_DAILY_BUDGET`, and ad-group `bid_type` is `BID_TYPE_NO_BID`. Minimum ad-group budget. The system will aim to spend at least this amount, but it is not guaranteed.

Required when `promotion_type` is `MINI_APP` or `MINI_GAME`. TikTok Minis ID. If `promotion_type` is `MINI_APP`, provide a mini app ID; if `MINI_GAME`, provide a mini game ID.

Valid when campaign `is_promotional_campaign` is `true` and the advertiser is allowlisted for theatrical-release promotion settings. Theatrical release date in `YYYY-MM-DD` (UTC+0).

Required when `promotion_type` is `NATIVE_SERIES`. TikTok Series ID.

Status to apply when the ad group is created. Default is `ENABLE`.

Required when `pixel_id` is specified; or when `pixel_id` is not specified and `optimization_goal` is `IN_APP_EVENT` or `VALUE`; or when `pixel_id` is not specified and `minis_id` is specified. Conversion event. When CBO is enabled (`budget_optimize_on=true`) at the campaign level, this setting, if specified, must be the same across all ad groups in the same campaign.

The measurable result to optimize for. Supported values are `CLICK`, `INSTALL`, `IN_APP_EVENT`, `VALUE`, `CONVERT`, `TRAFFIC_LANDING_PAGE_VIEW`, `CONVERSATION`, and `LEAD_GENERATION`. When CBO is enabled (`budget_optimize_on=true`) at the campaign level, this setting, if specified, must be the same across all ad groups in the same campaign. When `promotion_type` is `LEAD_GEN_CLICK_TO_SOCIAL_MEDIA_APP_MESSAGE` and `optimization_goal` is `CONVERSATION`, `messaging_app_type` can only be `MESSENGER`, `WHATSAPP`, or `ZALO`.

Required when `messaging_app_type` is `WHATSAPP`, or when `messaging_app_type` is `ZALO` and `zalo_id_type` is `ZALO_PHONE_ACCOUNT`. Phone details used for WhatsApp or Zalo phone-number messaging. Once set, this field cannot be updated.

Required when campaign `objective_type` is `WEB_CONVERSIONS` or `LEAD_GENERATION` and ad-group `optimization_goal` is `CONVERT` or `VALUE`. Not supported when `optimization_goal` is `CLICK`, `INSTALL`, `IN_APP_EVENT`, or `TRAFFIC_LANDING_PAGE_VIEW`. Pixel ID.

Placement strategy. By default, the system may automatically configure placements for Upgraded Smart+ campaigns. If only Select Placement is supported in your scenario, omitting `placement_type` and `placements` can trigger a placement error; in that case set `placement_type` to `PLACEMENT_TYPE_NORMAL` and provide `placements`. `placement_type` cannot be updated after creation. If set to `PLACEMENT_TYPE_AUTOMATIC`, the actual supported placements are returned in `placements`.

Required when `placement_type` is `PLACEMENT_TYPE_NORMAL`. Ignored and overwritten by the system when `placement_type` is `PLACEMENT_TYPE_AUTOMATIC`. `placements` cannot be updated after creation. `PLACEMENT_GLOBAL_APP_BUNDLE` is limited to certain target locations and does not support `optimization_goal=TRAFFIC_LANDING_PAGE_VIEW`.

Required when `objective_type` is `LEAD_GENERATION`. Optimization location for lead generation. When CBO is enabled (`budget_optimize_on=true`) at the campaign level, this setting, if specified, must be the same across all ad groups in the same campaign.

Promotion type (optimization location). Choose where to promote. Supported values are `APP_ANDROID`, `APP_IOS`, `WEBSITE`, `MINI_APP`, `MINI_GAME`, `NATIVE_SERIES`, `LEAD_GENERATION`, `LEAD_GEN_CLICK_TO_TT_DIRECT_MESSAGE`, `LEAD_GEN_CLICK_TO_SOCIAL_MEDIA_APP_MESSAGE`, and `LEAD_GEN_CLICK_TO_CALL`, depending on campaign settings. When campaign `objective_type` is `APP_PROMOTION` and `app_promotion_type` is `APP_INSTALL` or `APP_RETARGETING`, set this to `APP_ANDROID` or `APP_IOS`. When `objective_type` is `APP_PROMOTION` and `app_promotion_type` is `MINIS`, set this to `MINI_APP`, `MINI_GAME`, or `NATIVE_SERIES`. When `objective_type` is `WEB_CONVERSIONS`, set this to `WEBSITE` if `sales_destination` is `WEBSITE`, or `APP_ANDROID`/`APP_IOS` if `sales_destination` is `APP`. When `objective_type` is `LEAD_GENERATION`, set this to one of `LEAD_GENERATION`, `LEAD_GEN_CLICK_TO_TT_DIRECT_MESSAGE`, `LEAD_GEN_CLICK_TO_SOCIAL_MEDIA_APP_MESSAGE`, or `LEAD_GEN_CLICK_TO_CALL`. When CBO is enabled (`budget_optimize_on=true`) at the campaign level, this setting must be the same across all ad groups in the same campaign.

Idempotency key for ad group creation.

Required when `deep_bid_type` is `VO_MIN_ROAS`. Target ROAS for value-based optimization. Range: 0.01 to 1,000. When CBO is enabled (`budget_optimize_on=true`) at the campaign level, this setting, if specified, must be the same across all ad groups in the same campaign.

Required when `schedule_type` is `SCHEDULE_START_END`. Schedule end time in `YYYY-MM-DD HH:MM:SS` (UTC+0). Must not be later than `2038-01-01 00:00:00`.

Schedule start time in `YYYY-MM-DD HH:MM:SS` (UTC+0). Can be up to 12 hours earlier than the current time, but not later than `2028-01-01 00:00:00`.

Schedule type. `SCHEDULE_FROM_NOW` can only be used when campaign-level or ad-group-level `budget_mode` is `BUDGET_MODE_DYNAMIC_DAILY_BUDGET`. `SCHEDULE_START_END` runs between `schedule_start_time` and `schedule_end_time`.

Whether to disable sharing to third-party platforms. Default is `false`.

Valid only when `targeting_optimization_mode` is `AUTOMATIC`. Whether to enable audience suggestions. Default is `false`. When `true`, you can additionally specify `age_groups`, `gender`, `audience_ids`, `interest_category_ids`, `interest_keyword_ids`, `purchase_intention_keyword_ids`, and `actions` in `targeting_spec` as suggestions for automatic targeting. These are guidance signals only and delivery to those audiences is not guaranteed. If targeting settings do not align with `targeting_optimization_mode` and `suggestion_audience_enabled`, they are ignored without error. You cannot set this field to `true` if Realtime API (RTA) is enabled at the campaign level.

Audience targeting optimization mode. Default is `AUTOMATIC`. When `AUTOMATIC` and `suggestion_audience_enabled=false`, allowed targeting fields depend on campaign scenario but generally include a limited control set such as `location_ids`, `zipcode_ids`, `spc_audience_age`, `languages`, `operating_systems`, and `excluded_audience_ids`; for app-destination Smart+ catalog ad groups, it can instead include `audience_ids` and `gender` rather than some other fields. When `AUTOMATIC` and `suggestion_audience_enabled=true`, you can additionally provide suggestion fields such as `age_groups`, `gender`, `audience_ids`, `interest_category_ids`, `interest_keyword_ids`, `purchase_intention_keyword_ids`, and `actions`. When `MANUAL`, you can specify the full custom-targeting set listed under `targeting_spec`, including demographic, audience, interest, behavior, device, network, and saved-audience fields. If you send targeting settings that do not match the selected `targeting_optimization_mode` and `suggestion_audience_enabled`, those settings are ignored without error.

Targeting settings object. Which nested fields are accepted depends on `targeting_optimization_mode` and `suggestion_audience_enabled`; see those fields for the exact allowed combinations.

array

Window for the selected value-based bidding strategy. Default is `SEVEN_DAYS`. When `deep_bid_type` uses Minimum ROAS / Target ROAS, this controls whether the target ROAS is Day 7 or Day 0. When Highest Value is used, this controls whether value is maximized within Day 7 or Day 0. This setting, if specified, must be the same across all ad groups in the same campaign. Some VBO IAP/VBO IAA Day 0 and Day 7 scenarios are allowlist-only. Once set, this field cannot be updated.

Whether users can download your video ads on TikTok. Default is `false`.

View-through attribution window. If you manually configure attribution windows, you must pass at least `click_attribution_window` and `view_attribution_window` together, and may optionally include `engaged_view_attribution_window`; if `engaged_view_attribution_window` is passed, it must be accompanied by both `click_attribution_window` and `view_attribution_window`. If you omit `click_attribution_window`, `engaged_view_attribution_window`, `view_attribution_window`, and `attribution_event_count`, default settings, if any, are used; you can confirm defaults via `/smart_plus/adgroup/get/`. Once set, this field cannot be updated.

Required when `messaging_app_type` is `ZALO`. Zalo contact format. If `ZALO_OFFICIAL_ACCOUNT`, you must also specify `messaging_app_account_id`. If `ZALO_PHONE_ACCOUNT`, you must also specify `phone_info`. You can only set `zalo_id_type` to `ZALO_PHONE_ACCOUNT` when `optimization_goal` is `CLICK`. Once set, this field cannot be updated.