飞书开放平台 Server API 文档

主题

资源介绍 ​

员工指飞书企业内身份为「Employee」的成员，等同于通讯录OpenAPI中的「User」。

员工在飞书的身份标识包括employee_id、open_id 和 union_id，其中employee_id的值等同于通讯录中的 user_id，其余两个也和通讯录的User的值相同。有关员工各类ID的详细介绍，参考 用户身份概述。

员工生命周期流转的逻辑与通讯录的User一致，见下图：

image.png

字段说明 ​

名称类型描述
base_infoemployee_base_entity员工基础信息
  └ employee_idstring企业内在职员工的唯一标识，与employee_id_type类型保持一致。注：当 required_fields 字段未指定获取 employee_id 时，系统会返回无意义的 ID；若需获取该字段的值，请在 required_fields 中添加对应的字段名称。 获取employee_id的方式： - 企业管理员在 管理后台 > 组织架构 > 成员与部门 页面，点击 成员详情，查询员工ID - 通过 批量获取员工列表 的接口，通过手机号或邮箱查询员工ID。 employee_id_type为open_id或者union_id时无需权限，使用employee_id类型时，权限要求如下字段权限要求： directory:employee.base.external_id:read 查看员工自定义 ID
  └ namename姓名
    └ namei18n_text员工的姓名
字段权限要求（满足任一）： directory:employee.base.base:read 查看员工个人基本信息 directory:employee.base.name.name:read 查看员工的姓名
      └ default_valuestring默认值
      └ i18n_valuemap<string, string>国际化值，key为zh_cn, ja_jp, en_us, value为对应的值
    └ another_namestring别名
字段权限要求（满足任一）： directory:employee.base.base:read 查看员工个人基本信息 directory:employee.base.name.another_name:read 查看员工的别名
  └ mobilestring员工的手机号。注意： 1. 在企业内的在职员工中不可重复。 2. 未认证企业仅支持添加中国大陆手机号，通过飞书认证的企业允许添加海外手机号。 3. 国际电话区号前缀中必须包含加号 +。
字段权限要求： directory:employee.base.mobile:read 查看员工手机号
  └ emailstring员工在工作中的邮箱。注意： 1. 在企业内的在职员工中不可重复。 2. 非中国大陆手机号成员必须同时添加邮箱。
字段权限要求： directory:employee.base.email:read 查看员工联系邮箱
  └ enterprise_emailstring企业邮箱
字段权限要求： directory:employee.base.enterprise_email:read 查看员工企业邮箱
  └ genderint性别
可选值有：
- 0: 未知 - 1: 男 - 2: 女 - 3: 其他
字段权限要求： directory:employee.base.gender:read 查看员工性别
  └ departmentsdepartment\[\]员工所属的部门信息。一个员工可属于多个部门，排在第一个的为主部门
字段权限要求： directory:employee.base.department:read 查看员工所属部门信息
    └ department_idstring部门ID
字段权限要求（满足任一）： directory:department.base:read 查看部门基础信息 directory:department.external_id:read 查看部门自定义 ID
    └ department_countdepartment_count部门成员与子部门计数
字段权限要求（满足任一）： directory:department.count:read 查看部门成员与子部门计数 directory:department.organization:read 查看部门组织架构信息
      └ recursive_members_countstring递归成员数量
      └ direct_members_countstring直属成员数量
      └ recursive_members_count_exclude_leadersstring递归成员数量(不含leader)
      └ recursive_departments_countstring递归子部门数量
      └ direct_departments_countstring直属子部门数量
    └ has_childboolean是否有子部门
字段权限要求（满足任一）： directory:department.has_child:read 查看部门是否有子部门 directory:department.organization:read 查看部门组织架构信息
    └ leadersdepartment_leader\[\]部门负责人
字段权限要求： directory:department.leader:read 查看部门负责人信息
      └ leader_typeint部门负责人类型
可选值有：
- 1: 主 - 2: 副
      └ leader_idstring部门负责人ID
    └ parent_department_idstring父部门ID
