飞书开放平台 Server API 文档

主题

创建员工 ​

本接口用于在企业下创建员工。支持传入姓名、手机号等信息，生成在职状态的员工对象。 员工指飞书企业内身份为「Employee」的成员，等同于通讯录OpenAPI中的「User」。

Tip: 注意：

  • 只能在当前应用的通讯录授权范围内的部门下创建员工，如果要在根部门下创建员工，必须拥有全员权限。可以在开发者后台-应用详情-权限管理中查看通讯录授权范围。 > - 本接口中支持的user_access_token 默认为管理员用户，将校验管理员管理范围。当用户有多个管理员身份均可创建员工时，管理员管理范围取最大集。管理员权限可查看帮助中心文档：管理员创建管理员角色及分配权限
  • 拥有本接口权限后，即可写入员工信息。但创建员工后仅返回应用有权限的字段数据，如果需要指定字段请按照文档中的描述申请对应权限。
  • 本接口仅对自建应用开放。
  • 创建出来的是在职状态的员工。
  • 创建员工后，会发送邀请短信/邮件，需被邀请人点击同意后才可加入企业。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/directory/v1/employees
HTTP MethodPOST
接口频率限制5 次/秒
支持的应用类型custom
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可directory:employee.create: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_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: 用来标识租户内一个唯一的部门 - open_department_id: 用来在具体某个应用中标识一个部门，同一个部门 在不同应用中的 open_department_id 相同。
默认值：open_department_id

请求体 ​

名称类型必填描述
employeecreate_employee是创建员工对象
  └ nameupsert_name否姓名
    └ namei18n_text是员工的姓名，最多可输入 64 字
      └ default_valuestring是默认值 最小长度：1字符
示例值："张三"
      └ i18n_valuemap<string, string>否国际化值，key为zh_cn, ja_jp, en_us, value为对应的值。
示例值：{"zh_cn":"张三"}
    └ another_namestring否别名，最多可输入 64 字
示例值："jack"
  └ mobilestring否员工的手机号，最多可输入 255 字。注意： 1. 在企业内的在职员工中不可重复。 2. 未认证企业仅支持添加中国大陆手机号，通过飞书认证的企业允许添加海外手机号。 3. 国际电话区号前缀中必须包含加号 +。
示例值："13011111111" 或 "+8613011111111"
  └ custom_employee_idstring否企业内在职员工的唯一标识。支持自定义，未自定义时系统自动生成。ID支持修改。注意： 1. 在职员工的ID不可重复 2. ID不能包含空格
示例值："u273y71
数据校验规则：
长度范围：1-64字符"
  └ avatar_keystring否员工的头像key。获取图片的key请使用 上传图片 - 服务端 API - 开发文档 - 飞书开放平台，上传时图片类型需要选择 用于设置头像
示例值："8abc397a-9950-44ea-9302-e1d8fe00858g"
数据校验规则：
- 长度范围：0 ～ 255 字符
  └ emailstring否员工在工作中的邮箱。注意： 1. 在企业内的在职员工中不可重复。 2. 非中国大陆手机号成员必须同时添加邮箱。
示例值："zhangsan@gmail.com"
数据校验规则：
- 长度范围：0 ～ 255 字符
  └ enterprise_emailstring否员工的企业邮箱。请先确保已在管理后台启用飞书邮箱服务。企业邮箱的域名需要企业在管理后台申请并开启。如果企业没有开启对应域名的企业邮箱，设置用户的企业邮箱会操作失败。
示例值："zhangsan@gmail.com"
数据校验规则：
- 长度范围：0 ～ 255 字符
  └ genderint否性别
示例值：1
可选值有：
- 0: 未知 - 1: 男 - 2: 女 - 3: 其他
  └ employee_order_in_departmentsupsert_user_department_sort_info\[\]否员工在所属部门内的排序信息。
数据校验规则：
- 长度范围：0 ～ 10
    └ department_idstring否指定员工所在的部门，标识企业内一个唯一的部门，与department_id_type类型保持一致。
示例值："eeddjisdwe"
    └ order_weight_in_deparmentstring否员工在部门内的排序权重。
示例值："100"
    └ order_weight_among_deparmentsstring否该部门在用户所属的多个部门间的排序权重。
示例值："20"
    └ is_main_departmentboolean否是否为用户的主部门（用户只能有一个主部门，且排序权重应最大，不填则默认使用系统默认排序下的第一个部门作为主部门，系统默认排序与部门数组传入顺序无关）
示例值：true
  └ leader_idstring否员工的直属上级ID，与employee_id_type类型保持一致。注意： 1. 不可成环，即A的上级是B，B的上级是A。 2. 上级需要是一个在职的员工。
示例值："eeasdqwwe"
  └ dotted_line_leader_idsstring\[\]否员工的虚线上级ID，与employee_id_type类型保持一致。注意： 1. 不可成环，即A的上级是B，B的上级是A。 2. 上级需要是一个在职的员工。
示例值：["hdsuqw"]
数据校验规则：
- 长度范围：0 ～ 20
  └ work_country_or_regionstring否工作地国家/地区码。获取国家/地区的编码请使用 分页批量查询国家/地区。
示例值："MDM34234234"
  └ work_place_idstring否工作地点ID
示例值："eqwedas"
  └ work_stationi18n_text否工位
    └ default_valuestring是默认值
