第三方应用开发 服务端API 通讯录管理 通讯录搜索
通讯录搜索
最后更新:2024/03/14
可联系渠道经理采购或代理智慧硬件接口已支持设备 联系渠道经理
通讯录搜索
最后更新:2024/03/14

通讯录单个搜索

请求方式:POST(HTTPS
请求地址:https://qyapi.weixin.qq.com/cgi-bin/service/contact/search?provider_access_token=ACCESS_TOKEN

请求包体:

{
	"auth_corpid":"wwxxxxxx",
	"query_word": "zhangsan",
	"query_type":1,
	"query_range":1,
	"agentid": 1000046,
	"limit":50,
	"full_match_field":1,
	"cursor":"CURSOR"
}

参数说明:

参数必须说明
provider_access_token应用提供商的provider_access_token,获取方法参见服务商的凭证
auth_corpid查询的企业corpid
query_word搜索关键词。当查询用户时应为用户名称、名称拼音或者英文名;当查询部门时应为部门名称或者部门名称拼音
query_type查询类型 1:查询用户,返回用户userid列表 2:查询部门,返回部门id列表。 不填该字段或者填0代表同时查询部门跟用户
query_range查询范围,仅查询类型包含用户时有效。 0:只查询在职用户 1:同时查询在职和离职用户(离职用户仅当离职前有激活企业微信才可以被搜到
agentid应用id,若非0则只返回应用可见范围内的用户或者部门信息
limit查询返回的最大数量,默认为50,最多为200,查询返回的数量可能小于limit指定的值。limit会分别控制在职数据和离职数据的数量。
full_match_field精确匹配的字段。1:匹配用户名称或者部门名称 2:匹配用户英文名。不填则为模糊匹配
cursor用于分页查询的游标,字符串类型,由上一次调用返回,首次调用可不填

权限说明:

agentid为0则返回该服务商授权通讯录权限范围内的用户信息或者部门信息,否则返回指定agentid应用可见范围内的信息。
查询范围包含离职用户时,将查询一年内的所有离职用户。

返回结果:

{
   "errcode": 0,
   "errmsg": "ok",
   "query_result":{
  	    "user":{
    	    "userid":["zhangshan","lisi"],
		    "open_userid":["wwxxxx","wwxxxa"]
  	    },
    	"party":{
     	    "department_id":[1,2,3]
   	    },
    	"dismiss_user":{
    	    "userid":["zhangshan","lisi"],
		    "open_userid":["wwxxxx","wwxxxa"]
   	    }
   },
   "is_last":false,
   "next_cursor":"NEXT_CURSOR"
}

参数说明:

参数说明
errcode返回码
errmsg对返回码的文本描述内容
is_last根据该字段判断是否是最后一页,若为false,开发者需要使用limit+cursor继续调用
query_result查询结果
user返回的在职用户信息(通过用户名称,拼音匹配)
userid查询到的用户userid
open_userid查询到的用户open_userid
party返回的部门信息 (通过部门名称,拼音匹配)
department_id返回的部门id
dismiss_user返回的离职用户信息(通过用户名称,拼音匹配)
next_cursor分页游标,再下次请求时填写以获取之后分页的记录,如果已经没有更多的数据则返回空
注意:由于查询结果会过滤掉不在应用可见范围的成员与部门,所以每次返回的记录数可能小于limit。此时,如果is_last为false,则说明后续还有匹配的记录,服务商需要继续调用该接口进行查询。

通讯录批量搜索

请求方式:POST(HTTPS
请求地址:https://qyapi.weixin.qq.com/cgi-bin/service/contact/batchsearch?provider_access_token=ACCESS_TOKEN

请求包体:

{
	"auth_corpid":"wwxxxxxx",
	"agentid": 1000046,
    "query_request_list":[
		{
			"query_word": "zhangsan",
			"query_type":1,
			"query_range":1,
			"limit":50,
			"full_match_field":1,
			"cursor":"CURSOR"
		}
	]
}

参数说明:

参数必须说明
provider_access_token应用提供商的provider_access_token,获取方法参见服务商的凭证
auth_corpid查询的企业corpid
agentid应用id,若非0则只返回应用可见范围内的用户或者部门信息
query_request_list搜索请求列表,每次搜索列表数量不超过50
query_word搜索关键词。当查询用户时应为用户名称、名称拼音或者英文名;当查询部门时应为部门名称或者部门名称拼音
query_type查询类型 1:查询用户,返回用户userid列表 2:查询部门,返回部门id列表。 不填该字段或者填0代表同时查询部门跟用户
query_range查询范围,仅查询类型包含用户时有效。 0:只查询在职用户 1:同时查询在职和离职用户
limit查询返回的最大数量,默认为50,最多为200,查询返回的数量可能小于limit指定的值。limit会分别控制在职数据和离职数据的数量。
full_match_field如果需要精确匹配用户名称或者部门名称或者英文名,不填则默认为模糊匹配;1:匹配用户名称或者部门名称 2:匹配用户英文名
cursor用于分页查询的游标,字符串类型,由上一次调用返回,首次调用可不填

权限说明:

agentid为0则返回该服务商授权通讯录权限范围内的用户信息或者部门信息,否则返回指定agentid应用可见范围内的信息。
查询范围包含离职用户时,将查询一年内的所有离职用户。

返回结果:

{
   "errcode": 0,
   "errmsg": "ok",
   "query_result_list":[
		{
			"query_request":
			{
				"query_word": "zhangsan",
				"query_type":1,
				"limit":50,
				"cursor":"CURSOR"
			},
			"query_result":{
				"user":{
					"userid":["zhangshan","lisi"],
					"open_userid":["wwxxxx","wwxxxa"]
			 	},
				"party":{
					"department_id":[1,2,3]
			  	},
				"dismiss_user":{
					"userid":["zhangshan","lisi"],
					"open_userid":["wwxxxx","wwxxxa"]
				}
			},
			"is_last":false,
			"next_cursor":"NEXT_CURSOR"
		}
   ]
}

参数说明:

参数说明
errcode返回码
errmsg对返回码的文本描述内容
is_last根据该字段判断是否是最后一页,若为false,开发者需要使用limit+cursor继续调用
query_result_list搜索结果列表
query_request原搜索请求报文
query_result搜索请求对应的查询结果
user返回的在职用户信息(通过用户名称,拼音匹配)
userid查询到的用户userid
open_userid查询到的用户open_userid
party返回的部门信息 (通过部门名称,拼音匹配)
department_id返回的部门id
dismiss_user返回的离职用户信息(通过用户名称,拼音匹配)
next_cursor分页游标,再下次请求时填写以获取之后分页的记录,如果已经没有更多的数据则返回空
上一篇
通讯录展示组件
下一篇
概述