获取广告账号信息
您可以使用本接口获取一个广告账户的详细信息。
若您希望添加合作伙伴并向合作伙伴分配广告账号，请使用/bc/partner/add/接口。将asset_type 设置为 ADVERTISER，并在asset_ids 字段传入广告账号ID。您可以通过/advertiser/info/的返回字段advertiser_id获取广告账号ID。
v1.2与v1.3版本对比
以下表格概括了 v1.2与v1.3接口的变化。
``xtable
|变化内容{30%}|v1.2{35%}|v1.3{35%}|
|---|---|---|
|接口路径| /v1.2/advertiser/info/|/v1.3/advertiser/info/ |
|请求参数类型|advertiser_ids: number[] |advertiser_ids: string[] |
|请求参数可选值名称|telephone<br>phonenumber<br>reason<br>id<br> (皆位于fields字段下) |telephone_number<br>cellphone_number<br>rejection_reason<br>advertiser_id<br>(皆位于fields字段下) |
|返回参数名称|reason<br>phonenumber<br>telephone<br>(皆位于data字段下)|rejection_reason<br>cellphone_number<br>telephone_number<br>(皆位于list字段下)</li></ul>|
|返回参数类型|data: object[] |data: object |
|返回参数名称和类型|id: number|advertiser_id: string|
|新增返回参数|/|list: object[] (位于data字段下)<br>advertiser_account_type<br>company_name_editable<br>can_use_custom_identity<br>ads_only_mode`|
## 请求
**地址** https://business-api.tiktok.com/open_api/v1.3/advertiser/info/
**方法** GET
**Header**
```xtable
|字段{35%}|类型{10%}|描述{55%}|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。可以通过[获取访问令牌](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162)接口获取。|
参数
|字段{35%}|类型{10%}|描述{55%}|
|---|---|---|
|advertiser_ids {必填}|string[]|需要查看详细信息的广告主 ID 列表。<br><br>可从[获取广告主账号列表](https://ads.tiktok.com/marketing_api/docs?id=1738455508553729)接口获取 ID。|
|fields |string[]|需要获取的字段。<br><br>如果您没有传入该字段，系统将默认返回除`company_name_editable`、`can_use_custom_identity`和 `ads_only_mode` 外的所有数据。 <br><br>可选值：<br> `telephone_number`, `contacter`, `currency`, `cellphone_number`, `timezone`, `advertiser_id`, `role`, `company`, `status`, `description`, `rejection_reason`, `address`, `name`, `language`, `industry`, `license_no`, `email`, `license_url`, `country`, `balance`, `create_time`, `display_timezone`, `owner_bc_id`, `company_name_editable`，`can_use_custom_identity`，`ads_only_mode`。 <br><br>含义详见返回参数。<br><br><p><span style="color:darkred"><b>注意</b></span>：若您在本字段的值中包含了`company_name_editable`、`can_use_custom_identity`或 `ads_only_mode`，则仅返回`company_name_editable`、`can_use_custom_identity` 或 `ads_only_mode` 和 `advertiser_id` ，同时忽略通过本字段指定的其他值。|
示例
(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.Map;
public class Demo {
private static final String ACCESS_TOKEN = "xxx";
private static final String PATH = "/open_api/v1.3/advertiser/info/";
/**
* 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));
ObjectMapper mapper = new ObjectMapper();
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 fields = FIELDS;
String advertiser_ids = ADVERTISER_IDS;
// Args in JSON format
String myArgs = String.format("{\"fields\": [\"%s\"], \"advertiser_ids\": [\"%s\"]}",fields, advertiser_ids);
System.out.println(get(myArgs));
}
}
(/code)
(code Python python)
# coding=utf-8
import json
from six import string_types
from six.moves.urllib.parse import urlencode, urlunparse # noqa
import requests
ACCESS_TOKEN = "xxx"
PATH = "/open_api/v1.3/advertiser/info/"
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__':
fields = FIELDS
advertiser_ids = ADVERTISER_IDS
# Args in JSON format
my_args = "{\"fields\": [\"%s\"], \"advertiser_ids\": [\"%s\"]}" % (fields, advertiser_ids)
print(get(my_args))
(/code)
(code PHP php)
$ACCESS_TOKEN = "xxx";
$PATH = "/open_api/v1.3/advertiser/info/";
/**
* 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;
}
$fields = FIELDS;
$advertiser_ids = ADVERTISER_IDS;
/* Args in JSON format */
$my_args = sprintf("{\"fields\": [\"%s\"], \"advertiser_ids\": [\"%s\"]}", $fields, $advertiser_ids);
echo get($my_args);
(/code)
(code curl http)
curl --location --request GET 'https://business-api.tiktok.com/open_api/v1.3/advertiser/info/?advertiser_ids={{advertiser_ids}}' \
--header 'Access-Token: {{Access-Token}}' \
(/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)。|
|request_id |string|请求的日志 ID，唯一标识一个请求。|
|data|object|返回数据。|
#|list|object[]|广告账号（广告主账号）信息列表。|
##|advertiser_id|string|广告账号 ID。|
##|can_use_custom_identity |boolean|广告账号是否有可用于创建广告的自定义身份。<br><br>支持的值：<ul><li>`true`：广告账号可使用自定义身份创建广告。</li><li>`false`：广告账号不可使用自定义身份创建广告。<ul><li>不过，在某些场景下，您仍可使用自定义身份。若想了解不受影响的场景，可查看[关于即将变更的“自定义身份”功能](https://ads.tiktok.com/help/article/about-changes-coming-to-custom-identity)。</li></ul>|
##| ads_only_mode | boolean | 广告账号是否必须为使用 Spark Ads 推送创建的 Spark Ads 启用“仅在广告中显示”。<br><br>支持的值：`true`，`false`。<br><br>当此字段为 `true` 时，广告账号的强制开启“仅在广告中显示”模式将被激活。因此，在使用 Spark Ads 推送（通过 [/smart_plus/ad/create/](1843317390059522.html)、[/ad/create/](1739953377508354.html) 或 [/campaign/spc/create/](1767334204047362.html)）创建 Spark Ads 或（通过 [/smart_plus/ad/update/](1843317411665921.html)、[/ad/update/](1739953405142018.html) 或 [/campaign/spc/update/](1767334250066945.html)）更新广告时，您只能将 `dark_post_status` 设置为 `ON`。从而防止您的帖子出现在您的 TikTok 主页上并获得自然流量，无论广告发布身份自身的 `ads_only_mode` 设置如何。这是一个保障措施，可确保您的 Spark Ads 推送内容保持仅广告可见，并避免意外发布帖子到个人主页。 |
##|owner_bc_id|string|广告账户所属的商务中心的 ID。<br><br><p><span style="color:darkred"><b>注意</b></span>：仅当以下条件均满足时返回本字段：<ul><li>对于拥有该广告账户的商务中心，用户有管理员权限，</li><li>用户有对该广告账户的管理员（Admin）/操作员（Operator）/ 分析师（Analyst））权限，且该权限从拥有该广告账户的商务中心，而非合作伙伴商务中心处获得。</li></ul> |
##|status |string|广告账号状态。<br><br>枚举值详见[枚举值-广告主状态](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。<br><br>示例：`STATUS_ENABLE`。|
##|role |string|广告账号角色。<br><br>枚举值详见[枚举值-广告主角色](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。<br><br>示例：`ROLE_ADVERTISER`。|
##|rejection_reason |string|审核拒绝原因。|
##|name |string|广告账号名称。|
##|timezone |string|广告账号与 GMT 偏移的时区信息，或广告账号所在时区在[时区数据库](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)中的名字，格式为“地域/城市”。<br><br>示例：`Etc/GMT`，`Europe/London`。|
##|display_timezone|string|广告账号所在时区在[时区数据库](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)中的名字。<br><br>示例：`Europe/London`。|
##|company |string|广告账号公司名。|
##|company_name_editable| boolean | 该广告账号的公司名称是否支持通过 API 修改。<br><ul><li>若本字段值为 `true`，则支持通过[/advertiser/update/](1739939050770434.html)中的 `company` 字段修改公司名称。</li><li>对于非自助广告主（即由 TikTok 代表或直客销售直接管理的广告主），本字段值将为 `false`。此时若想修改公司名称，需联系 TikTok 代表。</li></ul> |
##|industry |string|广告账号行业类别代码。<br><br>枚举值详见[行业信息](https://ads.tiktok.com/marketing_api/docs?id=1739357589575681)。<br><br>示例：`290303`。|
##|address |string|广告账号地址信息。|
##|country |string|广告账号注册地代码。<br><br>示例：`290303`。|
##|advertiser_account_type |string|广告账户类型。<br><br>枚举值：`RESERVATION` （合约广告账户），`AUCTION`（竞价广告账户）。|
##|currency |string|广告账号使用的货币类型，格式为 [ISO 4217 代码](https://en.wikipedia.org/wiki/ISO_4217)。<br><br>示例：`EUR`。|
##|contacter |string|联系人姓名。详细信息已脱敏。<br><br>示例：`Te********************nt`。|
##|email |string|广告账号联系人邮箱。详细信息已脱敏。<br><br>示例：`l***********@*************`。|
##|cellphone_number|string|联系手机号码。详细信息已脱敏。|
##|telephone_number|string|固定电话号码。详细信息已脱敏。|
##|language |string|广告账号所使用的语言的代码。<br><br>示例：`en`。|
##|license_no |string|营业执照编号。|
##|license_url |string|营业执照预览 URL。<br><br>链接默认 1 小时内有效。|
##| license_province {-即将废弃} | string | 营业执照的颁发省份。 |
##| license_city {-即将废弃} | string | 营业执照的颁发城市。 |
##| promotion_area {-即将废弃} | string |广告账户主要推广地域。 |
##| promotion_center_province {-即将废弃} |string | 广告账户主要推广省份。 |
##| promotion_center_city {-即将废弃} |string | 广告账户主要推广城市。 |
##| brand {-即将废弃} | string | 品牌名称。 |
##|description |string|品牌描述。|
##|balance |float|广告账户总余额。<br><br>单位与广告账户货币类型（`currency`）相关。<br><br>示例：5325.43。<br><br><p><span style="color:darkred"><b>注意</b></span>：该字段不提供余额明细。如需获取详细的余额明细与具体金额（如现金余额、赠款余额、可用余额以及冻结余额），需调用 [/advertiser/balance/get/](https://business-api.tiktok.com/portal/docs/get-the-balance-and-budget-of-ad-accounts/v1.3) 接口，并查看返回的 `balance_info` 字段。|
##|create_time |datetime|广告账号创建时间，格式为 Epoch/Unix 时间戳，单位为秒。<br><br>示例：`1510740064`。|
示例
(code Success-Response http)
{
"code": 0,
"message": "OK",
"request_id": "{{request_id}}",
"data": {
"list": [
{
"company": "{{company}}",
"address": null,
"status": "STATUS_ENABLE",
"contacter": null,
"license_province": null,
"license_city": null,
"currency": "USD",
"promotion_area": "0",
"promotion_center_city": null,
"cellphone_number": null,
"timezone": "Etc/GMT+8",
"description": "{{description}}",
"rejection_reason": "",
"advertiser_id": "{{advertiser_id}}",
"license_no": "{{license_no}}",
"promotion_center_province": null,
"name": "{{name}}",
"industry": "{{industry}}",
"telephone_number": null,
"license_url": "{{license_url}}",
"role": "ROLE_CHILD_ADVERTISER",
"advertiser_account_type": "AUCTION",
"create_time": {{create_time}},
"owner_bc_id": "{{owner_bc_id}}",
"language": "zh",
"email": null,
"country": "CN",
"balance": 0.0,
"brand": null,
"display_timezone": "America/Los_Angeles"
}
]
}
}
(/code);