adgroup_create

List of behavioral targeting category objects.

Whether to use App Profile Page. `ON` or `OFF`. 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 `ON` when all of the following are true: `ios14_targeting=IOS14_PLUS`, `optimization_goal=IN_APP_EVENT`, and `bid_type=BID_TYPE_CUSTOM`.

Ad group name. Maximum 512 characters; emoji is not allowed.

Advertiser ID.

Age groups to target. In certain scenarios, ad groups targeting `AGE_13_17` in the US, Latin America, the European Economic Area, the UK, Switzerland, or Canada are not allowed (see New age restrictions for ads on TikTok). If you use targeting options that do not support `AGE_13_17` in those regions and you leave `age_groups` unspecified or as `[]`, the field defaults to `["AGE_18_24", "AGE_25_34", "AGE_35_44", "AGE_45_54", "AGE_55_100"]`. If your ad group targets `AGE_13_17` in those regions, explicitly specify the exact age groups you want to target.

Required when `sales_destination=WEB_AND_APP` at the campaign level. Details of the app(s) to promote. Maximum size: 2. You can specify an Android app, an iOS app, or both.

App ID of the app to promote. Required when `objective_type=APP_PROMOTION` and `app_promotion_type=APP_RETARGETING`, or when `objective_type=APP_PROMOTION` with `app_promotion_type=APP_INSTALL` or `APP_PREREGISTRATION` and the campaign is not an iOS14 Dedicated Campaign. You cannot use an app that has not activated the SAN module on your MMP.

Event count (Statistic type) for the ad group, controlling how actions are counted after viewing or clicking. `UNSET` = unset. `EVERY` = count multiple events as separate conversions. `ONCE` = count multiple events as 1 conversion. Allowed values vary by advertising objective. If you omit all four attribution fields, default settings (if any) are used; check via `/adgroup/get/`. Once set, this field cannot be updated.

List of custom audience IDs to include.

Rules that specify your audience. Valid only when `objective_type` is `TRAFFIC` or `APP_PROMOTION`. For details, see Audience Rules.

Required and valid only when the campaign-level `app_promotion_type=APP_RETARGETING`. Not supported otherwise. App retargeting audience type. `NEW_CUSTOM_AUDIENCE` = retargeting custom audience. To use an empty retargeting custom audience, omit `audience_ids` and `excluded_audience_ids`. To use a non-empty audience, specify `audience_ids` (Include), `excluded_audience_ids` (Exclude), or both — they cannot share the same IDs.

Valid only when at the campaign level `is_search_campaign=true`. Whether to enable automated keywords (system-generated keywords after ads are added). Default: `false`. Automated keywords in Search Ads Campaigns are allowlist-only.

Required and must be `CPV` (Cost per One View) when `objective_type=VIDEO_VIEW`. How Cost per View is calculated and measured. Cannot be updated after creation. Not needed when `objective_type` is not `VIDEO_VIEW`. The enum value `CPMV` is deprecated in v1.3.

Required when `billing_event` is `CPC`, `CPM`, or `CPV` and `bid_type` is `BID_TYPE_CUSTOM` or omitted (see `bid_type`). Must be greater than 0. Bid price (the average cost per result, used for the Cost Cap bidding strategy). When CBO is enabled at the campaign level, set the same bid value across all ad groups. Must be lower than the campaign-level and ad-group-level budget. See Bidding-Bidding limits for the verification mechanism.

Bidding strategy. If omitted, `BID_TYPE_CUSTOM` is used, which requires a bid greater than 0 and lower than the ad group budget: `conversion_bid_price` when `billing_event=OCPM`, or `bid_price` when `billing_event` is `CPC`, `CPM`, or `CPV`. To bid without a price, pass `bid_type=BID_TYPE_NO_BID`. `BID_TYPE_NO_BID` does not support accelerated delivery, so always set `pacing=PACING_MODE_SMOOTH` with it; omitting `pacing` counts as accelerated. Required when Campaign Budget Optimization (CBO) is enabled at the campaign level (`budget_optimize_on=true`). For new ad groups under one CBO campaign, this field should match the first ad group. For enum values, see the TikTok Marketing API Bidding Strategy enumeration.

Events you want to pay for. Must be exactly one of: `CPC`, `CPM`, `CPV`, `OCPM`, and must match `optimization_goal`: - `CPC`: `CLICK`, `PAGE_VISIT` - `CPM`: `SHOW`, `REACH` - `CPV`: `ENGAGED_VIEW`, `ENGAGED_VIEW_FIFTEEN` - `OCPM`: `CONVERT`, `INSTALL`, `IN_APP_EVENT`, `TRAFFIC_LANDING_PAGE_VIEW`, `LEAD_GENERATION`, `CONVERSATION`, `FOLLOWERS`, `VALUE`, `AUTOMATIC_VALUE_OPTIMIZATION`, `PRODUCT_CLICK_IN_LIVE`, `MT_LIVE_ROOM`, `DESTINATION_VISIT` Required. With `bid_type=BID_TYPE_CUSTOM`, `OCPM` needs `conversion_bid_price`; `CPC`, `CPM`, and `CPV` need `bid_price`.

Pangle app block list IDs. You can obtain an ID from the `app_package_id` field returned by Get Pangle block list. Takes effect only when Pangle placement is selected.

Required only when `brand_safety_type=THIRD_PARTY` and `placements=["PLACEMENT_TIKTOK"]`. Brand safety partner. `IAS` = IAS. `OPEN_SLATE` = the partner is named DoubleVerify on TikTok Ads Manager because it has been acquired by DoubleVerify. Pre-bid third-party brand safety solutions are allowlist-only. Once set, this field cannot be modified.