字段权限要求（满足任一）： directory:department.organization:read 查看部门组织架构信息 directory:department.parent_id:read 查看部门的父部门 ID
    └ namei18n_text部门名称
字段权限要求（满足任一）： directory:department.base:read 查看部门基础信息 directory:department.name:read 查看部门的名称
      └ default_valuestring默认值
      └ i18n_valuemap<string, string>国际化值，key为zh_cn, ja_jp, en_us, value为对应的值
    └ enabled_statusboolean是否启用
字段权限要求： directory:department.status:read 查看部门的停启用状态
    └ order_weightstring部门排序权重
字段权限要求（满足任一）： directory:department.order_weight:read 查看部门排序权重 directory:department.organization:read 查看部门组织架构信息
    └ custom_field_valuescustom_field_value\[\]自定义字段
字段权限要求： directory:department.custom_field:read 查看部门自定义字段信息
      └ field_keystring自定义字段key
      └ field_typestring自定义字段类型
可选值有：
- 1: 多行文本 - 2: 网页链接 - 3: 枚举选项 - 4: 人员 - 10: 多选枚举类型(目前仅支持文本类型) - 11: 人员列表
      └ text_valuei18n_text文本字段值
        └ default_valuestring默认值
        └ i18n_valuemap<string, string>国际化值，key为zh_cn, ja_jp, en_us, value为对应的值
      └ url_valueurl_value网页链接字段值
        └ link_texti18n_text网页标题
          └ default_valuestring默认值
          └ i18n_valuemap<string, string>国际化值，key为zh_cn, ja_jp, en_us, value为对应的值
        └ urlstring移动端网页链接
        └ pcurlstring桌面端网页链接
      └ enum_valueenum_value枚举
        └ enum_idsstring\[\]选项结果ID
        └ enum_typestring选项类型
可选值有：
- 1: 文本 - 2: 图片
      └ user_valuesuser_value\[\]人员字段值
        └ idsstring\[\]人员ID
        └ user_typestring人员类型
可选值有：
- 1: 员工
    └ department_path_infosdepartment_base_info\[\]部门路径信息，排列顺序为根部门到末级部门
字段权限要求： directory:department.department_path:read 查看部门路径信息
      └ department_idstring部门ID
      └ department_namei18n_text部门名称
        └ default_valuestring默认值
        └ i18n_valuemap<string, string>国际化值，key为zh_cn, ja_jp, en_us, value为对应的值
    └ data_sourceint数据来源
可选值有：
- 1: 管理后台 - 2: 人事企业版 - 3: SCIM
字段权限要求（满足任一）： directory:department.base:read 查看部门基础信息 directory:department.data_source:read 查看部门数据来源
  └ employee_order_in_departmentsuser_department_sort_info\[\]用户在部门内的排序信息， 第一个部门为主部门
字段权限要求（满足任一）： directory:employee.base.department:read 查看员工所属部门信息 directory:employee.base.dept_order:read 查看员工在部门内的排序
    └ department_idstring部门id
    └ order_weight_in_deparmentstring用户在部门内的排序权重
    └ order_weight_among_deparmentsstring用户多个部门间的排序权重
  └ descriptionstring个人签名
字段权限要求（满足任一）： directory:employee.base.base:read 查看员工个人基本信息 directory:employee.base.description:read 查看员工的个性签名
  └ active_statusint员工的账号活跃状态
可选值有：
- 1: 未激活 - 2: 激活 - 3: 冻结 - 4: 主动退出 - 5: 未加入
字段权限要求（满足任一）： directory:employee.base.active_status:read 查看员工账号活跃状态 directory:employee.base.status:read 查看员工状态信息
  └ is_resignedboolean是否离职
字段权限要求（满足任一）： directory:employee.base.is_resigned:read 查看员工离职状态 directory:employee.base.status:read 查看员工状态信息
  └ leader_idstring员工的直属上级ID
