| actions |
list[OpenApiv13adgroupcreateActions] |
A list of action category objects. |
[optional] |
| adgroup_id |
str |
Ad group ID |
[required] |
| adgroup_name |
str |
Ad group name. Character limit is 512 and cannot contain emoji. |
[optional] |
| advertiser_id |
str |
Advertiser ID |
[required] |
| age_groups |
list[str] |
Age groups you want to target. For enum values, see Enumeration - Targeting Age Group. |
[optional] |
| app_download_url |
str |
App download link |
[optional] |
| app_id |
str |
The Application id of the promoted app. You can get `app_id` by using the /app/list/ endpoint. Required in the following use cases- When `objective_type` is `APP_INSTALL`.When `objective_type` is `APP_PROMOTION` and `app_promotion_type` is `APP_RETARGETING` (App retargeting).When `objective_type` is `APP_PROMOTION` , `app_promotion_type` is `APP_INSTALL`(App install), and it is not an iOS14 Dedicated Campaign.When `objective_type` is `CONVERSIONS` and `promotion_type` is `APP_ANDROID` or `APP_IOS` |
[optional] |
| audience_ids |
list[str] |
List of audience IDs. You can get audience IDs by using the /dmp/custom_audience/list/ endpoint. |
[optional] |
| audience_rule |
OpenApiv13adgroupupdateAudienceRule |
|
[optional] |
| audience_type |
str |
App retargeting audience type, required when objective_type is `CONVERSIONS` and externla_type is app-related. Currently, the only supported enumeration is `NEW_CUSTOM_AUDIENCE`; for this type, you must pass audience IDs to the `audience_ids` field when creating or updating the ad group. The audiences to be used must be either Custom File Audience or App Activity Audience. Optionally, you can specify the `excluded_audience_ids` field. If both `audience_ids` and `excluded_audience_ids` are specified, they cannot contain the same IDs |
[optional] |
| auto_targeting_enabled |
bool |
Whether to enable automated targeting. |
[optional] |
| bid_price |
float |
The maximum cost per result you are willing to bid (for Bid Cap bidding strategy), or an average cost per result that you want to achieve (for Cost Cap bidding strategy). When Campaign Budget Optimization (`budget_optimize_on`) is on, we suggest that you set the same bid value for all ad groups in the campaign. Note- To specify `bid_price`, you need to set `bid_type` as `BID_TYPE_CUSTOM`.`bid_price` needs to be lower than budget set at the campaign level and ad group level. See Bidding-Bidding limits to learn more about the bid verification mechanism. |
[optional] |
| bid_type |
str |
Bidding strategy that determines how the system manages your cost per result, spends your budget, and how it delivers ads. Required when Campaign Budget Optimization (CBO) is enabled (`budget_optimize_on` = `TRUE`). For enum values, see Enumeration - Bidding Strategy. |
[optional] |
| billing_event |
str |
Events that you want to pay for. For enum values, see Enumeration - Billing Event. |
|
| blocked_pangle_app_ids |
list[str] |
Pangle app block list ID. You can get an ID via the `app_package_id` field returned by Get Pangle block list. It only takes effect when Pangle placement is selected. |
[optional] |
| brand_safety_type |
str |
Valid only when `placements` is set as `PLACEMENT_TIKTOK`. Default value- `NO_BRAND_SAFETY`. Enum values- `NO_BRAND_SAFETY`- To not use any brand safety solution. Full inventory, which means your ads may appear next to some content featuring mature themes. `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 in a value to the `brand_safety_partner` field. To get the countries and regions that your ads can be deployed to based on your brand safety settings, use the [/tool/region/] function. Note - Pre-bid first-party Brand Safety solutions for `APP_PROMOTION`, `APP_INSTALL`, `WEB_CONVERSIONS`, `CONVERSIONS`, `TRAFFIC`, `LEAD_GENERATION` objectives in Auction ads, and pre-bid third-party brand safety solutions are currently allowlist-only features. If you would like to access them, please contact your TikTok representative. Pre-bid third-party Brand Safety solutions are not supported for TikTok Pulse campaigns (`rf_campaign_type` =`PULSE`). See Brand safety to learn about the supported advertising objectives, supported markets, and the general introduction of pre-bid Brand Safety filtering. Once set, this field cannot be modified. |
[optional] |
| budget |
float |
Ad group budget. The setting will be ignored when Campaign Budget Optimization (`budget_optimize_on` = `TRUE`) is enabled. For how to configure budget settings, see Budget. To directly see the daily budget value range for a currency, see Currency-Daily budget value range. |
[optional] |
| carrier_ids |
list[str] |
Carriers that you want to target. A carrier is valid only when the `in_use` field for the carrier is `true`. The carriers must be consistent with the location(s) that you want to target. Use /tool/carrier/ endpoint to get the enum values. |
[optional] |
| catalog_authorized_bc_id |
str |
For catalogs in Business Center, you must specify the ID of the Business Center that a catalog belongs to. |
[optional] |
| comment_disabled |
str |
Whether to allow comments on your ads on TikTok. |
[optional] |
| contextual_tag_ids |
list[str] |
Contextual tag IDs. You can use /tool/contextual_tag/get/ to get available contextual tags. See Contextual targeting to learn more about how to use contextual targeting.<p><span style="color-darkred"><b>Note</b></span>- This is an allowlist-only feature. If you would like to access it, please contact your TikTok representative.Only supports `REACH` and `VIDEO_VIEWS` as objectives (`objective_type`) at the campaign level. Not supported when `brand_safety_type` is set to `THIRD_PARTY`. |
[optional] |
| conversion_bid_price |
float |
Where you can set a target cost per conversion for oCPM(Optimized Cost per Mille); Required when `billing_event` = `OCPM` and `bid_type` = `BID_TYPE_CUSTOM`.`conversion_bid_price` needs to be lower than budget set at the campaign level and ad group level. See Bidding-Bidding limits to learn more about the bid verification mechanism. |
[optional] |
| conversion_id |
int |
Conversion Id |
[optional] |
| creative_material_mode |
str |
The strategy that your creatives will be delivered.<br data-tomark-pass>`Note`- When you choose automated ad, your creative materials will automatically be combined for delivery. Tiktok Ads' smart optimization algorithm is applied and will be used to achieve the best ad performance during delivery. <br data-tomark-pass>Optional values include- `CUSTOM` (custom), `DYNAMIC` (automated). Default value is `CUSTOM` (custom). See help center for more. |
[optional] |
| dayparting |
str |
Ad delivery arrangement, in the format of a string that consists of 48 x 7 characters. Each character is mapped to a 30-minute timeframe from Monday to Sunday. Each character can be set to either 0 or 1. 1 represents delivery in the 30-minute timeframe, and 0 stands for non-delivery in the 30-minute timeframe. The first character is mapped to 0-01-0-30 of Monday; The second character is mapped to 0-31-1-00 of Monday, and the last character represents 23-31-0-00 Sunday. |
[optional] |
| deep_bid_type |
str |
Bidding strategy for in-app events. Required when Campaign Budget Optimization (CBO) is enabled (`budget_optimize_on` = `TRUE`) and `optimization_goal` is `VALUE`. Enum values- `VO_MIN_ROAS` (allowlisted), `VO_HIGHEST_VALUE` (allowlisted). For details, see Enumeration - Deep-level Bidding Strategy. |
[optional] |
| deep_cpa_bid |
float |
Deep CPA bid |
[optional] |
| device_model_ids |
list[str] |
IDs of the device models that you want to target. Use /tool/device_model/ to get the complete list of device model IDs and their statuses, and only active devices (`is_active` = `True` in the response of /tool/device_model/) can be used to create ads. |
[optional] |
| device_price_ranges |
list[int] |
Targeting device price range. 10000 means 1000+. The numbers must be in multiples of 50. The upper limit you set will be added by 50 and the resulting new number will be used as the actual upper limit for device targeting. The actual upper limit is shown in the ad group settings in TikTok Ads Manager. If you set and get the price range of [0, 250], it actually means [0, 300]. |
[optional] |
| excluded_audience_ids |
list[str] |
List of audience ID to be excluded. You can get audience IDs by using the /dmp/custom_audience/list/ endpoint. |
[optional] |
| excluded_custom_actions |
OpenApiv13adgroupcreateExcludedCustomActions |
|
[optional] |
| excluded_pangle_audience_package_ids |
list[str] |
IDs of the Pangle audiences that you want to exclude. Valid only for Pangle placement. You can get audience IDs (`package_id`) by using the /pangle_audience_package/get/ endpoint. You need to set `bind_type` to `EXCLUDE`. Do not specify this field and `included_pangle_audience_package_ids` at the same time. |
[optional] |
| frequency |
int |
Frequency, together with `frequency_schedule`, controls how often people see your ad (only available for `REACH` ads). The below conditions should be both met-1 <= `frequency` <= `frequency_schedule` * 3 1 <= `frequency_schedule` <=7 For example, `frequency` = 2 & `frequency_schedule` = 3 means "show ads no more than twice every 3 day". |
[optional] |
| frequency_schedule |
int |
Frequency_schedule`, together with `frequency`, controls how often people see your ad (only available for `REACH` ads). See `frequency` fields for more. |
[optional] |
| gender |
str |
Gender that you want to target. Enum values- `GENDER_FEMALE`,`GENDER_MALE`,`GENDER_UNLIMITED` |
[optional] |
| household_income |
list[str] |
Household income that you want to target. Enum values- `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). Note- It only supports the ad objectives for Auction ads. See Advertising objectives for details. It is only applicable the TikTok Placement in US. If you have specified `special_industries` at the campaign level, then you cannot use the field here. `household_income` is an allowlist-only feature that is only available in US. If you would like to access it, please contact your TikTok representative. |
[optional] |
| identity_authorized_bc_id |
str |
ID of the Business Center that a TikTok Account User in Business Center identity is associated with. Required when `identity_type` is `BC_AUTH_TT`. |
[optional] |
| identity_id |
str |
Identity ID. Required and only valid when `objective_type` is `SHOP_PURCHASES` or `PRODUCT_SALES`. |
[optional] |
| identity_type |
str |
Identity type. Enum values- `AUTH_CODE` (Authorized Post User), `TT_USER` (TikTok Business Account User), `BC_AUTH_TT`(The TikTok account that a Business Center is authorized to access). Required and only valid when `objective_type` is `SHOP_PURCHASES` or `PRODUCT_SALES`. See Identities for details. |
[optional] |
| included_custom_actions |
OpenApiv13adgroupcreateIncludedCustomActions |
|
[optional] |
| included_pangle_audience_package_ids |
list[str] |
IDs of the Pangle audiences that you want to include. Valid only for Pangle placement. You can get audience IDs (`package_id`) by using the /pangle_audience_package/get/ endpoint. You need to set `bind_type` to `INCLUDE`. Do not specify this field and `excluded_pangle_audience_package_ids` at the sa |
[optional] |
| interest_category_ids |
list[str] |
Interest classification. If the interest is specified, users that do not meet interest target will be excluded during delivery. Do not specify if you wish to target everyone. Use /tool/target_recommend_tags/ to get a list of recommended interest categories based on your targeting regions and your industries. Use /tool/interest_category/ endpoint to get the complete list of interest categories. |
[optional] |
| interest_keyword_ids |
list[str] |
IDs of interest keywords that you want to use to target audience. You can get recommended interest keywords IDs by using the /tool/interest_keyword/recommend/ endpoint. |
[optional] |
| interest_keywords |
list[str] |
Interest Keywords |
[optional] |
| ios14_targeting |
str |
The iOS devices that you want to target. When `campaign_type` of the campaign is set as `IOS14_CAMPAIGN`, `ios14_targeting` is required and must be specified as `IOS14_PLUS`. Enum values-`UNSET`- Devices with iOS 14.4 or earlier versions. The default value for ad groups that were created before the introduction of this field.`IOS14_MINUS`- Devices with versions earlier than iOS 14.0, which are not affected by the iOS 14 privacy update. This is the default value for ad groups that are created after the introduction of this field.`IOS14_PLUS`- Devices with iOS 14.5 and above. The iOS 14 privacy update has been enforced in this group of devices. Specify this value if you want to create an iOS 14 campaign. Each iOS 14 campaign can have up to 2 active ad groups. <br data-tomark-pass> If `IOS14_PLUS` is specified, this field cannot be updated. If `IOS14_PLUS` is specified for this field, the system will verify if related fields meet the requirements for an iOS 14 campaign. The following fields will be checked. `app_id`- It must not be an ID of an Android app.`operating_systems`- It must not be `ANDROID` or `PC`.`min_ios_version`- You must specify a value for this field, and the the value must not contradict with the selection for `ios14_targeting`.`min_android_version`- Must not be specified.`optimization_goal`- Can only be set to `IN_APP_EVENT`, `INSTALL`, or `CLICK`.`shopping_ads_retargeting_type`- Must not be specified.`shopping_ads_retargeting_actions_days`- Must not be specified. `conversion_window`- Must not be specified.On the Ad level, `deeplink_type` must not be set to `DEFERRED_DEEPLINK`. |
[optional] |
| is_hfss |
bool |
Whether the promoted content is HFSS foods (foods that are high in fat, salt, or sugar). |
[optional] |
| languages |
list[str] |
Codes of the languages that you want to target. For the list of languages codes supported, see Enumeration - Language Code.You can get language codes via /tool/language/, and if you don't want to limit the languages you target, assign an empty value to this field or do not pass in this field. |
[optional] |
| location_ids |
list[str] |
IDs of the locations that you want to target. To get the available locations and corresponding IDs based on your placement and objective, use the /tool/region/ endpoint. To get the list of location IDs, see Location IDs. |
[optional] |
| min_android_version |
str |
Minimum device Android version. For enum values, see Enumeration - Minimum Android Version. |
[optional] |
| min_ios_version |
str |
Minimum iOS version. For enum values, see Enumeration - Minimum iOS Version. This field is required when `ios14_targeting` is specified. |
[optional] |
| network_types |
list[str] |
Device connection types that you want to target. Default- `unlimited`. For enum values, see Enumeration - Connection Type. |
[optional] |
| next_day_retention |
float |
Day 2 retention ratio. Formula- `next_day_retention` = `conversion_bid_price`/`deep_cpa_bid`. Value range is (0,1]. Only valid when `placements` is `PLACEMENT_PANGLE` and `secondary_optimization_event` is `NEXT_DAY_OPEN`. If you want to use this field, please pass in `conversion_bid_price`, `deep_cpa_bid`, and `next_day_retention` at the same time, and make sure the value of them meets the calculation formula. Otherwise there might be unexpected errors. |
[optional] |
| operating_systems |
list[str] |
Device operating systems that you want to target. Only one value is allowed. Enum values- `ANDROID`, `IOS`. This field is required in two scenarios- `objective_type` = `APP_INSTALL``objective`=`TRAFFIC` and `optimization_event` = `APP_IOS` or `APP_ANDROID` |
[optional] |
| pacing |
str |
You can choose between `PACING_MODE_SMOOTH` and `PACING_MODE_FAST`. For `PACING_MODE_SMOOTH`, the budget is allocated evenly within the scheduled time. `PACING_MODE_FAST` would consume budget and produce results as soon as possible. When Campaign Budget Optimization (`budget_optimize_on`) is on, your setting will be ignored and it will be set as `PACING_MODE_SMOOTH`. Otherwise, this field is required. |
[optional] |
| purchase_intention_keyword_ids |
list[str] |
IDs of purchase intention keywords that you want to use to target audiences with an interest in purchases related to a content category. To get purchase intention keyword IDs, you need to set `audience_type` as `PURCHASE_INTENTION` when calling /tool/interest_keyword/recommend/ and then get purchase intention keyword IDs from `keyword_id` in the response. Note-Do not pass in `purchase_intention_keyword_ids` and `interest_keyword_ids` at the same time. Otherwise, keyword conflict will occur.`purchase_intention_keyword_ids` only supports auctions ads with the corresponding advertising objective(`objective_type`) as App promotion (`APP_PROMOTION`), Conversions (`CONVERSIONS` ) ，or Product sales (`PRODUCT_SALES` when the corresponding `promotion_type` = `APP_ANDROID`, `APP_IOS`, or `WEBSITE`）, and the placement setting should include TikTok. |
[optional] |
| roas_bid |
float |
ROAS goal for Value Optimization. Required when `deep_bid_type` is `VO_MIN_ROAS`. |
[optional] |
| schedule_end_time |
str |
Schedule end time (UTC+0), in the format of "YYYY-MM-DD HH-MM-SS". This field is required when `schedule_type` is `SCHEDULE_START_END` or `budget_mode` is `BUDGET_MODE_TOTAL` |
[optional] |
| schedule_start_time |
str |
Schedule start time (UTC+0), in the format of "YYYY-MM-DD HH-MM-SS". The start time can be up to 12 hours earlier than the current time. |
[optional] |
| schedule_type |
str |
The schedule type can be either `SCHEDULE_START_END` or `SCHEDULE_FROM_NOW`. If you choose `SCHEDULE_START_END`, you need to specify a start time and an end time. If you choose `SCHEDULE_FROM_NOW`, you only need to specify a start time and the end time will be automatically set to 10 years later than the start time. If `budget_mode` is `BUDGET_MODE_TOTAL`, this field must be set to `SCHEDULE_START_END`. |
[optional] |
| secondary_optimization_event |
str |
The secondary goal when optimization goal (`optimization_goal`) is Install (`INSTALL`) or Value (`VALUE`). For enum values, see Conversion events - Secondary-goal events. |
[optional] |
| shopping_ads_retargeting_actions_days |
int |
The valid time range for the specified audience action. Audiences who have completed the specified action within the time range will be retargeted by the shopping ads. Required when `shopping_ads_retargeting_type` is `LAB1` or `LAB2`. |
[optional] |
| shopping_ads_retargeting_type |
str |
Valid when the campaign `objective_type` is `PRODUCT_SALES`. The retargeting type of shopping ads. Enum values- `LAB1`- Retargeting audiences who viewed products or added products to cart but didn't purchase products. `LAB2`- Retargeting audiences who added products to cart but didn't purchase products. `LAB3`- Retargeting audiences using custom combination. `OFF`- No retargeting. |
[optional] |
| spending_power |
str |
Spending power that you want to target. Enum values- `ALL`, `HIGH`. If it is set to `HIGH`, you can target high spending users who typically spend more on purchases than average users. Note- It is only applicable to the TikTok placement. Your `placements` field must contain the enum value of `PLACEMENT_TIKTOK` . It only supports the ad objectives for Auction ads. See Advertising objectives for details. It cannot be used with special industries targeting at the same time. If you have specified `special_industries` at the campaign level, then you cannot use the field here. When `auto_targeting_enabled` is `True` at the ad group level, then `spending_power` will be automatically set to `ALL`. Enum values are `ALL` and `HIGH`. Even if you don't specify this field, then we will still return `ALL` spending power users. |
[optional] |
| targeting_expansion |
OpenApiv13adgroupcreateTargetingExpansion |
|
[optional] |