飞书开放平台 Server API 文档

主题

获取用户列表 ​

基于部门ID获取部门下直属用户列表。 常见问题答疑。

Warning: 本接口已为历史版本，不再维护更新，不推荐使用。推荐你使用获取部门直属用户列表接口。

Tip: - 使用 user_access_token 情况下根据个人组织架构的通讯录可见范围进行权限过滤，返回个人组织架构通讯录范围（登陆企业管理后台进行权限配置）内可见的用户数据。

  • tenant_access_token 基于应用通讯录范围进行权限鉴定。由于 department_id 是非必填参数，填与不填存在两种数据权限校验与返回情况：1、请求设置了 department_id （根部门为0），会检验所带部门ID是否具有通讯录权限（如果带上 department_id=0 会校验是否有全员权限），有则返回部门下直属的成员列表, 否则提示无部门权限的错误码返回。2、请求未带 department_id 参数，则会返回权限范围内的独立用户（权限范围直接包含了某用户，则该用户视为权限范围内的独立用户）。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/contact/v3/users
HTTP MethodGET
支持的应用类型custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可contact:department.organize:readonly 获取部门组织架构信息 contact:contact:readonly_as_app 以应用身份读取通讯录 contact:contact:readonly 读取通讯录 contact:contact:access_as_app 以应用身份访问通讯录
字段权限要求> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 contact:user.base:readonly 获取用户基本信息 contact:contact:readonly_as_app 以应用身份读取通讯录 contact:user.employee:readonly 获取用户雇佣信息 contact:user.department:readonly 获取用户组织架构信息 contact:user.gender:readonly 获取用户性别 contact:user.email:readonly 获取用户邮箱信息 contact:user.phone:readonly 获取用户手机号 contact:user.employee_id:readonly 获取用户 user ID contact:contact:readonly 读取通讯录 contact:contact:access_as_app 以应用身份访问通讯录

请求头 ​

名称类型必填描述
Authorizationstring是tenant_access_token 或 user_access_token 值格式："Bearer access_token" 示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token

查询参数 ​