字段权限要求（满足任一）： directory:employee.base.leader:read 查看员工上级信息 directory:employee.base.leader_id:read 查看员工直属上级 ID
  └ dotted_line_leader_idsstring\[\]员工的虚线上级ID
字段权限要求（满足任一）： directory:employee.base.dotted_line_leaders:read 查看员工虚线上级 ID directory:employee.base.leader:read 查看员工上级信息
  └ is_primary_adminboolean是否租户超级管理员
字段权限要求（满足任一）： directory:employee.base.is_primary_admin:read 查看员工是否是超级管理员 directory:employee.base.role:read 查看员工角色信息
  └ enterprise_email_aliasesstring\[\]员工的企业邮箱别名。当成员希望针对不同人使用不同的邮箱地址进行邮件往来时，可为其企业邮箱添加别名。添加后，成员可使用别名发送邮件，也可接受发送至别名的邮件。
字段权限要求（满足任一）： directory:employee.base.enterprise_email:read 查看员工企业邮箱 directory:employee.base.enterprise_email_alias:read 查看员工的企业邮箱别名
  └ custom_field_valuescustom_field_value\[\]自定义字段值
字段权限要求： directory:employee.base.custom_field:read 查看员工自定义字段值
    └ field_keystring自定义字段key
    └ field_typestring自定义字段类型
可选值有：
- 1: 多行文本 - 2: 网页链接 - 3: 枚举选项 - 4: 人员 - 10: 多选枚举类型(目前仅支持文本类型) - 11: 人员列表
    └ text_valuei18n_text文本字段值
      └ default_valuestring默认值
      └ i18n_valuemap<string, string>国际化值，key为zh_cn, ja_jp, en_us, value为对应的值
    └ url_valueurl_value网页链接字段值
      └ link_texti18n_text网页标题
        └ default_valuestring默认值
        └ i18n_valuemap<string, string>国际化值，key为zh_cn, ja_jp, en_us, value为对应的值
      └ urlstring移动端网页链接
      └ pcurlstring桌面端网页链接
    └ enum_valueenum_value枚举
      └ enum_idsstring\[\]选项结果ID
      └ enum_typestring选项类型
可选值有：
- 1: 文本 - 2: 图片
    └ user_valuesuser_value\[\]人员字段值
      └ idsstring\[\]人员ID
      └ user_typestring人员类型
可选值有：
- 1: 员工
  └ department_path_infosdepartment_base_info\[\]\[\]全部直属部门对应的全路径。排列顺序为根部门到末级部门对应结构 json [ /*所属部门A相关部门路径*/ [ {/*根部门*/}, {/*A的父部门*/}, { "department_id": "abcdefg", "i18n_text": `{ "default_value": "A", "i18n_value": { "zh_cn": "A cn name", "en_us": "A en name" }` } } ] ]
字段权限要求： directory:employee.base.department_path:read 查看员工部门路径
  └ resign_timestring离职时间。离职操作的时间，系统自动生成，无法写入
字段权限要求： directory:employee.base.resign_time:read 查看员工离职时间
  └ avatarimage_link员工的头像url
字段权限要求（满足任一）： directory:employee.base.avatar:read 查看员工的头像 directory:employee.base.base:read 查看员工个人基本信息
    └ avatar_72string72*72像素头像链接
    └ avatar_240string240*240像素头像链接
    └ avatar_640string640*640像素头像链接
    └ avatar_originstring原始头像链接
  └ background_imagestring员工的自定义背景图url
字段权限要求（满足任一）： directory:employee.base.background_image:read 查看员工的名片页自定义背景图 directory:employee.base.base:read 查看员工个人基本信息
  └ is_adminboolean是否租户普通管理员
字段权限要求（满足任一）： directory:employee.base.is_admin:read 查看员工是否是普通管理员 directory:employee.base.role:read 查看员工角色信息
  └ data_sourceint数据来源
可选值有：
- 1: 管理后台 - 2: 人事企业版 - 3: SCIM
字段权限要求（满足任一）： directory:employee.base.base:read 查看员工个人基本信息 directory:employee.base.data_source:read 查看员工数据来源
  └ geo_namestring员工数据驻留地