Brand safety type. Default value: NO_BRAND_SAFETY. Enum values: NO_BRAND_SAFETY (to be deprecated in the next API version): To not use any brand safety solution. Full inventory, which means your ads may appear next to some content featuring mature themes. EXPANDED_INVENTORY: Use TikTok's brand safety solution. Expanded inventory means that your ads will appear next to content where most inappropriate content has been removed, and that does not contain mature themes. In the next API version, EXPANDED_INVENTORY will replace NO_BRAND_SAFETY and will be the default brand safety option. STANDARD_INVENTORY: Use TikTok's brand safety solution. Standard inventory means that ads will appear next to content that is appropriate for most brands. LIMITED_INVENTORY: Use TikTok's brand safety solution. Limited inventory means that your ads will not appear next to content that contains mature themes. THIRD_PARTY: Use a third-party brand safety solution. You also need to pass a value to the brand_safety_partner field.

Ad group budget, in the advertiser's account currency. It must reach the minimum for that currency, so check the account currency before choosing an amount: a daily budget (`BUDGET_MODE_DAY` or `BUDGET_MODE_DYNAMIC_DAILY_BUDGET`) has a fixed minimum per day (20 in a USD account), and a lifetime budget (`BUDGET_MODE_TOTAL`) has a minimum that grows with the length of the schedule (140 for a 7-day schedule in a USD account). If the amount the user asked for is below this minimum, do not raise it on your own: tell the user the minimum and ask whether to raise it. Ignored when Campaign Budget Optimization is enabled (`budget_optimize_on=true` at the campaign level). For daily budget value ranges by currency, see Currency-Daily budget value range.

Ad group budget mode. When Campaign Budget Optimization (CBO) is enabled at the campaign level, ad-group `budget_mode` is ignored. When CBO is disabled: `BUDGET_MODE_TOTAL` = lifetime budget; `BUDGET_MODE_DYNAMIC_DAILY_BUDGET` = average daily budget over a week (daily costs do not exceed 125% of the average; weekly costs do not exceed average × 7); `BUDGET_MODE_DAY` = daily budget. When `objective_type` is `TRAFFIC`, `APP_PROMOTION`, `WEB_CONVERSIONS`, `LEAD_GENERATION`, `PRODUCT_SALES` (Video Shopping Ads only), `REACH`, `VIDEO_VIEWS`, or `ENGAGEMENT`, and you want a non-lifetime budget, use `BUDGET_MODE_DYNAMIC_DAILY_BUDGET`. `BUDGET_MODE_DYNAMIC_DAILY_BUDGET` for `REACH`, `VIDEO_VIEWS`, and `ENGAGEMENT` is allowlist-only. For `REACH`, `VIDEO_VIEWS`, and `ENGAGEMENT`, prefer `BUDGET_MODE_DYNAMIC_DAILY_BUDGET` over `BUDGET_MODE_DAY`. If `BUDGET_MODE_DAY`, then `schedule_type` can be `SCHEDULE_START_END` or `SCHEDULE_FROM_NOW`. If `BUDGET_MODE_TOTAL`, then `schedule_type` must be `SCHEDULE_START_END` (which requires `schedule_end_time`).

ID of the campaign that this ad group belongs to.

Carriers to target. Carriers must be consistent with the targeted location(s). Only carriers with `in_use=true` are valid.

Required when `shopping_ads_type=VIDEO` and `product_source` is `CATALOG` or `STORE`. Optional when `shopping_ads_type=LIVE`. Not supported when `shopping_ads_type=PRODUCT_SHOPPING_ADS` and `product_source=STORE`. Business Center ID that has permission for the catalog. For catalogs in Business Center, pass the Business Center ID that owns the catalog. Starting June 30th, 2024, when `product_source=STORE`, this field is ignored.

Required when `product_source` is `CATALOG` or `STORE`. When `shopping_ads_type=LIVE`, `catalog_id`, `catalog_authorized_bc_id`, `store_id`, and `store_authorized_bc_id` are optional: if you provide a TikTok Shop through these parameters, sales of products in that shop are reported; otherwise sales of products showcased in `identity_id` are reported. When `product_source=CATALOG`, set this to the catalog you want to promote products from. When `product_source=STORE`, set this to the catalog bound to the promoted TikTok Shop. Starting June 30th, 2024, when `product_source=STORE`, `catalog_id` is ignored.

Valid only when at the campaign level `objective_type` is `REACH`, `VIDEO_VIEWS`, `ENGAGEMENT`, `RF_REACH`, `APP_PROMOTION`, `WEB_CONVERSIONS`, `TRAFFIC`, or `LEAD_GENERATION`, and at the ad group level `placements=["PLACEMENT_TIKTOK"]` and `brand_safety_type` is `STANDARD_INVENTORY` or `LIMITED_INVENTORY`. Content exclusion category IDs.

Click-through attribution window for the ad group. `OFF`, `ONE_DAY` = 1-day click, `SEVEN_DAYS` = 7-day click, `FOURTEEN_DAYS` = 14-day click, `TWENTY_EIGHT_DAYS` = 28-day click. Allowed values vary by advertising objective. To manually configure attribution windows, you must pass at least `click_attribution_window` and `view_attribution_window` simultaneously, and `engaged_view_attribution_window` is optional but, if passed, must be accompanied by both. If you omit `click_attribution_window`, `engaged_view_attribution_window`, `view_attribution_window`, and `attribution_event_count`, default settings (if any) are used; check via `/adgroup/get/`. Once set, this field cannot be updated.

