adgroup_rf_create

Ad group name. Must not exceed 100 characters and must not contain emojis.

Advertiser ID.

Age groups to target. If your targeting locations include Israel or Brazil, `AGE_13_17` cannot be used. In some US scenarios, creating ad groups targeting `AGE_13_17` is not allowed. If you use targeting options that are not supported for age 13-17 in the US and omit `age_groups` or set it to `[]`, an error occurs; explicitly specify the exact age groups you want to target, such as `AGE_18_24`, to avoid errors.

ID of the promoted mobile application.

Audience IDs to target. For an audience to be used in Reach & Frequency ads, its `audience_sub_type` must be `REACH_FREQUENCY` when the audience is created or updated. Lookalike Audience cannot be used in Reach & Frequency ads; otherwise, an error occurs.

Brand safety partner for Reach & Frequency ads. Required when `brand_safety_type` is `THIRD_PARTY`. Pre-bid third-party brand safety solutions are currently allowlist-only features. Once set, this field cannot be modified. `OPEN_SLATE` is named DoubleVerify in TikTok Ads Manager because the partner has been acquired by DoubleVerify.

Brand safety type for Reach & Frequency ads. Default value: `NO_BRAND_SAFETY`. If set to `THIRD_PARTY`, you must also provide `brand_safety_partner`. `NO_BRAND_SAFETY` uses full inventory and ads may appear next to some content featuring mature themes. `EXPANDED_INVENTORY` uses TikTok's brand safety solution with most inappropriate content removed and no mature themes; in the next API version, `EXPANDED_INVENTORY` will replace `NO_BRAND_SAFETY` as the default. `STANDARD_INVENTORY` is appropriate for most brands. `LIMITED_INVENTORY` avoids content containing mature themes. `THIRD_PARTY` uses a third-party brand safety solution. Pre-bid third-party brand safety solutions are currently allowlist-only features. To determine countries and regions where ads can be deployed based on brand safety settings, use `/tool/region/`.

Budget. Fill this value based on data returned by the ad inventory estimate API.

ID of the campaign this ad group belongs to.

Carrier IDs to target. A carrier is valid only when its `in_use` field is `true`. Carriers must be consistent with the targeted location(s).

Valid only when `brand_safety_type` is `STANDARD_INVENTORY` or `LIMITED_INVENTORY`. Content exclusion category IDs.

Whether to prohibit users from commenting on your ads on TikTok. Default value: `False`.

Contextual tag IDs. Not supported when `brand_safety_type` is `THIRD_PARTY`. Not supported when `feed_type` is `TOP_FEED`. If `rf_campaign_type` is `PULSE` in `/campaign/create/`, you must include contextual tags from either the `MAX_PULSE` or `CUSTOM` content lineup types under `PREMIUM` when creating an ad group; `GENERAL` contextual tags are optional. Max Pulse and Category Lineups are available only in specified markets and both features are allowlist only. This field itself is also allowlist-only.

Required when `optimization_goal` is `VIDEO_VIEW` or when using the 6s view-through rate (View+) optimization goal. Target video view duration. For TikTok Pulse campaigns where `rf_campaign_type` is `PULSE` in `/campaign/create/`, use `optimization_goal=REACH` and `cpv_video_duration=SIX_SECONDS` for the 6s view-through rate (View+) optimization goal.

Enum values: STANDARD: Standard delivery. Your ads will be distributed evenly and are expected to achieve similar traffic size. This value is not available for the 6s view-through rate (View+) optimization goal with optimization_goal as REACH and cpv_video_duration as SIX_SECONDS. SCHEDULE: Scheduled delivery. Set specific time periods to deliver each ad in. If you use this value, you need to pass the object array schedules at the same time. SEQUENCE: Sequenced delivery. Set a specific sequence to deliver your ads in. If you use this value, you need to pass the field expected_orders at the same time. VIEW_OPTIMIZE: View optimized delivery. Your ads are distributed to maximize view-through rate (VTR), with more impressions allocated to ads predicted to achieve higher VTR. This value is only available for the 6s view-through rate (View+) optimization goal with optimization_goal as REACH and cpv_video_duration as SIX_SECONDS.

Device model IDs to target. Currently only brand-level model IDs are supported. If this field is specified, `device_price_ranges` must not be specified. Only active devices (`is_active` = `True` in the response of `/tool/device_model/`) can be used to create ads.

Targeting device price range. Values must be multiples of 50; `10000` means `1000+`. If you set this field, do not specify `device_model_ids`. Important: the upper limit you set is increased by 50 and that new number is used as the actual upper limit for device targeting. For example, if you set and later get `[0, 250]`, it actually means `[0, 300]`.

Audience IDs to exclude. For an audience to be used in Reach & Frequency ads, its `audience_sub_type` must be `REACH_FREQUENCY` when the audience is created or updated. Lookalike Audience cannot be used in Reach & Frequency ads; otherwise, an error occurs.