字段权限要求（满足任一）： directory:employee.base.base:read 查看员工个人基本信息 directory:employee.base.geo:read 查看员工数据驻留地
  └ subscription_idsstring\[\]分配给员工的席位ID列表。
字段权限要求（满足任一）： directory:employee.base.base:read 查看员工个人基本信息 directory:employee.base.subscription_ids:read 查看员工席位信息
work_infoemployee_work_entity员工工作信息
  └ work_country_or_regionstring工作地国家/地区 如何查询国家/地区的编码含义
字段权限要求（满足任一）： directory:employee.work.base_work:read 查看员工基础工作信息 directory:employee.work.work_country_or_region:read 查看员工的工作国家/地区
  └ work_placeplace工作地点
字段权限要求（满足任一）： directory:employee.work.base_work:read 查看员工基础工作信息 directory:employee.work.work_place:read 查看员工的工作地点
    └ place_idstringID，不存在时默认返回"0"
    └ place_namei18n_text工作地点的名称
字段权限要求： directory:place.base:read 查看地点基础信息
      └ default_valuestring默认值
      └ i18n_valuemap<string, string>国际化值，key为zh_cn, ja_jp, en_us, value为对应的值
    └ is_enabledboolean是否启用
字段权限要求： directory:place.status:read 查看地点状态
    └ descriptioni18n_text描述
字段权限要求： directory:place.base:read 查看地点基础信息
      └ default_valuestring默认值
      └ i18n_valuemap<string, string>国际化值，key为zh_cn, ja_jp, en_us, value为对应的值
  └ work_stationi18n_text工位
字段权限要求（满足任一）： directory:employee.work.base_work:read 查看员工基础工作信息 directory:employee.work.work_station:read 查看员工的工位
    └ default_valuestring默认值
    └ i18n_valuemap<string, string>国际化值，key为zh_cn, ja_jp, en_us, value为对应的值
  └ job_numberstring工号
字段权限要求（满足任一）： directory:employee.work.base_work:read 查看员工基础工作信息 directory:employee.work.job_number:read 查看员工的工号
  └ extension_numberstring分机号
字段权限要求（满足任一）： directory:employee.work.base_work:read 查看员工基础工作信息 directory:employee.work.extension_number:read 查看员工的分机号
  └ join_datestring入职日期。如“2007-03-20”
字段权限要求（满足任一）： directory:employee.work.join_date:read 查看员工的入职日期 directory:employee.work.employment:read 查看员工雇佣信息
  └ employment_typeint可选值有：
- 0: 未知 - 1: 全职 - 2: 实习 - 3: 外包 - 4: 劳务 - 5: 顾问
或者使用租户内自定义的员工类型
字段权限要求（满足任一）： directory:employee.work.employment_type:read 查看员工的员工类型 directory:employee.work.employment:read 查看员工雇佣信息
  └ staff_statusint员工人事状态
可选值有：
- 1: 在职 - 2: 离职 - 3: 待入职 - 4: 取消入职 - 5: 待离职
字段权限要求（满足任一）： directory:employee.work.staff_status:read 查看员工的人事状态 directory:employee.work.employment:read 查看员工雇佣信息
  └ job_titlejob_title职务
字段权限要求： directory:employee.work.job_title:read 查看员工职务信息
    └ job_title_idstringID，不存在时默认返回"0"
    └ job_title_namei18n_text职务名称
字段权限要求： directory:job_title.base:read 查看职务基础信息
      └ default_valuestring默认值
      └ i18n_valuemap<string, string>国际化值，key为zh_cn, ja_jp, en_us, value为对应的值
    └ is_enabledboolean是否启用
字段权限要求： directory:job_title.status:read 查看职务状态
    └ descriptioni18n_text描述
字段权限要求： directory:job_title.base:read 查看职务基础信息
      └ default_valuestring默认值
      └ i18n_valuemap<string, string>国际化值，key为zh_cn, ja_jp, en_us, value为对应的值
  └ job_familyjob_family序列