Whether to disable comments on ads on TikTok.

Contextual tag IDs. Allowlist-only. Only supports campaign-level `objective_type` of `REACH` and `VIDEO_VIEWS`. Not supported when `brand_safety_type=THIRD_PARTY`.

Required when `bid_type=BID_TYPE_CUSTOM` and `billing_event=OCPM`. Target cost per conversion for oCPM (Optimized Cost per Mille). Must be lower than the campaign-level and ad-group-level budget. See Bidding-Bidding limits for the verification mechanism.

Creative delivery strategy. `CUSTOM` = custom (default). Automated ads (`creative_material_mode=DYNAMIC`) are deprecated; use Smart Creative ads (`creative_material_mode=CUSTOM`).

ID of the Custom Conversion to use. Valid only when all of the following are met: either `pixel_id` or `app_id` is specified; a Custom Conversion has been configured for that `pixel_id`/`app_id`; `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's `activity_status` is `ACTIVE` or `NO_RECENT_ACTIVITY`.

Ad delivery arrangement, a 48 × 7 = 336-character string of `0` and `1`. Each character maps to a 30-minute slot from Monday through Sunday: the first character is 0:01-0:30 Monday, the second is 0:31-1:00 Monday, the last is 23:31-0:00 Sunday. `1` = deliver in that slot; `0` = do not deliver. If unspecified, all-`0`, or all-`1`, full-time delivery is used.

Bidding strategy for in-app events. Must be exactly one of: `DEFAULT` (no deep event bid), `MIN` (cap both install and target-event cost), `PACING` (keep install cost on target, maximize target events), `AEO` (App Event Optimization), `VO_MIN_ROAS` (value optimization with a ROAS goal; requires `roas_bid`), `VO_HIGHEST_VALUE` (value optimization without cost cap or ROAS goal). `VO_MIN_ROAS` and `VO_HIGHEST_VALUE` are valid only when `optimization_goal=VALUE`. Required when CBO is enabled (`budget_optimize_on=true`) and `optimization_goal=VALUE`, and whenever `secondary_optimization_event` is specified. For full details, see the TikTok Marketing API Deep Event Bidding Strategy enumeration.

Required when `deep_funnel_optimization_status=ON`. Event source type. `PIXEL` = Pixel. `OFFLINE` = Offline Event Set. `CRM` = CRM Event Set.

Required when `deep_funnel_optimization_status=ON`. Event Source ID. When `deep_funnel_event_source=PIXEL`, pass a Pixel ID. When `deep_funnel_event_source=OFFLINE`, pass an Offline Event Set ID. When `deep_funnel_event_source=CRM`, pass a CRM Event Set ID.

Deep funnel optimization event. Must be one of the standard event names for ad creation: `ON_WEB_DETAIL`, `ON_WEB_SEARCH`, `ON_WEB_ADD_TO_WISHLIST`, `ON_WEB_CART`, `INITIATE_ORDER`, `ADD_BILLING`, `SHOPPING`, `CONSULT`, `DOWNLOAD_START`, `FORM`, `ON_WEB_REGISTER`, `ON_WEB_SUBSCRIBE`, `LANDING_PAGE_VIEW`, `ENGAGED_SESSION`. Do not use the event-data names such as `Purchase` or `ViewContent`. For `deep_funnel_event_source=PIXEL`, the event must be set up on that pixel; check with `pixel_list_get`. Required when `deep_funnel_optimization_status=ON`.

Valid only when `promotion_type=LEAD_GENERATION`. Status of deep funnel optimization, which optimizes upper-funnel events alongside a deeper-funnel secondary event to improve campaign effectiveness. Default: `OFF`. Deep funnel optimization with CRM events is allowlist-only; with Pixel or Offline events it is generally available.

IDs of device models to target. Only active devices (`is_active=true` in the response of `/tool/device_model/`) can be used. `device_model_ids` and `device_price_ranges` cannot be set at the same time.

Targeting device price range. 10000 means 1000+. Numbers must be multiples of 50. The upper limit you set is increased by 50 to form the actual upper limit (for example, [0, 250] actually means [0, 300] in TikTok Ads Manager).

Engaged view-through attribution window (after at least 6 seconds of video). `ONE_DAY` = 1-day engaged view. `SEVEN_DAYS` = 7-day engaged view. Allowed values vary by advertising objective. If passed, must be accompanied by `click_attribution_window` and `view_attribution_window`. If you omit all four attribution fields, default settings (if any) are used; check via `/adgroup/get/`. Once set, this field cannot be updated.

List of custom audience IDs to exclude.

When `shopping_ads_retargeting_type=LAB3`, you must pass either `included_custom_actions` or `excluded_custom_actions`. Custom actions to use as Exclude conditions for the retargeted audience.

Valid only for Pangle placement. Do not specify alongside `included_pangle_audience_package_ids`. IDs of Pangle audiences to exclude; the package's `bind_type` must be `EXCLUDE`.

Together with `frequency_schedule`, controls how often people see your ad (only available for `REACH` ads). Both conditions must hold: `1 <= frequency <= 1000` and `1 <= frequency_schedule <= 30`. For example, `frequency=2` and `frequency_schedule=3` means "show ads no more than twice every 3 days".

Together with `frequency`, controls how often people see your ad (only available for `REACH` ads). See `frequency` for the valid combinations.

Gender to target.

Household income to target. `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. Supported only for Auction ad objectives, on TikTok placement, in the US.

