接口文档SDK业务专题开发者工具

获取线索列表
全部接口
V1.1
loading

所属权限 Ads Insight
请求地址 lead_clues/get
请求方法 post

全局参数

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

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

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

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

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

nonce 随机字串标识,不超过 32 个字符,由调用方自行生成,需保证全局唯一性
fields get 接口增加 fields 字段,用于指定返回参数的字段列表,为选填字段。fields 取值范围为 get 接口返回的 list 中的字段。如不填写,则根据默认值进行返回

请求参数

标有*的参数为必填项

名称 类型 描述
account_id*
integer 广告主账号 id,直客账号或子客账号
time_type
enum 时间类型,不填默认为 TIME_TYPE_ACTION_TIME,此参数会影响到 time_range、last_search_after_values、返回数据的排序规则,[枚举详情]
枚举列表:{ TIME_TYPE_ACTION_TIME, TIME_TYPE_CREATED_TIME }
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
filtering
struct[] 过滤条件,若此字段不传,或传空则视为无限制条件,详见 [过滤条件]
数组最小长度 0,最大长度 100
field*
string 过滤字段
可选值:{ campaign_id, campaign_created_time, position_type, leads_convert_type }
operator*
enum 操作符
当 field 取值 campaign_id 时,枚举列表:{ EQUALS, IN }
当 field 取值 campaign_created_time 时,枚举列表:{ GREATER_EQUALS }
当 field 取值 position_type 时,枚举列表:{ EQUALS }
当 field 取值 leads_convert_type 时,枚举列表:{ EQUALS }
values*
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
string[] 线索深度翻页参数
time_type=TIME_TYPE_ACTION_TIME 时填写线索提交时间和线索 id
time_type=TIME_TYPE_CREATED_TIME 时填写线索入库时间和线索 id

使用说明

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

请求示例


curl 'https://api.e.qq.com/v1.1/lead_clues/get?access_token=<ACCESS_TOKEN>&timestamp=<TIMESTAMP>&nonce=<NONCE>' \
-H 'Content-Type: application/json' \
-d '{
    "account_id": 123456,
    "time_range": {
        "start_time": 1571367150,
        "end_time": 1571367160
    },
    "filtering": [
        {
            "field": "campaign_id",
            "operator": "EQUALS",
            "values": [
                "11111111"
            ]
        }
    ],
    "page": 51,
    "page_size": 100,
    "last_search_after_values": [
        "1571367160000",
        "111111"
    ]
}'
					

应答字段

名称 类型 描述
leads_info
struct[] 返回信息列表
account_id
integer 广告主账号 id,直客账号或子客账号
leads_id
integer 线索 id
outer_leads_id
string 外部线索 id,作为线索管理平台的线索与客户侧 CRM 系统的线索关联的唯一标识
click_id
string 点击 id,预览数据的点击 id 为空
wechat_appid
string 微信 appId
agency_id
string 服务商 id:
广点通服务商=服务商 id
微信服务商=服务商 spid
agency_name
string 服务商名称
campaign_id
int64 推广计划 id
campaign_name
string 推广计划名称
adgroup_id
int64 广告 id
adgroup_name
string 广告名称
creative_id
string 创意 id(废弃中)
注:此字段概念有些混淆,如有需要请改用 ad_id / adcreative_id。
creative_name
string 创意名称(废弃中)
注:此字段概念有些混淆,如有需要请改用 ad_name / adcreative_name。
ad_id
int64 广告 id
ad_name
string 广告名称
adcreative_id
int64 广告创意 id
adcreative_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
string 二级线索类型
FORM_SUBMIT__UNKNOWN : 未知
FORM_SUBMIT__FORM_SUBMIT : 提交表单
FORM_SUBMIT__LEAVE_MESSAGE_CONSULT : 离线留言
FORM_SUBMIT__LEAVE_INFORMATION_CONSULT : 在线咨询
FORM_SUBMIT__PHONE_CONSULT : 电话咨询
ONE_CLICK_AUTHORIZE__UNKNOWN : 未知
ONE_CLICK_AUTHORIZE__FORM_SUBMIT : 提交表单
ONE_CLICK_AUTHORIZE__PHONE_CONSULT : 开口咨询
ONE_CLICK_AUTHORIZE__CLICK_FORM : 点击表单
ONE_CLICK_AUTHORIZE__CLICK_CONSULT : 点击咨询
ONE_CLICK_AUTHORIZE__CLICK_CALL : 点击拨打
INTELLIGENT_TOOL__FIRST_TALK : 开口咨询
INTELLIGENT_TOOL__LEAVE_INFORMATION : 咨询留咨
chat_id
string 会话 id
leads_source
string 线索来源
OUTER_TRAFFIC : 其他
OFFLINE : 外部导入
AD_PREVIEW : 广告创意
XJ : 蹊径落地页
ONE_LEAF : 一叶智能
WECHAT_CANVAS : 微信原生推广页
XUNDA : 讯达小程序
INTERACTIVEPAGE : 互动落地页
JIAOPEITONG : 教培通
leads_potential_score
string 系统评分
leads_follow_tag
string 线索状态
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_user_id
string 线索用户 id
leads_user_type
enum 线索用户类型,[枚举详情]
leads_user_wechat_appid
string 线索用户的微信 AppId,微信公众号/小程序/小游戏的开发者 id
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 其他表单字段
pos_type
integer 广告位类型
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 意向表单内容
nick_name
string 微信昵称
is_broad_cast_leads
string 是否为多发表单
page_info
struct 分页配置信息
page
integer 搜索页码
page_size
integer 一页显示的数据条数
total_number
integer 总条数
total_page
integer 总页数

应答示例

{
    "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": "门店地址"
            }
        ],
        "page_info": {
            "page": 51,
            "page_size": 100,
            "total_number": 5001,
            "total_page": 51
        }
    }
}

可视化调试工具