示例值："张三"
    └ i18n_valuemap<string, string>否国际化值，key为zh_cn, ja_jp, en_us, value为对应的值
示例值：{"zh_cn":"张三"}
  └ job_numberstring否工号。企业内在职员工的工号不可重复。
示例值："2845435
数据校验规则：
长度范围：0-255字符"
  └ extension_numberstring否分机号，最多可输入 99 字。企业内所有员工的分机号不可重复。
示例值："2845435"
  └ join_datestring否入职日期
示例值："2022-10-10
数据校验规则：
长度范围：固定长度：10 个字符，固定格式：“yyyy-mm-dd”"
  └ employment_typeint否员工类型
示例值：1
可选值有：
- 1: 全职 - 2: 实习 - 3: 外包 - 4: 劳务 - 5: 顾问
  └ job_title_idstring否职务ID
示例值："wqedsaqw"
  └ custom_field_valuescustom_field_value\[\]否自定义字段
数据校验规则：
- 长度范围：0 ～ 100
    └ field_typestring否自定义字段类型
示例值："1"
可选值有：
- 1: 多行文本 - 2: 网页链接 - 3: 枚举选项 - 4: 人员 - 9: 电话 - 10: 多选枚举类型 - 11: 人员列表
    └ text_valuei18n_text否文本字段值
      └ default_valuestring是默认值
最小长度：1字符
示例值："张三"
      └ i18n_valuemap<string, string>否国际化值，key为zh_cn, ja_jp, en_us, value为对应的值
示例值：{"zh_cn":"张三"}
    └ url_valueurl_value否网页链接字段值
      └ link_texti18n_text是网页标题
        └ default_valuestring是默认值
长度范围：1-40字符
示例值："张三"
        └ 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"
optionscreate_employee_options否接口拓展选项
  └ geo_namestring否员工的数据驻留地。仅限开通了Multi-Geo的企业可选填，且仅能填入企业数据驻留地列表中的Geo。可通过获取地理位置列表接口查询企业开通的Geo，请注意这里需要传入小写字母。 需要申请以下权限才能写入：directory:employee.base.geo:write 写入员工数据所在地
示例值："cn"
  └ subscription_idsstring\[\]否分配给员工的席位ID列表。可通过下方接口获取到该租户的可用席位ID，参见获取席位信息。当在混合license模式下，此字段为必填。 需要申请以下权限才能写入： directory:employee.base.subscription_ids:write 写入员工席位信息
示例值：["123123123"]
数据校验规则：
- 长度范围：0 ～ 20

请求体示例 ​

json
{
    "employee": {
        "name": {
            "name": {
                "default_value": "张三",
                "i18n_value": {
                    "zh_cn": "中文",
                    "ja_jp": "ja_jp_name",
                    "en_us": "en_us_name"
                }
            },
            "another_name": "jack"
        },
        "mobile": "13011111111 或 +8613011111111",
        "custom_employee_id": "u273y71",
        "avatar_key": "8abc397a-9950-44ea-9302-e1d8fe00858g",
        "email": "zhangsan@gmail.com",
        "enterprise_email": "zhangsan@gmail.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": "ja_jp_name",
                "en_us": "en_us_name"
            }
        },
        "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": "3",
                "text_value": {
                    "default_value": "张三",
                    "i18n_value": {
                        "zh_cn": "中文",
                        "ja_jp": "ja_jp_name",
                        "en_us": "en_us_name"
                    }
                },
                "url_value": {
                    "link_text": {
                        "default_value": "张三",
                        "i18n_value": {
                            "zh_cn": "中文",
                            "ja_jp": "ja_jp_name",
                            "en_us": "en_us_name"
                        }
                    },
                    "url": "https://m.bytedance.com/afnasjfna",
                    "pcurl": "http://www.fs.cn"
                },
                "enum_value": {
                    "enum_ids": [
                        "75ec5g97"
                    ],
                    "enum_type": "1"
                },
                "user_values": [
                    {
                        "ids": [
                            "27al2hef"
                        ],
                        "user_type": "1"
                    }
                ],
                "field_key": "C-1000001"
            }
        ]
    },
    "options": {
        "geo_name": "cn",
        "subscription_ids": [
            "123123123"
        ]
    }
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ employee_idstring员工ID当employee_id_type值为 employee_id，字段权限要求： directory:employee.base.external_id:read 查看员工自定义 ID

响应体示例 ​

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

错误码 ​

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中国地区手机号不能为空
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部门内成员人数不能超过一万， 请联系管理员寻求帮助，在桌面端访问飞书管理后台（feishu.cn/admin），引导页会显示管理员信息。
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指定的subscription_ids非法，请检查席位ID
4002221111Exceeds certified seat limit超出认证席位限制，请修改席位信息
4002221112Exceeds billing plan seat limit超出套餐席位限制，请修改席位信息
4002221115ExternalID is not unique自定义ID已存在，请修改自定义ID
4002221116Invalid ExternalID无效的用户ID，请检查是否包含空白符
4002221175Feishu only supports +86mobile飞书租户仅支持+86手机号，请修改手机号
4002221163Users are created too frequently员工创建过于频繁，请稍后再试
4002221109Name contains sensitive info姓名包含敏感信息，请修改姓名
4002221292User department is disabled用户部门已经禁用，请联系管理员启用该部门，或修改员工所属部门。

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

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