获取线索列表

开发环境

POST

/v1.3/lead_clues/get

使用说明

获取线索管理平台（http://leads.qq.com）线索列表，线索来源于蹊径落地页、微信原生推广页、微信原生推广页小程序版、附加创意等。说明：为保证接口使用的安全性避免调取他人的线索信息，该接口只可用于查询自己广告主下的线索信息。

服务的沙箱环境正在建设中，近期即将上线。

接口暂时不支持 BM 角色调用。

POST 请求，Content-Type: application/json。

返回数据的排序规则与请求参数 time_type 相关，当传入 TIME_TYPE_ACTION_TIME 会按照 leads_action_time+leads_id 降序排列，当传入 TIME_TYPE_CREATED_TIME 会按照 leads_create_time+leads_id 降序排列。

如需根据推广计划创建的时间或者推广计划 id 或者广告位类型进行过滤，可以通过使用 filtering 结构进行调用。

当查询数据在 5000 之前，不需传递参数 last_search_after_values，只需传递 page 和 page_size 参数。

当查询数据在 5000 之后，只能顺序翻页查询深层数据，必须传递参数 last_search_after_values，不需传递参数 page，可选传递 page_size。last_search_after_values 的类型是字符串数组，长度固定为 2，必须按照顺序填入前一次翻页最后一条数据的 leads_action_time/leads_create_time（毫秒）和 leads_id，用于深度翻页。

部分销售线索可能因为用户异常提交无法识别来源的广告，campaign_id、adgroup_id 信息可能为空。

请求示例

Shell

JavaScript

Java

Swift

curl --location --request POST '/v1.3/lead_clues/get' \
--header 'access_token;' \
--header 'timestamp;' \
--header 'nonce;' \
--header 'Content-Type: application/json' \
--data-raw '{
    "account_id": 123456,
    "time_range": {
        "start_time": 1571367150,
        "end_time": 1571367160,
        "time_type": "TIME_TYPE_ACTION_TIME"
    },
    "filtering": [
        {
            "field": "campaign_id",
            "operator": "EQUALS",
            "values": [
                "11111111"
            ]
        }
    ],
    "page": 51,
    "page_size": 100,
    "last_search_after_values": [
        "1571367160000",
        "111111"
    ]
}'

响应示例

{
    "code": 0,
    "message": "",
    "message_cn": "",
    "data": {
        "leads_info": [
            {
                "account_id": 123456,
                "leads_id": 79865,
                "outer_leads_id": "outerLeadsId_20210120_001",
                "click_id": "xvssdrewrrer3",
                "agency_id": "",
                "agency_name": "",
                "wechat_appid": "",
                "campaign_id": "11111111",
                "campaign_name": "测试推广计划名称",
                "adgroup_id": "123",
                "adgroup_name": "测试广告名称",
                "creative_id": "123",
                "creative_name": "测试创意名称",
                "component_id": "id",
                "component_name": "name",
                "page_id": "25891541",
                "page_name": "落地页名称",
                "page_url": "www.123",
                "leads_type": "LEADS_TYPE_FORM",
                "leads_source": "XJ",
                "leads_potential_score": "80",
                "leads_follow_tag": "LEADS_FOLLOW_TAG_DEFAULT",
                "outer_leads_convert_type": "LEADS_CONVERT_STATUS_DEPRECATED",
                "outer_leads_ineffect_reason": "LEADS_INEFFECT_REASION_NO_INTENTION",
                "leads_user_id": "123456",
                "leads_user_type": "USER_TYPE_QQ",
                "leads_name": "姓名",
                "leads_telephone": "25895117",
                "telephone_location": "北京",
                "leads_area": "深圳市南山区",
                "leads_email": "34354345@qq.com",
                "leads_qq": "0",
                "leads_wechat": "cvxsfs",
                "leads_gender": "GENDER_TYPE_UNKNOWN",
                "nationality": "中国",
                "working_years": "1 年",
                "age": "21 岁",
                "profession": "律师",
                "id_number": "210111199912110901",
                "address": "广东省深圳市南山区南山街道 1 号",
                "bundle": "{\"国籍\":\"test\"}",
                "pos_type": 0,
                "leads_create_time": "2019-10-18 10:52:39",
                "leads_action_time": "2019-10-18 10:52:39",
                "leads_tags": "重复 2 条;分享注册",
                "shop_name": "门店名称",
                "shop_address": "门店地址",
                "owner_name": "当前归属人",
                "owner_id": 557,
                "all_follow_records": "线索手动回收(原归属人:张三);线索自动回收(原归属人:李四)",
                "claim_account_id": 123456
            }
        ],
        "page_info": {
            "page": 51,
            "page_size": 100,
            "total_number": 5001,
            "total_page": 51
        }
    }
}

