Name
QQ::weixin::work::user
DESCRIPTION
通讯录管理->成员管理
FUNCTION
create(access_token, hash);
创建成员
SYNOPSIS
https://work.weixin.qq.com/api/doc/90000/90135/90195
请求说明：
请求包结构体为：
{
"userid": "zhangsan",
"name": "张三",
"alias": "jackzhang",
"mobile": "13800000000",
"department": [1, 2],
"order":[10,40],
"position": "产品经理",
"gender": "1",
"email": "zhangsan@gzdev.com",
"is_leader_in_dept": [1, 0],
"enable":1,
"avatar_mediaid": "2-G6nrLmr5EC3MNb_-zL1dDdzkd0p7cNliYu9V5w7o8K0",
"telephone": "020-123456",
"address": "广州市海珠区新港中路",
"extattr": {
"attrs": [
{
"type": 0,
"name": "文本名称",
"text": {
"value": "文本"
}
},
{
"type": 1,
"name": "网页名称",
"web": {
"url": "http://www.test.com",
"title": "标题"
}
}
]
},
"to_invite": true,
"external_position": "高级产品经理",
"external_profile": {
"external_corp_name": "企业简称",
"external_attr": [
{
"type": 0,
"name": "文本名称",
"text": {
"value": "文本"
}
},
{
"type": 1,
"name": "网页名称",
"web": {
"url": "http://www.test.com",
"title": "标题"
}
},
{
"type": 2,
"name": "测试app",
"miniprogram": {
"appid": "wx8bd8012614784fake",
"pagepath": "/index",
"title": "my miniprogram"
}
}
]
}
}参数说明：
参数 必须 说明
access_token 是 调用接口凭证。获取方法查看“获取access_token”
userid 是 成员UserID。对应管理端的帐号，企业内必须唯一。不区分大小写，长度为1~64个字节。只能由数字、字母和“_-@.”四种字符组成，且第一个字符必须是数字或字母。
name 是 成员名称。长度为1~64个utf8字符
alias 否 成员别名。长度1~32个utf8字符
mobile 否 手机号码。企业内必须唯一，mobile/email二者不能同时为空
department 是 成员所属部门id列表,不超过20个
order 否 部门内的排序值，默认为0，成员次序以创建时间从小到大排列。数量必须和department一致，数值越大排序越前面。有效的值范围是[0, 2^32)
position 否 职务信息。长度为0~128个字符
gender 否 性别。1表示男性，2表示女性
email 否 邮箱。长度6~64个字节，且为有效的email格式。企业内必须唯一，mobile/email二者不能同时为空
telephone 否 座机。32字节以内，由纯数字或’-‘号组成。
is_leader_in_dept 否 个数必须和department一致，表示在所在的部门内是否为上级。1表示为上级，0表示非上级。在审批等应用里可以用来标识上级审批人
avatar_mediaid 否 成员头像的mediaid，通过素材管理接口上传图片获得的mediaid
enable 否 启用/禁用成员。1表示启用成员，0表示禁用成员
extattr 否 自定义字段。自定义字段需要先在WEB管理端添加，见扩展属性添加方法，否则忽略未知属性的赋值。与对外属性一致，不过只支持type=0的文本和type=1的网页类型，详细描述查看对外属性
to_invite 否 是否邀请该成员使用企业微信（将通过微信服务通知或短信或邮件下发邀请，每天自动下发一次，最多持续3个工作日），默认值为true。
external_profile 否 成员对外属性，字段详情见对外属性
external_position 否 对外职务，如果设置了该值，则以此作为对外展示的职务，否则以position来展示。长度12个汉字内
address 否 地址。长度最大128个字符权限说明
仅通讯录同步助手或第三方通讯录应用可调用。
注意，每个部门下的部门、成员总数不能超过3万个。建议保证创建department对应的部门和创建成员是串行化处理。
RETURN 返回结果
{
"errcode": 0,
"errmsg": "created"
}RETURN 参数说明
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容get(access_token, userid);
读取成员
SYNOPSIS
https://work.weixin.qq.com/api/doc/90000/90135/90196
请求说明：
参数说明：
参数 必须 说明
access_token 是 调用接口凭证
userid 是 成员UserID。对应管理端的帐号，企业内必须唯一。不区分大小写，长度为1~64个字节权限说明
应用须拥有指定成员的查看权限。
RETURN 返回结果
{
"errcode": 0,
"errmsg": "ok",
"userid": "zhangsan",
"name": "李四",
"department": [1, 2],
"order": [1, 2],
"position": "后台工程师",
"mobile": "13800000000",
"gender": "1",
"email": "zhangsan@gzdev.com",
"is_leader_in_dept": [1, 0],
"avatar": "http://wx.qlogo.cn/mmopen/ajNVdqHZLLA3WJ6DSZUfiakYe37PKnQhBIeOQBO4czqrnZDS79FH5Wm5m4X69TBicnHFlhiafvDwklOpZeXYQQ2icg/0",
"thumb_avatar": "http://wx.qlogo.cn/mmopen/ajNVdqHZLLA3WJ6DSZUfiakYe37PKnQhBIeOQBO4czqrnZDS79FH5Wm5m4X69TBicnHFlhiafvDwklOpZeXYQQ2icg/100",
"telephone": "020-123456",
"enable": 1,
"alias": "jackzhang",
"address": "广州市海珠区新港中路",
"extattr": {
"attrs": [
{
"type": 0,
"name": "文本名称",
"text": {
"value": "文本"
}
},
{
"type": 1,
"name": "网页名称",
"web": {
"url": "http://www.test.com",
"title": "标题"
}
}
]
},
"status": 1,
"qr_code": "https://open.work.weixin.qq.com/wwopen/userQRCode?vcode=xxx",
"external_position": "产品经理",
"external_profile": {
"external_corp_name": "企业简称",
"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": "my miniprogram"
}
}
]
}
}RETURN 参数说明
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
userid 成员UserID。对应管理端的帐号，企业内必须唯一。不区分大小写，长度为1~64个字节
name 成员名称，此字段从2019年12月30日起，对新创建第三方应用不再返回，2020年6月30日起，对所有历史第三方应用不再返回，后续第三方仅通讯录应用可获取，第三方页面需要通过通讯录展示组件来展示名字
mobile 手机号码，第三方仅通讯录应用可获取
department 成员所属部门id列表，仅返回该应用有查看权限的部门id
order 部门内的排序值，默认为0。数量必须和department一致，数值越大排序越前面。值范围是[0, 2^32)
position 职务信息；第三方仅通讯录应用可获取
gender 性别。0表示未定义，1表示男性，2表示女性
email 邮箱，第三方仅通讯录应用可获取
is_leader_in_dept 表示在所在的部门内是否为上级。；第三方仅通讯录应用可获取
avatar 头像url。 第三方仅通讯录应用可获取
thumb_avatar 头像缩略图url。第三方仅通讯录应用可获取
telephone 座机。第三方仅通讯录应用可获取
enable 成员启用状态。1表示启用的成员，0表示被禁用。注意，服务商调用接口不会返回此字段
alias 别名；第三方仅通讯录应用可获取
extattr 扩展属性，第三方仅通讯录应用可获取
status 激活状态: 1=已激活，2=已禁用，4=未激活。已激活代表已激活企业微信或已关注微工作台（原企业号）。未激活代表既未激活企业微信又未关注微工作台（原企业号）。
qr_code 员工个人二维码，扫描可添加为外部联系人(注意返回的是一个url，可在浏览器上打开该url以展示二维码)；第三方仅通讯录应用可获取
external_profile 成员对外属性，字段详情见对外属性；第三方仅通讯录应用可获取
external_position 对外职务，如果设置了该值，则以此作为对外展示的职务，否则以position来展示。
address 地址。update(access_token, hash);
更新成员
SYNOPSIS
https://work.weixin.qq.com/api/doc/90000/90135/90197
请求说明：
请求包体:
{
"userid": "zhangsan",
"name": "李四",
"department": [1],
"order": [10],
"position": "后台工程师",
"mobile": "13800000000",
"gender": "1",
"email": "zhangsan@gzdev.com",
"is_leader_in_dept": [1],
"enable": 1,
"avatar_mediaid": "2-G6nrLmr5EC3MNb_-zL1dDdzkd0p7cNliYu9V5w7o8K0",
"telephone": "020-123456",
"alias": "jackzhang",
"address": "广州市海珠区新港中路",
"extattr": {
"attrs": [
{
"type": 0,
"name": "文本名称",
"text": {
"value": "文本"
}
},
{
"type": 1,
"name": "网页名称",
"web": {
"url": "http://www.test.com",
"title": "标题"
}
}
]
},
"external_position": "工程师",
"external_profile": {
"external_corp_name": "企业简称",
"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": "my miniprogram"
}
}
]
}
}参数说明：
参数 必须 说明
access_token 是 调用接口凭证
userid 是 成员UserID。对应管理端的帐号，企业内必须唯一。不区分大小写，长度为1~64个字节
name 否 成员名称。长度为1~64个utf8字符
alias 否 别名。长度为1-32个utf8字符
mobile 否 手机号码。企业内必须唯一。若成员已激活企业微信，则需成员自行修改（此情况下该参数被忽略，但不会报错）
department 否 成员所属部门id列表，不超过20个
order 否 部门内的排序值，默认为0。数量必须和department一致，数值越大排序越前面。有效的值范围是[0, 2^32)
position 否 职务信息。长度为0~128个字符
gender 否 性别。1表示男性，2表示女性
email 否 邮箱。长度不超过64个字节，且为有效的email格式。企业内必须唯一。若是绑定了腾讯企业邮的企业微信，则需要在腾讯企业邮中修改邮箱（此情况下该参数被忽略，但不会报错）
telephone 否 座机。由1-32位的纯数字或’-‘号组成
is_leader_in_dept 否 上级字段，个数必须和department一致，表示在所在的部门内是否为上级。
avatar_mediaid 否 成员头像的mediaid，通过素材管理接口上传图片获得的mediaid
enable 否 启用/禁用成员。1表示启用成员，0表示禁用成员
extattr 否 自定义字段。自定义字段需要先在WEB管理端添加，见扩展属性添加方法，否则忽略未知属性的赋值。与对外属性一致，不过只支持type=0的文本和type=1的网页类型，详细描述查看对外属性
external_profile 否 成员对外属性，字段详情见对外属性
external_position 否 对外职务，如果设置了该值，则以此作为对外展示的职务，否则以position来展示。不超过12个汉字
address 否 地址。长度最大128个字符
特别地，如果userid由系统自动生成，则仅允许修改一次。新值可由new_userid字段指定。权限说明
仅通讯录同步助手或第三方通讯录应用可调用。
注意，每个部门下的部门、成员总数不能超过3万个。
RETURN 返回结果
{
"errcode": 0,
"errmsg": "updated"
}RETURN 参数说明
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容delete(access_token, userid);
删除成员
SYNOPSIS
https://exmail.qq.com/qy_mng_logic/doc#10016
请求说明：
参数说明：
参数 必须 说明
access_token 是 调用接口凭证
userid 是 成员UserID。成员UserID。对应管理端的帐号权限说明
仅通讯录同步助手或第三方通讯录应用可调用。 若是绑定了腾讯企业邮，则会同时删除邮箱帐号。
RETURN 返回结果
{
"errcode": 0,
"errmsg": "deleted"
}RETURN 参数说明
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容batchdelete(access_token, hash);
批量删除成员
SYNOPSIS
https://work.weixin.qq.com/api/doc/90000/90135/90199
请求说明：
请求包结构体为：
{
"useridlist": ["zhangsan", "lisi"]
}参数说明：
参数 必须 说明
access_token 是 调用接口凭证
useridlist 是 成员UserID列表。对应管理端的帐号。最多支持200个。若存在无效UserID，直接返回错误权限说明
仅通讯录同步助手或第三方通讯录应用可调用。RETURN 返回结果
{
"errcode": 0,
"errmsg": "deleted"
}RETURN 参数说明
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容simplelist(access_token, department_id, fetch_child);
获取部门成员
SYNOPSIS
https://work.weixin.qq.com/api/doc/90000/90135/90200
请求说明：
参数说明：
参数 必须 说明
access_token 是 调用接口凭证
department_id 是 获取的部门id
fetch_child 否 是否递归获取子部门下面的成员：1-递归获取，0-只获取本部门权限说明
应用须拥有指定部门的查看权限。
RETURN 返回结果
{
"errcode": 0,
"errmsg": "ok",
"userlist": [
{
"userid": "zhangsan",
"name": "李四",
"department": [1, 2]
}
]
}RETURN 参数说明
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
userlist 成员列表
userid 成员UserID。对应管理端的帐号
name 成员名称，此字段从2019年12月30日起，对新创建第三方应用不再返回，2020年6月30日起，对所有历史第三方应用不再返回，后续第三方仅通讯录应用可获取，第三方页面需要通过通讯录展示组件来展示名字
department 成员所属部门列表。列表项为部门ID，32位整型list(access_token, department_id, fetch_child);
获取部门成员详情
SYNOPSIS
https://work.weixin.qq.com/api/doc/90000/90135/90201
请求说明：
参数说明：
参数 必须 说明
access_token 是 调用接口凭证
department_id 是 获取的部门id
fetch_child 否 1/0：是否递归获取子部门下面的成员权限说明
应用须拥有指定部门的查看权限。
RETURN 返回结果
{
"errcode": 0,
"errmsg": "ok",
"userlist": [
{
"userid": "zhangsan",
"name": "李四",
"department": [1, 2],
"order": [1, 2],
"position": "后台工程师",
"mobile": "13800000000",
"gender": "1",
"email": "zhangsan@gzdev.com",
"is_leader_in_dept": [1, 0],
"avatar": "http://wx.qlogo.cn/mmopen/ajNVdqHZLLA3WJ6DSZUfiakYe37PKnQhBIeOQBO4czqrnZDS79FH5Wm5m4X69TBicnHFlhiafvDwklOpZeXYQQ2icg/0",
"thumb_avatar": "http://wx.qlogo.cn/mmopen/ajNVdqHZLLA3WJ6DSZUfiakYe37PKnQhBIeOQBO4czqrnZDS79FH5Wm5m4X69TBicnHFlhiafvDwklOpZeXYQQ2icg/100",
"telephone": "020-123456",
"enable": 1,
"alias": "jackzhang",
"status": 1,
"address": "广州市海珠区新港中路",
"hide_mobile" : 0,
"english_name" : "jacky",
"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": "企业简称",
"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"
}
}
]
}
}
]
}RETURN 参数说明
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
userlist 成员列表
userid 成员UserID。对应管理端的帐号
name 成员名称，此字段从2019年12月30日起，对新创建第三方应用不再返回，2020年6月30日起，对所有历史第三方应用不再返回，后续第三方仅通讯录应用可获取，第三方页面需要通过通讯录展示组件来展示名字
mobile 手机号码，第三方仅通讯录应用可获取
department 成员所属部门id列表，仅返回该应用有查看权限的部门id
order 部门内的排序值，32位整数，默认为0。数量必须和department一致，数值越大排序越前面。
position 职务信息；第三方仅通讯录应用可获取
gender 性别。0表示未定义，1表示男性，2表示女性
email 邮箱，第三方仅通讯录应用可获取
is_leader_in_dept 表示在所在的部门内是否为上级；第三方仅通讯录应用可获取
avatar 头像url。第三方仅通讯录应用可获取
thumb_avatar 头像缩略图url。第三方仅通讯录应用可获取
telephone 座机。第三方仅通讯录应用可获取
enable 成员启用状态。1表示启用的成员，0表示被禁用。服务商调用接口不会返回此字段
alias 别名；第三方仅通讯录应用可获取
status 激活状态: 1=已激活，2=已禁用，4=未激活 已激活代表已激活企业微信或已关注微工作台（原企业号）。未激活代表既未激活企业微信又未关注微工作台（原企业号）。
extattr 扩展属性，第三方仅通讯录应用可获取
qr_code 员工个人二维码，扫描可添加为外部联系人；第三方仅通讯录应用可获取
external_profile 成员对外属性，字段详情见对外属性；第三方仅通讯录应用可获取
external_position 对外职务。 第三方仅通讯录应用可获取
address 地址
hide_mobile 是否隐藏手机号
english_name 英文名convert_to_openid(access_token, hash);
userid与openid互换: userid转openid
SYNOPSIS
https://work.weixin.qq.com/api/doc/90000/90135/90202
请求说明：
该接口使用场景为企业支付，在使用企业红包和向员工付款时，需要自行将企业微信的userid转成openid。
注：需要成员使用微信登录企业微信或者关注微工作台（原企业号）才能转成openid;
如果是外部联系人，请使用外部联系人openid转换转换openid
请求包结构体为：
{
"userid": "zhangsan"
}参数说明：
参数 必须 说明
access_token 是 调用接口凭证
userid 是 企业内的成员id权限说明
成员必须处于应用的可见范围内RETURN 返回结果
{
"errcode": 0,
"errmsg": "ok",
"openid": "oDjGHs-1yCnGrRovBj2yHij5JAAA"
}RETURN 参数说明
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
openid 企业微信成员userid对应的openidconvert_to_userid(access_token, hash);
userid与openid互换: openid转userid
SYNOPSIS
https://work.weixin.qq.com/api/doc/90000/90135/90202
请求说明：
该接口主要应用于使用企业支付之后的结果查询。
开发者需要知道某个结果事件的openid对应企业微信内成员的信息时，可以通过调用该接口进行转换查询。
请求包结构体为：
{
"openid": "oDjGHs-1yCnGrRovBj2yHij5JAAA"
}参数说明：
参数 必须 说明
access_token 是 调用接口凭证
openid 是 在使用企业支付之后，返回结果的openid权限说明
管理组需对openid对应的企业微信成员有查看权限。RETURN 返回结果
{
"errcode": 0,
"errmsg": "ok",
"userid": "zhangsan"
}RETURN 参数说明
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
userid 该openid在企业微信对应的成员useridauthsucc(access_token, userid);
二次验证
SYNOPSIS
https://work.weixin.qq.com/api/doc/90000/90135/90203
请求说明：
此接口可以满足安全性要求高的企业进行成员加入验证。开启二次验证后，用户加入企业时需要跳转企业自定义的页面进行验证。
企业在开启二次验证时，必须在管理端填写企业二次验证页面的url。
当成员登录企业微信或关注微工作台（原企业号）加入企业时，会自动跳转到企业的验证页面。在跳转到企业的验证页面时，会带上如下参数：code=CODE。
企业收到code后，使用“通讯录同步助手”调用接口“根据code获取成员信息”获取成员的userid。然后在验证成员信息成功后，调用如下接口即可让成员成功加入企业。
参数说明：
参数 必须 说明
access_token 是 调用接口凭证
userid 是 成员UserID。对应管理端的帐号权限说明
RETURN 返回结果
{
"errcode": 0,
"errmsg": "ok"
}RETURN 参数说明
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容getuserinfo(access_token, code);
获取访问用户身份
SYNOPSIS
https://work.weixin.qq.com/api/doc/90000/90135/91023
请求说明：
该接口用于根据code获取成员信息
参数说明：
参数 必须 说明
access_token 是 调用接口凭证
code 是 通过成员授权获取到的code，最大为512字节。每次成员授权带上的code将不一样，code只能使用一次，5分钟未被使用自动过期。权限说明
跳转的域名须完全匹配access_token对应应用的可信域名，否则会返回50001错误。
RETURN 返回结果a
{
"errcode": 0,
"errmsg": "ok",
"UserId":"USERID",
"DeviceId":"DEVICEID"
}RETURN 参数说明a
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
UserId 成员UserID。若需要获得用户详情信息，可调用通讯录接口：读取成员
DeviceId 手机设备号(由企业微信在安装时随机生成，删除重装会改变，升级不受影响)RETURN 返回结果b
{
"errcode": 0,
"errmsg": "ok",
"OpenId":"OPENID",
"DeviceId":"DEVICEID"
}RETURN 参数说明b
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
OpenId 非企业成员的标识，对当前企业唯一
DeviceId 手机设备号(由企业微信在安装时随机生成，删除重装会改变，升级不受影响)get_mobile_hashcode(access_token, hash);
获取手机号随机串
SYNOPSIS
https://work.weixin.qq.com/api/doc/90000/90135/91735
请求说明：
支持企业获取手机号随机串，该随机串可直接在企业微信终端搜索手机号对应的微信用户。
请求包结构体为：
{
"mobile" : "+8613800000000",
"state": "123456"
}参数说明：
参数 必须 说明
access_token 是 调用接口凭证
mobile 是 手机号
state 否 企业自定义的state参数，用于区分不同的添加渠道，在调用“获取外部联系人详情”时会返回该参数值权限说明
仅限自建应用调用。RETURN 返回结果
{
"errcode": 0,
"errmsg": "ok",
"hashcode": "1abcd2xaba3dxab4sdxa"
}RETURN 参数说明
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
hashcode 手机号对应的随机串，20个字节，30分钟内有效