TOOL API

dmp_custom_audience_rule_create

Creates a custom audience from rule-based inclusion criteria and optional exclusion criteria. Newly created audiences can take up to 48 hours to be analyzed before becoming active. Use /dmp/custom_audience/get/ to check audience status; only available audiences (`is_valid` = `true`) can be operated on. When an audience expires, it becomes unavailable (`is_valid` = `false`) and is detached from active campaigns. If a campaign has no targeting other than audience targeting, the campaign will be paused.

ecommerceOAuth1 credits

Call information

Tool slug
tiktok-ads.dmp_custom_audience_rule_create
Provider
TikTok for Business
Average response
0 ms
Calls in 7 days
0

Input parameters

advertiser_idrequired

Advertiser ID.

audience_sub_type

Audience subtype indicating which ad type can use the audience. `NORMAL` is for non-Reach & Frequency ads. `REACH_FREQUENCY` can only be used in Reach & Frequency ads. Defaults to `NORMAL`.

audience_typerequired

Audience type. Determines valid rule inputs such as `event_source_ids`, identity fields, and filter values. `ENGAGEMENT`: engagement audience using ad groups as assets. `ENGAGEMENT_ORGANIC_VIDEO`: organic engagement audience using public videos; requires `identity_id` and `identity_type`. `ENGAGEMENT_LIVE_VIDEO`: live engagement audience using live videos; requires `identity_id` and `identity_type`. `APP`: app activity audience. `PIXEL`: website traffic audience. `LEAD_GENERATION`: lead generation audience; do not pass `event_source_ids` in rules or an error occurs. `BUSINESS_ACCOUNT`: business account audience. `TIKTOK_SHOP`: shop activity audience. `OFFLINE`: offline activity audience.

custom_audience_namerequired

Audience name. Length limit: 128 characters.

identity_authorized_bc_id

Business Center ID associated with a TikTok Account User in Business Center identity. Required when `identity_type` is `BC_AUTH_TT`.

identity_id

Identity ID. Required when `audience_type` is `ENGAGEMENT_LIVE_VIDEO` or `ENGAGEMENT_ORGANIC_VIDEO`.

identity_type

Identity type. Required when `audience_type` is `ENGAGEMENT_LIVE_VIDEO` or `ENGAGEMENT_ORGANIC_VIDEO`. If `identity_type` is `BC_AUTH_TT`, you must also provide `identity_authorized_bc_id`.

is_auto_refresh

Whether to enable auto-refresh. Supported values: `true`, `false`. Defaults to `true`. When enabled, the audience automatically refreshes based on the lookback window you set; when disabled, it does not automatically refresh.

retention_in_days

Number of days to retain the audience. Range: 1-365. If set, the audience expires this many days after creation and later operations cannot reset the expiration date. If omitted, expiration is 365 days from the last time the audience was applied to an active ad group or modified; applying it to an active ad group or modifying it resets expiration.

rule_specrequired

Audience rule definition, containing a required inclusion rule set and an optional exclusion rule set.