Feed type option. `STANDARD_FEED` provides larger inventory with normal CPM, while `TOP_FEED` provides limited inventory with higher CPM.

`frequency`, together with `frequency_schedule`, controls how often people see your ad and is available only for `REACH` ads. Example: `frequency` = 2 and `frequency_schedule` = 3 means show ads no more than twice every 3 days. Conditions: `1 ≤ frequency ≤ frequency_schedule`; `1 ≤ frequency_schedule ≤ min(schedule_end_time - schedule_start_time, 30)`; and the resulting frequency cap must not exceed four times a day.

`frequency_schedule`, together with `frequency`, controls how often people see your ad and is available only for `REACH` ads. See `frequency` for the full constraints.

Audience gender.

Interest category IDs to target.

Whether the promoted content is HFSS foods (foods high in fat, salt, or sugar). Note that the European market prohibits promoting HFSS foods to underage users.

Language codes to target.

IDs of targeted locations (country/region, province, DMA/metropolitan, or city level). Get valid IDs from `tool_region_get` with `objective_type=RF_REACH` and the same `placements`; do not pass country codes such as `US`. All IDs must belong to a single country or region. R&F supports only these countries and regions: Argentina, Australia, Austria, Bahrain, Belarus, Belgium, Brazil, Cambodia, Canada, Chile, Colombia, Czech Republic, Denmark, Ecuador, Egypt, Finland, France, Germany, Greece, Hungary, Indonesia, Iraq, Ireland, Israel, Italy, Japan, Jordan, Kazakhstan, Kuwait, Lebanon, Malaysia, Mexico, Morocco, Netherlands, New Zealand, Norway, Oman, Pakistan, Peru, Philippines, Poland, Portugal, Qatar, Romania, Russia, Saudi Arabia, Singapore, South Africa, South Korea, Spain, Sweden, Switzerland, Taiwan Province, Thailand, Turkey, Ukraine, United Arab Emirates, United Kingdom, United States, Uruguay, Vietnam.

Device connection types to target. Default value: `unlimited`.

Device operating systems to target. Allowed values: `ANDROID`, `IOS`, `PC`.

Conversion event for the ad group. Required when the promoted object is an app with tracking URLs. Supported app events depend on the app; use `/app/external_action/` to retrieve the supported events for your app.

Desired measurable result for the ad group. Must align with campaign-level `objective_type`. For TikTok Pulse ad groups where `rf_campaign_type` is `PULSE` in `/campaign/create/`, if you want the 6s view-through rate (View+) optimization goal, set `optimization_goal` to `REACH` and `cpv_video_duration` to `SIX_SECONDS`. The 6s view-through rate (View+) optimization goal in TikTok Pulse ad groups is currently an allowlist-only feature.

Promotion type that determines what you promote. If campaign-level `objective_type` is `RF_REACH`, set this field to `WEBSITE_OR_DISPLAY`. Allowed values: `APP_ANDROID`, `APP_IOS`, `WEBSITE`, `WEBSITE_OR_DISPLAY`.

Impressions to purchase, in units of 1,000. Fill this value based on data returned by the ad inventory estimate API.

Purchased user reach, in units of 1,000. Fill this value based on data returned by the ad inventory estimate API.

Client-supplied request ID used to allow duplicate ad group names and support idempotency so the same create request is not processed twice. This is different from the `request_id` returned in the response, which uniquely identifies the HTTP request. Must be a string representation of a 64-bit integer, for example `"123456789"`.

Buying type. `FIXED_SHOW` purchases a fixed amount of impressions, `FIXED_REACH` purchases a fixed user reach, and `FIXED_BUDGET` purchases with a fixed budget.

Schedule end time in UTC+0, format `YYYY-MM-DD HH:MM:SS`. The interval between `schedule_start_time` and `schedule_end_time` must not exceed 90 days. The value must be at `YYYY-MM-DD HH:59:59` in the ad delivery time zone. For example, if an advertiser in UTC-5 wants delivery to end on November 10, 2023, set this field to `"2023-11-10 04:59:59"`.

Ad delivery information. When `delivery_mode` is `SEQUENCE`, the number of objects in this array represents the number of ads for which you specify sequence.

Schedule start time in UTC+0, format `YYYY-MM-DD HH:MM:SS`. The interval between `schedule_start_time` and `schedule_end_time` must not exceed 90 days. The value must be at `YYYY-MM-DD HH:00:00` in the ad delivery time zone. For example, if an advertiser in UTC-5 wants delivery to start on November 1, 2023, set this field to `"2023-11-01 05:00:00"`.

Whether sharing to third-party platforms is disabled for ads in this ad group. Default value: `False`.

Whether users can download your video ads on TikTok. Cannot be updated once created. Default value: `false`.