查询联系人 - 尘锋SCRM开放平台

根据员工和联系人创建时间查询联系人资料

POST https://qw-openapi-tx.dustess.com/customer/v1/getCustomerList?accessToken=

Content-Type: application/json

接口限制：每分钟调用600次；单次最大限制500；

通过本接口查询的联系人数据与页面查询到的一致，本接口包含了存在于公海和员工名下的联系人数据。如对比数据量不一致，请检查查询条件是否正确

本接口不会返回存在于回收站的联系人数据

如需获取全量数据，推荐通过联系人的创建时间（时间范围请求参数为start、end）逐月拉取，当查询的数据超过500条时，可以使用当前页第500个联系人的cf_ts字段值进行翻页查询（详情查看参数列表说明）

cf_ts字段分页问题：分页使用cf_ts字段实现，具体是：获取第一页数据之后，用第一页的最后一条数据的cf_ts字段作为参数，比如：获取一个时间段的数据，单页数量为10，获取第二页的数据，cf_ts参数以第一页数据的最后一条数据的cf_ts字段作为参数，即获取大于当前cf_ts值的10条数据也就是第二页;

注意：当以下参数之一传入时，其他参数条件将失效，参数优先级：cids > external_ids > qw_external_userids > union_ids > mobiles > 其他参数，例：当参数cids和external_ids同时传参，只会以cids进行查询，external_ids等其他参数条件将被舍弃；

请求参数

请求参数名	类型	说明	是否必须
cids	`String[]`	尘锋联系人id，超过500个默认只返回500个	false
external_ids	`String[]`	联系人所关联的外部系统ID ，超过500个默认只返回500个	false
uid	`String`	员工的id(可筛选当前员工的联系人，查出的联系人当前员工为主跟进人或共享人)	false
type	`String`	联系人类型 "external"：外部联系人，"ordinary"：普通联系人（原联系人线索），"all":全部	false
start	`Int64`	查询起始时间（时间戳，单位秒，指联系人的创建时间,未传时间区间默认查询最近一周，时间区间最长31天）	false
end	`Int64`	查询结束时间（时间戳，单位秒，指联系人的创建时间,未传时间区间默认查询最近一周，时间区间最长31天）	false
cf_ts	`Int`	分页标记，每个联系人都有唯一的cf_ts值，通过本字段实现翻页查询，传入后将会返回大于此值的数据，如不传值，默认为0，表示从头开始遍历查询。	false
mobiles	`String[]`	联系方式列表，超过500个默认只返回500个	false
union_ids	`String[]`	unionid列表，超过500个默认只返回500个	false
page_size	`Int`	分页尺码(最大值500，若没传或是0默认500)	false
start_update_time	`Int`	通过联系人更新时间查询的起始时间（时间戳，单位秒，指联系人的更新时间，未传时间区间不做查询，时间区间最长31天）	false
end_update_time	`Int`	通过联系人更新时间查询的结束时间（时间戳，单位秒，指联系人的更新时间，未传时间区间不做查询，时间区间最⻓31天）	false
qw_external_userids	`String[]`	联系人所关联的企微好友（外部联系人ID）	false

请求参数示例
json - Request-Example:

{
  "uid": "11",
  "start": 1500084074,
  "end": 1600084074,
  "cf_ts": 100000000,
  "page_size": 100,
  "type":"external",
  "start_update_time": 1500084074,
  "end_update_time": 1600084074,
  "qw_external_userids": ["user1", "user2"]
}

成功响应

