获取受众列表
您可以使用本接口获取一个广告主账号下所有受众的信息。返回列表是分页的，最大分页大小为100。该接口返回的信息包括每个受众的ID、名称、类型、创建时间、过期时间等。该接口会返回属于您的受众和共享受众。您可以使用is_creator查看您是否为该受众的拥有者。
如果需要获取受众详细信息，例如当前状态以及历史操作记录详情，请使用/dmp/custom_audience/get/接口。
v1.2与v1.3版本对比
以下表格概括了 v1.2与v1.3接口的变化。
``xtable
|变化内容{30%}|v1.2{35%}|v1.3{35%}|
|---|---|---|
|接口路径| /v1.2/dmp/custom_audience/list/|/v1.3/dmp/custom_audience/list/|
|请求参数类型|advertiser_id: number<br>|advertiser_id: string<br>|
|返回参数名称|type<br>|audience_type<br>|
|返回参数类型|audience_id: number<br>|audience_id: string<br>|
|新增请求参数|/|custom_audience_ids: string[]<br>|
|新增返回参数|/|shared: boolean<br>is_creator`: boolean|
## 请求
**地址** https://business-api.tiktok.com/open_api/v1.3/dmp/custom_audience/list/
**方法** GET
**Header**
``` xtable
|字段|类型|描述|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。可以通过[获取访问令牌](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162)接口获取。|
参数
|字段|类型|描述|
|---|---|---|
|advertiser_id {必填}|string|广告主ID。|
|custom_audience_ids |string[]|受众ID列表。长度范围：[1, 100]。|
|page |number|当前页数。默认值: `1`。取值范围: ≥ 1。|
|page_size |number|分页大小。默认值: `10`。取值范围：1-100。|
示例
(code curl http)
curl --get -H "Access-Token:xxx" \\
--data-urlencode "advertiser_id=ADVERTISER_ID" \\
--data-urlencode "page=PAGE" \\
--data-urlencode "page_size=PAGE_SIZE" \\
https://business-api.tiktok.com/open_api/v1.3/dmp/custom_audience/list/
(/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|返回数据。 |
#|list |object[]|受众群体列表。 |
##|shared |boolean| 是否是共享的受众。枚举值：`True`，`False`。|
##|is_creator |boolean|广告主是否是受众的拥有者。枚举值：`true`，`false`。 您可以使用`shared` 和 `is_creator` 查看广告主的所属情况和分享状态。规则如下：<br>1. `shared` = `true` 且 `is_creator` = `true`：广告主是该受众的拥有者，且该受众由广告主分享给其他账户。<br>2. `shared` = `true` 且 `is_creator` = `false`：广告主不是该受众的拥有者，该受众由其他账户分享给广告主。<br>3. `shared` = `false` 且 `is_creator` = `true`：广告主是该受众的拥有者，且该受众未与其他人共享。
##|audience_id |string|受众群体ID。|
##|cover_num |number|覆盖人数。即TikTok上匹配的用户人数。|
##|create_time |string|受众创建时间，GMT时间。|
##|is_valid |boolean|受众群体是否可用。计算中或已过期的受众群体不可用。|
##|is_expiring|boolean|受众群体是否即将过期。受众群体会在过期时间的60天内进入即将过期状态。
##|expired_time|string|受众群体过期时间。时间格式为“YYYY-MM-DD HH:MM:SS"。|
##|name |string|受众群体名称。|
##|audience_type|string|受众群体类型。 枚举值：<br><ul><li>`Customer File Audience` ([客户文件受众](https://ads.tiktok.com/help/article?aid=6721963343558475781))。</li><li>`Engagement Audience` ([广告互动受众](https://ads.tiktok.com/help/article?aid=6721963298155134982))。</li><li>`App Activity Audience` ([应用活动受众](https://ads.tiktok.com/help/article?aid=6721962999092871173))。</li><li>`Website Audience` ([网站访客受众](https://ads.tiktok.com/help/article?aid=6721962903081058309))。</li><li>`Lookalike Audience` ([相似受众](https://ads.tiktok.com/help/article?aid=6746381707865227270))。</li><li>`Lead Generation `([线索收集受众](https://ads.tiktok.com/help/article/lead-generation-audience?lang=zh))</li><li>`Rule Business Account` ([企业号受众](https://ads.tiktok.com/help/article?aid=10011405&redirected=1))</li><li>`Rule ad shop` （[商店活动受众](https://ads.tiktok.com/help/article/shop-retargeting?lang=zh)）</li><li>`Partner` （合作伙伴受众）</li><li>`Challenge` (非标互动受众) </li><li>`Preferred Population` (优选人群受众)</li></ul><p><span style="color:darkred"><b>注意</b></span>：当前，无法通过API创建合作伙伴受众，非标互动受众和优选人群受众。 |
##|calculate_type|string |加密类型。只适用于客户文件受众。枚举值详见[枚举值-加密类型](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。|
#|page_info |object | 分页信息。 |
##|page |number | 当前页数。 |
##|page_size |number | 分页大小。 |
##|total_number |number | 总结果数。 |
##|total_page |number | 总页数。 |
|request_id |string|请求的日志ID，唯一标识一个请求。 |
示例
(code Success-Response http)
HTTPS/1.1 200 OK
{
"message": "OK",
"code": 0,
"data": {
"page_info": {
"total_number": 98,
"page": 1,
"page_size": 2,
"total_page": 49
},
"list": [
{
"audience_id": 100000000,
"name": "create_12",
"cover_num": 1046,
"is_valid": false,
"create_time": "2020-07-02 14:28:22 UTC",
"shared": false,
"type": "Customer File Audience",
"calculate_type": "FIRST_NORMAL"
},
{
"audience_id": 100000000,
"name": "create_6",
"cover_num": 3148,
"is_valid": true,
"create_time": "2020-07-02 14:26:14 UTC",
"shared": false,
"type": "Customer File Audience",
"calculate_type": "FIRST_SHA256"
}
]
},
"request_id": "20200702143049010189056028052FFBFA"
}
(/code);