← 返回目录
📁 API Reference › Audience

通过规则创建受众

您可以使用本接口通过规则创建受众。

您需要传入一系列的包含规则及可选的排除规则来创建受众。

注意

  • 新建的受众最多需要48小时来处理，然后才能使用。
  • 请使用/dmp/custom_audience/get/接口来检查新建受众的状态，只有状态是“可用”（is_valid = true）才能被使用。
    受众过期后，其状态将变为“已过期”（is_valid = false），并解除与投放中的推广系列的绑定。
  • 若推广系列仅设置了受众定向，未设置其他定向，则推广系列将暂停。

v1.2与v1.3版本对比

以下表格概括了 v1.2与v1.3接口的变化。 ``xtable |变化内容{30%}|v1.2{35%}|v1.3{35%}| |---|---|---| |接口路径|/v1.2/dmp/custom_audience/rule/create/|/v1.3/dmp/custom_audience/rule/create/| |请求参数类型|advertiser_id: number<br>is_auto_refresh: number|advertiser_id: string<br>is_auto_refresh: boolean| |新增请求参数| / |retention_in_days<br>identity_id<br>identity_type<br>identity_authorized_bc_id<br>parameter_filters（包含该对象数组中的所有参数） | |返回参数类型|custom_audience_id: number|custom_audience_id`: string|


## 请求

**地址** https://business-api.tiktok.com/open_api/v1.3/dmp/custom_audience/rule/create/

**方法** POST

**Header**

``` xtable
|字段{35%}|类型{10%}|描述{55%}|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。可以通过[获取访问令牌](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162)接口获取。|
|Content-Type {必填}|string|请求信息类型。<br>允许格式：`application/json`。|

参数

