飞书开放平台 Server API 文档

主题

获取单个用户信息 ​

调用该接口获取通讯录中某一用户的信息，包括用户 ID、名称、邮箱、手机号、状态以及所属部门等信息。

注意事项 ​

使用应用身份（tenant_access_token）调用本接口时，响应结果中不会返回部门路径字段（department_path）。因此，如需获取部门路径字段值，请为应用申请 获取成员所在部门路径 API 权限，并使用用户身份（user_access_token）调用接口。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/contact/v3/users/:user_id
HTTP MethodGET
接口频率限制1000 次/分钟、50 次/秒
支持的应用类型custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可contact:contact.base:readonly 获取通讯录基本信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
字段权限要求> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 contact:user.assign_info:read 查询用户席位信息 contact:user.base:readonly 获取用户基本信息 contact:user.department:readonly 获取用户组织架构信息 contact:user.department_path:readonly 获取成员所在部门路径 contact:user.dotted_line_leader_info.read 查看成员的虚线上级 ID contact:user.employee:readonly 获取用户受雇信息 contact:user.employee_number:read 查看成员工号 contact:user.gender:readonly 获取用户性别 contact:user.email:readonly 获取用户邮箱信息 contact:user.user_geo 查看成员数据驻留地 contact:user.employee_id:readonly 获取用户 user ID contact:user.job_level:readonly 查询用户职级 contact:user.phone:readonly 获取用户手机号 contact:user.job_family:readonly 查询用户所属的工作序列 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录

请求头 ​

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

路径参数 ​

名称类型描述
user_idstring用户ID。ID 类型与查询参数 user_id_type 保持一致。
示例值："7be5fg9a"

查询参数 ​

名称类型必填描述
user_id_typestring否用户 ID 类型
示例值：open_id
可选值有：
- open_id: 标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。了解更多：如何获取 Open ID - union_id: 标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。了解更多：如何获取 Union ID？ - user_id: 标识一个用户在某个租户内的身份。同一个用户在租户 A 和租户 B 内的 User ID 是不同的。在同一个租户内，一个用户的 User ID 在所有应用（包括商店应用）中都保持一致。User ID 主要用于在不同的应用间打通用户数据。了解更多：如何获取 User ID？
默认值：open_id
当值为 user_id，字段权限要求： contact:user.employee_id:readonly 获取用户 user ID
department_id_typestring否指定查询结果中的部门 ID 类型。关于部门 ID 的详细介绍，可参见部门 ID 说明。
示例值：open_department_id
可选值有：
- department_id: 支持用户自定义配置的部门 ID。自定义配置时可复用已删除的 department_id，因此在未删除的部门范围内 department_id 具有唯一性。 - open_department_id: 由系统自动生成的部门 ID，ID 前缀固定为 od-，在租户内全局唯一。
默认值：open_department_id

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ useruser用户信息。
    └ 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:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ en_namestring英文名。
字段权限要求（满足任一）： contact:user.base:readonly 获取用户基本信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ nicknamestring别名。
字段权限要求（满足任一）： contact:user.base:readonly 获取用户基本信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ emailstring邮箱。
字段权限要求： contact:user.email:readonly 获取用户邮箱信息
    └ mobilestring手机号。
字段权限要求： contact:user.phone:readonly 获取用户手机号
    └ mobile_visibleboolean手机号码是否可见。
可能值有：
- true：可见。 - false：不可见。不可见时，企业内的员工将无法查看该用户的手机号码。
    └ genderint性别。
可选值有：
- 0: 保密 - 1: 男 - 2: 女 - 3: 其他
字段权限要求（满足任一）： contact:user.gender:readonly 获取用户性别 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ avataravatar_info用户头像信息。
字段权限要求（满足任一）： contact:user.base:readonly 获取用户基本信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_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:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
      └ is_frozenboolean是否为暂停状态。
可能值有：
- true：是 - false：否
      └ is_resignedboolean是否为离职状态。
可能值有：
- true：是 - false：否
      └ is_activatedboolean是否为激活状态。
可能值有：
- true：是 - false：否
      └ is_exitedboolean是否为主动退出状态。主动退出一段时间后用户状态会自动转为已离职。
可能值有：
- true：是 - false：否
      └ is_unjoinboolean是否为未加入状态，需要用户自主确认才能加入企业或团队。
可能值有：
- true：是 - false：否
    └ department_idsstring\[\]用户所属部门的 ID 列表，一个用户可属于多个部门。ID 值的类型与查询参数 department_id_type 的取值保持一致。
