用户资源介绍

用户是通讯录中的基础资源，对应企业组织架构中的成员实体。

基本概念

在调用通讯录 API 之前，建议你了解以下基本概念。

用户 ID

在调用通讯录 API 时，你将会用到用户的多种身份标识，包括 user_id、open_id 和 union_id。

• user_id 是用户在某一租户内的身份标识。
• open_id 是用户在某一应用内的身份标识。
• union_id 是用户在同一应用服务商所开发的多个应用下的身份标识。

你可以根据实际应用场景选择合适的用户 ID。例如，应用服务商想查询当前应用下的某一用户是否在使用其开发的其他应用，则可以通过用户的 union_id 来查询判断。

• 有关用户身份的详细介绍，可参见用户身份概述。
• 如何选择用户 ID，可参见如何选择使用哪种 ID。

用户状态

在调用通讯录 API 时，你可能会查询到用户的多种状态（status 参数，可调用获取单个用户信息、批量获取用户信息接口查询用户状态），包括是否激活、是否暂停、是否离职、是否主动退出、是否未加入。用户的各类状态之间的转换关系如下图所示。

字段说明

名称	类型	描述
user_id	string	租户内用户的唯一标识。user_id 可以自定义设置，也可以由系统随机生成。关于用户 ID 的详细说明，参见用户身份概述。 自定义 user_id 时要遵循以下数据校验规则： - 最大长度：64 字符 - 正则校验：不能包含空格字 示例值："u273y71" 字段权限要求：contact:user.employee_id:readonly 获取用户 user ID
open_id	string	应用内用户的唯一标识，同一用户在不同应用内的 open_id 不同。关于用户 ID 的详细说明，参见用户身份概述。 示例值："ou_7dab8a3d3cdcc9da365777c7ad535d62"
union_id	string	在同一应用服务商所开发的多个应用内用户的唯一标识。应用开发商可以通过用户的 union_id，把其开发的多个应用内的同一个用户关联起来。关于用户 ID 的详细说明，参见用户身份概述。 示例值："on_cad4860e7af114fb4ff6c5d496d1dd76"
name	string	用户名。长度不能超过 255 字符。 示例值："张三" 字段权限要求（满足任一）： contact:user.base:readonly 获取用户基本信息 contact:contact:readonly_as_app 以应用身份读取通讯录
en_name	string	英文名。长度不能超过 255 字符。 示例值："San Zhang" 字段权限要求（满足任一）： contact:user.base:readonly 获取用户基本信息 contact:contact:readonly_as_app 以应用身份读取通讯录
email	string	邮箱。 示例值："zhangsan@gmail.com" 字段权限要求： contact:user.email:readonly 获取用户邮箱信息
mobile	string	手机号。 使用限制： - 在本企业内手机号不可重复。 - 未认证企业仅支持添加中国大陆手机号；通过飞书认证的企业允许添加海外手机号。 示例值："13011111111" 字段权限要求： contact:user.phone:readonly 获取用户手机号
mobile_visible	boolean	手机号码是否可见。 可选值有： - true：可见。 - false：不可见。不可见时，组织员工将无法查看该员工的手机号码。 默认值： true 示例值：false
gender	int	性别。 可选值有： - 0：保密 - 1：男 - 2：女 - 3：其他 字段权限要求（满足任一）： contact:user.gender:readonly 获取用户性别 contact:contact:readonly_as_app 以应用身份读取通讯录 示例值：1
avatar_key	string	头像的文件 Key。你可以通过上传图片接口，上传并获取头像文件 Key。 示例值："2500c7a9-5fff-4d9a-a2de-3d59614ae28g"
department_ids	string\[\]	用户所属部门的 ID 列表。关于部门资源的详细说明，可参见部门资源介绍。 示例值：od-4e6ac4d14bcd5071a37a39de902c7141
leader_user_id	string	用户的直接主管的用户 ID（open_id）。 示例值："ou_7dab8a3d3cdcc9da365777c7ad535d62"
city	string	工作城市。 示例值："杭州" 字段权限要求（满足任一）： contact:user.employee:readonly 获取用户受雇信息 contact:contact:readonly_as_app 以应用身份读取通讯录
country	string	国家或地区。格式为国家或地区缩写 Code，具体参见国家或地区 Code 参照表。 示例值："CN" 字段权限要求（满足任一）： contact:user.employee:readonly 获取用户受雇信息 contact:contact:readonly_as_app 以应用身份读取通讯录
work_station	string	工位。 示例值："北楼-H34" 字段权限要求（满足任一）： contact:user.employee:readonly 获取用户受雇信息 contact:contact:readonly_as_app 以应用身份读取通讯录
join_time	int	入职时间。秒级时间戳格式，表示从 1970 年 1 月 1 日开始所经过的秒数。 示例值：2147483647 字段权限要求（满足任一）： contact:user.employee:readonly 获取用户受雇信息 contact:contact:readonly_as_app 以应用身份读取通讯录
employee_no	string	工号。 示例值："1" 字段权限要求（满足任一）： contact:user.employee:readonly 获取用户受雇信息 contact:contact:readonly_as_app 以应用身份读取通讯录
employee_type	int	员工类型。 可选值有： - 1：正式员工 - 2：实习生 - 3：外包 - 4：劳务 - 5：顾问 同时接口可读取到自定义员工类型的 int 值。你可以调用查询人员类型接口，获取到当前租户内自定义员工类型的名称。 示例值：1
orders	user_order\[\]	用户排序信息。该参数用于标记通讯录下组织架构的人员顺序，人员可能存在多个部门中，且有不同的排序。
∟ department_id	string	排序信息对应的部门 ID。关于部门资源的详细说明，可参见部门资源介绍。 示例值："od-4e6ac4d14bcd5071a37a39de902c7141"
∟ user_order	int	用户在其直属部门内的排序。数值越大，排序越靠前。 示例值：100
∟ department_order	int	用户所属的多个部门之间的排序。数值越大，排序越靠前。 示例值：100
custom_attrs	user_custom_attr\[\]	自定义字段。 字段权限要求（满足任一）： contact:user.employee:readonly 获取用户受雇信息 contact:contact:readonly_as_app 以应用身份读取通讯录
∟ type	string	自定义字段类型 - TEXT：文本 - HREF：网页 - ENUMERATION：枚举 - PICTURE_ENUM：图片 - GENERIC_USER：用户 示例值："TEXT"
∟ id	string	自定义字段 ID。 示例值："DemoId"
∟ value	user_custom_attr_value	自定义字段取值。
∟ text	string	- 字段类型为 TEXT 时，该参数取值为定义的字段值。 - 字段类型为 HREF 时，该参数取值为定义的网页标题。 示例值："DemoText"
∟ url	string	字段类型为 HREF 时，该参数取值为定义的默认 URL。 示例值："http://www.fs.cn"
∟ pc_url	string	字段类型为 HREF 时，该参数取值为定义的 PC 端 URL。 示例值："http://www.fs.cn"
∟ option_id	string	字段类型为 ENUMERATION 或 PICTURE_ENUM 时，该参数取值为定义的选项值。 示例值："edcvfrtg"
∟ generic_user	custom_attr_generic_user	字段类型为 GENERIC_USER 时，该参数取值为定义的引用人员。该类型的自定义字段主要用于在成员名片页展示对另一用户的引用，实现成员名片页之间的跳转。
∟ id	string	被引用的用户的 user_id。 示例值："9b2fabg5"
∟ type	int	用户类型。目前仅支持取值 1，表示用户。 示例值：1
enterprise_email	string	企业邮箱。 注意事项：企业管理员在管理后台启用飞书邮箱服务后，才会生效该参数。 示例值："demo@mail.com" 字段权限要求（满足任一）： contact:user.employee:readonly 获取用户受雇信息 contact:contact:readonly_as_app 以应用身份读取通讯录
job_title	string	职务。 字段权限要求（满足任一）： contact:user.employee:readonly 获取用户受雇信息 contact:contact:readonly_as_app 以应用身份读取通讯录

数据示例

{
    "user_id": "u273y71",
    "open_id": "ou_7dab8a3d3cdcc9da365777c7ad535d62",
    "union_id": "ou_be2c1742f2bb189469bdd33f0b1516ea",
    "name": "张三",
    "en_name": "San Zhang",
    "email": "zhangsan@gmail.com",
    "mobile": "13011111111",
    "mobile_visible": false,
    "gender": 1,
    "avatar_key": "2500c7a9-5fff-4d9a-a2de-3d59614ae28g",
    "department_ids": [
        "od-4e6ac4d14bcd5071a37a39de902c7141"
    ],
    "leader_user_id": "ou_7dab8a3d3cdcc9da365777c7ad535d62",
    "city": "杭州",
    "country": "CN",
    "work_station": "北楼-H34",
    "join_time": 2147483647,
    "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_id": "edcvfrtg",
                "generic_user": {
                    "id": "9b2fabg5",
                    "type": 1
                }
            }
        }
    ],
    "enterprise_email": "demo@mail.com",
    "job_title": "xxxxx"
}