← 返回目录
📁 API Reference › Leads

创建线索下载任务

您可以使用本接口为您在请求参数中传入的page_id或ad_id产生的所有线索创建下载任务。

异步下载任务创建后，再次调用/page/lead/task/检查任务是否完成（status = SUCCEED）。若任务已完成，调用/page/lead/task/download/下载线索。

不同市场的线索数据是分开保存的。根据您的广告定向的地区，您可能需要使用不同的地址访问线索下载任务的创建接口（/page/lead/task/）和线索下载的接口（/page/lead/task/download/ ）。若想查询您的广告定向的地区（即线索数据保存的地区），可使用/adgroup/get/接口。广告定向的地区将通过location_ids字段，或zipcode_ids字段，或同时通过location_ids 和 zipcode_ids 字段返回。 - 对于欧洲经济区/瑞士/英国市场的线索数据，使用URL https://business-api.tiktok.com/open_api/并指定 Header x-lead-region: eu。

注意
以上新的带有euHeader 的 URL 已从2023年7月13日（UTC+0）开始生效。在7月13日（UTC+0）之后，如果您继续使用旧的URL https://ads.us.tiktok.com/open_api/，您将只收到美国的线索。如果您使用不在 Header 中指定区域的 URL https://business-api.tiktok.com/open_api/，您将只收到其他国家或地区的线索。

  • 对于美国市场的线索数据，选择以下 URL 和 Header 设置方式之一：

    • （推荐）https://business-api.tiktok.com/open_api/ 并指定 Header x-lead-region: us
    • https://ads.us.tiktok.com/open_api/ (计划在未来版本中弃用)

  • 对于其他市场的线索数据，基础 URL 为https://business-api.tiktok.com/open_api/，无需指定 Header x-lead-region。

注意
为了保护客户信息，只有广告账户管理员才有权创建及查询线索下载任务，或进行线索下载。广告账户的角色在商务中心中进行配置。

线索文件下载后会在十分钟后失效。若文件失效，您会收到的file not exist （文件不存在）的报错提示。

v1.2与v1.3版本对比

以下表格概括了 v1.2与v1.3接口的变化。 xtable |变化内容{30%}|v1.2{35%}|v1.3{35%}| |---|---|---| |接口路径|/v1.2/pages/leads/task/|/v1.3/page/lead/task/| |方法|GET|POST| |请求参数类型 |`advertiser_id`: number<br>`library_id `: number<br>`page_id`: number<br>`ad_id `: number|`advertiser_id`: string<br>`library_id `: string<br>`page_id`: string<br>`ad_id `: string|

请求

地址 - 欧洲经济区/瑞士/英国市场线索数据：https://business-api.tiktok.com/open_api/v1.3/page/lead/task/并指定 Header x-lead-region: eu

  • 美国市场线索数据：
  • （推荐）https://business-api.tiktok.com/open_api/v1.3/page/lead/task/ 并指定 Header x-lead-region: us

  • [或] https://ads.us.tiktok.com/open_api/v1.3/page/lead/task/ (计划在未来版本中弃用)

  • 其他地区线索数据：https://business-api.tiktok.com/open_api/v1.3/page/lead/task/

方法 POST

Header

|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌，可以通过[获取访问令牌](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162)接口获取  |

参数

|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|advertiser_id {+条件必填}|string|需传入 `advertiser_id` 和 `library_id` 其中之一。<ul><li>若您尚未使用[/page/library/transfer/](1740029931324417.html)将广告账户的线索迁移至商务中心，需指定 `advertiser_id`。</li><li>若您已使用[/page/library/transfer/](1740029931324417.html)将广告账户的线索迁移至商务中心，需指定 `library_id`。</li></ul><br>广告账户 ID。|
|library_id {+条件必填}|string|需传入 `advertiser_id` 和 `library_id` 其中之一。<ul><li>若您尚未使用[/page/library/transfer/](1740029931324417.html)将广告账户的线索迁移至商务中心，需指定 `advertiser_id`。</li><li>若您已使用[/page/library/transfer/](1740029931324417.html)将广告账户的线索迁移至商务中心，需指定 `library_id`。</li></ul><br>表单库 ID。<br><br>若想获取您有权访问的表单库 ID 列表，可使用[/page/library/get/](1740029915327489.html)。|
|ad_id {+条件必填}|string| 需传入 `ad_id` 和 `page_id` 其中之一。<ul><li>若指定 `ad_id`，将为某个广告创建线索下载任务。</li><li>若指定 `page_id`，将为某个即时表单（线索表单）创建线索下载任务。</li></ul><br>广告 ID。<br>您需指定使用即时表单收集线索的广告。若想了解如何创建此类广告，可查看[创建优化位置为即时表单的线索广告](1774482920012801.html)。<br><br>若想获取广告账户中的广告 ID 列表，可使用 [/ad/get/](1735735588640770.html)。|
|page_id {+条件必填}|string| 需传入 `ad_id` 和 `page_id` 其中之一。<ul><li>若指定 `ad_id`，将为某个广告创建线索下载任务。</li><li>若指定 `page_id`，将为某个即时表单（线索表单）创建线索下载任务。</li></ul><br>即时表单 ID。<br><br>若想获取广告账户中的即时表单 ID 列表，可使用 [/page/get/](1820826387779586.html) 并将 `business_type` 设置为 `LEAD_GEN`。 |
|task_id |string| 任务 ID。<ul><li>若不传入该字段，该请求将创建一个线索下载任务。您会在返回中得到`task_id`。</li><li>若传入该字段，该请求会进行轮询操作，检查任务是否完成 (`status` 为 `SUCCEED`) 。</li></ul> |