字段权限要求（满足任一）： contact:user.department:readonly 获取用户组织架构信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ leader_user_idstring用户的直接主管的用户ID。ID 值的类型与查询参数 user_id_type 的取值保持一致。
字段权限要求（满足任一）： contact:user.department:readonly 获取用户组织架构信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ citystring工作城市。
字段权限要求（满足任一）： contact:user.employee:readonly 获取用户受雇信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ countrystring国家或地区 Code 缩写，具体格式参考 国家/地区 Code 参照表。
字段权限要求（满足任一）： contact:user.employee:readonly 获取用户受雇信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ work_stationstring工位。
字段权限要求（满足任一）： contact:user.employee:readonly 获取用户受雇信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ join_timeint入职时间。秒级时间戳格式，表示从 1970 年 1 月 1 日开始所经过的秒数。
字段权限要求（满足任一）： contact:user.employee:readonly 获取用户受雇信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ is_tenant_managerboolean用户是否为租户超级管理员。
可能值有： - true：是 - false：否
字段权限要求（满足任一）： contact:user.employee:readonly 获取用户受雇信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ employee_nostring工号。
字段权限要求（满足任一）： contact:user.employee_number:read 查看成员工号 contact:user.employee:readonly 获取用户受雇信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ employee_typeint员工类型。
可能值有：
- 1：正式员工 - 2：实习生 - 3：外包 - 4：劳务 - 5：顾问
同时支持自定义员工类型的 int 值。你可通过获取人员类型接口获取到当前租户内自定义员工类型的名称。
字段权限要求（满足任一）： contact:user.employee:readonly 获取用户受雇信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ ordersuser_order\[\]用户排序信息。用于标记通讯录下组织架构的人员顺序，人员可能存在多个部门中，且有不同的排序。
字段权限要求（满足任一）： contact:user.department:readonly 获取用户组织架构信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
      └ department_idstring排序信息对应的部门 ID，表示用户所在的、且需要排序的部门。ID 类型与查询参数 department_id_type 的取值保持一致。
      └ user_orderint用户在其直属部门内的排序。数值越大，排序越靠前。
      └ department_orderint用户所属的多个部门间的排序。数值越大，排序越靠前。
      └ is_primary_deptboolean标识是否为用户的唯一主部门。主部门为用户所属部门中排序第一的部门(department_order 最大)。
可能值有： - true：是 - false：否
    └ custom_attrsuser_custom_attr\[\]自定义字段。了解自定义字段可参见自定义字段资源介绍。
注意事项：当企业管理员在管理后台配置了自定义字段，且开启了 允许开放平台 API 调用 功能后，该字段才会生效。
字段权限要求（满足任一）： contact:user.employee:readonly 获取用户受雇信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_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。
        └ option_valuestring枚举类型中选项的选项值。当返回该值时，还会返回 option_id 参数，取值为枚举值的 ID。
        └ namestring图片类型中图片选项的名称。
        └ picture_urlstring图片类型中图片选项的链接。
        └ generic_usercustom_attr_generic_user字段类型为 GENERIC_USER 时，该参数返回定义的引用人员。
          └ idstring引用人员的用户 ID。ID 类型与查询参数 user_id_type 的取值保持一致。
          └ typeint用户类型。目前固定为 1，表示用户类型。
    └ enterprise_emailstring企业邮箱。 注意事项：企业管理员在管理后台启用飞书邮箱服务后，才会生效该参数。
字段权限要求（满足任一）： contact:user.employee:readonly 获取用户受雇信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ job_titlestring职务。
字段权限要求（满足任一）： contact:user.employee:readonly 获取用户受雇信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ geostring数据驻留地。
字段权限要求： contact:user.user_geo 查看成员数据驻留地
    └ job_level_idstring职级 ID。
字段权限要求： contact:user.job_level:readonly 查询用户职级
    └ job_family_idstring序列 ID。
字段权限要求： contact:user.job_family:readonly 查询用户所属的工作序列
    └ assign_infouser_assign_info\[\]用户席位列表。
字段权限要求： contact:user.assign_info:read 查询用户席位信息
      └ subscription_idstring席位 ID。
      └ license_plan_keystring席位许可（License Plan Key）。
      └ product_namestring席位名称。
      └ i18n_nameproduct_i18n_name国际化名称。
        └ zh_cnstring席位中文名。
        └ ja_jpstring席位日文名。
        └ en_usstring席位英文名。
      └ start_timestring席位起始时间。秒级时间戳格式。
      └ end_timestring席位结束时间。秒级时间戳格式。
    └ department_pathdepartment_detail\[\]部门路径列表。
