飞书开放平台 Server API 文档

主题

更新员工信息 ​

本接口用于更新在职/离职员工的信息、冻结/恢复员工。未传递的参数不会进行更新。 员工指飞书企业内身份为「Employee」的成员，等同于通讯录OpenAPI中的「User」。

Tip: - 员工状态的修改遵循生命周期流转的规则，具体规则详见 Directory-员工管理-资源介绍 。

  • 本接口支持tenant_access_token和user_access_token，接口获取方式参考获取访问凭证 。
    • 使用tenant_access_token时，只能在当前应用的通讯录授权范围内更新员工信息。可在开发者后台 > 权限管理 > 通讯录权限 中查看。
      • 当变更员工的部门信息时，应用需要有变更前后的部门权限，才能变更成功。 > - 使用user_access_token 时，默认为管理员用户，将校验管理员管理范围。当用户有多个管理员身份均可更新员工信息时，管理员管理范围取最大集。管理员权限可查看帮助中心文档：管理员创建管理员角色及分配权限
  • 变更「未加入」、「未激活」状态的员工的联系手机号、工作邮箱，会修改员工的登录凭证，并将员工重置为「未加入」状态，并发送邀请短信/邮件。其他状态的员工修改联系方式不影响登录凭证。
  • 修改员工ID（employee_id）需要悉知以下影响：
    • 员工ID（employee_id）是员工在企业内的唯一ID，可能会被应用引用来实现各种内部逻辑，唯一ID修改之后可能会导致引用失败，导致所有引用且保存了‘被修改 ID 员工’的业务全部受影响。
  • 更新离职状态的员工信息时，以下字段不可更新：
    • email、mobile、department_ids、leader_id、is_frozen、work_city_id

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/directory/v1/employees/:employee_id
HTTP MethodPATCH
接口频率限制10 次/秒
支持的应用类型custom
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可directory:employee.update:write 更新员工 directory:employee:write 创建、更新、离职、恢复员工
字段权限要求> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 directory:employee.base.external_id:read 查看员工自定义 ID

请求头 ​

名称类型必填描述
Authorizationstring是tenant_access_token 或 user_access_token 值格式："Bearer access_token" 示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token
Content-Typestring是固定值："application/json; charset=utf-8"

路径参数 ​

名称类型描述
employee_idstring员工ID，与employee_id_type类型保持一致。
示例值："eehsdna"

查询参数 ​

名称类型必填描述
employee_id_typestring否用户 ID 类型
示例值：open_id
可选值有：
- open_id: 标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。了解更多：如何获取 Open ID - union_id: 标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。了解更多：如何获取 Union ID？ - employee_id: 企业内在职员工的唯一标识。支持自定义，未自定义时系统自动生成。ID支持修改。 获取employee_id的方式： - 企业管理员在 管理后台 > 组织架构 > 成员与部门 页面，点击 成员详情，查询员工ID - 通过 批量获取员工列表 的接口，通过手机号或邮箱查询员工ID。
默认值：open_id
当值为 employee_id，字段权限要求： directory:employee.base.external_id:read 查看员工自定义 ID
department_id_typestring否部门ID类型
示例值：open_department_id
可选值有：
- department_id: department_id - open_department_id: open_department_id
默认值：open_department_id

请求体 ​

名称类型必填描述
employeeupdate_employee是更新员工对象
  └ nameupsert_name否姓名
    └ namei18n_text是员工的姓名。
      └ default_valuestring是默认值
长度范围：1- 64 字符
示例值："工位"
      └ i18n_valuemap<string, string>否国际化值，key为zh_cn, ja_jp, en_us, value为对应的值
示例值：{"zh_cn":"工位1"}
    └ another_namestring否别名，最多可输入 64 字
示例值："Jack"
  └ mobilestring否员工的手机号，最多可输入 255 字。注意： 1. 在企业内的在职员工中不可重复 2. 未认证企业仅支持添加中国大陆手机号，通过飞书认证的企业允许添加海外手机号 3. 国际电话区号前缀中必须包含加号 +
示例值："13011111111" 或 "+8613011111111"
  └ custom_employee_idstring否企业内在职员工的唯一标识。支持自定义，未自定义时系统自动生成。ID支持修改。注意： 1. 在职员工的ID不可重复。 2. ID不能包含空格。
示例值："eesadeq"
  └ avatar_keystring否员工的头像key。获取图片的key请使用 上传图片 - 服务端 API - 开发文档 - 飞书开放平台，上传时图片类型需要选择 用于设置头像
示例值："dadwqeqwdsa"
  └ emailstring否员工在工作中的邮箱。注意： 1. 在企业内的在职员工中不可重复。 2. 非中国大陆手机号成员必须同时添加邮箱。
