第三方应用开发 服务端API 通讯录管理 成员管理 获取部门成员详情
获取部门成员详情
最后更新:2023/09/07
可联系渠道经理采购或代理智慧硬件接口已支持设备 联系渠道经理
获取部门成员详情
最后更新:2023/09/07

应用只能获取可见范围内的成员信息,且每种应用获取的字段有所不同,在返回结果说明中会逐个说明。企业通讯录安全特别重要,企业微信持续升级加固通讯录接口的安全机制,以下是关键的变更点:

  • 从2022年6月20号20点开始,除通讯录同步以外的基础应用(如客户联系、微信客服、会话存档、日程等),以及新创建的自建应用与代开发应用,调用该接口时,不再返回以下字段:头像、性别、手机、邮箱、企业邮箱、员工个人二维码、地址,应用需要通过oauth2手工授权的方式获取管理员与员工本人授权的字段。

  • 【重要】从2022年8月15日10点开始,“企业管理后台 - 管理工具 - 通讯录同步”的新增IP将不能再调用此接口,企业可通过「获取成员ID列表」和「获取部门ID列表」接口获取userid和部门ID列表。查看调整详情

 

请求方式:GET(HTTPS
请求地址:https://qyapi.weixin.qq.com/cgi-bin/user/list?access_token=ACCESS_TOKEN&department_id=DEPARTMENT_ID

参数说明:

参数必须说明
access_token调用接口凭证
department_id获取的部门id
如需获取该部门及其子部门的所有成员,需先获取该部门下的子部门,然后再获取子部门下的部门成员,逐层递归获取。

权限说明:

应用须拥有指定部门的查看权限。

返回结果:

{
	"errcode": 0,
	"errmsg": "ok",
	"userlist": [{
		"userid": "zhangsan",
		"name": "李四",
		"department": [1, 2],
		"order": [1, 2],
		"position": "后台工程师",
		"mobile": "13800000000",
		"gender": "1",
		"email": "zhangsan@gzdev.com",
		"biz_mail":"zhangsan@qyycs2.wecom.work",
		"is_leader_in_dept": [1, 0],
		"direct_leader":["lisi"],
		"avatar": "http://wx.qlogo.cn/mmopen/ajNVdqHZLLA3WJ6DSZUfiakYe37PKnQhBIeOQBO4czqrnZDS79FH5Wm5m4X69TBicnHFlhiafvDwklOpZeXYQQ2icg/0",
		"thumb_avatar": "http://wx.qlogo.cn/mmopen/ajNVdqHZLLA3WJ6DSZUfiakYe37PKnQhBIeOQBO4czqrnZDS79FH5Wm5m4X69TBicnHFlhiafvDwklOpZeXYQQ2icg/100",
		"telephone": "020-123456",
		"alias": "jackzhang",
		"status": 1,
		"address": "广州市海珠区新港中路",
		"english_name" : "jacky",
		"open_userid": "xxxxxx",
		"main_department": 1,
		"extattr": {
			"attrs": [
				{
					"type": 0,
					"name": "文本名称",
					"text": {
						"value": "文本"
					}
				},
				{
					"type": 1,
					"name": "网页名称",
					"web": {
						"url": "http://www.test.com",
						"title": "标题"
					}
				}
			]
		},
		"qr_code": "https://open.work.weixin.qq.com/wwopen/userQRCode?vcode=xxx",
		"external_position": "产品经理",
		"external_profile": {
			"external_corp_name": "企业简称",
			"wechat_channels": {
				"nickname": "视频号名称",
				"status": 1
			},
			"external_attr": [{
					"type": 0,
					"name": "文本名称",
					"text": {
						"value": "文本"
					}
				},
				{
					"type": 1,
					"name": "网页名称",
					"web": {
						"url": "http://www.test.com",
						"title": "标题"
					}
				},
				{
					"type": 2,
					"name": "测试app",
					"miniprogram": {
						"appid": "wx8bd80126147dFAKE",
						"pagepath": "/index",
						"title": "miniprogram"
					}
				}
			]
		}
	}]
}

参数说明 :

参数说明
errcode返回码
errmsg对返回码的文本描述内容
userlist成员列表
userid成员UserID。对应管理端的账号
name成员名称;第三方不可获取,调用时返回userid以代替name;代开发自建应用需要管理员授权才返回;对于非第三方创建的成员,第三方通讯录应用也不可获取;未返回名称的情况需要通过通讯录展示组件来展示名字
mobile手机号码,代开发自建应用需要管理员授权才返回;第三方仅通讯录应用可获取;对于非第三方创建的成员,第三方通讯录应用也不可获取;上游企业不可获取下游企业成员该字段
department成员所属部门id列表,仅返回该应用有查看权限的部门id。对授权了“组织架构信息”的第三方应用或授权了“组织架构信息”-“部门及父部门ID、部门负责人”的代开发应用,返回成员所属的全部部门id列表
order部门内的排序值,默认为0。数量必须和department一致,数值越大排序越前面。值范围是[0, 2^32)
position职务信息;代开发自建应用需要管理员授权才返回;第三方仅通讯录应用可获取;对于非第三方创建的成员,第三方通讯录应用也不可获取;上游企业不可获取下游企业成员该字段
gender性别。0表示未定义,1表示男性,2表示女性。第三方仅通讯录应用可获取;对于非第三方创建的成员,第三方通讯录应用也不可获取;上游企业不可获取下游企业成员该字段。注:不可获取指返回值为0
email邮箱,代开发自建应用需要管理员授权才返回;第三方仅通讯录应用可获取;对于非第三方创建的成员,第三方通讯录应用也不可获取;上游企业不可获取下游企业成员该字段
biz_mail企业邮箱,代开发自建应用不返回;第三方仅通讯录应用可获取;对于非第三方创建的成员,第三方通讯录应用也不可获取;上游企业不可获取下游企业成员该字段
is_leader_in_dept表示在所在的部门内是否为部门负责人。0-否;1-是。是一个列表,数量必须与department一致。第三方通讯录应用或者授权了“组织架构信息-应用可获取企业的部门组织架构信息-部门负责人”权限的第三方应用和代开发应用可获取;对于非第三方创建的成员,第三方通讯录应用不可获取;上游企业不可获取下游企业成员该字段
direct_leader直属上级UserID,返回在应用可见范围内的直属上级列表,最多有1个直属上级;第三方通讯录应用或者授权了“组织架构信息-应用可获取可见范围内成员组织架构信息-直属上级”权限的第三方应用和代开发应用可获取;对于非第三方创建的成员,第三方通讯录应用不可获取;上游企业不可获取下游企业成员该字段;代开发自建应用不可获取该字段
avatar头像url。 第三方仅通讯录应用可获取;对于非第三方创建的成员,第三方通讯录应用也不可获取;上游企业不可获取下游企业成员该字段
thumb_avatar头像缩略图url。第三方仅通讯录应用可获取;对于非第三方创建的成员,第三方通讯录应用也不可获取;上游企业不可获取下游企业成员该字段
telephone座机。代开发自建应用需要管理员授权才返回;第三方仅通讯录应用可获取;对于非第三方创建的成员,第三方通讯录应用也不可获取;上游企业不可获取下游企业成员该字段
alias别名;第三方仅通讯录应用可获取;对于非第三方创建的成员,第三方通讯录应用也不可获取;上游企业不可获取下游企业成员该字段
extattr扩展属性,代开发自建应用需要管理员授权才返回;第三方仅通讯录应用可获取;对于非第三方创建的成员,第三方通讯录应用也不可获取;上游企业不可获取下游企业成员该字段
status激活状态: 1=已激活,2=已禁用,4=未激活,5=退出企业。
已激活代表已激活企业微信或已关注微信插件(原企业号)。未激活代表既未激活企业微信又未关注微信插件(原企业号)。
qr_code员工个人二维码,扫描可添加为外部联系人(注意返回的是一个url,可在浏览器上打开该url以展示二维码);第三方仅通讯录应用可获取;对于非第三方创建的成员,第三方通讯录应用也不可获取;上游企业不可获取下游企业成员该字段
external_profile成员对外属性,字段详情见对外属性;代开发自建应用需要管理员授权才返回;第三方仅通讯录应用可获取;对于非第三方创建的成员,第三方通讯录应用也不可获取;上游企业不可获取下游企业成员该字段
external_position对外职务,如果设置了该值,则以此作为对外展示的职务,否则以position来展示。代开发自建应用需要管理员授权才返回;第三方仅通讯录应用可获取;对于非第三方创建的成员,第三方通讯录应用也不可获取;上游企业不可获取下游企业成员该字段
address地址。代开发自建应用需要管理员授权才返回;第三方仅通讯录应用可获取;对于非第三方创建的成员,第三方通讯录应用也不可获取;上游企业不可获取下游企业成员该字段
open_userid全局唯一。对于同一个服务商,不同应用获取到企业内同一个成员的open_userid是相同的,最多64个字节。仅第三方应用可获取
main_department主部门,仅当应用对主部门有查看权限时返回。
上一篇
获取部门成员
下一篇
userid与openid互换