获取即时表单线索或私信线索

您可以使用本接口获取即时表单线索或私信线索。

请求

地址 https://business-api.tiktok.com/open_api/v1.3/lead/get/

方法 GET

Header

|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。<br>可以通过[获取访问令牌](1738373164380162.html)接口获取。|

参数

|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
| lead_source  {必填}| string | 线索来源。<br><br>枚举值：<ul><li>`INSTANT_FORM`：通过即时表单生成的线索。</li><li>`DIRECT_MESSAGE`：通过绑定的企业号的私信生成的线索。</li></ul> |
| advertiser_id  {+条件必填} | string | 线索在广告账户中时，本字段必填。<br><br>广告账号 ID。 |
| library_id  {+条件必填} | string | 线索在商务中心中的表单库中时，本字段必填。<br><br>表单库 ID。<br><br>若想获取某一商务中心中的表单库列表，可使用[/page/library/get/](1740029915327489.html)。 |
| page_id  {+条件必填} | string | <ul><li>`lead_source` 为 `INSTANT_FORM` 时必填。</li><li>`lead_source` 为 `DIRECT_MESSAGE` 时不支持本字段。</li></ul><br>即时表单的页面 ID。<br><br>若想获取即时表单列表，可使用[/page/get/](1820826387779586.html)并将 `business_type` 设置为 `LEAD_GEN`。 |

示例

获取即时表单线索

(code curl http)
curl --location  --request GET 'https://business-api.tiktok.com/open_api/v1.3/lead/get/?lead_source=INSTANT_FORM&advertiser_id={{advertiser_id}}&page_id={{page_id}}' \
--header 'Access-token: {{Access-token}}'
(/code)

获取私信线索

(code curl http)
curl --location  --request GET 'https://business-api.tiktok.com/open_api/v1.3/lead/get/?lead_source=DIRECT_MESSAGE&advertiser_id={{advertiser_id}}' \
--header 'Access-token: {{Access-token}}'
(/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)。 |
|request_id |string| 请求的日志 ID，唯一标识一个请求。 |
|data |object| 返回数据。 |
#| lead_data | object | 线索信息。<br><br><p><span style="color:darkred"><b>注意</b></span>：本对象中的数据取决于即时表单中设置的问题或私信线索收集的问题。 |
#| meta_data | object | 线索的元信息。 |
##| lead_source | string | 线索来源。<br><br>枚举值：<ul><li>`INSTANT_FORM`：通过即时表单生成的线索。</li><li>`DIRECT_MESSAGE`：通过绑定的企业号的私信生成的线索。</li></ul> |
##| lead_id | string | 线索 ID。 |
##| page_id | string | 仅当 `lead_source` 为 `INSTANT_FORM` 时返回本字段。<br><br>即时表单的页面 ID。 |
##| campaign_id | string | 推广系列 ID。 |
##| campaign_name | string | 推广系列名称。 |
##| adgroup_id | string | 广告组 ID。 |
##| adgroup_name | string | 广告组名称。 |
##| ad_id | string | 广告 ID。 |
##| ad_name | string | 广告名称。 |
##| create_time | string | 线索的创建时间，格式为 `YYYY-MM-DD HH:MM:SS` （UTC+0 时间）。<br><br>示例：`2025-01-01 00:00:01`。 |

示例

获取即时表单线索

(code Success-Response http)
HTTPS/1.1 200 OK
{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": {
        "lead_data": {
            "email": "{{email}}"
        },
        "meta_data": {
            "ad_id": "{{ad_id}}",
            "ad_name": "{{ad_name}}",
            "adgroup_id": "{{adgroup_id}}",
            "adgroup_name": "{{adgroup_name}}",
            "campaign_id": "{{campaign_id}}",
            "campaign_name": "{{campaign_name}}",
            "create_time": "{{create_time}}",
            "lead_id": "{{lead_id}}",
            "lead_source": "INSTANT_FORM",
            "page_id": "{{page_id}}"
        }
    }
}
(/code)

获取私信线索

(code Success-Response http)
HTTPS/1.1 200 OK
{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": {
        "lead_data": {
            "email": "{{email}}",
            "name": "{{name}}",
            "phone_number": "{{phone_number}}",
            "tiktok": "{{tiktok}}"
        },
        "meta_data": {
            "ad_id": "{{ad_id}}",
            "ad_name": "{{ad_name}}",
            "adgroup_id": "{{adgroup_id}}",
            "adgroup_name": "{{adgroup_name}}",
            "campaign_id": "{{campaign_id}}",
            "campaign_name": "{{campaign_name}}",
            "create_time": "{{create_time}}",
            "lead_id": "{{lead_id}}",
            "lead_source": "DIRECT_MESSAGE",
            "page_id": "{{page_id}}"
        }
    }
}
(/code)