示例值："zhangsan@163.com"
  └ enterprise_emailstring否员工的企业邮箱。请先确保已在管理后台启用飞书邮箱服务。企业邮箱的域名需要企业在管理后台申请并开启。如果企业没有开启对应域名的企业邮箱，设置用户的企业邮箱会操作失败。
示例值："zhangsan@163.com"
  └ genderint否性别
示例值：1
可选值有：
- 0: 未知 - 1: 男 - 2: 女 - 3: 其他
  └ employee_order_in_departmentsupsert_user_department_sort_info\[\]否员工在所属部门内的排序信息
数据校验规则：
- 长度范围：0 ～ 10
    └ department_idstring否部门id，与department_id_type类型保持一致。
示例值："eediasdjw"
    └ order_weight_in_deparmentstring否员工在部门内的排序权重
数据校验规则：
示例值："100"
    └ order_weight_among_deparmentsstring否该部门在用户所属的多个部门间的排序权重
示例值："20"
    └ is_main_departmentboolean否是否为用户的主部门（用户只能有一个主部门，且排序权重应最大，不填则默认使用系统默认排序下的第一个部门作为主部门，系统默认排序与部门数组传入顺序无关）
示例值：true
  └ background_image_keystring否背景图的key。获取图片的key请使用 上传图片 - 服务端 API - 开发文档 - 飞书开放平台，上传时图片类型需要选择 用于发送消息
示例值："qweasdqawqeq"
  └ descriptionstring否员工的个性签名
示例值："新员工入职"
  └ leader_idstring否员工的直属上级ID。注意： 1. 不可成环，即A的上级是B，B的上级是A。 2. 上级需要是一个在职的员工。
示例值："eeshfosd"
  └ dotted_line_leader_idsstring\[\]否员工的虚线上级ID，与employee_id_type类型保持一致。注意： 1. 不可成环，即A的上级是B，B的上级是A。 2. 上级需要是一个在职的员工。
示例值：["eefhdgsd"]
数据校验规则：
- 长度范围：0 ～ 10
  └ work_country_or_regionstring否工作地国家/地区码。获取国家/地区的编码请使用 分页批量查询国家/地区。
示例值："MDM2312312"
  └ work_place_idstring否工作地点ID
示例值："1111sdda"
  └ work_stationi18n_text否工位
    └ default_valuestring是默认值
示例值："工位"
    └ i18n_valuemap<string, string>否国际化值，key为zh_cn, ja_jp, en_us, value为对应的值
示例值：{"zh_cn":"工位"}
  └ job_numberstring否工号。企业内在职员工的工号不可重复。
示例值："28549233"
  └ extension_numberstring否分机号，最多可输入 99 字。企业内所有员工的分机号不可重复。
示例值："2854923"
  └ join_datestring否入职日期
固定格式为：'YYYY-MM-DD' , 固定长度为：10
示例值："2022-10-10"
  └ employment_typeint否员工类型
示例值：1
可选值有：
- 0: 未知 - 1: 全职 - 2: 实习 - 3: 外包 - 4: 劳务 - 5: 顾问
  └ job_title_idstring否职务ID
示例值："ewdjdssd"
  └ job_level_idstring否职级ID
示例值："asdfghjk"
  └ job_family_idstring否序列ID
示例值："qwertyui"
  └ resign_datestring否离职日期
固定格式为：'YYYY-MM-DD' , 固定长度为：10
示例值："2022-10-10"
数据校验规则：
- 长度范围：0 ～ 20 字符
  └ resign_reasonstring否离职原因
示例值："1"
可选值有：
- 0: 置空 - 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: 其他（其他）
  └ resign_remarkstring否离职备注信息
示例值："个人原因"
数据校验规则：
- 长度范围：0 ～ 255 字符
  └ resign_typestring否离职类型
示例值："1"
可选值有：
- 0: 置空 - 1: 主动 - 2: 被动 - 3: 其他
  └ is_frozenboolean否是否冻结员工账号。 true为冻结，false为恢复账号。
示例值：true
  └ custom_field_valuescustom_field_value\[\]否自定义字段
数据校验规则：
- 长度范围：0 ～ 100
    └ field_typestring否自定义字段类型
示例值："1"
可选值有：
- 1: 多行文本 - 2: 网页链接 - 3: 枚举选项 - 4: 人员 - 9: 电话 - 10: 多选枚举类型(目前仅支持文本类型) - 11: 人员列表
    └ text_valuei18n_text否文本字段值
      └ default_valuestring是默认值
示例值："姓名字段"
      └ i18n_valuemap<string, string>否国际化值，key为zh_cn, ja_jp, en_us, value为对应的值
示例值：{"zh_cn":"姓名字段"}
    └ url_valueurl_value否网页链接字段值
      └ link_texti18n_text是网页标题
        └ default_valuestring是默认值
示例值："网页标题"
        └ i18n_valuemap<string, string>否国际化值，key为zh_cn, ja_jp, en_us, value为对应的值
