获取线索列表

所属权限 ads_management,ads_insights,account_management,audience_management,user_actions
请求地址 leads_list/get
请求方法 GET

全局参数

全局参数是指每一个接口都需要使用到的参数。详情参考,代码案例参考

参数名称 参数类型
access_token 授权令牌,完成 OAuth 2.0 授权后获得,参考授权认证章节
timestamp

当前的时间戳,单位为秒,允许客户端请求最大时间误差为 300 秒。

MarketingAPI 所使用的时间戳,若无特殊说明,均为秒级时间戳

MarketingAPI 所使用的时区为 GMT+8,例如当时间戳为 1494840119 时,表示 2017-05-15 17:21:59

nonce 随机字串标识,不超过 32 个字符,由调用方自行生成,需保证全局唯一性

请求参数

标有*的参数为必填项

名称 类型 描述
account_id*
integer 广告主账号 id,直客账号或子客账号
time_range*
struct 时间范围,最长跨度 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*
enum 时间类型,必填,此参数会影响到 time_range、last_search_after_values、返回数据的排序规则。返回数据的排序规则与请求参数 time_type 相关,当传入 TIME_TYPE_ACTION_TIME 会按照 leads_action_time+leads_id 降序排列,当传入 TIME_TYPE_CREATED_TIME 会按照 leads_create_time+leads_id 降序排列,[枚举详情]
可选值:{ TIME_TYPE_CREATED_TIME, TIME_TYPE_ACTION_TIME }
page
integer 搜索页码
最小值 1,最大值 1000
默认值:1
page_size
integer 一页显示的数据条数
最小值 1,最大值 200
默认值:10
last_search_after_values
string[] 线索深度翻页参数,例如['1571367160000', '111111']
time_type=TIME_TYPE_ACTION_TIME 时填写线索提交时间和线索 id
time_type=TIME_TYPE_CREATED_TIME 时填写线索入库时间和线索 id。当查询数据在 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,用于深度翻页。

