VI | EN
Message us on Messenger
Developer resources

Update an R&F ad group — TikTok Business API

Update an R&F ad group · call it through Quantri360 with one API key for your own accounts / assets that you connected and authorized — 360 handles request signing and refreshing the authorization you granted.

Update an R&F ad group

POST/adgroup/rf/update/Via 360: POST https://partner.quantri360.com/v1/tiktok_business/adgroup/rf/update/
Write endpoint — changes data on TikTok Business. The key must be created with "Allow write API calls" ticked, otherwise you get 403 write_not_allowed. Every call is logged.
Description

Use this endpoint to update Reach & Frequency ad groups.

Request

Endpoint

POST https://partner.quantri360.com/v1/tiktok_business/adgroup/rf/update/

Authentication & shop

NameInTypeSampleDescription
AuthorizationheaderheaderBearer q360_live_ab12cd34_…Khóa API của brand (tạo ở mục API key). Bắt buộc với mọi request. Brand suy từ key — không truyền mã brand.
platform_shop_idquerystring7000000000000000001Tài sản TikTok Business đã kết nối — "Mã tài sản" ở trang Nền tảng hoặc GET /v1/platforms (tài khoản quảng cáo cho Marketing API, tài khoản TikTok cho Organic / Messaging). Có thể bỏ khi chỉ kết nối một tài sản.

Request parameters

