通过文件创建受众

您可以使用本接口通过上传的文件创建受众。您需要先上传受众数据文件，获得一个全局唯一的file_path，并使用该file_path创建一个对应的受众群体。

查看身份标识符标准化指南，了解身份标识符标准化的相关步骤。

提示

请查看下表了解本接口相关的文件大小，受众生效时间，受众状态和定向设置限制。

| 类型 {30%}| 详情{70%} |
|---|---|
| 文件大小 | 单个广告主账户中最多可创建400个受众群体，该限制为广告主层级限制。若广告主账户的受众群体数量达到上限，则需在创建新受众前先删除现有受众。 |
| 受众生效时间| 在您创建受众群体后，系统最多需要48个小时进行解析处理，请耐心等候。 |
| 受众状态 | 您可以通过[获取受众详情](https://ads.tiktok.com/marketing_api/docs?id=1739940507792385)接口查看当前的受众状态。当受众状态变为“可用”（`is_valid` = `true`）后，您才可以使用该受众群体进行后续操作。<br>受众过期后，其状态将变为“已过期”（`is_valid` = `false`），并解除与投放中的推广系列的绑定。 |
| 定向设置 | 若推广系列仅设置了受众定向，未设置其他定向，则推广系列将暂停。|
| 关联接口 |如果您在创建受众时指定了错误的`file_path`，可以通过[修改受众](https://ads.tiktok.com/marketing_api/docs?id=1739940572667906)接口修改。|

v1.2与v1.3版本对比

以下表格概括了 v1.2与v1.3接口的变化。 ``xtable |变化内容{30%}|v1.2{35%}|v1.3{35%}| |---|---|---| |接口路径| /v1.2/dmp/custom_audience/create/|/v1.3/dmp/custom_audience/create/| |请求参数类型|advertiser_id: number<br>|advertiser_id: string<br>| |新增请求参数| / |retention_in_days| |返回参数|custom_audience_id: number<br>|custom_audience_id`: string
|



## 请求

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

**方法** POST

**Header**

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

参数

|字段|类型|描述|
|---|---|---|
|advertiser_id {必填}|string|广告主ID。|
|custom_audience_name {必填}|string|自定义受众名称，限128字符内。|
|audience_sub_type|string| 受众子类型，表明可以使用的广告类型。枚举值：`NORMAL`: 常规受众，可用于非覆盖和频次广告。`REACH_FREQUENCY`：覆盖和频次广告受众，只可用于覆盖和频次广告。默认值：`NORMAL`。|
|file_paths {必填}|string[]|数据文件地址列表。<br>为确保请求稳定性，推荐数量<b><50</b>。您可使用[/dmp/custom_audience/update/](1739940572667906.html)接口为受众增加更多数据文件。<br>在您通过接口[上传受众文件](https://ads.tiktok.com/marketing_api/docs?id=1739940567842818)上传文件后，您会在返回中获得`file_path`。|
|calculate_type {必填} |string |加密类型。`calculate_type`必须与`file_path`中所有文件的加密类型保持一致，否则您将无法获得受众ID，或导致受众ID无效。枚举值详见[枚举值-加密类型](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。 |
|retention_in_days |integer |保留该受众的天数。<br>取值范围：&#91;1, 365&#93;。 <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>|

示例

(code curl http)
curl --location --request POST 'https://ads.tiktok.com/open_api/v1.3/dmp/custom_audience/create/' \
--header 'Access-Token: {{Access-Token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "advertiser_id": "{{advertiser_id}}",
    "custom_audience_name": "test_new",
    "file_paths": ["{{file_paths}}"],
    "calculate_type": "{{calculate_type}}"
}'
(/code)

|字段|类型|描述|
|---|---|---|
|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 |string|自定义受众ID。|
|request_id |string|请求的日志ID，唯一标识一个请求。  |

示例

(code Success-Response http)
HTTPS/1.1 200 OK
{
    "message": "OK",
    "code": 0,
    "data": {
        "custom_audience_id": "123"
    }
}
(/code);