|字段{35%}|类型{10%}|描述{55%}|
|---|---|---|
|advertiser_id {必填}|string|广告主 ID。|
|custom_audience_name {必填}|string|受众名称。<br><br>长度限制：128 个字符。|
|audience_type{必填}|string|受众类型。<br><br>枚举值：<ul><li>`ENGAGEMENT`：广告互动受众（资产类型为广告组）。</li><li>`ENGAGEMENT_ORGANIC_VIDEO`：自然流量视频互动受众（资产类型为公开视频）。</li><li>`ENGAGEMENT_LIVE_VIDEO`：直播视频互动受众（资产类型为直播视频）。</li><li>`APP`：应用事件受众。</li><li>`PIXEL`：网站访客受众。</li><li>`LEAD_GENERATION`：线索收集受众。</li><li> `BUSINESS_ACCOUNT`：企业号受众。</li><li>`TIKTOK_SHOP` ：商店活动受众。</li><li>`OFFLINE`：线下活动受众。</li></ul> |
|audience_sub_type|string|受众子类型，表明该受众可用于的广告类型。<br><br>枚举值：<ul><li>`NORMAL`：常规受众，即可用于非覆盖和频次广告的受众。</li><li>`REACH_FREQUENCY`：覆盖和频次广告受众，即只可用于覆盖和频次广告。</li></ul>默认值：`NORMAL`。|
|retention_in_days |integer |保留该受众的天数。<br><br>取值范围：1-365。<br> <br><p><span style="color:darkred"><b>注意</b></span>：<ul><li>若设置了本字段，受众将在距离创建时间的指定保留天数后过期，对该受众的任何操作均<strong>不会</strong>重置过期日期。</li><li>若未设置本字段，受众将在连续12个月未应用于任何活跃广告组且未进行任何修改后过期，将该受众应用于活跃广告组或修改该广告组<strong>会</strong>重置过期日期。欲了解会重置过期日期的操作，请查看帮助中心文档[受众过期政策](https://ads.tiktok.com/help/article/audience-expiration-policy?redirected=2)。 </li></ul>|
|is_auto_refresh|boolean|是否开启受众自动刷新功能。<br> <br>支持的值：`true`，`false`。<br> 默认值：`true`。<br> <br>如果开启该功能，受众将会根据您选择的天数进行自动更新。如果关闭该功能，受众将会保持不变。|
| identity_id {+条件必填} | string | 当 `audience_type` 为 `ENGAGEMENT_LIVE_VIDEO` 或 `ENGAGEMENT_ORGANIC_VIDEO` 时本字段必填。 <br> <br>认证身份ID， |
| identity_type {+条件必填} | string | 当 `audience_type` 为 `ENGAGEMENT_LIVE_VIDEO` 或 `ENGAGEMENT_ORGANIC_VIDEO` 时本字段必填。<br> <br>认证身份类型。<br><br>枚举值：`TT_USER`，`BC_AUTH_TT`。 |
| identity_authorized_bc_id {+条件必填} | string | 当 `audience_type`为`BC_AUTH_TT`时本字段必填。 <br> <br>与添加到商务中心的 TikTok 用户这一认证身份绑定的商务中心的 ID。 |
|rule_spec{必填}|object|受众的规则。|
#|inclusion_rule_set{必填}|object| 包含规则集的详情。|
##|operator{必填}|string|包含规则集中的包含规则之间的操作符。<br> <br>枚举值：`OR`。<br> <br>若您指定了一条以上的包含规则，则包含规则间将通过 OR 逻辑组合，从而扩大受众范围。|
##|rules{必填}|object[]|包含规则集中的包含规则列表。|
###|event_source_ids|string[]|当`audience_type`不为`ENGAGEMENT`或`LEAD_GENERATION`时本字段必填。<br> <br>规则的事件源 ID 列表。<br> <br><ul><li>对于广告互动受众，需要填入广告组 ID。不填默认使用所有事件源 ID。</li><li>对于自然流量视频互动受众，使用 TikTok 帖子 ID 作为事件源 ID。您可以使用[/identity/video/get/](1740218475032577.html) 接口获取 TikTok 帖子 ID 。最多填入10个 TikTok 帖子 ID 。</li><li> 对于直播互动受众，使用直播视频 ID 作为事件源 ID。 您可以使用[/identity/live/get/](1785238052792321.html)接口获取直播视频 ID。最多填入10个直播视频 ID。</li><li>对于应用事件受众，需要填入 App ID。</li><li>对于网站访客受众，需要填入Pixel ID。</li><li>对于线索收集受众，不能填入该字段，否则会出现报错。不填默认使用所有事件源 ID。</li><li>对于商店活动受众，填入 TikTok Shop ID。您可以使用 [/store/list/](1752267762718722.html)接口获取 TikTok Shop ID。</li><li>对于企业号受众，需要填入广告主的核心用户 ID。您可以使用 [/user/info/](1739665513181185.html) 接口获取核心用户 ID。</li><li>对于线下活动受众，使用线下事件组 ID 作为事件源 ID。您可以使用[/offline/get/](1765596808589313.html) 获取线下事件组 ID。|
###|retention_days{必填}|number|受众回溯期。 <br> <br>枚举值详情可查看[枚举值 - 回溯期](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138#item-link-回溯期%EF%BC%88retention_days%EF%BC%89)。 <br> <br><p><span style="color:darkred"><b>注意</b></span>：<ul><li> 如果`audience_type`为`BUSINESS_ACCOUNT`，且`filters`对象中的`value`不为`BUSINESS ACCOUNT PROFILE FOLLOW`，则`retention_days`必须为`7`，`14`或`30`。</li><li>如果`audience_type`为`ENGAGEMENT_LIVE_VIDEO` 或`ENGAGEMENT_ORGANIC_VIDEO`，`retention_days`必须为`7`，`14`或`30`。</li><li>为避免`retention_days`和`retention_in_days`字段的混淆，我们将在下个API版本修改`retention_days`的字段名。</li></ul>|
###|filter_set{必填}|object|每个包含规则集中的筛选条件集。|
####|operator{必填}|string|对象数值`filters`中的筛选条件间的操作符。 <br> <br>枚举值：`OR`。 <br> <br>每个包含规则集中，仅可在`filters`中指定一个对象。|
####|filters{必填}|object[]|筛选条件数组，其中包含过去受众行为的筛选条件，可同时指定链接关键词和参数的筛选条件。 <br> <br>最大数量：1。|
#####|field{必填}|string|筛选字段。 <br> <br>枚举值：<ul><li>`EVENT`： 包含在`retention_days`指定的受众回溯期内发生了某个行为的受众。</li></ul>|
#####|operator{必填}|string|连接筛选字段和筛选字段值的操作符。<br> <br>枚举值：<ul><li>`EQ`：等于。</li></ul>|
#####|value{必填}|string|筛选值。<br> <br>详情可查看 [枚举值-筛选字段值](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138#item-link-筛选字段值)。 |
#####| parameter_filters | object[] | 链接关键词和参数的筛选条件列表。 <br><br>您可在 `parameter_filters` 中最多指定 1 个链接关键词筛选条件（`field`设置为`URL`）和 10 个参数筛选条件（`field`设置为非 `URL`）。 <br>若指定了`parameter_filters`中的筛选条件，这些条件将与（通过`field`、`operator` 和 `value` 定义的）受众行为筛选条件默认通过 AND 逻辑组合，形成最终的包含规则。 <br><br> 例如，若`retention_days`为`30`，且 `filter_set` 设置为`&#123;"operator": "OR", "filters":[&#123;"field":"EVENT","operator":"EQ", "value":"PIXEL COMPLETE PAYMENT"&#125;,"parameter_filters":[&#123;"field":"URL","operator":"CONTAINS","value":"us"&#125;]]}`，则该包含规则生成的受众将包含过去 30 天内在安装了所指定的 Pixel 的网站上的网页链接中带有"us"字样的网页上发生了“支付完成”行为的受众。 |
######| field {+条件必填} | string | 传入 `inclusion_rule_set` 中的 `parameter_filters` 时本字段必填。 <br><br>筛选条件。<br>使用本字段指定筛选链接关键词或[ Pixel 报告的网站事件参数](https://business-api.tiktok.com/portal/docs?id=1739585702922241#item-link-%E5%8F%82%E6%95%B0)。<br><br>枚举值：<ul><li>`URL`：链接关键词。</li><li>`CONTENT_TYPE`：参数 `content_type`。</li><li>`PRICE`：参数 `price`。</li><li>`VALUE`：参数 `value`。 </li><li>`CONTENT_ID`：参数 `content_id`。</li><li>`CONTENT_CATEGORY`：参数 `content_category`。 </li></ul> |
######| operator {+条件必填}  | string | 传入 `inclusion_rule_set` 中的 `parameter_filters` 时本字段必填。  <br><br>连接筛选条件和筛选值的操作符。  <br><br>枚举值： <ul><li> `CONTAINS`：包含。</li><li>`DOES_NOT_CONTAIN`：不包含。</li><li>`EQ`：等于。</li><li>`NOT_EQUAL`：不等于。</li><li>`IS_LESS_THAN`：小于。</li><li>`IS_GREATER_THAN`：大于。 </li><li>`IS_LESS_THAN_OR_EQUAL_TO`：小于或等于。</li><li>`IS_GREATER_THAN_OR_EQUAL_TO`：大于或等于。</li></ul><br> 本字段的可选值根据 `field` 而变化：<ul><li>若 `field` 设置为 `URL`，仅可将 `operator` 设置为 `CONTAINS`，`DOES_NOT_CONTAIN`，`EQ` 或 `NOT_EQUAL`。</li><li>若 `field` 未设置为 `URL`，可将 `operator` 设置为 `CONTAINS`, `DOES_NOT_CONTAINS`，`EQ`，`NOT_EQUAL`，`IS_LESS_THAN`，`IS_GREATER_THAN`，`IS_LESS_THAN_OR_EQUAL_TO` 或`IS_GREATER_THAN_OR_EQUAL_TO`。</li></ul>|
######| values {+条件必填}  | string[] | 传入 `inclusion_rule_set` 中的 `parameter_filters` 时本字段必填。  <br><br>筛选值列表。 <br><br> 最大数量：10。 <br>每个筛选值的长度限制：100 个字符。 <br><br>若您指定多个值，值之间将通过 OR 逻辑连接。 |
#|exclusion_rule_set|object|排除规则集的详情。|
##|operator{+条件必填}|string|传入 `exclusion_rule_set` 时本字段必填。<br> <br>排除规则集中的排除规则之间的操作符。<br> <br>枚举值：`OR`。|
##|rules{+条件必填}|object[]|传入 `exclusion_rule_set` 时本字段必填。<br> <br>排除规则集中的排除规则列表。|
###|event_source_ids|string[]|规则的事件源 ID 列表。<br> <br><ul><li>对于广告互动受众，需要填入广告组 ID。不填默认使用所有事件源 ID。</li><li>对于自然流量视频互动受众，使用 TikTok 帖子 ID 作为事件源 ID。您可以使用[/identity/video/get/](1740218475032577.html) 接口获取 TikTok 帖子 ID 。最多填入10个 TikTok 帖子 ID 。</li><li> 对于直播互动受众，使用直播视频 ID 作为事件源 ID。 您可以使用[/identity/live/get/](1785238052792321.html)接口获取直播视频 ID。最多填入10个直播视频 ID。</li><li>对于应用事件受众，需要填入 App ID。</li><li>对于网站访客受众，需要填入Pixel ID。</li><li>对于线索收集受众，不能填入该字段，否则会出现报错。不填默认使用所有事件源 ID。</li><li>对于商店活动受众，填入 TikTok Shop ID。您可以使用 [/store/list/](1752267762718722.html)接口获取 TikTok Shop ID。</li><li>对于企业号受众，需要填入广告主的核心用户 ID。您可以使用 [/user/info/](1739665513181185.html) 接口获取核心用户 ID。</li><li>对于线下活动受众，使用线下事件组 ID 作为事件源 ID。您可以使用[/offline/get/](1765596808589313.html) 获取线下事件组 ID。|
###|retention_days{必填}|number|受众回溯期。<br><br> 枚举值详情可查看[枚举值 - 回溯期](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138#item-link-回溯期%EF%BC%88retention_days%EF%BC%89)。 <br><br><p><span style="color:darkred"><b>注意</b></span>：<ul><li> 如果`audience_type`为`BUSINESS_ACCOUNT`，且`filters`对象中的`value`不为`BUSINESS ACCOUNT PROFILE FOLLOW`，则`retention_days`必须为`7`，`14`或`30`。<li>为避免`retention_days`和`retention_in_days`字段的混淆，我们将在下个API版本修改`retention_days`的字段名。|
###|filter_set{+条件必填}|object|传入 `exclusion_rule_set` 时本字段必填。<br> <br>每个排除规则集中的筛选条件集。|
####|operator{+条件必填}|string|传入 `exclusion_rule_set` 时本字段必填。<br> <br>对象数值`filters`中的筛选条件间的操作符。<br> <br>枚举值：`OR`。 <br> <br>每个排除规则集中，仅可在`filters`中指定一个对象。|
####|filters{+条件必填}|object[]|传入 `exclusion_rule_set` 时本字段必填。<br> <br>筛选条件数组，其中包含过去受众行为的筛选条件，可同时指定链接关键词和参数的筛选条件。 <br> <br>最大数量：1。|
#####|field{+条件必填}|string|传入 `exclusion_rule_set` 时本字段必填。<br> <br>筛选字段。 <br> <br>枚举值：<ul><li>`EVENT`： 排除在`retention_days`指定的受众回溯期内发生了某个行为的受众。</li></ul>|
#####|operator{+条件必填}|string|传入 `exclusion_rule_set` 时本字段必填。<br> <br>连接筛选字段和筛选字段值的操作符。<br> <br>枚举值：<ul><li>`EQ`：等于。</li></ul>|
#####|value{+条件必填}|string|传入 `exclusion_rule_set` 时本字段必填。<br> <br>筛选值。<br> <br>详情可查看 [枚举值-筛选字段值](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138#item-link-筛选字段值)。 |
#####| parameter_filters | object[] | 链接关键词和参数的筛选条件列表。 <br><br>您可在 `parameter_filters` 中最多指定 1 个链接关键词筛选条件（`field`设置为`URL`）和 10 个参数筛选条件（`field`设置为非 `URL`）。 <br>若指定了`parameter_filters`中的筛选条件，这些条件将与（通过`field`、`operator` 和 `value` 定义的）受众行为筛选条件默认通过 AND 逻辑组合，形成最终的排除规则。 <br><br> 例如，若`retention_days`为`30`，且 `filter_set` 设置为`&#123;"operator": "OR", "filters":[&#123;"field":"EVENT","operator":"EQ", "value":"PIXEL COMPLETE PAYMENT"&#125;,"parameter_filters":[&#123;"field":"URL","operator":"CONTAINS","value":"us"&#125;]]}`，则该排除规则生成的受众将排除过去 30 天内在安装了所指定的 Pixel 的网站上的网页链接中带有"us"字样的网页上发生了“支付完成”行为的受众。 |
######| field {+条件必填} | string | 传入 `exclusion_rule_set` 中的 `parameter_filters` 时本字段必填。 <br><br>筛选条件。<br>使用本字段指定筛选链接关键词或[ Pixel 报告的网站事件参数](https://business-api.tiktok.com/portal/docs?id=1739585702922241#item-link-%E5%8F%82%E6%95%B0)。<br><br>枚举值：<ul><li>`URL`：链接关键词。</li><li>`CONTENT_TYPE`：参数 `content_type`。</li><li>`PRICE`：参数 `price`。</li><li>`VALUE`：参数 `value`。 </li><li>`CONTENT_ID`：参数 `content_id`。</li><li>`CONTENT_CATEGORY`：参数 `content_category`。 </li></ul> |
######| operator {+条件必填}  | string | 传入 `exclusion_rule_set` 中的 `parameter_filters` 时本字段必填。  <br><br>连接筛选条件和筛选值的操作符。  <br><br>枚举值： <ul><li> `CONTAINS`：包含。</li><li>`DOES_NOT_CONTAIN`：不包含。</li><li>`EQ`：等于。</li><li>`NOT_EQUAL`：不等于。</li><li>`IS_LESS_THAN`：小于。</li><li>`IS_GREATER_THAN`：大于。 </li><li>`IS_LESS_THAN_OR_EQUAL_TO`：小于或等于。</li><li>`IS_GREATER_THAN_OR_EQUAL_TO`：大于或等于。</li></ul><br> 本字段的可选值根据 `field` 而变化：<ul><li>若 `field` 设置为 `URL`，仅可将 `operator` 设置为 `CONTAINS`，`DOES_NOT_CONTAIN`，`EQ` 或 `NOT_EQUAL`。</li><li>若 `field` 未设置为 `URL`，可将 `operator` 设置为 `CONTAINS`, `DOES_NOT_CONTAINS`，`EQ`，`NOT_EQUAL`，`IS_LESS_THAN`，`IS_GREATER_THAN`，`IS_LESS_THAN_OR_EQUAL_TO` 或`IS_GREATER_THAN_OR_EQUAL_TO`。</li></ul>|
######| values {+条件必填}  | string[] | 传入 `exclusion_rule_set` 中的 `parameter_filters` 时本字段必填。  <br><br>筛选值列表。 <br><br> 最大数量：10。 <br>每个筛选值的长度限制：100 个字符。 <br><br>若您指定多个值，值之间将通过 OR 逻辑连接。 |

示例


(code curl http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/dmp/custom_audience/rule/create/' \
--header 'Content-Type: application/json' \
--header 'Access-Token: {{Access-Token}}' \
--data '{
    "advertiser_id": "{{advertiser_id}}",
    "custom_audience_name": "{{custom_audience_name}}",
    "audience_type": "OFFLINE",
    "rule_spec": {
        "inclusion_rule_set": {
            "operator": "OR",
            "rules": [
                {
                    "event_source_ids": [
                        "{{event_source_id}}"
                    ],
                    "retention_days": 7,
                    "filter_set": {
                        "operator": "OR",
                        "filters": [
                            {
                                "field": "EVENT",
                                "operator": "EQ",
                                "value": "OFFLINE COMPLETE PAYMENT"
                            }
                        ]
                    }
                }
            ]
        }
    }
}'
(/code)

返回

|字段{35%}|类型{10%}|描述{55%}|
|---|---|---|
|code |number|返回码，详见[附录-返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。|
|message |string|返回信息，详见[附录-返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。|
|data|object|返回数据。|
#|custom_audience_id |number|自定义受众 ID。|
|request_id |string|请求的日志id，唯一标识一个请求。  |

示例

(code Success-Response http)
{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": {
        "custom_audience_id": "{{custom_audience_id}}"
    }
}
(/code);
← 修改受众刷新相似受众 →

内容来源：TikTok API for Business 官方文档 · 本地归档

在接这个接口时卡住了？
Stuck wiring this API into production? We build ad-delivery tooling on these platforms — campaign automation, reporting pipelines, error-handling and migration between API versions.
联系我们 · Talk to us 每日平台更新简报 →