获取部门成员详情

GET

/cgi-bin/user/list

服务端API企业内部开发第三方应用开发智慧硬件开发

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

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

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

如需获取该部门及其子部门的所有成员，需先获取该部门下的子部门，然后再获取子部门下的部门成员，逐层递归获取。

权限说明：

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

请求示例

Shell

JavaScript

Java

Swift

curl --location -g --request GET 'https://qyapi.weixin.qq.com/cgi-bin/user/list?access_token=&department_id={{department_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",
        "wangwu"
      ],
      "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"
            }
          }
        ]
      }
    }
  ]
}

请求参数

Query 参数

access_token

调用接口凭证

必需

示例值:

fetch_child

可选

1/0：是否递归获取子部门下面的成员

示例值:

department_id

获取的部门id

必需

示例值:

返回响应

🟢200成功

application/json

Body

errcode

integer

返回码

必需

errmsg

string

必需

对返回码的文本描述内容

userlist

array [object {24}]

成员列表

必需

userid

string

可选

成员UserID。对应管理端的帐号

name

string

可选

成员名称；第三方不可获取，调用时返回userid以代替name；代开发自建应用需要管理员授权才返回；对于非第三方创建的成员，第三方通讯录应用也不可获取；未返回名称的情况需要通过通讯录展示组件来展示名字

department

array[integer]

可选

成员所属部门id列表，仅返回该应用有查看权限的部门id。对授权了“组织架构信息”的第三方应用，返回成员所属的全部部门id列表

order

array[integer]

可选

部门内的排序值，默认为0。数量必须和department一致，数值越大排序越前面。值范围是[0, 2^32)

position

string

可选

职务信息；代开发自建应用需要管理员授权才返回；第三方仅通讯录应用可获取；对于非第三方创建的成员，第三方通讯录应用也不可获取；上游企业不可获取下游企业成员该字段

mobile

string

可选

手机号码，代开发自建应用需要管理员授权才返回；第三方仅通讯录应用可获取；对于非第三方创建的成员，第三方通讯录应用也不可获取；上游企业不可获取下游企业成员该字段

gender

string

可选

性别。0表示未定义，1表示男性，2表示女性。第三方仅通讯录应用可获取；对于非第三方创建的成员，第三方通讯录应用也不可获取；上游企业不可获取下游企业成员该字段。注：不可获取指返回值为0

string

可选

邮箱，代开发自建应用需要管理员授权才返回；第三方仅通讯录应用可获取；对于非第三方创建的成员，第三方通讯录应用也不可获取；上游企业不可获取下游企业成员该字段

biz_mail

string

可选

企业邮箱，代开发自建应用不返回；第三方仅通讯录应用可获取；对于非第三方创建的成员，第三方通讯录应用也不可获取；上游企业不可获取下游企业成员该字段

is_leader_in_dept

array[integer]

可选

表示在所在的部门内是否为部门负责人。0-否；1-是。是一个列表，数量必须与department一致。第三方通讯录应用或者授权了“组织架构信息-应用可获取企业的部门组织架构信息-部门负责人”权限的第三方应用可获取；对于非第三方创建的成员，第三方通讯录应用不可获取；上游企业不可获取下游企业成员该字段

direct_leader

array[string]

可选

直属上级UserID，返回在应用可见范围内的直属上级列表，最多有五个直属上级；第三方通讯录应用或者授权了“组织架构信息-应用可获取可见范围内成员组织架构信息-直属上级”权限的第三方应用可获取；对于非第三方创建的成员，第三方通讯录应用不可获取；上游企业不可获取下游企业成员该字段；代开发自建应用不可获取该字段

avatar

string

可选

头像url。第三方仅通讯录应用可获取；对于非第三方创建的成员，第三方通讯录应用也不可获取；上游企业不可获取下游企业成员该字段

thumb_avatar

string

可选

头像缩略图url。第三方仅通讯录应用可获取；对于非第三方创建的成员，第三方通讯录应用也不可获取；上游企业不可获取下游企业成员该字段

telephone

string

可选

座机。代开发自建应用需要管理员授权才返回；第三方仅通讯录应用可获取；对于非第三方创建的成员，第三方通讯录应用也不可获取；上游企业不可获取下游企业成员该字段

alias

string

可选

别名；第三方仅通讯录应用可获取；对于非第三方创建的成员，第三方通讯录应用也不可获取；上游企业不可获取下游企业成员该字段

status

integer

可选

激活状态: 1=已激活，2=已禁用，4=未激活，5=退出企业。已激活代表已激活企业微信或已关注微信插件（原企业号）。未激活代表既未激活企业微信又未关注微信插件（原企业号）。

address

string

可选

地址。代开发自建应用需要管理员授权才返回；第三方仅通讯录应用可获取；对于非第三方创建的成员，第三方通讯录应用也不可获取；上游企业不可获取下游企业成员该字段

english_name

string

可选

open_userid

string

可选

全局唯一。对于同一个服务商，不同应用获取到企业内同一个成员的open_userid是相同的，最多64个字节。仅第三方应用可获取

main_department

integer

可选

主部门，仅当应用对主部门有查看权限时返回。

extattr

object

可选

扩展属性，代开发自建应用需要管理员授权才返回；第三方仅通讯录应用可获取；对于非第三方创建的成员，第三方通讯录应用也不可获取；上游企业不可获取下游企业成员该字段

qr_code

string

可选

员工个人二维码，扫描可添加为外部联系人(注意返回的是一个url，可在浏览器上打开该url以展示二维码)；第三方仅通讯录应用可获取；对于非第三方创建的成员，第三方通讯录应用也不可获取；上游企业不可获取下游企业成员该字段

external_position

string

可选

对外职务，如果设置了该值，则以此作为对外展示的职务，否则以position来展示。代开发自建应用需要管理员授权才返回；第三方仅通讯录应用可获取；对于非第三方创建的成员，第三方通讯录应用也不可获取；上游企业不可获取下游企业成员该字段

external_profile

object

可选

成员对外属性，字段详情见对外属性；代开发自建应用需要管理员授权才返回；第三方仅通讯录应用可获取；对于非第三方创建的成员，第三方通讯录应用也不可获取；上游企业不可获取下游企业成员该字段

修改于 2022-12-06 06:36:37

获取部门成员

userid与openid互换-userid转openid