下载线索

您可以使用本接口下载线索。您需要先通过/page/lead/task/ 接口创建下载任务并确保任务已完成（status = SUCCEED） 。

• 若接口调用成功，数据为UTC+0时间数据，且为 CSV (原始 CSV 文件 <= 10MB) 或 zip (原始 CSV 文件 > 10MB) 格式，而非 JSON 格式。
• 若接口产生错误，根据错误类型可能返回 JSON 格式或在返回的 CSV 文件中输出错误信息。

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

若线索已经迁移到商务中心下，只有商务中心的管理员可下载线索。

v1.2与v1.3版本对比

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

请求

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

xcodeblock (code curl http) curl --location 'https://business-api.tiktok.com/open_api/v1.3/page/lead/task/download/?advertiser_id={{advertiser_id}}&task_id={{task_id}}' \ --header 'Access-Token: ACCESS_TOKEN' \ --header 'x-lead-region: eu' (/code)

注意
以上新的带有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/，您将只收到其他国家/地区的线索。

• 美国市场线索数据：
• https://ads.us.tiktok.com/open_api/v1.3/page/lead/task/download/ (计划在未来版本中弃用)

• [或] https://business-api.tiktok.com/open_api/v1.3/page/lead/task/download/ 和Header x-lead-region: us

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

Header

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

参数

|字段|类型|描述|
|---|---|---|
|advertiser_id {+条件必填}|string|如果相应的表单和线索在广告账号下（即未迁移到商务中心），你必须传入广告账号ID。 |
|library_id {+条件必填}|string|如果相应的表单和线索已经迁移到商务中心下，你必须传入相应的表单库ID。|
|task_id {必填}|string| 任务 ID。 |

示例

(code curl http)
curl --get -H "Access-Token:xxx" \
--data-urlencode "advertiser_id=ADVERTISER_ID" \
--data-urlencode "task_id=TASK_ID" \
https://ads.tiktok.com/open_api/v1.3/page/lead/task/download/
(/code)

返回

• 若接口正常返回，数据为 CSV (原始 CSV 文件 <= 10MB) 或 zip (原始 CSV 文件 > 10MB) 格式，而非 JSON 格式。
• 若接口产生错误，根据错误类型可能返回 JSON 格式或在返回的 CSV 文件中输出错误信息。

示例

成功

(code Success-Response CSV)
HTTPS/1.1 200 OK
lead id,created_time,ad_id,ad_name,adgroup_id,adgroup_name,campaign_id,campaign_name,form_id,form_name,Name,First name,Surname,Gender,Birthday,Phone number,Email,Country,Province/State,City,Address,Please select the service you are interested in?)
6864523782069944581,2020-06-24 12:18:11(UTC+00:00),1674635134905355,,0,,0,,6856667798307864597,test,test,joe,smith,male,1998.02.22,17681120000,test@foo.bar,china,shanghai,shanghai,somewhere,my name is test
6864523781998641414,2020-06-24 12:18:11(UTC+00:00),1674635134905355,,0,,0,,6856667798307864597,test,test,joe,smith,male,1998.02.22,17681120000,test@foo.bar,china,shanghai,shanghai,somewhere,my name is test
(/code)

失败

(code Fail-Response JSON)
{
    "message": "failed to download.",
    "code": 40000,
    "data": {}
}
(/code)