NameInTypeRequiredSampleDescription
adgroup_idbodystringYesID of the ad group to be modified. The objective_type of the campaign it belongs to must be RF_REACH.
share_disabledbodybooleanNoWhether sharing to third-party platforms is disabled for ads in this ad group
adgroup_namebodystringNoName of the ad group. It must not exceed 100 characters or contain any emojis.
comment_disabledbodybooleanNoWhether to prohibit users from posting comments to your ads on TikTok.
audience_idsbodystring[]NoIDs of the audiences that you want to target. For an audience to be targeted or excluded in R&F ads, you must set audience_sub_type to REACH_FREQUENCY when creating or updating the audience. Note: You cannot use Lookalike Audience in R&F ads. Otherwise, an error will occur.
excluded_audience_idsbodystring[]NoIDs of the audiences that you want to exclude. For an audience to be targeted or excluded in R&F ads, you must set audience_sub_type to REACH_FREQUENCY when creating or updating the audience. Note: You cannot use Lookalike Audience in R&F ads. Otherwise, an error will occur.
age_groupsbodystring[]NoAudience age range. If your targeting locations include Israel or Brazil, AGE_13_17 cannot be used. For enum values, see Appendix - Enumeration - Audience Age Range. In certain scenarios, creation of ad groups that target the age group 13-17 (AGE_13_17) in the US will not be allowed. See New age restrictions for ads on TikTok to learn more. If you use targeting options that are not supported for the age group 13-17 in the US and leave the age_groups field unspecified or set it as [], an error will occur. You need to explicitly specify the exact age groups that you want to target, such as AGE_18_24, in the field to avoid any errors.
genderbodystringNoTarget gender. For enum values, see Appendix - Enumeration - Audience Gender.
languagesbodystring[]NoAudience language. Available values: see Appendix - Enumeration - Audience Language.
location_idsbodystring[]NoIDs of the targeted locations. The location can be at the country or region level, the Province, DMA (Designated Market Area) or Metropolitan level, or the city level. Location targeting supports a single country or region only. If you want to target multiple locations, they must be from the same country or region. You can find the supported countries and regions from Reach & Frequency.
is_hfssbodybooleanNoWhether the promoted content is HFSS foods (foods that are high in fat, salt, or sugar). Please note that the European market prohibits the promotion of HFSS foods to underage users.
operating_systemsbodystring[]NoOperating system. See Appendix - Enumeration - Audience Operating System.
network_typesbodystring[]NoDevice connection types that you want to target. Default value: unlimited. For enum values, see Enumeration - Connection Type.
device_model_idsbodystring[]NoIDs of the device models that you want to target. Currently only brand-level model IDs are supported. When this field is specified, device_price_ranges must not be specified. For enum values of device model IDs on different levels, please see Device Models. Note: Only active devices (is_active = True in the response of /tool/device_model/) can be used to create ads.
device_price_rangesbodynumber[]NoTargeting device price range. 10000 means 1000+. The numbers must be in multiples of 50. Important: 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].
carrier_idsbodystring[]NoCarriers 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. For enum values (carrier_id), see Appendix - Carriers.
interest_category_idsbodystring[]NoInterest 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.
rf_purchased_typebodystringNoBuying type. Allowed values: - FIXED_SHOW: Purchase to achieve a fixed amount of impressions. - FIXED_REACH: Purchase to reach a fixed number of users. - FIXED_BUDGE: Purchase with a fixed budget.
budgetbodyfloatNoBudget. Please fill in this number based on the data returned via the ad inventory estimate API.
purchased_impressionbodynumberNoImpressions to be purchased, in the unit of 1,000. Please fill in this number based on the data returned via the ad inventory estimate API.
purchased_reachbodynumberNoNumber of users reached to be purchased, in the unit of 1,000. Please fill in this number based on the results of inventory estimation.
schedule_start_timebodystringNoSchedule start time (UTC+0), in the format of YYYY-MM-DD HH:MM:SS. The time interval between schedule_start_time and schedule_end_time must not exceed 90 days. The value of this field must be at YYYY-MM-DD HH:00:00 for the time zone where the ad will be delivered. For instance, if an advertiser in the UTC-5 time zone wants to create an R&F ad group that starts delivery on November 1st, 2023, this field must be set to "2023-11-01 05:00:00".
schedule_end_timebodystringNoSchedule end time (UTC+0), in the format of YYYY-MM-DD HH:MM:SS. The time interval between schedule_start_time and schedule_end_time must not exceed 90 days. The value of this field must be at YYYY-MM-DD HH:59:59 for the time zone where the ad will be delivered. For instance, if an advertiser in the UTC-5 time zone wants to create an R&F ad group that ends delivery on November 10th, 2023, this field must be set to "2023-11-10 04:59:59".
frequencybodynumberNofrequency, together with frequency_schedule, controls how often people see your ad (only available for REACH ads). For example, frequency = 2 & frequency_schedule = 3 means "show ads no more than twice every 3 days". The following conditions should be met: - 1 ≤ frequency ≤ frequency_schedule. - 1 ≤ frequency_schedule ≤ min (schedule_end_time - schedule_start_time, 30). - The frequency cap determined by frequency and frequency_schedule does not exceed four times a day.
frequency_schedulebodynumberNofrequency_schedule, together with frequency, controls how often people see your ad (only available for REACH ads). See frequency field for more.
feed_typebodystringNoFeed type option. Enum: STANDARD_FEED, TOP_FEED. STANDARD_FEED refers to large inventory with normal CPM price while TOP_FEEDrefers to limited inventory with higher CPM price.
delivery_modebodystringNoThe strategy for sequencing and scheduling your ad delivery. 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. - OPTIMIZE: Optimized delivery that delivers ads to achieve the best performance.
schedule_infosbodyobject[]NoAd delivery information. When delivery_mode is set to SEQUENCE, the number of objects in this array represents the number of ads that you will specify the sequence for.
contextual_tag_idsbodystring[]NoContextual tag IDs. You can use /tool/contextual_tag/get/ to get available contextual tags. Note: - This is an allowlist-only feature. If you would like to access it, please contact your TikTok representative. - Only supports RF_REACH as objectives (objective_type) at the campaign level. - Not supported when brand_safety_type is set to THIRD_PARTY. - Not supported when feed_type is set to TOP_FEED. - If you set rf_campaign_type to PULSE in /campaign/create/, then you must enter contextual tags of PREMIUM type in this field.
brand_safety_typebodystringNoTo learn about the eligibility for updating this field, see Eligibility for updating pre-bid brand safety filtering settings. Brand safety type. Enum values: - 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. To get the countries and regions that your ads can be deployed to based on your brand safety settings, use the /tool/region/ endpoint. Note: - Updating Brand Safety settings, including brand_safety_type, category_exclusion_ids, and vertical_sensitivity_id, is currently an allowlist-only feature. If you would like to access it, please contact your TikTok representative. - See Brand safety to learn about the supported advertising objectives, supported markets, and the general introduction of pre-bid Brand Safety filtering.
category_exclusion_idsbodystring[]NoThis field can only be updated when any of the following conditions is met: - schedule_start_time of the ad group has not been reached. - schedule_start_time of the ad group has been reached, but the operation_status is DISABLE and the cost is 0. To retrieve the schedule_start_time and operation_status of an ad group, use /adgroup/get/. Content exclusion category IDs. You can use /tool/content_exclusion/get/ to get a list of content category IDs (excluded_category_list) that can be excluded from being displayed next to your ads. Note: - Updating Brand Safety settings, including brand_safety_type, category_exclusion_ids, and vertical_sensitivity_id, is currently an allowlist-only feature. If you would like to access it, please contact your TikTok representative.

Request examples