请求参数

Header 参数

Content-Type

string

必需

示例值:

application/json

access_token

string

必需

以Query Parameter方式在请求路径中传递。授权令牌，完成 OAuth 2.0 授权后获得，参考授权认证章节。

默认值:

<ACCESS_TOKEN>

timestamp

string

必需

以Query Parameter方式在请求路径中传递。当前的时间戳，单位为秒，允许客户端请求最大时间误差为300秒。
MarketingAPI 所使用的时间戳，若无特殊说明，均为秒级时间戳
MarketingAPI 所使用的时区为GMT+8，例如当时间戳为1494840119时，表示 2018-05-15 17:21:59

默认值:

nonce

string

必需

以Query Parameter方式在请求路径中传递。随机字串标识，不超过32个字符，由调用方自行生成，需保证全局唯一性。

默认值:

<NONCE>

Body 参数application/json

account_id

integer

必需

广告主账号 id，直客账号或子客账号

time_range

object

必需

时间范围，最长跨度 1 年。 time_type=TIME_TYPE_ACTION_TIME 时填写线索提交时间，time_type=TIME_TYPE_CREATED_TIME 时填写线索入库时间

start_time

integer

必需

开始时间戳，精确到秒，小于 end_time 最小值 0，最大值 9999999999

end_time

integer

必需

结束时间戳，精确到秒，大于 start_time 最小值 0，最大值 9999999999

time_type

string

必需

时间类型，不填默认为 TIME_TYPE_ACTION_TIME，此参数会影响到 time_range、last_search_after_values、返回数据的排序规则，[枚举详情] 枚举列表：{ TIME_TYPE_ACTION_TIME, TIME_TYPE_CREATED_TIME }

filtering

array [object {3}]

必需

过滤条件，若此字段不传，或传空则视为无限制条件，详见 [过滤条件] 数组最小长度 0，最大长度 100

field

string

必需

过滤字段可选值：{ campaign_id, campaign_created_time, position_type, leads_convert_type }

operator

string

必需

操作符当 field 取值 campaign_id 时，枚举列表：{ EQUALS, IN } 当 field 取值 campaign_created_time 时，枚举列表：{ GREATER_EQUALS } 当 field 取值 position_type 时，枚举列表：{ EQUALS } 当 field 取值 leads_convert_type 时，枚举列表：{ EQUALS }

values

array[string]

必需

字段取值 values 数组的个数限制与 operator 的取值相关，详见 [过滤条件] 当 field 取值 position_type 时，枚举列表：{ MINI_PROGRAM, ARTICLE, CIRCLE_OF_FRIENDS } 当 field 取值 leads_convert_type 时，枚举列表：{ LEADS_CONVERT_STATUS_DEPRECATED, LEADS_CONVERT_STATUS_POTENTIAL_CUSTOMER, LEADS_CONVERT_STATUS_HIGH_INTENTION_CUSTOMER, LEADS_CONVERT_STATUS_TRANS_COMPLETED }

page

integer

可选

搜索页码，默认值：1 最小值 1，最大值 1000

page_size

integer

可选

一页显示的数据条数，默认值：50 最小值 1，最大值 200

last_search_after_values

array[string]

必需

线索深度翻页参数 time_type=TIME_TYPE_ACTION_TIME 时填写线索提交时间和线索 id time_type=TIME_TYPE_CREATED_TIME 时填写线索入库时间和线索 id

示例

返回响应

🟢200成功

application/json

Body

code

integer

必需

message

string

必需

message_cn

string

必需

data

object

必需

leads_info

array [object {51}]

返回信息列表

必需

page_info

object

分页配置信息

必需

修改于 2023-11-07 09:12:31

更新订单

回传线索状态