响应参数名	类型	说明
success	`Bool`	请求状态，true：成功，false：失败_Allowed values: true,false_
code	`Int`	响应代码
msg	`String`	消息提示
data	`Object[]`	数据信息
data.id	`String`	联系人id
data.name	`String`	企微昵称
data.corp_name	`String`	企业简称
data.corp_full_name	`String`	企业全称
data.mobiles	`Object[]`	联系方式（联系人去重核心字段）
data.mobiles.tel	`String`	联系方式具体内容，如：type=mobile，则值为手机号码
data.mobiles.type	`String`	mobile（手机号），landline（座机），other（其他）,11b90rp60zya（自定义联系方式，如：微信号）
data.mobiles.display	`String`	联系方式名称
data.position	`String`	职位
data.sourceCode	`String`	来源id 来源列表查询（企业&联系人）
data.prov_city	`String`	省市区（县）
data.address	`String`	地址
data.birthday	`String`	生日
data.email	`String`	email
data.gender	`Int`	性别 0-未知 1-男性 2-女性
data.custom_fields	`Object[]`	自定义字段查询字段模版
data.custom_fields.id	`String`	字段id
data.custom_fields.array_value	`String[]`	字段类型为：checkbox（多项选择）,cascader（多级联选单选），multiCascader（多级联选多选）时使用此字段
data.custom_fields.float_value	`Int`	字段类型为：number（数字）时使用此字段
data.custom_fields.type	`String`	字段类型
data.custom_fields.string_value	`String`	字段类型为：radio（单选），date（日期），datetime（日期时间），text（单行文本），textarea（多行文本）时使用此字段
data.custom_fields.files_value	`Object[]`	字段类型为：附件列表时使用此字段, 最大文件个数5个
data.custom_fields.files_value.name	`String`	文件名称, 使用附件类型必填
data.custom_fields.files_value.url	`String`	文件链接, 使用附件类型必填获取附件URL访问签名
data.custom_fields.files_value.file_type	`String`	文件type
data.external_userid	`String`	外部联系人的userid
data.avatar	`String`	外部联系人头像
data.type	`Int`	1表示该外部联系人是微信用户，2表示该外部联系人是企业微信用户，3表示该联系人为普通联系人
data.unionid	`String`	外部联系人在微信开放平台的唯一身份标识
data.qwcreatetime	`Int`	企微添加此外部联系人的时间
data.uids	`String[]`	跟进员工id集合查询员工信息
data.owner	`String`	主跟进员工id
data.share_uids	`String[]`	共享员工id集合
data.remark	`String`	联系人名称
data.description	`String`	描述
data.tags	`String[]`	好友标签id集合查询好友标签列表
data.remark_corp_name	`String`	企业名称
data.status	`String`	联系人状态id 查询跟进状态列表
data.reason	`String`	无效原因id 无效&放弃&删除原因查询
data.price	`Int`	销售机会金额
data.pool	`String`	公海id 查询联系人公海列表
data.corp_id	`String`	企业id 查询企业列表
data.updatetime	`Int`	更新时间
data.gettime	`Int`	获取时间
data.add_time	`Int`	添加时间
data.add_way	`Int[]`	添加来源
data.updateuser	`String`	更新员工id
data.update_qw_user_id	`String`	更新人的企微userId
data.createuser	`String`	创建人id
data.is_del	`Bool`	是否删除
data.from	`Int`	1111表示微信线索，2222表示联系人线索
data.mergetime	`Int`	合并联系人的时间
data.age	`Int`	年龄
data.national	`String`	民族
data.nationality	`String`	国籍
data.education	`String`	教育
data.major	`String`	专业
data.id_card	`String`	身份证
data.wx	`String`	微信
data.qq	`String`	QQ
data.mkScore	`Int`	营销评分，如返回值为1500，实际分值为15
data.intentionDegreeScore	`Int`	意向分，如返回值为1500，实际分值为15
data.biz_tags	`String[]`	联系人标签id集合查询联系人标签列表
data.have_sale_chance	`Bool`	联系人拥有销售机会
data.duplicate	`Bool`	是否存在与之重复的联系人
data.categoryId	`String`	联系人类型id
data.province	`Int`	省
data.city	`Int`	市
data.district	`Int`	县
data.external_id	`String`	联系人所关联的外部系统ID
data.follow_user	`Object[]`	员工添加外部联系人记录
data.follow_user.uid	`String`	员工id
data.follow_user.external_userid	`String`	联系人所关联的企微好友（外部联系人ID）
data.follow_user.createtime	`Int`	联系人资料创建时间
data.follow_user.qw_create_time	`Int`	企微好友添加时间
data.follow_user.add_way	`Int`	添加来源
data.follow_user.is_deleted	`Bool`	是否删除
data.rule_tags	`String[]`	规则标签id集合
data.first_add_friend_time	`Int`	首次添加好友时间（秒级时间戳）