示例

为表单库中的单个即时表单创建线索下载任务（欧洲经济区/瑞士/英国市场）

(code curl http)
curl --location  --request POST 'https://business-api.tiktok.com/open_api/v1.3/page/lead/task/' \
--header 'Access-Token: {{Access-Token}}' \
--header 'x-lead-region: eu' \
--data '{
    "library_id":"{{library_id}}",
    "page_id":"{{page_id}}"
}'
(/code)

为单个广告创建线索下载任务（美国市场）

(code curl http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/page/lead/task/' \
--header 'Access-Token: {{Access-Token}}' \
--header 'x-lead-region: us' \
--data '{
    "advertiser_id":"{{advertiser_id}}",
    "ad_id":"{{ad_id}}"
}'
(/code)

为广告账户中的单个即时表单创建线索下载任务（其他地区）

(code curl http)
curl --location  --request POST 'https://business-api.tiktok.com/open_api/v1.3/page/lead/task/' \
--header 'Access-Token: {{Access-Token}}' \
--data '{
    "advertiser_id":"{{advertiser_id}}",
    "page_id":"{{page_id}}"
}'
(/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/page/lead/task/";
    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", "ads.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 {
        Long advertiser_id = ADVERTISER_ID;
        Long page_id = PAGE_ID;

        // Args in JSON format
        String myArgs = String.format("{\"advertiser_id\": \"%s\", \"page_id\": \"%s\"}",advertiser_id, page_id);
        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/page/lead/task/"


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", "ads.tiktok.com"
    return urlunparse((scheme, netloc, path, "", query, ""))

def post(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.post(url, headers=headers)
    return rsp.json()

if __name__ == '__main__':
    advertiser_id = ADVERTISER_ID
    page_id = PAGE_ID

    # Args in JSON format
    my_args = "{\"advertiser_id\": \"%s\", \"page_id\": \"%s\"}" % (advertiser_id, page_id)
    print(get(my_args))

(/code)

(code PHP php)

$ACCESS_TOKEN = "xxx";
$PATH = "/open_api/v1.3/page/lead/task/";

/**
 * Build request URL
 * @param $path : Request path
 * @return string
 */
function build_url($path)
{
    return "https://ads.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;
$page_id = PAGE_ID;

/* Args in JSON format */
$my_args = sprintf("{\"advertiser_id\": \"%s\", \"page_id\": \"%s\"}", $advertiser_id, $page_id);
echo get($my_args);
(/code)

查询表单库中的单个即时表单的线索下载任务状态（欧洲经济区/瑞士/英国市场）

(code curl http)
curl --location  --request POST 'https://business-api.tiktok.com/open_api/v1.3/page/lead/task/' \
--header 'Access-Token: {{Access-Token}}' \
--header 'x-lead-region: eu' \
--data '{
    "library_id":"{{library_id}}",
    "page_id":"{{page_id}}",
    "task_id": "{{task_id}}"
}'
(/code)

返回

|字段{30%}|类型{15%}|描述{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|返回数据。  |
#|status |string| 任务状态。<br><br>枚举值: `CREATED`,`FAILED`,`RUNNING`,`SUCCEED`。 |
#|task_id |string| 任务 ID。<br>您可以在请求中传入`task_id`进行轮询操作，检查任务是否完成 (`status` = `SUCCEED`) 。  |
#|file_name|string| 仅当 `status` 为 `SUCCEED` 时返回。<br><br>线索文件的文件名。 |
#|file_type|string| 仅当 `status` 为 `SUCCEED` 时返回。<br><br>线索文件的文件类型。<br><br>枚举值： `csv`, `zip` 。|
|request_id |string|请求的日志 ID，唯一标识一个请求  |

示例

处理中的任务

(code Success-Response http)
HTTPS/1.1 200 OK
{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": {
        "status": "RUNNING",
        "task_id": "{{task_id}}"
    }
}
(/code);

已成功的任务（请求中需传入task_id）

(code Success-Response http)
HTTPS/1.1 200 OK
{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": {
        "file_name": "lead_generation_0_2024-01-01.csv",
        "task_id": "{{task_id}}"
        "file_type": "csv",
        "status": "SUCCEED"
    }
}
(/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 每日平台更新简报 →