curl -s -X POST "https://partner.quantri360.com/v1/tiktok_business/adgroup/rf/update/" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"adgroup_id":"","schedule_infos":[{}]}'
Python
import requests

KEY = "q360_live_..."  # khóa API của brand
r = requests.post(
    "https://partner.quantri360.com/v1/tiktok_business/adgroup/rf/update/",
    params={},
    json={
        "adgroup_id": "",
        "schedule_infos": [
            {}
        ]
    },
    headers={"Authorization": f"Bearer {KEY}"},
    timeout=60,
)
print(r.status_code)
print(r.json())
Node.js
const KEY = 'q360_live_...'; // khóa API của brand
const url = new URL('https://partner.quantri360.com/v1/tiktok_business/adgroup/rf/update/');
for (const [k, v] of Object.entries({})) url.searchParams.set(k, typeof v === 'object' ? JSON.stringify(v) : String(v));
const r = await fetch(url, {
  method: 'POST',
  headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({"adgroup_id":"","schedule_infos":[{}]}),
});
console.log(r.status, await r.json());
PHP
<?php
$key = 'q360_live_...'; // khóa API của brand
$url = 'https://partner.quantri360.com/v1/tiktok_business/adgroup/rf/update/' . '?' . http_build_query([]);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $key, 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"adgroup_id":"","schedule_infos":[{}]}');
$res = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status, "\n", $res;

Response

Response fields (as returned by TikTok Business)

