第三方应用开发 服务端API 通讯录管理 通讯录搜索
通讯录搜索

通讯录单个搜索

请求方式: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,
	"agentid": 1000046,
	"offset":0,
	"limit":50,
	"full_match_field":1
}

参数说明:

参数必须说明
provider_access_token应用提供商的provider_access_token,获取方法参见服务商的凭证
auth_corpid查询的企业corpid
query_word搜索关键词。当查询用户时应为用户名称、名称拼音或者英文名;当查询部门时应为部门名称或者部门名称拼音
query_type查询类型 1:查询用户,返回用户userid列表 2:查询部门,返回部门id列表。 不填该字段或者填0代表同时查询部门跟用户
agentid应用id,若非0则只返回应用可见范围内的用户或者部门信息
offset查询的偏移量,每次调用的offset在上一次offset基础上加上limit
limit查询返回的最大数量,默认为50,最多为200,查询返回的数量可能小于limit指定的值
full_match_field精确匹配的字段。1:匹配用户名称或者部门名称 2:匹配用户英文名。不填则为模糊匹配

权限说明:

agentid为0则返回该服务商授权通讯录权限范围内的用户信息或者部门信息,否则返回指定agentid应用可见范围内的信息

返回结果:

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

参数说明:

参数说明
errcode返回码
errmsg对返回码的文本描述内容
is_last根据该字段判断是否是最后一页,若为false,开发者需要使用offset+limit继续调用
query_result查询结果
user返回的用户信息(通过用户名称,拼音匹配)
userid查询到的用户userid
open_userid查询到的用户open_userid
party返回的部门信息 (通过部门名称,拼音匹配)
department_id返回的部门id
注意:由于查询结果会过滤掉不在应用可见范围的成员与部门,所以每次返回的记录数可能小于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,
			"offset":0,
			"limit":50,
			"full_match_field":1
		}
	]
}

参数说明:

参数必须说明
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代表同时查询部门跟用户
offset查询的偏移量,每次调用的offset在上一次offset基础上加上limit
limit查询返回的最大数量,默认为50,最多为200,查询返回的数量可能小于limit指定的值
full_match_field如果需要精确匹配用户名称或者部门名称或者英文名,不填则默认为模糊匹配;1:匹配用户名称或者部门名称 2:匹配用户英文名

权限说明:

agentid为0则返回该服务商授权通讯录权限范围内的用户信息或者部门信息,否则返回指定agentid应用可见范围内的信息

返回结果:

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

参数说明:

参数说明
errcode返回码
errmsg对返回码的文本描述内容
is_last根据该字段判断是否是最后一页,若为false,开发者需要使用offset+limit继续调用
query_result_list搜索结果列表
query_request原搜索请求报文
query_result搜索请求对应的查询结果
user返回的用户信息(通过用户名称,拼音匹配)
userid查询到的用户userid
open_userid查询到的用户open_userid
party返回的部门信息 (通过部门名称,拼音匹配)
department_id返回的部门id
上一篇
通讯录展示组件
下一篇
概述