从 2022年12月01日前开户的客户，来源会在‘source’字段中返回

add_way表示添加联系人的来源，有固定的值，而state表示此联系人的渠道，可以由企业进行自定义的配置，请注意二者的不同。
参考：企微来源定义

值	含义
0	未知来源
1	扫描二维码
2	搜索手机号
3	名片分享
4	群聊
5	手机通讯录
6	微信联系人
7	来自微信的添加好友申请
8	安装第三方应用时自动添加的客服人员
9	搜索邮箱
201	内部成员共享
202	管理员/负责人分配

成功响应示例

{
    "success": true,
    "msg": "",
    "data": [{
        "MKScoreDetail": [{
            "tagScore": 9,
            "tid": "d1b78d16-dd2e-11ea-a9ec-11111112"
        }],
        "add_time": 1600154045,
        "add_way": [
            1
        ],
        "address": "",
        "age": 0,
        "avatar": "http://wx.qlogo.cn/mmhead/test/0",
        "birthday": "",
        "birthdayDay": 0,
        "birthdayMonth": 0,
        "birthdayMonthAndDay": "",
        "birthdayYear": 0,
        "biz_tags": [

        ],
        "categoryId": "00000000-0000-0000-0000-000000000000",
        "cf_ts": 1019989493388034000,
        "city": 0,
        "contact_time": 0,
        "corp_full_name": "",
        "corp_id": "",
        "corp_name": "",
        "create_clueTime": 0,
        "createtime": 1600154045,
        "createuser": "13",
        "custom_fields": null,
        "description": "",
        "district": 0,
        "duplicate": false,
        "dynamic_time": 0,
        "education": "",
        "email": "",
        "external_userid": "wmMXXWDQAAgTH4QinMwEpqZAFQX_1111",
        "from": 0,
        "gender": 1,
        "gettime": 1600154045,
        "have_sale_chance": false,
        "id": "0a4f8601-f723-11ea-8f15-1111111",
        "id_card": "",
        "is_del": false,
        "log_time": 0,
        "log_type": "",
        "major": "",
        "mergetime": 0,
        "mkScore": 9,
        "mobiles": [{
                "tel": "12500010002",
                "type": "mobile",
                "display": "手机号"
            },
            {
                "tel": "ead12312acxzcasd",
                "type": "11b90rp60zya",
                "display": "微信号"
            }
        ],
        "name": "Air",
        "national": "",
        "nationality": "",
        "owner": "13",
        "pool": "",
        "pool_dynamic": "",
        "position": "",
        "price": 0,
        "prov_city": "",
        "province": 0,
        "qq": "",
        "qwcreatetime": 1600154042,
        "reason": "",
        "recovery_time": "",
        "remark": "Air",
        "remark_corp_name": "",
        "remind_time": "",
        "sourceCode": "01i",
        "status": "uuid0",
        "tags": [

        ],
        "rule_tags": [],
        "type": 1,
        "uids": [
            "13"
        ],
        "unionid": "owx_AwDYE_Y3aq7twzt1111111",
        "updatetime": 1600154042,
        "updateuser": "",
        "wx": "",
        "wx_clue_tags": [
            "d1b78d16-dd2e-11ea-a9ec-1111111"
        ],
        "follow_user": [{
            "uid": "2",
            "external_userid": "woDolHEAAA6rJmSXoNB11111111111",
            "createtime": 1590579533,
            "add_way": 0,
            "is_deleted": false
        }]
    }]
}

错误响应示例

 {
    "success":false,
    "code": 10001,
    "msg": "system unknown error",
    "data": null
}