NameTypeSampleDescription
codenumberThe response code. For the complete list of response codes and descriptions, see Appendix - Return Codes.
messagestringThe response message. For details, see Appendix - Return Codes.
request_idstringThe log id of a request, which uniquely identifies the request.
dataobjectReturn data
advertiser_idstringAdvertiser ID.
campaign_idstringThe campaign the ad group belongs to.
adgroup_idstringAd group ID.
share_disabledbooleanWhether sharing to third-party platforms is disabled for ads in this ad group. Default value: `False`.
adgroup_namestringName of the ad group. It must not exceed 100 characters or contain any emojis.
promotion_typestringPromotion type and you can decide where you'd like to promote your products using this field. Enum: `APP_ANDROID`, `APP_IOS`, `WEBSITE`, `WEBSITE_OR_DISPLAY`.
optimization_eventstringConversion event for the ad group. It is required when the promoted object is an App with tracking urls. For the supported app events, see Conversion events. You can use the /app/external_action/ endpoint to find out the supported events for your app.
app_idstringID of the promoted mobile application.
comment_disabledbooleanWhether to prohibit users from commenting on your ads on TikTok. Default value: `False`.
audience_idsstring[]IDs of the audiences that you want to target. For an audience to be targeted or excluded in R&F ads, you must set `audience_sub_type` to `REACH_FREQUENCY` when creating or updating the audience.
excluded_audience_idsstring[]IDs of the audiences that you want to exclude. For an audience to be targeted or excluded in R&F ads, you must set `audience_sub_type` to `REACH_FREQUENCY` when creating or updating the audience.
age_groupsstring[]Age groups you want to target. If your targeting locations include Israel or Brazil, `AGE_13_17` cannot be used. For enum values, see Enumeration - Age Group.
genderstringAudience gender. For enum values, see Enumeration - Audience Gender.
languagesstring[]Codes of the languages that you want to target. For the list of languages codes supported, see Enumeration - Language Code.
location_idsstring[]IDs of the targeted locations. If you want to target multiple locations, they must from the same country or region. You can find the supported countries and regions in Reach & Frequency. For the list of location IDs, see Location IDs.
is_hfssbooleanWhether the promoted content is HFSS foods (foods that are high in fat, salt, or sugar). Please note that the European market prohibits the promotion of HFSS foods to underage users.
operating_systemsstring[]Device operating systems that you want to target. Enum: `ANDROID`, `IOS`, `PC`.
network_typesstring[]Device connection types that you want to target. Default: `unlimited`. For enum values, see Enumeration - Connection Type.
device_model_idsstring[]IDs of the device models that you want to target. Currently only brand-level model IDs are supported. When this field is specified, `device_price_ranges` must not be specified. For enum values of device model IDs on different levels, please see Device Models.
device_price_rangesnumber[]Targeting device price range. 10000 means 1000+. The numbers must be in multiples of 50. Important: 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].
carrier_idsstring[]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. For enum values (`carrier_id`), see Get Carriers.
interest_category_idsstring[]List of interest categories that you want to target. Use /tool/interest_category/ endpoint to get the complete list of interest categories.
rf_purchased_typestringBuying type. Allowed values: - `FIXED_SHOW`: Purchase to achieve a fixed amount of impressions. - `FIXED_REACH`: Purchase to reach a fixed number of users. - `FIXED_BUDGET`: Purchase with a fixed budget.
budgetfloatBudget. Please fill in this number based on the data returned via the ad inventory estimate API.
purchased_impressionnumberImpressions to be purchased, in the unit of 1,000.
purchased_reachnumberPurchased user reach, in the unit of 1,000
schedule_start_timestringSchedule start time (UTC+0), in the format of `YYYY-MM-DD HH:MM:SS`.
schedule_end_timestringSchedule end time (UTC+0), in the format of `YYYY-MM-DD HH:MM:SS`.
frequencynumber`frequency`, together with `frequency_schedule`, controls how often people see your ad (only available for `REACH` ads). For example, `frequency` = 2 & `frequency_schedule` = 3 means "show ads no more than twice every 3 days".
frequency_schedulenumber`frequency_schedule`, together with `frequency`, controls how often people see your ad (only available for `REACH` ads). See `frequency` field for more.
optimization_goalstringThe measurable results you'd like to drive with your ads. It must be aligned with the value for `objective_type` on the campaign level. Enum values: `REACH`, `VIDEO_VIEW`, `CLICK`, `POST_ENGAGEMENT`, `INSTALL`.
cpv_video_durationstringThe target video view duration. Enum values: `TWO_SECONDS`, `SIX_SECONDS`.
brand_safety_typestringBrand safety type for Reach and Frequency ads. 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. - `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. To get the countries and regions that your ads can be deployed to based on your brand safety settings, use the /tool/region/ endpoint.
brand_safety_partnerstringBrand safety partner for Reach and Frequency ads. Available only when `brand_safety_type` is `THIRD_PARTY`. Enum values: `IAS`, `OPEN_SLATE`(The partner is named DoubleVerify on TikTok Ads Manager because the partner has been acquired by DoubleVerify). Note: - Pre-bid third-party brand safety solutions are currently allowlist-only features. If you would like to access them, please contact your TikTok representative.
category_exclusion_idsstring[]Content exclusion category IDs.
video_download_disabledbooleanWhether users can download your video ads on TikTok(cannot be updated once created). Default: False.
feed_typestringFeed type option. Enum values: `STANDARD_FEED`, `TOP_FEED`. `STANDARD_FEED` refers to large inventory with normal CPM price while `TOP_FEED`refers to limited inventory with higher CPM price.
delivery_modestringThe strategy for sequencing and scheduling your ad delivery. Enum values: - `STANDARD`: Standard delivery. Your ads will be distributed evenly and are expected to achieve similar traffic size. - `SCHEDULE`: Scheduled delivery. Set specific time periods to deliver each ad in. - `SEQUENCE`: Sequenced delivery. Set a specific sequence to deliver your ads in. - `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. - `OPTIMIZE`: Optimized delivery that delivers ads to achieve the best performance.
schedule_infosobject[]Ad delivery information.
schedulesobject[]The details of the scheduled delivery for the ad.
start_timestringAd delivery start time.
end_timestringAd delivery end time.
expected_ordersnumber[]The delivery order for an ad within the ad group. For example, a value of `[1]` indicates that the ad will be delivered first.
is_draftbooleanWhether the ad delivery information is in draft mode. If the value of this field is `true`, then the ad delivery information defined in the request has not been associated with any specific ads. To associate the ad delivery information with ads, pass the value of the returned `schedule_id` to the request parameter `schedule_id` in /ad/create/. After you associate the ad delivery information with an ad, the value of this field will automatically be set to `false`, and the value of `schedule_id` will be the ID of the ad that you have associated the ad delivery information with.
schedule_idstringSchedule ID. If the value of `is_draft` is `true`, then the ad delivery information defined in the request has not been associated with any specific ads. To associate the ad delivery information with ads, pass the value of this field to the request parameter `schedule_id` in /ad/create/. After you associate the ad delivery information with an ad, the value of `is_draft` will automatically be set to `false`, and the value of this field will be the ID of the ad that you have associated the ad delivery information with.
noticestringSystem notice.
contextual_tag_idsstring[]Contextual tag IDs.

Response sample

HTTPS/1.1 200 OK
{
    "code": 40002,
    "message": "This ad has finished delivering and can no longer be edited.",
    "request_id": "{{request_id}}",
    "data": {}
}
(/code);

Get started

  1. Sign up for Partner
  2. Enable a data type of the Ads (Marketing API) group on the platform page
  3. Create an API key (tick the TikTok Business channel)
  4. Call it as in the examples above