获取认证身份列表
您可以使用本接口获取广告账户下的认证身份列表。您可以根据身份类型或显示名称筛选结果。
v1.2与v1.3版本对比
以下表格概括了 v1.2与v1.3接口的变化。
``xtable
|变化内容{30%}|v1.2{35%}|v1.3{35%}|
|---|---|---|
|接口路径| /v1.2/identity/get/| /v1.3/identity/get/|
|请求参数类型 |advertiser_id: number |advertiser_id: string |
|返回参数名称|list|identity_list|
|新增返回参数| / |can_manage_message<br>is_gpppa<br>ads_only_mode<br>username`|
## 请求
**地址** https://business-api.tiktok.com/open_api/v1.3/identity/get/
**方法** GET
**Header**
```xtable
|字段|类型|描述|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。可以通过[获取访问令牌](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162)接口获取。|
参数
|字段|类型|描述|
|---|---|---|
| advertiser_id {必填} | string |广告主 ID。|
| identity_type | string | 认证身份类型。<br><br>枚举值：`CUSTOMIZED_USER`, `AUTH_CODE`, `TT_USER`, `BC_AUTH_TT`。获取更多相关信息，请访问[认证身份](https://ads.tiktok.com/marketing_api/docs?id=1738958351620097)。<br><br>如果不传入本字段，则返回所有结果。<br><br><p><span style="color:darkred"><b>注意</b></span>：如果将此字段设置为 `BC_AUTH_TT` 并指定 `identity_authorized_bc_id`，则会返回与广告账户（`advertiser_id`）关联的所有身份。</p> |
| identity_authorized_bc_id {+条件必填}| string | 当`identity_type`为`BC_AUTH_TT`时必填。<br><br>与添加到商务中心的 TikTok 用户这一认证身份绑定的商务中心的 ID。|
|filtering|object|筛选条件。<br><br><p><span style="color:darkred"><b>注意</b></span>：本字段仅当`identity_type` 为 `CUSTOMIZED_USER` 或不传入`identity_type`时生效。 |
#|keyword|string|筛选关键词。<br><br>当 `identity_type` 为 `CUSTOMIZED_USER`时，您可以通过本字段传入显示名称（`display_name`）进行模糊匹配。 |
| page | number | 当前页数。<br><br>默认值：1。 |
| page_size | number | 分页大小。<br><br>取值范围：1-100。<br><br>默认值：20。|
示例
(code curl http)
curl --location --request GET 'https://business-api.tiktok.com/open_api/v1.3/identity/get/?advertiser_id={{advertiser_id}}&identity_type=TT_USER' \
--header 'Access-Token: {{Access-Token}}'
(/code)
(code Java java)
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import okhttp3.*;
import org.apache.http.client.utils.URIBuilder;
import java.io.IOException;
import java.net.URI;
import java.net.URISyntaxException;
import java.net.URL;
import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;
public class Demo {
private static final String ACCESS_TOKEN = "xxx";
private static final String PATH = "/open_api/v1.3/identity/get/";
private static final ObjectMapper mapper = new ObjectMapper();
/**
* Build request URL
*
* @param path Request path
* @return Request URL
*/
private static String buildUrl(String path) throws URISyntaxException {
URI uri = new URI("https", "business-api.tiktok.com", path, "", "");
return uri.toString();
}
/**
* Send GET request
*
* @param jsonStr:Args in JSON format
* @return Response in JSON format
*/
private static String get(String jsonStr) throws IOException, URISyntaxException {
OkHttpClient client = new OkHttpClient().newBuilder().build();
URIBuilder ub = new URIBuilder(buildUrl(PATH));
Map< String, Object > map = mapper.readValue(jsonStr, Map.class);
map.forEach((k, v) -> {
try {
ub.addParameter(k, v instanceof String ? (String) v : mapper.writeValueAsString(v));
} catch (JsonProcessingException e) {
e.printStackTrace();
}
});
URL url = ub.build().toURL();
Request request = new Request.Builder()
.url(url)
.method("GET", null)
.addHeader("Access-Token", ACCESS_TOKEN)
.build();
Response response = client.newCall(request).execute();
return response.body().string();
}
public static void main(String[] args) throws IOException, URISyntaxException {
String advertiser_id = ADVERTISER_ID;
String identity_type = IDENTITY_TYPE;
String identity_authorized_bc_id = IDENTITY_AUTHORIZED_BC_ID;
Long page = PAGE;
Long page_size = PAGE_SIZE;
// Args in JSON format
String myArgs = String.format("{\"advertiser_id\": \"%s\", \"identity_type\": \"%s\", \"identity_authorized_bc_id\": \"%s\", \"page\": \"%s\", \"page_size\": \"%s\"}",advertiser_id, identity_type, identity_authorized_bc_id, page, page_size);
System.out.println(get(myArgs));
}
}
(/code)
(code Python python)
# coding=utf-8
import json
import requests
from six import string_types
from six.moves.urllib.parse import urlencode, urlunparse # noqa
ACCESS_TOKEN = "xxx"
PATH = "/open_api/v1.3/identity/get/"
def build_url(path, query=""):
# type: (str, str) -> str
"""
Build request URL
:param path: Request path
:param query: Querystring
:return: Request URL
"""
scheme, netloc = "https", "business-api.tiktok.com"
return urlunparse((scheme, netloc, path, "", query, ""))
def get(json_str):
# type: (str) -> dict
"""
Send GET request
:param json_str: Args in JSON format
:return: Response in JSON format
"""
args = json.loads(json_str)
query_string = urlencode({k: v if isinstance(v, string_types) else json.dumps(v) for k, v in args.items()})
url = build_url(PATH, query_string)
headers = {
"Access-Token": ACCESS_TOKEN,
}
rsp = requests.get(url, headers=headers)
return rsp.json()
if __name__ == '__main__':
advertiser_id = ADVERTISER_ID
identity_type = IDENTITY_TYPE
identity_authorized_bc_id = IDENTITY_AUTHORIZED_BC_ID
page = PAGE
page_size = PAGE_SIZE
# Args in JSON format
my_args = "{\"advertiser_id\": \"%s\", \"identity_type\": \"%s\", \"identity_authorized_bc_id\": \"%s\", \"page\": \"%s\", \"page_size\": \"%s\"}" % (advertiser_id, identity_type, identity_authorized_bc_id, page, page_size)
print(get(my_args))
(/code)
(code PHP php)
$ACCESS_TOKEN = "xxx";
$PATH = "/open_api/v1.3/identity/get/";
/**
* Build request URL
* @param $path : Request path
* @return string
*/
function build_url($path)
{
return "https://business-api.tiktok.com" . $path;
}
/**
* Send GET request
* @param $json_str : Args in JSON format
* @return bool|string : Response in JSON format
*/
function get($json_str)
{
global $ACCESS_TOKEN, $PATH;
$curl = curl_init();
$args = json_decode($json_str, true);
/* Values of querystring is also in JSON format */
foreach ($args as $key => $value) {
$args[$key] = is_string($value) ? $value : json_encode($value);
}
$url = build_url($PATH) . "?" . http_build_query(
$args
);
curl_setopt_array($curl, array(
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => array(
"Access-Token: " . $ACCESS_TOKEN,
),
));
$response = curl_exec($curl);
curl_close($curl);
return $response;
}
$advertiser_id = ADVERTISER_ID;
$identity_type = IDENTITY_TYPE;
$identity_authorized_bc_id = IDENTITY_AUTHORIZED_BC_ID;
$page = PAGE;
$page_size = PAGE_SIZE;
/* Args in JSON format */
$my_args = sprintf("{\"advertiser_id\": \"%s\", \"identity_type\": \"%s\", \"identity_authorized_bc_id\": \"%s\", \"page\": \"%s\", \"page_size\": \"%s\"}", $advertiser_id, $identity_type, $identity_authorized_bc_id, $page, $page_size);
echo get($my_args);
(/code)
返回
|字段|类型|描述|
|---|---|---|
|code |number|返回码，详见[附录-返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。|
|message |string|返回信息，详见[附录-返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。|
|request_id |string|请求的日志 ID，唯一标识一个请求。|
|data|object|返回数据。|
#| identity_list | object[] |认证身份列表。 |
##| identity_id | string | 认证身份 ID。|
##| identity_type | string | 认证身份类型。 |
##| identity_authorized_bc_id | string | 当`identity_type`为`BC_AUTH_TT`时返回。<br><br>与添加到商务中心的TikTok用户这一认证身份绑定的商务中心的 ID。|
##| ads_only_mode | boolean | 该认证身份是否启用“仅在广告中显示”模式。<br><br>支持的值：`true`，`false`。<br>仅当 `identity_type` 为 `BC_AUTH_TT` 时返回非 null 值。<br><br>当此字段为 `true` 时，在（通过 [/smart_plus/ad/create/](1843317390059522.html)、[/ad/create/](1739953377508354.html) 或 [/campaign/spc/create/](1767334204047362.html)）创建广告或（通过 [/smart_plus/ad/update/](1843317411665921.html)、[/ad/update/](1739953405142018.html) 或 [/campaign/spc/update/](1767334250066945.html)）更新广告时，您不能将 `dark_post_status` 设置为 `OFF`，从而防止您的帖子出现在您的 TikTok 主页上并获得自然流量。 |
##| username | string | 认证身份的用户名。 |
##|is_gpppa|boolean|该 TikTok 账号是否为[政府、政治人物和政党账号](https://support.tiktok.com/en/using-tiktok/growing-your-audience/government-politician-and-political-party-accounts)。<br><br>支持的值：`true`，`false`。<br><br>本字段为 `true` 时，对应的 TikTok 账号不可用于[创建 Spark Ads](1739470744631298.html)。|
##| can_push_video | boolean |该 `BC_AUTH_TT` 或 `TT_USER` 认证身份是否可以创建或编辑视频。<br><br>支持的值：`true`， `false`。 |
##| can_pull_video | boolean | 该 `BC_AUTH_TT` 或 `TT_USER` 认证身份是否可以获取 TikTok 账户下的所有视频。<br><br>支持的值：`true`， `false`。 |
##| can_use_live_ads | boolean | 该 `BC_AUTH_TT` 或 `TT_USER` 认证身份是否可以访问 TikTok 账户的直播间。<br><br>支持的值：`true`， `false`。 |
##| can_manage_message | boolean | 该 `BC_AUTH_TT` 或 `TT_USER` 认证身份是否可以管理私信。<br><br>支持的值：`true`， `false`。 |
##| display_name | string |显示名称（昵称）。|
##| available_status | string | 认证身份的可用状态。只对`TT_USER`和`BC_AUTH_TT`类型的身份认证有效。枚举值： `AVAILABLE`, `NO_VALID_BIND_ACCOUNT`, `SCOPE_UNAVAILABLE`,` IS_PRIVATE_ACCOUNT`, `NOT_BUSINESS_ACCOUNT`。|
##| profile_image | string |头像URL。|
#| page_info | object | 分页信息。<br><p><span style="color:darkred"><b>注意</b></span>：为获取正确的分页信息，请求中需传入身份类型（`identity_type`）。|
##| page | number | 当前页码。|
##| total_page | number |总页数。|
##| total_number | number | 总结果数。 |
##| page_size | number | 每页的结果数。|
示例
(code Success-Response http)
HTTPS/1.1 200 OK
{
"code": 0,
"message": "OK",
"request_id": "{{request_id}}",
"data": {
"page_info": {
"total_number": 1,
"page_size": 20,
"total_page": 1,
"page": 1
},
"identity_list": [
{
"ads_only_mode": null,
"profile_image": "{{profile_image}}",
"identity_type": "TT_USER",
"identity_id": "{{identity_id}}",
"can_pull_video": true,
"display_name": "{{display_name}}",
"identity_authorized_bc_id": null,
"can_push_video": true,
"can_use_live_ads": true,
"can_manage_message": true,
"available_status": "AVAILABLE",
"is_gpppa": false,
"username": "{{username}}"
}
]
}
}
(/code)