字段权限要求： directory:employee.work.job_family:read 查看员工的工作序列信息
    └ job_family_idstringID，不存在时默认返回"0"
    └ job_family_namei18n_texti18n文本
字段权限要求： directory:job_family.base:read 查看工作序列的信息
      └ default_valuestring默认值
      └ i18n_valuemap<string, string>国际化值，key为zh_cn, ja_jp, en_us, value为对应的值
    └ is_enabledboolean是否启用
字段权限要求： directory:job_family.status:read 查看企业中工作序列的状态信息
    └ parent_job_family_idstring上级序列
字段权限要求： directory:job_family.path:read 查看工作序列的路径信息
    └ descriptioni18n_texti18n文本
字段权限要求： directory:job_family.base:read 查看工作序列的信息
      └ default_valuestring默认值
      └ i18n_valuemap<string, string>国际化值，key为zh_cn, ja_jp, en_us, value为对应的值
  └ resign_datestring离职日期 2007-03-20
字段权限要求（满足任一）： directory:employee.work.resign_date:read 查看员工离职日期 directory:employee.work.employment:read 查看员工雇佣信息
  └ resign_reasonstring离职原因 示例值："1"
可选值有：
- 1: 薪酬不符合预期 - 2: 工作时间过长 - 3: 不满意工作内容 - 4: 不认可上级或管理层 - 5: 职业发展机会有限 - 6: 对公司文化缺乏认同 - 7: 组织架构调整（主动离职） - 8: 合同到期 - 9: 跳槽 - 10: 转行 - 11: 家庭原因 - 12: 健康状况不佳 - 13: 工作地点原因 - 14: 其他(主动离职) - 15: 意外 - 16: 身故 - 17: 解雇 - 18: 试用期不通过 - 19: 工作表现不佳 - 20: 工作产出低 - 21: 组织架构调整（被动离职） - 22: 违纪 - 23: 违法 - 24: 其他（被动离职） - 25: 其他（其他）
字段权限要求（满足任一）： directory:employee.work.resign_reason:read 查看员工离职原因 directory:employee.work.employment:read 查看员工雇佣信息
  └ resign_remarkstring离职备注
字段权限要求（满足任一）： directory:employee.work.resign_remark:read 查看员工离职备注 directory:employee.work.employment:read 查看员工雇佣信息
  └ resign_typestring离职类型示例值："1"
可选值有：
- 1: 主动 - 2: 被动 - 3: 其他
字段权限要求（满足任一）： directory:employee.work.resign_type:read 查看员工离职类型 directory:employee.work.employment:read 查看员工雇佣信息

数据示例 ​