Required when `identity_type=BC_AUTH_TT`. Business Center ID associated with the TikTok Account User identity.

Required only when (`shopping_ads_type=VIDEO` and `product_source=SHOWCASE`) or `shopping_ads_type=LIVE`. Identity ID.

Required only when (`shopping_ads_type=VIDEO` and `product_source=SHOWCASE`) or `shopping_ads_type=LIVE`. Identity type. `AUTH_CODE` = Authorized Post User. `TT_USER` = TikTok Business Account User. `BC_AUTH_TT` = TikTok account that a Business Center is authorized to access; when used, you must also pass `identity_authorized_bc_id`.

When `shopping_ads_retargeting_type=LAB3`, you must pass either `included_custom_actions` or `excluded_custom_actions`. Custom actions to use as Include conditions for the retargeted audience.

Valid only for Pangle placement. Do not specify alongside `excluded_pangle_audience_package_ids`. IDs of Pangle audiences to include; the package's `bind_type` must be `INCLUDE`.

IDs of general interest categories to target.

IDs of additional interest categories to target.

Required and must be `IOS14_PLUS` when the campaign-level `campaign_type=IOS14_CAMPAIGN`. iOS devices to target. `UNSET` = devices with iOS 14.4 or earlier (default for most scenarios). `IOS14_MINUS` = devices earlier than iOS 14.0 (not affected by the iOS 14 privacy update). `IOS14_PLUS` = devices with iOS 14.5 or later, used only for Dedicated Campaigns; each iOS 14 campaign can have up to 2 active ad groups. `ALL` = devices with iOS 14.5 or later, used only for iOS App Retargeting ads and iOS retargeting Video Shopping Ads with `product_source=CATALOG` and optimization location App. To target iOS 14.5+ in App Retargeting ads, set this to `ALL` and set `min_ios_version` to `14.5` or later. For iOS App Retargeting ads (`app_promotion_type=APP_RETARGETING` and `promotion_type=APP_IOS`) and for iOS retargeting Video Shopping Ads (`shopping_ads_type=VIDEO`, `product_source=CATALOG`, `promotion_type=APP_IOS`, and `shopping_ads_retargeting_type` is not `OFF`), `ALL` is used regardless of the value you pass. Once set to `IOS14_PLUS`, this field cannot be updated, and the following must hold: at the ad group level, `app_id` is an iOS App ID (the app's `platform=IOS`), `operating_systems=["IOS"]`, `min_ios_version` is passed and consistent with `ios14_targeting`, `optimization_goal` is `CLICK`, `INSTALL`, `IN_APP_EVENT`, or `VALUE`, and `min_android_version`, `shopping_ads_retargeting_type`, and `shopping_ads_retargeting_actions_days` are not specified; at the ad level, `deeplink_type` is not `DEFERRED_DEEPLINK`.

Whether the promoted content is HFSS (High Fat, Salt, Sugar). Set to `true` if your ad promotes or prominently features an HFSS product or brand. In regulated regions, HFSS ads must only target users 18 or older. You can set `true` only when targeted locations include locations in the UK, Australia, New Zealand, or the European Union. Default: `false`.

Whether the promoted content complies with LHF (Less Healthy Foods) regulations. Setting `true` certifies compliance with the 2024 UK LHF Regulations and other applicable laws for food/drink products advertised in the UK. Default: `false`. Starting January 1st, 2026, when targeting UK locations and `is_hfss=true`, this field is required and must be `true`.

Valid only when a country- or region-level location is specified via `location_ids`. IDs of Internet service providers to target. When `isp_ids` is passed, you cannot set the placement to Global App Bundle only (`placements=PLACEMENT_GLOBAL_APP_BUNDLE`).

Codes of the languages to target. To target all languages, omit the field or pass an empty array.

You must set `location_ids` or `zipcode_ids` or both. Location IDs to target. Maximum 3,000 (the combined total of `location_ids` and `zipcode_ids` cannot exceed 3,000 per ad group). Overlapping locations are not supported (for example, you cannot target the U.S. and California at the same time). If you target US locations on creation, you can later switch to other US locations but you cannot remove all US locations to target only non-US countries.

Required when all of the following are true: `promotion_type=LEAD_GEN_CLICK_TO_SOCIAL_MEDIA_APP_MESSAGE`, `optimization_goal=CONVERSATION`, and the instant messaging account in your ad group settings does not match an existing message event set. ID of the message event set used in the Instant Messaging Ad Group. If the chosen IM account does match an existing event set (Messenger via `messaging_app_account_id`, or WhatsApp populated from `phone_region_code`/`phone_region_calling_code`/`phone_number`), this field is ignored and auto-populated. Use `/ctm/message_event_set/get/` and check `matched_event_set` to determine if a unique set already exists; if not, the same call's `message_event_set_list` provides the available sets for ad creation. Once set, this field cannot be updated.

Required when `messaging_app_type` is `MESSENGER` or `LINE`. Ignored when `messaging_app_type` is `WHATSAPP`, `ZALO`, or `IM_URL`. ID of the instant messaging app account. When `messaging_app_type=MESSENGER`, pass the Facebook Page ID. When `messaging_app_type=LINE`, pass the LINE Business ID. When `messaging_app_type=WHATSAPP`, this field is ignored and is set automatically from `phone_region_code`, `phone_region_calling_code`, and `phone_number`. Once set, this field cannot be updated.

Valid only when `promotion_type=LEAD_GEN_CLICK_TO_SOCIAL_MEDIA_APP_MESSAGE`. Required when `optimization_goal=CONVERSATION`; when `optimization_goal=CLICK`, the default is `IM_URL`. Type of instant messaging app or customized URL. `MESSENGER` requires you to also pass a Facebook Page ID via `messaging_app_account_id`. `WHATSAPP` requires you to also pass `phone_region_code`, `phone_region_calling_code`, and `phone_number` (used to populate the WhatsApp number). `ZALO` requires you to also pass `phone_region_code`, `phone_region_calling_code`, and `phone_number` (used to populate the Zalo number). `LINE` requires you to also pass a LINE Business ID via `messaging_app_account_id`. `IM_URL` is for an Instant Messaging URL. When `optimization_goal=CONVERSATION`, you cannot set this field to `ZALO`, `LINE`, or `IM_URL`. Once set, this field cannot be updated.

Minimum device Android version, passed as a string. Must be `NONE` (no limit) or one of: `4.0`, `4.1`, `4.2`, `4.3`, `4.4`, `5.0`, `5.1`, `6.0`, `7.0`, `7.1`, `8.0`, `8.1`, `9.0`, `10.0`, `10.1`, `10.2`, `10.3`, `10.5`, `10.6`, `11.0`, `12.0`, `13.0`. For the latest list, call `tool_os_version_get` with `os_type=ANDROID`.

Minimum iOS version, passed as a string. Must be `NONE` (no limit) or one of: `8.0`–`8.4`, `9.0`–`9.3`, `10.1`–`10.3`, `11.0`–`11.4`, `12.0`–`12.4`, `13.0`–`13.7`, `14.0`–`14.8`, `15.0`–`15.6`, `16.0`–`16.4` (every minor version in each range; there is no `10.0`). For the latest list, call `tool_os_version_get` with `os_type=IOS`. When `ios14_targeting=IOS14_PLUS` or targeting iOS 14.5+ retargeting, use `14.5` or later. Required when `ios14_targeting` is specified.

Device connection types to target. Each item must be one of: `WIFI`, `2G`, `3G`, `4G`, `5G`. Omit the field to target all connection types.

Valid only when `placements` is `PLACEMENT_PANGLE` and `secondary_optimization_event=NEXT_DAY_OPEN`. Day 2 retention ratio. Formula: `next_day_retention = conversion_bid_price / deep_cpa_bid`. Value range: (0, 1]. To use this field, pass `conversion_bid_price`, `deep_cpa_bid`, and `next_day_retention` together such that they satisfy the formula; otherwise unexpected errors may occur.

Device operating systems to target. Only one value is allowed. Required when `objective_type=APP_PROMOTION`, or when `objective_type=TRAFFIC` and `promotion_type` is `APP_IOS` or `APP_ANDROID`.

Status of the ad group when created. `ENABLE` = enabled at creation. `DISABLE` = disabled at creation. Default: `ENABLE`. To update status after creation, use `/adgroup/status/update/`.

Conversion event name. For a purchase, use `SHOPPING`; `PURCHASE`, `COMPLETE_PAYMENT`, and `CompletePayment` are not valid event names. Required when `pixel_id` is specified, or when `pixel_id` is not specified and `optimization_goal` is `IN_APP_EVENT` or `VALUE`. For new ad groups created under one CBO campaign, this field should match the first ad group. When `optimization_goal=PAGE_VISIT`, `optimization_event` is automatically set to `PAGE_VISIT`.

The measurable result to drive with your ads. Use `CONVERT` for website conversions (requires `pixel_id` and `optimization_event`), `MT_LIVE_ROOM` / `PRODUCT_CLICK_IN_LIVE` only with `promotion_type=LIVE_SHOPPING`, and `PAGE_VISIT` only when `objective_type=ENGAGEMENT`. `PROFILE_VIEWS` is being deprecated; use `PAGE_VISIT` (ENGAGEMENT objective only). Set `billing_event` to match (see `billing_event`). For CBO support, see Campaign Budget Optimization-Supported optimization goals. To use "Install with in-app event" on Pangle and/or Global App Bundle placements, set `optimization_goal=INSTALL`, specify a valid `secondary_optimization_event`, and only include `PLACEMENT_PANGLE` or `PLACEMENT_GLOBAL_APP_BUNDLE` (or both) in `placements`. When `promotion_type` is `LEAD_GEN_CLICK_TO_TT_DIRECT_MESSAGE`, `LEAD_GEN_CLICK_TO_SOCIAL_MEDIA_APP_MESSAGE`, or `LEAD_GEN_CLICK_TO_CALL`, the default is `CLICK`. Starting November 30th, 2024, you can no longer create or copy ad groups using `optimization_goal=INSTALL` with a valid `secondary_optimization_event` on TikTok placement or Automatic Placement when `objective_type=APP_PROMOTION` (existing such ad groups are unaffected; Pangle-only and Global App Bundle-only configurations are not impacted). `VIDEO_VIEW` is removed in v1.3; for `VIDEO_VIEWS` campaigns prefer `ENGAGED_VIEW` or `ENGAGED_VIEW_FIFTEEN`. For new ad groups under one CBO campaign, this field should match the first ad group.

Pacing mode. `PACING_MODE_SMOOTH` = budget allocated evenly within the scheduled time. `PACING_MODE_FAST` = consume budget and produce results as soon as possible. When CBO is on at the campaign level, the setting is ignored and `PACING_MODE_SMOOTH` is used. Otherwise this field is required.

Required when `messaging_app_type` is `WHATSAPP` or `ZALO`. WhatsApp or Zalo phone number. For WhatsApp, use the same number connected to the Messagement Management Tool (MMT). Once set, this field cannot be updated.

Required when `messaging_app_type` is `WHATSAPP` or `ZALO`. Region calling code for the WhatsApp or Zalo phone number, for example `+1`. To obtain matching region codes and calling codes, use `/tool/phone_region_code/`. Once set, this field cannot be updated.

Required when `messaging_app_type` is `WHATSAPP` or `ZALO`. Region code for the WhatsApp or Zalo phone number, for example `US`. To obtain matching region codes and calling codes, use `/tool/phone_region_code/`. Once set, this field cannot be updated.

Required when `optimization_goal` is `CONVERT` or `VALUE`. Not supported when `optimization_goal` is neither `CONVERT` nor `VALUE`. Pixel ID.

Placement strategy for where ads are shown. `PLACEMENT_TYPE_AUTOMATIC` = TikTok's ad system selects the best combination of placements. `PLACEMENT_TYPE_NORMAL` = manual placement selection. Default: `PLACEMENT_TYPE_NORMAL`. Cannot be updated after creation. When set to `PLACEMENT_TYPE_AUTOMATIC`, the actual supported placements are reflected in the response `placements` (for example, if only TikTok is supported, the response returns `PLACEMENT_TIKTOK`).

Required when `placement_type=PLACEMENT_TYPE_NORMAL`. Ignored and overwritten by the system when `placement_type=PLACEMENT_TYPE_AUTOMATIC`. Apps where you want to deliver your ads. Cannot be updated after creation. Currently supports `PLACEMENT_TIKTOK`, `PLACEMENT_PANGLE`, and `PLACEMENT_GLOBAL_APP_BUNDLE`; do not select `PLACEMENT_TOPBUZZ` or `PLACEMENT_HELO` (deprecated). Locations available for `PLACEMENT_GLOBAL_APP_BUNDLE` are: Brazil, Indonesia, Vietnam, the Philippines, Thailand, Malaysia, Mexico, Saudi Arabia, and Japan; it does not support `optimization_goal=TRAFFIC_LANDING_PAGE_VIEW`. Using `PLACEMENT_GLOBAL_APP_BUNDLE` in Auction Reach is allowlist-only. If `objective_type=REACH` at the campaign level and `placements` includes `PLACEMENT_GLOBAL_APP_BUNDLE`, you cannot also specify `contextual_tag_ids`. If `objective_type=REACH` and `placements=["PLACEMENT_GLOBAL_APP_BUNDLE"]`, you cannot set `brand_safety_type=THIRD_PARTY`. For Product Sales campaigns (`objective_type=PRODUCT_SALES`), only `PLACEMENT_TIKTOK` is supported.

Required for Video Shopping Ads and Product Shopping Ads. Product source. For Video Shopping Ads, the campaign-level `campaign_product_source` constrains allowed values: if campaign is `CATALOG`, this field must be `CATALOG`; if campaign is `STORE`, this field must be `STORE` or `SHOWCASE`. If `campaign_product_source` is unset and the same campaign already contains both a `CATALOG` ad group and a `STORE`/`SHOWCASE` ad group, you cannot create more ad groups under that campaign — ad groups in the same campaign must use either `CATALOG` only, or some combination of `STORE` and `SHOWCASE`. For Product Shopping Ads, set this field to `STORE`.

Valid when the campaign `objective_type=LEAD_GENERATION`. Promotion type for the Lead Generation objective. `INSTANT_PAGE` = TikTok Instant Form (in-app fast-loading form to collect leads). `EXTERNAL_WEBSITE` = Website Form (your landing page or a TikTok Instant Page that redirects to a website with the form). When `promotion_target_type=EXTERNAL_WEBSITE` and `optimization_goal=CLICK`, do not pass `pixel_id` or `optimization_event`.

Promotion type (optimization location). Must be exactly one of: `WEBSITE`, `WEBSITE_OR_DISPLAY`, `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`, `TIKTOK_SHOP`, `VIDEO_SHOPPING`, `LIVE_SHOPPING`, `PSA_PRODUCT`. Values such as `EXTERNAL_OR_DISPLAY`, `EXTERNAL_WEBSITE`, and `SHOP` are rejected. `LEAD_GEN_CLICK_TO_TT_DIRECT_MESSAGE` is generally available only to advertisers registered in APAC (Australia, Bangladesh, Cambodia, Indonesia, Japan, Malaysia, New Zealand, Pakistan, the Philippines, Singapore, South Korea, Sri Lanka, Taiwan, Thailand, and Vietnam) or LATAM (Argentina, Bolivia, Brazil, Chile, Colombia, Costa Rica, the Dominican Republic, Ecuador, Guatemala, Mexico, Panama, Paraguay, Peru, Puerto Rico, and Uruguay); `LEAD_GEN_CLICK_TO_SOCIAL_MEDIA_APP_MESSAGE` is generally available only to advertisers registered in APAC (Australia, Bangladesh, Cambodia, Indonesia, Japan, Malaysia, New Zealand, Pakistan, the Philippines, Singapore, South Korea, Sri Lanka, Taiwan, Thailand, and Vietnam). Advertisers registered in other regions need allowlist access for these two values. Required when the campaign `objective_type` is not `REACH`, `VIDEO_VIEWS`, or `ENGAGEMENT`; for those three objectives omit this field. For the full list of enum values, see the TikTok Marketing API Promotion Type enumeration.

TikTok Instant Page type for the ad group. `UNSET` = do not use TikTok Instant Page. `TIKTOK_NATIVE_PAGE` = use TikTok Instant Page; in this case `pixel_id` is not supported and you must specify a TikTok Instant Page through `page_id` at the ad level. Required when `app_promotion_type=APP_PREREGISTRATION` at the campaign level.

IDs of purchase-intention categories to target. Do not pass `purchase_intention_keyword_ids` and `interest_keyword_ids` simultaneously, otherwise keyword conflict will occur. Supported only for Auction ads with `objective_type` in {`APP_PROMOTION`, `WEB_CONVERSIONS`, `LEAD_GENERATION`, `TRAFFIC`} or `PRODUCT_SALES` with `product_source=CATALOG`, and `placements` must include TikTok (`PLACEMENT_TIKTOK`) or Pangle (`PLACEMENT_PANGLE`).

Optional request identifier that allows duplicate `adgroup_name` values and provides 10-second idempotency. To create ad groups with the same `adgroup_name`, send different `request_id` values; retries with the same `request_id` within 10 seconds succeed only once. This is different from the response `request_id`, which uniquely identifies an HTTP request. Must be the string form of a 64-bit integer, for example `123456789`.

Required when `deep_bid_type=VO_MIN_ROAS`. ROAS goal for Value Optimization. Value range: in-app advertising scenarios (`objective_type=APP_PROMOTION`, `optimization_goal=VALUE`, and `optimization_event=AD_REVENUE_VALUE`) 0.01-10; Product Shopping Ads with TikTok Shop product source (`shopping_ads_type=PRODUCT_SHOPPING_ADS` and `product_source=STORE`) 0.01-20; other scenarios 0.01-1,000.

Saved Audience ID. Supported only when all of the following are met at the campaign level: `special_industries` is not specified (no Housing/Employment/Credit category) and `objective_type` is not `PRODUCT_SALES`; and at the ad group level: TikTok placement is selected (`placement_type=PLACEMENT_TYPE_AUTOMATIC` or `placement_type=PLACEMENT_TYPE_NORMAL` with `PLACEMENT_TIKTOK` in `placements`); and `auto_targeting_enabled` is not `true`. The advertiser ID associated with the Saved Audience must match the ad group's advertiser ID. When using a Saved Audience, do not concurrently set targeting options (such as `gender`) that are already inside the Saved Audience, or an error will occur. If the Saved Audience's device settings conflict with the ad group's (for example, Saved Audience OS is Android but `ios14_targeting=IOS14_PLUS`, or campaign uses an Android `app_id` while the Saved Audience OS is iOS), an error will occur. If `saved_audience_id` was created with `age_groups` specified, the age restriction rules in New age restrictions for ads on TikTok also apply.

Required when `schedule_type=SCHEDULE_START_END` or `budget_mode=BUDGET_MODE_TOTAL`. Schedule end time (UTC+0), in the format `YYYY-MM-DD HH:MM:SS`. No later than `2038-01-01 00:00:00`.

Required for every `schedule_type`, including `SCHEDULE_FROM_NOW` (which only omits the end time). Schedule start time (UTC+0), in the format `YYYY-MM-DD HH:MM:SS`, for example the current UTC time to start now. Can be up to 12 hours earlier than the current time and no later than `2028-01-01 00:00:00`.

Schedule type. `SCHEDULE_START_END` requires both a start time and an end time. `SCHEDULE_FROM_NOW` requires only a start time, and the end time is automatically set to 10 years later. If `budget_mode=BUDGET_MODE_TOTAL`, `schedule_type` must be `SCHEDULE_START_END`.

Required for Search Ads Campaigns (campaign-level `is_search_campaign=true`). Not supported for non-Search Ads Campaigns. List of search keywords used to match ads with user searches. Maximum 1,000 per ad group.

Whether to include ads in Search Ads (showing ads to users searching for your business on TikTok). If `objective_type` is `APP_PROMOTION`, `WEB_CONVERSIONS`, `TRAFFIC`, or `LEAD_GENERATION`, and `placement_type=PLACEMENT_TYPE_AUTOMATIC` or (`placement_type=PLACEMENT_TYPE_NORMAL` and `placements` includes `PLACEMENT_TIKTOK`), this field is automatically set to `true` (Automatic Search Placement); you may omit it, or pass `true`/`false`. If `objective_type` is `WEB_CONVERSIONS`, `TRAFFIC`, or `LEAD_GENERATION` with the campaign's `is_search_campaign=true`, this field is automatically set to `false` and cannot be set to `true` (Search Ads Campaign is incompatible with Automatic Search Placement). Otherwise this field is automatically set to `false` and cannot be set to `true`.

Secondary goal. Must be exactly one of: - with `optimization_goal=INSTALL`: `ACTIVE_PAY`, `ACTIVE_REGISTER`, `IN_APP_CART`, `NEXT_DAY_OPEN`, `SUBSCRIBE`, `UPDATE_LEVEL`, `DAY7_RETENTION` (Pangle placement only); - with `optimization_goal=VALUE`: `PURCHASE_ROI`; - also listed: `ADD_PAYMENT_INFO`, `IN_APP_ORDER`, `PREFERRED_LEAD`. When this field is specified, you must also pass `deep_bid_type`. Since November 30th, 2024, `optimization_goal=INSTALL` with a secondary event cannot be created on TikTok or Automatic Placement for `objective_type=APP_PROMOTION`; use Pangle-only or Global App Bundle-only placements.

Whether to disable sharing ads to third-party platforms. Default: `false`. `true` is valid only when the campaign `objective_type` is `APP_PROMOTION`, `WEB_CONVERSIONS`, `REACH`, `TRAFFIC`, `VIDEO_VIEWS`, `ENGAGEMENT`, or `LEAD_GENERATION`, and at the ad group level either `placement_type=PLACEMENT_TYPE_AUTOMATIC` or (`placement_type=PLACEMENT_TYPE_NORMAL` and `placements=PLACEMENT_TIKTOK`).

Required when `shopping_ads_retargeting_type` is `LAB1` or `LAB2`. Time range (in days) for the targeted action. Allowed values: 1, 2, 3, 7, 14, 30, 60, 90, 180.

Valid only when `shopping_ads_type=VIDEO`, `product_source=CATALOG`, `shopping_ads_retargeting_type` is set to `LAB1`, `LAB2`, or `LAB3`, and `audience_ids` is passed. Logical relation between the Video Shopping Ads (VSA) retargeting audience (from `shopping_ads_retargeting_type`) and the custom audience (from `audience_ids`). `OR` = union of the two audiences. `AND` = intersection of the two audiences. If unset, the targeted audience defaults to the intersection. Once set, this field cannot be manually updated to a null value.

Required when `shopping_ads_type=VIDEO` and `product_source=CATALOG`. Retargeting type for shopping ads. `LAB1` = users who viewed products or added to cart but did not purchase. `LAB2` = users who added to cart but did not purchase. `LAB3` = users from a custom combination. `OFF` = no retargeting.

Required and valid only when the campaign `objective_type` is `PRODUCT_SALES`. Shopping ads type. `VIDEO` = Video Shopping Ads. `LIVE` = Live Shopping Ads. `PRODUCT_SHOPPING_ADS` = Product Shopping Ads.

Whether to enable Smart audience. Supported values: `true`, `false`.

Whether to enable Smart interests & behaviors. Supported values: `true`, `false`.

Spending power to target. `ALL` = all users. `HIGH` = high-spending users (typically spend more on TikTok ads than average). Not supported when the campaign `objective_type` is `PRODUCT_SALES` or `RF_REACH`. Requires Automatic Placement, or Select Placement with TikTok included (`placement_type=PLACEMENT_TYPE_AUTOMATIC`, or `placements` includes `PLACEMENT_TIKTOK`); does not take effect on Pangle. When `auto_targeting_enabled=true`, this is automatically set to `ALL`.

Conversion bid statistic type. `EVERYTIME` (Each Purchase) or `NONE` (Unique Purchase). Suitable values for your app event come from `/app/optimization_event/`.

Required when `store_id` is passed. Business Center ID authorized to access the specified `store_id`.

Required when (`shopping_ads_type=VIDEO` and `product_source=STORE`) or (`shopping_ads_type=PRODUCT_SHOPPING_ADS` and `product_source=STORE`); optional when `shopping_ads_type=LIVE`. TikTok Shop ID.

array

Time window of the VBO IAA (Value-Based Optimization for in-app advertising) or VBO IAP (in-app purchase) bidding strategy. `SEVEN_DAYS` = first seven days (day 7). `ZERO_DAY` = current day (day 0). Default: `SEVEN_DAYS`. With Minimum ROAS (Target ROAS), this is the window of the target ROAS value (Day 7 vs Day 0); the system aims to keep average ROAS at or above the target. With Highest Value, this is the Highest Value window type (Day 7 vs Day 0); the system aims to fully spend the budget and maximize result value within the window. VBO IAP and VBO IAA in different scenarios are allowlist-only; in particular, Day 0 or Day 7 bidding for VBO IAP and for VBO IAA in Advanced Dedicated Campaign or Android campaign scenarios are allowlist-only. Once set, this field cannot be updated.

Valid only when at the campaign level `objective_type` is `REACH`, `VIDEO_VIEWS`, or `ENGAGEMENT`, and at the ad group level `placements=["PLACEMENT_TIKTOK"]` and `brand_safety_type` is `STANDARD_INVENTORY` or `LIMITED_INVENTORY`. Vertical sensitivity category ID.

Whether to prevent users from downloading video ads on TikTok. Once set, this field cannot be updated.

View-through attribution window. `OFF`, `ONE_DAY` = 1-day view, `SEVEN_DAYS` = 7-day view. Allowed values vary by advertising objective. To manually configure attribution windows, pass at least `click_attribution_window` and `view_attribution_window` simultaneously. If you omit all four attribution fields, default settings (if any) are used; check via `/adgroup/get/`. Once set, this field cannot be updated.

You must set `location_ids` or `zipcode_ids` or both. Zip code or postal code IDs to target. Maximum 3,000 (combined with `location_ids` not exceeding 3,000 per ad group). Zip code targeting is supported only for the US; postal code targeting is supported for Canada, Brazil, Indonesia, Thailand, and Vietnam. Targeting postal code areas in Brazil, Indonesia, Thailand, and Vietnam is allowlist-only. Cannot be used in campaigns that have enabled `special_industries`. Cannot be used in campaigns with `objective_type=RF_REACH`. Only TikTok placement is supported (`placements` must include `PLACEMENT_TIKTOK`). Overlapping locations are not supported. If you target US locations on creation, you can later switch to other US locations but you cannot remove all US locations to target only non-US countries.