名称类型必填描述
user_id_typestring否用户 ID 类型 示例值："open_id" 可选值有： - open_id：用户的 open id - union_id：用户的 union id - user_id：用户的 user id 默认值：open_id 当值为 user_id，字段权限要求： contact:user.employee_id:readonly 获取用户 user ID
department_id_typestring否此次调用中使用的部门ID的类型 示例值："open_department_id" 可选值有： - department_id：以自定义department_id来标识部门 - open_department_id：以open_department_id来标识部门 默认值：open_department_id
department_idstring否填写该字段表示获取部门下所有用户，选填。 示例值："od-xxxxxxxxxxxxx"
page_tokenstring否分页标记，第一次请求不填，表示从头开始遍历；分页查询结果还有更多项时会同时返回新的 page_token，下次遍历可采用该 page_token 获取查询结果 示例值："AQD9/Rn9eij9Pm39ED40/dk53s4Ebp882DYfFaPFbz00L4CMZJrqGdzNyc8BcZtDbwVUvRmQTvyMYicnGWrde9X56TgdBuS%2BJKiSIkdexPw="
page_sizeint否分页大小 示例值：10 数据校验规则： - 最大值：100

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
∟ has_moreboolean是否还有更多项
∟ page_tokenstring分页标记，当 has_more 为 true 时，会同时返回新的 page_token，否则不返回 page_token
∟ itemsuser\[\]-
∟ union_idstring用户的 union_id，应用开发商发布的不同应用中同一用户的标识。关于用户 ID 的说明可参见 用户相关的 ID 概念。
∟ user_idstring用户的 user_id，租户内用户的唯一标识。关于用户 ID 的说明可参见 用户相关的 ID 概念。 字段权限要求： contact:user.employee_id:readonly 获取用户 user ID
∟ open_idstring用户的 open_id，应用内用户的唯一标识。关于用户 ID 的说明可参见 用户相关的 ID 概念。
∟ namestring用户名。 字段权限要求（满足任一）： contact:user.base:readonly 获取用户基本信息 contact:contact:readonly_as_app 以应用身份读取通讯录 contact:contact:readonly 读取通讯录 contact:contact:access_as_app 以应用身份访问通讯录
∟ en_namestring英文名。 字段权限要求（满足任一）： contact:user.base:readonly 获取用户基本信息 contact:contact:readonly_as_app 以应用身份读取通讯录 contact:contact:readonly 读取通讯录 contact:contact:access_as_app 以应用身份访问通讯录
∟ emailstring邮箱。 字段权限要求： contact:user.email:readonly 获取用户邮箱信息
∟ mobilestring手机号。 字段权限要求： contact:user.phone:readonly 获取用户手机号
∟ mobile_visibleboolean手机号码可见性，true 为可见，false 为不可见，目前默认为 true。不可见时，组织员工将无法查看该员工的手机号码
∟ genderint性别。 可选值有： - 0：保密。 - 1：男。 - 2：女。 字段权限要求（满足任一）： contact:user.gender:readonly 获取用户性别 contact:contact:readonly_as_app 以应用身份读取通讯录 contact:contact:readonly 读取通讯录 contact:contact:access_as_app 以应用身份访问通讯录
∟ avataravatar_info用户头像信息。 字段权限要求（满足任一）： contact:user.base:readonly 获取用户基本信息 contact:contact:readonly_as_app 以应用身份读取通讯录 contact:contact:readonly 读取通讯录 contact:contact:access_as_app 以应用身份访问通讯录
∟ avatar_72string72*72 像素头像链接。
∟ avatar_240string240*240 像素头像链接。
∟ avatar_640string640*640 像素头像链接。
∟ avatar_originstring原始头像链接。
∟ statususer_status用户状态。通过 is_frozen、is_resigned、is_activated、is_exited 布尔值类型参数进行展示。 用户状态的流转逻辑可参见用户资源介绍。 字段权限要求（满足任一）： contact:user.employee:readonly 获取用户雇佣信息 contact:contact:readonly_as_app 以应用身份读取通讯录 contact:contact:readonly 读取通讯录 contact:contact:access_as_app 以应用身份访问通讯录
∟ is_frozenboolean是否为暂停状态。 可能值有： - true：是 - false：否
∟ is_resignedboolean是否为离职状态。 可能值有： - true：是 - false：否
∟ is_activatedboolean是否为激活状态。 可能值有： - true：是 - false：否
∟ department_idsstring\[\]用户所属部门的ID列表，一个用户可属于多个部门。 ID值的类型与查询参数中的department_id_type 对应。 不同 ID 的说明与department_id的获取方式参见 部门ID说明 字段权限要求（满足任一）： contact:user.department:readonly 获取用户组织架构信息 contact:contact:readonly_as_app 以应用身份读取通讯录 contact:contact:readonly 读取通讯录 contact:contact:access_as_app 以应用身份访问通讯录
∟ leader_user_idstring用户的直接主管的 open_id。 关于用户 ID 的说明可参见 用户相关的 ID 概念。 字段权限要求（满足任一）： contact:user.department:readonly 获取用户组织架构信息 contact:contact:readonly_as_app 以应用身份读取通讯录 contact:contact:readonly 读取通讯录 contact:contact:access_as_app 以应用身份访问通讯录
∟ citystring工作城市。 字段权限要求（满足任一）： contact:user.employee:readonly 获取用户雇佣信息 contact:contact:readonly_as_app 以应用身份读取通讯录 contact:contact:readonly 读取通讯录 contact:contact:access_as_app 以应用身份访问通讯录
∟ countrystring国家或地区 Code 缩写。具体格式可参见 国家/地区码表。 字段权限要求（满足任一）： contact:user.employee:readonly 获取用户雇佣信息 contact:contact:readonly_as_app 以应用身份读取通讯录 contact:contact:readonly 读取通讯录 contact:contact:access_as_app 以应用身份访问通讯录
∟ work_stationstring工位。 字段权限要求（满足任一）： contact:user.employee:readonly 获取用户雇佣信息 contact:contact:readonly_as_app 以应用身份读取通讯录 contact:contact:readonly 读取通讯录 contact:contact:access_as_app 以应用身份访问通讯录
∟ join_timeint入职时间。秒级时间戳格式，表示从 1970 年 1 月 1 日开始所经过的秒数。 字段权限要求（满足任一）： contact:user.employee:readonly 获取用户雇佣信息 contact:contact:readonly_as_app 以应用身份读取通讯录 contact:contact:readonly 读取通讯录 contact:contact:access_as_app 以应用身份访问通讯录
∟ is_tenant_managerboolean是否是租户超级管理员 字段权限要求（满足任一）： contact:user.employee:readonly 获取用户雇佣信息 contact:contact:readonly_as_app 以应用身份读取通讯录 contact:contact:readonly 读取通讯录 contact:contact:access_as_app 以应用身份访问通讯录
∟ employee_nostring工号。 字段权限要求（满足任一）： contact:user.employee:readonly 获取用户雇佣信息 contact:contact:readonly_as_app 以应用身份读取通讯录 contact:contact:readonly 读取通讯录 contact:contact:access_as_app 以应用身份访问通讯录
∟ employee_typeint员工类型。 可能值有： - 1：正式员工 - 2：实习生 - 3：外包 - 4：劳务 - 5：顾问 同时可读取到自定义员工类型的 int 值，通过 int 值调用获取人员类型接口，进而获取到该租户的自定义员工类型的名称。 字段权限要求（满足任一）： contact:user.employee:readonly 获取用户雇佣信息 contact:contact:readonly_as_app 以应用身份读取通讯录 contact:contact:readonly 读取通讯录 contact:contact:access_as_app 以应用身份访问通讯录
∟ ordersuser_order\[\]用户排序信息。 用于标记通讯录下组织架构的人员顺序，人员可能存在多个部门中，且有不同的排序。 字段权限要求（满足任一）： contact:user.department:readonly 获取用户组织架构信息 contact:contact:readonly_as_app 以应用身份读取通讯录 contact:contact:readonly 读取通讯录 contact:contact:access_as_app 以应用身份访问通讯录
∟ department_idstring排序信息对应的部门 ID，表示用户所在的、且需要排序的部门。该 ID 均包含在用户所属部门 ID 列表（department_ids）的参数值当中。
∟ user_orderint用户在其直属部门内的排序，数值越大，排序越靠前。
∟ department_orderint用户所属的多个部门间的排序，数值越大，排序越靠前。
∟ custom_attrsuser_custom_attr\[\]自定义字段。如果企业管理员已在管理后台 > 组织架构 > 成员字段管理 > 自定义字段管理 > 全局设置中开启了 允许开放平台 API 调用，则该字段生效。 更多信息可参见用户接口相关问题。 字段权限要求（满足任一）： contact:user.employee:readonly 获取用户雇佣信息 contact:contact:readonly_as_app 以应用身份读取通讯录 contact:contact:readonly 读取通讯录 contact:contact:access_as_app 以应用身份访问通讯录
∟ typestring自定义字段类型。 可能值有： - TEXT：文本 - HREF：网页 - ENUMERATION：枚举 - PICTURE_ENUM：图片 - GENERIC_USER：用户
∟ idstring自定义字段 ID。
∟ valueuser_custom_attr_value自定义字段取值。
∟ textstring- 字段类型为 TEXT 时，该参数返回定义的字段值。 - 字段类型为 HREF 时，该参数返回定义的网页标题。
∟ urlstring字段类型为 HREF 时，该参数返回定义的默认 URL。
∟ pc_urlstring字段类型为 HREF 时，如果为 PC 端设置了 URL，则该参数返回定义的 PC 端 URL。
∟ option_valuestring选项类型的值，即用户详情或自定义字段中选中的选项值。
∟ namestring选项类型为图片时，图片的名称。
∟ picture_urlstring选项类型为图片时，图片的链接。
∟ generic_usercustom_attr_generic_user字段类型为 GENERIC_USER 时，该参数返回定义的引用人员信息。
∟ idstring引用人员的 user_id。关于用户 ID 的具体说明可参见用户相关的 ID 概念。
∟ typeint用户类型。目前固定取值为 1，表示用户。
∟ enterprise_emailstring企业邮箱。如果企业管理员已在管理后台启用飞书邮箱服务，则会返回该值。 字段权限要求（满足任一）： contact:user.employee:readonly 获取用户雇佣信息 contact:contact:readonly_as_app 以应用身份读取通讯录 contact:contact:readonly 读取通讯录 contact:contact:access_as_app 以应用身份访问通讯录
∟ job_titlestring职务。 字段权限要求（满足任一）： contact:user.employee:readonly 获取用户雇佣信息 contact:contact:readonly_as_app 以应用身份读取通讯录 contact:contact:readonly 读取通讯录 contact:contact:access_as_app 以应用身份访问通讯录

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "has_more": false,
        "page_token": "AQD9/Rn9eij9Pm39ED40/RD/cIFmu77WxpxPB/2oHfQLZ%2BG8JG6tK7%2BZnHiT7COhD2hMSICh/eBl7cpzU6JEC3J7COKNe4jrQ8ExwBCR",
        "items": [
            {
                "union_id": "on_94a1ee5551019f18cd73d9f111898cf2",
                "user_id": "3e3cf96b",
                "open_id": "ou_7dab8a3d3cdcc9da365777c7ad535d62",
                "name": "张三",
                "en_name": "San Zhang",
                "email": "zhangsan@gmail.com",
                "mobile": "130xxxx1111",
                "mobile_visible": false,
                "gender": 1,
                "avatar": {
                    "avatar_72": "https://foo.icon.com/xxxx",
                    "avatar_240": "https://foo.icon.com/xxxx",
                    "avatar_640": "https://foo.icon.com/xxxx",
                    "avatar_origin": "https://foo.icon.com/xxxx"
                },
                "status": {
                    "is_frozen": false,
                    "is_resigned": false,
                    "is_activated": true
                },
                "department_ids": [
                    "od-4e6ac4d14bcd5071a37a39de902c7141"
                ],
                "leader_user_id": "ou_7dab8a3d3cdcc9da365777c7ad535d62",
                "city": "杭州",
                "country": "CN",
                "work_station": "北楼-H34",
                "join_time": 2147483647,
                "is_tenant_manager": false,
                "employee_no": "1",
                "employee_type": 1,
                "orders": [
                    {
                        "department_id": "od-4e6ac4d14bcd5071a37a39de902c7141",
                        "user_order": 100,
                        "department_order": 100
                    }
                ],
                "custom_attrs": [
                    {
                        "type": "TEXT",
                        "id": "DemoId",
                        "value": {
                            "text": "DemoText",
                            "url": "http://www.fs.cn",
                            "pc_url": "http://www.fs.cn",
                            "option_value": "option",
                            "name": "name",
                            "picture_url": "https://xxxxxxxxxxxxxxxxxx",
                            "generic_user": {
                                "id": "9b2fabg5",
                                "type": 1
                            }
                        }
                    }
                ],
                "enterprise_email": "demo@mail.com",
                "job_title": "xxxxx"
            }
        ]
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
40041050no user authority error操作的用户需在通讯录权限范围中，了解更多
40040011page size is invalid无效的分页参数
40040012page token is invalid errorpage token无效。
40340004no dept authority error操作的部门需在通讯录权限范围中，了解更多

内容来源：飞书开放平台 · 自动爬取整理

本镜像仅供学习与查阅，文档版权归飞书所有