json
{
    "base_info": {
        "employee_id": "u273y71",
        "name": {
            "last_name": {
                "value": "王",
                "i18n_value": [
                    {
                        "language": "zh_cn",
                        "value": "王"
                    },
                    {
                        "language": "en_us",
                        "value": "Wang"
                    }
                ],
                "default_locale": "zh_cn"
            },
            "first_name": {
                "value": "小明",
                "i18n_value": [
                    {
                        "language": "zh_cn",
                        "value": "小明"
                    },
                    {
                        "language": "en_us",
                        "value": "Xiaoming"
                    }
                ],
                "default_locale": "zh_cn"
            },
            "name": {
                "value": "王小明",
                "i18n_value": [
                    {
                        "language": "zh_cn",
                        "value": "王小明"
                    },
                    {
                        "language": "en_us",
                        "value": "Wang Xiaoming"
                    }
                ],
                "default_locale": "zh_cn"
            },
            "another_name": {
                "value": "王明"
            }
        },
        "avatar_key": "2500c7a9-5fff-4d9a-a2de-3d59614ae28g",
        "background_image_key": "2500c7a9-5fff-4d9a-a2de-3d59614ae28g",
        "description": "新成员请多关照",
        "mobile": "+8613011111111",
        "email": "zhangsan@gmail.com",
        "enterprise_email": "zhangsan@gmail.com",
        "enterprise_email_alias": [
            "zhangsan_1@gmail.com",
            "zhangsan_2@gmail.com"
        ],
        "gender": 1,
        "departments": [
            {
                "department_id": "D100",
                "name": {
                    "value": "销售部",
                    "i18n_value": {
                        "language": "en_us",
                        "value": "Sale"
                    },
                    "default_locale": "zh_cn"
                },
                "parent_department_id": "D90",
                "leaders": [
                    {
                        "leader_ID": "u273y69",
                        "DepartmentLeaderType": 1
                    }
                ],
                "has_child": true,
                "department_count": {
                    "recursive_members_count": 100,
                    "direct_members_count": 90,
                    "recursive_members_count_exclue_leaders": 80,
                    "recursive_departments_count": 20,
                    "direct_departments_count": 10
                },
                "order_weight": 1
            }
        ],
        "employee_order_in_departments": [
            {
                "department_id": "D100",
                "order_weight_in_deparment": 100,
                "order_weight_among_deparments": 1
            }
        ],
        "department_path_infos": [
            {
                "department_id": "D100",
                "path_infos": [
                    {
                        "department_id": "h121921",
                        "department_name": {
                            "value": "根部门",
                            "i18n_value": {
                                "language": "en_us",
                                "value": "root"
                            },
                            "default_locale": "zh_cn"
                        }
                    },
                    {
                        "department_id": "D100",
                        "department_name": {
                            "value": "子部门",
                            "i18n_value": {
                                "language": "en_us",
                                "value": "leaf"
                            },
                            "default_locale": "zh_cn"
                        }
                    }
                ]
            }
        ],
        "leader_id": "2e1cf73b",
        "dotted_line_leader_ids": [
            "2b1ae26b"
        ],
        "active_status": 1,
        "is_resigned": false,
        "is_primary_admin": false,
        "is_admin": true,
        "custom_field_values": [
            {
                "field_id": "DemoId",
                "field_value": {
                    "field_type": 1,
                    "text_value": "DemoText"
                }
            },
            {
                "field_id": "DemoId_2",
                "field_value": {
                    "field_type": 4,
                    "user_value": [
                        "9b2fabg5"
                    ]
                }
            }
        ],
        "resign_time": 348970,
        "data_source": 1,
        "geo_name": "cn",
        "subscription_ids": [
            "23213213213123123"
        ]
    },
    "work_info": {
        "work_country_or_region": "MDCT00000040",
        "work_place": {
            "place_id": "mga5oa8ayjlp9rb",
            "place_name": {
                "value": "北京市"
            },
            "is_enable": true,
            "description": "主要的工作地点"
        },
        "work_station": {
            "value": "北楼-H34",
            "i18n_value": {
                "language": "en_us",
                "value": "North-H34"
            },
            "default_locale": "zh_cn"
        },
        "job_number": "2845435",
        "extension_number": "080",
        "join_date": "2007-03-20",
        "employment_type": 2,
        "staff_status": 1,
        "positions": [
            {
                "position_code": "fga7b946",
                "position_name": "销售",
                "is_main_position": true,
                "department_id": "D100",
                "leader_id": "2e1cf73b",
                "leader_position_code": "e71b94gb"
            }
        ],
        "job_title": {
            "job_title_id": "mga5oa8ayjlp9rb",
            "job_title_name": {
                "value": "销售"
            },
            "is_enable": true,
            "description": {
                "value": "销售岗位"
            }
        },
        "job_family": {
            "description": {
                "default_value": ""
            },
            "is_enabled": true,
            "job_family_id": "5rbknygz18kv2ge",
            "job_family_name": {
                "default_value": "研发",
                "i18n_value": {
                    "en_us": "研发en",
                    "ja_jp": "研发jp",
                    "zh_cn": "研发cn"
                }
            },
            "parent_job_family_id": "0"
        }
    }
}

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

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