使用说明

  1. 获取线索管理平台(http://leads.qq.com)线索列表,线索来源于蹊径落地页、微信原生推广页、微信原生推广页小程序版、附加创意等。说明:为保证接口使用的安全性避免调取他人的线索信息,该接口只可用于查询自己广告主下的线索信息。
  2. 接口暂时不支持 BM 角色调用。
  3. GET 请求,Content-Type: application/json。
  4. 返回数据的排序规则与请求参数 time_type 相关,当传入 TIME_TYPE_ACTION_TIME 会按照 leads_action_time+leads_id 降序排列,当传入 TIME_TYPE_CREATED_TIME 会按照 leads_create_time+leads_id 降序排列。
  5. 当查询数据在 5000 之前,不需传递参数 last_search_after_values,只需传递 page 和 page_size 参数。
  6. 当查询数据在 5000 之后,只能顺序翻页查询深层数据,必须传递参数 last_search_after_values,不需传递参数 page,可选传递 page_size。last_search_after_values 的类型是字符串数组,长度固定为 2,必须按照顺序填入前一次翻页最后一条数据的 leads_action_time/leads_create_time(毫秒)和 leads_id,用于深度翻页。
  7. 部分销售线索可能因为用户异常提交无法识别来源的广告,campaign_id、adgroup_id 信息可能为空。

请求示例


curl -v -G 'https://api.e.qq.com/v3.0/leads_list/get?access_token=<ACCESS_TOKEN>&timestamp=<TIMESTAMP>&nonce=<NONCE>' \
-d 'account_id=<ACCOUNT_ID>' \
-d 'time_range=[]' \
-d 'page=1' \
-d 'page_size=10' \
-d 'last_search_after_values=[]' 
					

应答字段

名称 类型 描述
leads_info
struct 返回结构
account_id
integer 广告主账号 id,直客账号或子客账号
leads_id
integer 线索 id
outer_leads_id
string 外部线索 id
click_id
string 点击 id
adgroup_id
int64 广告 id
adgroup_name
string 广告名称
dynamic_creative_id
integer 动态创意 id
dynamic_creative_name
string 动态创意名称
component_id
string 组件 id
component_name
string 组件名称
page_id
int64 落地页 id
page_name
string 落地页名称
page_url
string 落地页地址
leads_type
enum 线索类型,[枚举详情]
leads_sub_type
enum 二级线索类型,[枚举详情]
chat_id
string 会话 id
leads_source
enum 线索来源,[枚举详情]
leads_follow_tag
enum 线索状态
标准状态取值如下
LEADS_FOLLOW_TAG_DEFAULT : 未分配
LEADS_FOLLOW_TAG_ASSIGNED : 已分配待跟进
LEADS_FOLLOW_TAG_FOLLOWING : 跟进中
LEADS_FOLLOW_TAG_VALID : 已转换-潜在客户
LEADS_FOLLOW_TAG_VALID_HIGH_INTENTION : 已转换-高意向客户
LEADS_FOLLOW_TAG_VALID_CONVERTED : 已转换-已成单
LEADS_FOLLOW_TAG_INVALID_REPEAT : 无效-重复
LEADS_FOLLOW_TAG_INVALID_NOTSELF : 无效-非本人
LEADS_FOLLOW_TAG_INVALID_NOTTOUCH : 无效-未接通
LEADS_FOLLOW_TAG_INVALID_NOTINTENTION : 无效-无意向
LEADS_FOLLOW_TAG_INVALID_REGION_MISMATCHED : 无效-定向外
LEADS_FOLLOW_TAG_INVALID_OTHER : 无效-其他
其他枚举值为行业状态,[枚举详情]
outer_leads_convert_type
string 外部线索状态,自定义取值
outer_leads_ineffect_reason
string 外部无效原因,外部线索状态为无效时填写
leads_name
string 姓名
leads_telephone
string 电话
telephone_location
string 号码归属地
leads_area
string 所在地
leads_email
string 邮箱
leads_qq
string qq 号
leads_wechat
string 微信号
leads_gender
enum 性别,[枚举详情]
nationality
string 国籍
working_years
string 工作年限
age
string 年龄
profession
string 职业
id_number
string 身份证号
address
string 详细地址
bundle
string 其他线索信息,K-V 键值对, 字符串对字符串的 json 串,key 不能重复
custom_qa
string 互动问答
leads_create_time
string 线索入库时间,表示录入线索管理平台时间。
因线索提交后,需做相关处理后,再录入线索管理平台,所以线索入库时间会晚于线索提交时间
leads_action_time
string 线索提交时间,表示用户留资时间或拨打电话时间
leads_tags
string 线索标签
shop_name
string 门店名称
shop_address
string 门店地址
call_middle_num
string 智能电话中间号
call_consumer_hotline
string 智能电话-客服电话
call_touch_tag
string 智能电话-接通状态
call_duration
string 智能电话-通话时长
call_record_url
string 智能电话-通话录音链接
layer_form_content
string 意向表单内容
is_broad_cast_leads
string 是否为多发表单
nick_name
string 微信昵称
owner_name
string 当前归属人
owner_id
integer 当前归属人的 userId
all_follow_records
string 全部跟进记录
correlation_factor_rank
string 决策动因相关度:A/B/C/-
claim_account_id
integer ⼴告归因的⼴告主 id
leads_response_duration
integer 线索响应时长
page_info
struct 分页配置信息
page
integer 搜索页码
默认值:1
page_size
integer 一页显示的数据条数
默认值:10
total_number
integer 总条数
total_page
integer 总页数

应答示例

{
    "code": 0,
    "message": "",
    "message_cn": "",
    "data": {
        "leads_info": {
            "account_id": "<ACCOUNT_ID>",
            "adgroup_id": "<ADGROUP_ID>",
            "adgroup_name": "推广广告"
        },
        "page_info": {
            "page": 1,
            "page_size": 10,
            "total_number": 1,
            "total_page": 1
        }
    }
}

可视化调试工具