注意： - 该字段需要通过用户身份（user_access_token）调用接口才可以获取。 - 仅当管理后台 > 组织架构 > 字段管理 > 展示字段 > 名片页 内的 部门 设置为 展示完整部门路径 时，该字段才可以获取到完整部门路径。
字段权限要求： contact:user.department_path:readonly 获取成员所在部门路径
      └ department_idstring部门 ID。ID 类型与查询参数 department_id_type 的取值保持一致。
      └ department_namedepartment_path_name部门名称信息。
        └ namestring部门名。
        └ i18n_namedepartment_i18n_name部门国际化名。
          └ zh_cnstring部门的中文名。
          └ ja_jpstring部门的日文名。
          └ en_usstring部门的英文名。
      └ department_pathdepartment_path部门路径。
        └ department_idsstring\[\]部门路径 ID 列表。
        └ department_path_namedepartment_path_name部门路径名字信息。
          └ namestring部门名。
          └ i18n_namedepartment_i18n_name部门国际化名。
            └ zh_cnstring部门的中文名。
            └ ja_jpstring部门的日文名。
            └ en_usstring部门的英文名。
    └ dotted_line_leader_user_idsstring\[\]虚线上级的用户 ID。ID 类型与查询参数 user_id_type 的取值保持一致。
字段权限要求： contact:user.dotted_line_leader_info.read 查看成员的虚线上级 ID

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "user": {
            "union_id": "on_94a1ee5551019f18cd73d9f111898cf2",
            "user_id": "3e3cf96b",
            "open_id": "ou_7dab8a3d3cdcc9da365777c7ad535d62",
            "name": "张三",
            "en_name": "San Zhang",
            "nickname": "Alex Zhang",
            "email": "zhangsan@gmail.com",
            "mobile": "13011111111",
            "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,
                "is_exited": false,
                "is_unjoin": false
            },
            "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,
                    "is_primary_dept": true
                }
            ],
            "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",
            "geo": "cn",
            "job_level_id": "mga5oa8ayjlp9rb",
            "job_family_id": "mga5oa8ayjlp9rb",
            "assign_info": [
                {
                    "subscription_id": "7079609167680782300",
                    "license_plan_key": "suite_enterprise_e5",
                    "product_name": "旗舰版 E5",
                    "i18n_name": {
                        "zh_cn": "zh_cn_name",
                        "ja_jp": "ja_jp_name",
                        "en_us": "en_name"
                    },
                    "start_time": "1674981000",
                    "end_time": "1674991000"
                }
            ],
            "department_path": [
                {
                    "department_id": "od-4e6ac4d14bcd5071a37a39de902c7141",
                    "department_name": {
                        "name": "测试部门名1",
                        "i18n_name": {
                            "zh_cn": "测试部门名1",
                            "ja_jp": "試験部署名 1",
                            "en_us": "Testing department name 1"
                        }
                    },
                    "department_path": {
                        "department_ids": [
                            "od-4e6ac4d14bcd5071a37a39de902c7141"
                        ],
                        "department_path_name": {
                            "name": "测试部门名1",
                            "i18n_name": {
                                "zh_cn": "测试部门名1",
                                "ja_jp": "試験部署名 1",
                                "en_us": "Testing department name 1"
                            }
                        }
                    }
                }
            ],
            "dotted_line_leader_user_ids": [
                "ou_7dab8a3d3cdcc9da365777c7ad535d62"
            ]
        }
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
40041050no user authority无用户权限。需将当前操作的用户添加到应用或用户的权限范围内。根据调用 API 的身份不同，解决方案也不同，具体说明如下： - 使用 tenant_access_token 调用 API 当前操作的用户需要添加在应用的通讯录权限范围内。通讯录权限范围定义了应用在调用通讯录 API 时可获取的部门、用户的数据范围。应用无法访问不在通讯录权限范围内的数据。 由开发者登录开发者后台，在应用详情页的 开发配置 > 权限管理 > 数据权限 页面内，配置 通讯录权限范围，添加指定用户。 image.png 已发布的应用企业管理员可在管理后台 > 工作台 > 应用管理 页面，修改应用的通讯录权限范围。 image.png - 使用 user_access_token 调用 API 当你使用用户身份调用通讯录 API 时，可操作的权限范围不受应用的通讯录权限范围影响，而是受当前用户的组织架构可见范围影响，该范围限制了用户在企业内可见的组织架构数据范围。 由企业管理员在管理后台 > 安全 > 成员权限 页面中，点击 组织架构可见范围 进行管理。 image.png 完整介绍参见权限范围资源介绍。
40040001invalid parameter参数错误。你需要检查输入参数是否有问题，如果仍然无法解决，请咨询技术支持。
40041012user id invalid error用户 ID 无效。你可以通过以下接口获取指定用户的用户 ID，然后使用正确的用户 ID 再次尝试调用接口。 - 搜索用户 - 通过手机号或邮箱获取用户 ID
40040003internal error内部错误。请联系技术支持并提供请求头 X-Request-Id。

更多错误码信息，参见通用错误码。

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

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