示例值：{"zh_cn":"网页标题"}
      └ urlstring是移动端网页链接
示例值："https://m.bytedance.com/afnasjfna"
      └ pcurlstring是桌面端网页链接
示例值："http://www.fs.cn"
    └ enum_valueenum_value否枚举
      └ enum_idsstring\[\]是选项结果ID
示例值：["1"]
数据校验规则：
- 长度范围：0 ～ 100
      └ enum_typestring是选项类型
示例值："1"
可选值有：
- 1: 文本 - 2: 图片
    └ user_valuesuser_value\[\]否人员字段值
数据校验规则：
- 长度范围：0 ～ 100
      └ idsstring\[\]是人员ID，与employee_id_type类型保持一致。
示例值：["1"]
数据校验规则：
- 长度范围：0 ～ 100
    └ phone_valuephone_value否电话字段值
      └ phone_numberstring是电话号
示例值："18812345678"
      └ extension_numberstring否分机号
示例值："234234234"
    └ field_keystring否自定义字段key
示例值："C-1000001"

请求体示例 ​

json
{
    "employee": {
        "name": {
            "name": {
                "default_value": "张三",
                "i18n_value": {
                    "zh_cn": "张三",
                    "ja_jp": "佐藤はるか",
                    "en_us": "Alex Zhang"
                }
            },
            "another_name": "Jack"
        },
        "mobile": "+8613011111111",
        "custom_employee_id": "u273y71",
        "avatar_key": "8abc397a-9950-44ea-9302-e1d8fe00858g",
        "email": "zhangsan@test.com",
        "enterprise_email": "zhangsan@test.com",
        "gender": 1,
        "employee_order_in_departments": [
            {
                "department_id": "0",
                "order_weight_in_deparment": "100",
                "order_weight_among_deparments": "20",
                "is_main_department": false
            }
        ],
        "leader_id": "eeasdqwwe",
        "dotted_line_leader_ids": [
            "hdsuqw"
        ],
        "work_country_or_region": "MDM34234234",
        "work_place_id": "eqwedas",
        "work_station": {
            "default_value": "张三",
            "i18n_value": {
                "zh_cn": "工位",
                "ja_jp": "工位",
                "en_us": "Work Station"
            }
        },
        "job_number": "2845435",
        "extension_number": "2845435",
        "join_date": "2022-10-10",
        "employment_type": "1",
        "staff_status": "",
        "job_title_id": "wqedsaqw",
        "resign_reason": "",
        "resign_type": "",
        "custom_field_values": [
            {
                "field_type": "1",
                "text_value": {
                    "default_value": "姓名字段",
                    "i18n_value": {
                        "zh_cn": "姓名字段",
                        "ja_jp": "姓名字段",
                        "en_us": "Name Filed"
                    }
                },
                "url_value": {
                    "link_text": {
                        "default_value": "网页地址",
                        "i18n_value": {
                            "zh_cn": "网页地址",
                            "ja_jp": "This is a URL",
                            "en_us": "This is a URL"
                        }
                    },
                    "url": "https://www.feishu.cn/",
                    "pcurl": "https://www.feishu.cn/"
                },
                "enum_value": {
                    "enum_ids": [
                        "75ec5g97"
                    ],
                    "enum_type": "1"
                },
                "user_values": [
                    {
                        "ids": [
                            "27al2hef"
                        ]
                ],
                "field_key": "C-1000001"
            }
        ]
    }
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {}
}

错误码 ​

HTTP状态码错误码描述排查建议
4002221164User name exceeds limit姓名长度超过限制，最多可输入 64 字
4002221165User en_name exceeds limit英文名长度超过限制，最多可输入 64 字
4002221166User another_name exceeds limit别名长度超过限制，最多可输入 64 字
4002221103Mobile already exists手机号已存在，请修改手机号
4002221106Invalid mobile无效手机号，请修改手机号
4002221113Mobile or email not set手机号或邮箱必填
4002221114User must have a mobile in China中国必须有手机号，请添加中国手机号
4002221156Unable to edit verified mobile不允许编辑已认证手机号，请不要编辑已认证手机号或通过其他方式修改
4002221104Email already exists邮箱已存在，请求修改邮箱
4002221107Invalid email无效的邮箱，请求修改企业邮箱
4002221118Enterprise email already exists企业邮箱已存在，请求修改企业邮箱
4002221278Invalid enterprise email无效的邮箱，请求修改企业邮箱
4002221126Enterprise email domain unavailable企业邮箱域名不可用，请求修改企业邮箱
4002221146Enterprise email alias exceeds limit企业邮箱别名超过长度限制，最多可输入 255 字
4002221147Enterprise email address in recycle bin企业邮箱地址在回收站中，请修改企业邮箱
4002221176Add Feishu allow list tenant. Email must be included with non+86mobile飞书租户添加非+86的手机号时必须包含邮件信息，请包含邮件信息
4002221255Main department must be the first员工在所属部门内的排序信息中主部门必须在第一个，请修改员工所属部门内的排序信息
4002221125The number of members within the department exceeds the limit. Please contact an administrator for help部门内成员人数超过限制，人数不能超过一万，请联系管理员寻求帮助。
4002221129User department is empty员工所属部门为空，请修改员工所属部门内的排序信息
4002221141Unable to join multiple departments. Please upgrade relevant 'Organizational Structure Visible'.无法加入多个部门，请修改员工所属部门内的排序信息
4002221181Department does not exist部门不存在，请修改员工所属部门内的排序信息
4002221239Leader loop error直属上级成环，请修改直属上级
4002221238DottedLineLeaderID loop error虚线上级成环，请修改虚线上级
4002221221DottedLineLeaderID exceeds length limit虚线上级长度超过限制，请修改虚线上级
4002221222Invalid dottedLineLeaderID无效的虚线上级ID，请修改虚线上级
4002221242Invalid custom field无效的自定义字段，请修改自定义字段
4002221216Invalid work country or region无效的工作国家或区域，请修改工作国家或区域
4002221217WorkplaceID not found工作城市不存在，请修改工作城市
4002221240JobNumber not unique工号已存在，请修改工号
4002221191Invalid extension number分机号无效，请修改分机号
4002221192Repeated extension number within the tenant分机号已存在，请修改分机号
4002221193Extension number exceeds limit分机号长度超过限制，最多可输入 99 字
4002221210Invalid join date无效的入职时间，请修改入职时间
4002221144EmployeeType not found人员类型不存在，请修改人员类型
4002221145EmployeeType inactive人员类型未激活，请修改人员类型
4002221223Invalid job title ID职务不存在，请修改职务
4002221263Tenant has not activated multi geo租户未开启Multi-Geo，请先开通再试。Multi-Geo指的是多地理位置数据驻留。
4002221264User geo does not exist指定的Geo不存在，请检查Geo参数是否正确。可通过获取地理位置列表接口查询企业开通的Geo，请注意这里需要传入小写字母。
4002221265The application does not have permission to write to the geo无权限指定员工Geo，需申请，点击api调试台-权限配置，会显示需要的权限，点击“操作”-“...”-“开通”，即可。 directory:employee.base.geo:write 写入员工数据所在地
4002221266The application does not have permission to write to the SubscriptionID无权限指定席位，需申请，点击api调试台-权限配置，会显示需要的权限，点击“操作”-“...”-“开通”，即可。 directory:employee.base.subscription_ids:write 写入员工席位信息
4002224001No permission to operate无操作权限，请检查当前应用的权限或企业版本是否是商业专业版本及以上。
4002224002No permission to operate record无操作该记录权限，请检查当前应用的数据管理范围的权限或当前应用所操作的成员是否可更新。
4002224003No permission to operate dependent object无操作依赖对象权限，请检查要更新到的部门是否有权限。
4002221252Hybrid license tenant prohibits passing empty licenses to create users混合许可证租户禁止传递空许可证来创建用户，请传递有效的许可证
4002221253Designated licenseID is insufficient剩余席位不足，请修改席位信息
4002221254Designated licenseID is invalid应用没有权限写入员工数据驻留地，需申请写入员工数据驻留地权限(directory:employee.base.geo:write)
4002221111Exceeds certified seat limit混合许可证租户禁止传递空许可证来创建用户，请传递有效的许可证
4002221112Exceeds billing plan seat limit剩余席位不足，请修改席位信息
4002221115ExternalID is not unique自定义ID已存在，请修改自定义ID
4002221116Invalid ExternalID无效的自定义ID，请修改自定义ID
4002221175Feishu only supports +86mobile飞书租户仅支持+86手机号，请修改手机号
4002221182Unable to freeze tenant founder无法冻结企业管理员，请选择非企业管理员用户进行冻结操作
4002221109Name contains sensitive info姓名包含敏感信息，请修改姓名
4002221292User department is disabled用户部门已停用，请将用户转移至未停用的部门或激活该部门
4002221213Resign date invalid or earlier than join date or empty请检查离职日期格式可能非法、离职日期早于加入日期、离职日期为空
4002221214Resign reason invalid or not match resign type离职原因非法，或者离职原因和离职类型不匹配，请修改离职原因或离职类型使其匹配
4002221293Only allow update preResigned\resigned employee's resign info field只允许更新待离职、离职人员的离职信息字段（离职备注、离职类型、离职原因、离职日期），请更新待离职或离职人员的对应字段
4002221231Resign type invalid or not match resign reason离职类型非法，或者离职原因和离职类型不匹配，请修改离职类型或离职原因使其匹配

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

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