飞书开放平台 Server API 文档

主题

创建招聘需求 ​

创建招聘需求，可指定招聘需求部门、招聘人数、需求描述等，具体可参考「飞书招聘」-「设置」-「招聘需求字段管理」，或者参考获取招聘需求模板。

Warning: 除招聘需求编号（short_code）为必填外，其他字段是否必填请参考「飞书招聘」-「设置」-「招聘需求字段管理」

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/hire/v1/job_requirements
HTTP MethodPOST
接口频率限制5 次/秒
支持的应用类型custom
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用hire:job_requirement 更新招聘需求信息
字段权限要求> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 contact:user.employee_id:readonly 获取用户 user ID

请求头 ​

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

查询参数 ​

名称类型必填描述
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
可选值有：
- open_department_id: 由系统自动生成的部门 ID，ID 前缀固定为 od-，在租户内全局唯一。 - department_id: 支持用户自定义配置的部门 ID。自定义配置时可复用已删除的 department_id，因此在未删除的部门范围内 department_id 具有唯一性。
默认值：open_department_id
job_level_id_typestring否此次调用中使用的「职级 ID」的类型
示例值：job_level_id
可选值有：
- people_admin_job_level_id: 「人力系统管理后台」适用的职级 ID。人力系统管理后台逐步下线中，建议不继续使用此 ID。 - job_level_id: 「飞书管理后台」适用的职级 ID，可通过获取租户职级列表获取
默认值：people_admin_job_level_id
job_family_id_typestring否此次调用中使用的「序列 ID」的类型
示例值：job_family_id
可选值有：
- people_admin_job_category_id: 「人力系统管理后台」适用的序列 ID。人力系统管理后台逐步下线中，建议不继续使用此 ID。 - job_family_id: 「飞书管理后台」适用的序列 ID，可通过获取租户序列列表获取
默认值：people_admin_job_category_id
employee_type_id_typestring否此次调用中使用的「人员类型 ID」的类型
示例值：employee_type_enum_id
可选值有：
- people_admin_employee_type_id: 「人力系统管理后台」适用的人员类型 ID。人力系统管理后台逐步下线中，建议不继续使用此 ID。 - employee_type_enum_id: 「飞书管理后台」适用的人员类型 ID，可通过查询人员类型获取
默认值：people_admin_employee_type_id

请求体 ​

名称类型必填描述
short_codestring是招聘需求编号，需传入唯一的编号
示例值："R01905"
namestring是需求名称
示例值："HR部门春季招聘需求"
display_progressint是需求状态
示例值：1
可选值有：
- 1: 未开始 - 2: 进行中 - 3: 已取消 - 4: 已暂停 - 5: 已完成 - 6: 已超期
head_countint是需求人数
示例值：10
recruitment_type_idstring否职位性质 ID，可在枚举常量介绍查阅枚举值。 - 注意：该字段即将下线，请使用employee_type_id字段，与employee_type_id字段必填其一
示例值："101"
employee_type_idstring否人员类型ID，类型需与employee_type_id_type保持一致
示例值："6807409776231254285"
max_level_idstring否最高职级 ID，需与job_level_id_type类型保持一致
示例值："6807409776231254286"
min_level_idstring否最低职级 ID，需与job_level_id_type类型保持一致
示例值："6807409776231254287"
sequence_idstring否职位序列 ID，需与job_family_id_type类型保持一致
示例值："6911957338526091536"
categoryint否需求类型
示例值：1
可选值有：
- 1: 新增 - 2: 替换
department_idstring否需求部门 ID，需与department_id_type类型一致
示例值："od-4e6ac4d14bcd5071a37a39de902c7141"
recruiter_id_liststring\[\]否需求负责人 ID 列表，需与user_id_type类型保持一致
示例值：["od-4e6ac4d14bcd5071a37a39de902c7141"]
jr_hiring_manager_id_liststring\[\]否需求用人经理 ID 列表，需与user_id_type类型保持一致
示例值：["ou_0c9b1b7b9b94146b9df142c349e3c4bf"]
direct_leader_id_liststring\[\]否直属上级 ID，需与user_id_type类型保持一致
示例值：["od-4e6ac4d14bcd5071a37a39de902c7141"]
start_timestring否开始日期，毫秒时间戳
示例值："1625729379000"
deadlinestring否预计完成日期，毫秒时间戳
示例值："1625729379000"
priorityint否招聘优先级
示例值：1
可选值有：
- 1: 高 - 2: 中 - 3: 低
required_degreeint否学历要求
示例值：1
可选值有：
- 1: 小学及以上 - 2: 初中及以上 - 3: 专职及以上 - 4: 高中及以上 - 5: 大专及以上 - 6: 本科及以上 - 7: 硕士及以上 - 8: 博士及以上 - 20: 不限
max_salarystring否月薪范围-最高薪资，单位：K
示例值："10"
min_salarystring否月薪范围-最低薪资，单位：K
示例值："5"
address_idstring否工作地址 ID，可通过获取地址列表获取
示例值："7265901641899311105"
descriptionstring否需求描述
示例值："部门人力紧缺，需要招聘资深工程师10名"
customized_data_listjob_requirement_customized_data\[\]否自定义字段，可通过获取招聘需求模板获取自定义字段列表、类型等
  └ object_idstring否自定义字段 ID，可通过获取招聘需求模板获取
示例值："1213213123123"
  └ valuestring否自定义字段 value - 单选："1" - 多选："[\"1\", \"2\"]" - 单行："单行文本" - 多行："多行文本" - 数字："1" - 月份选择："1627379423000" - 年份选择："1627379423000" - 日期选择："1627379423000" - 时间段："[\"1577808000000\", \"1612108800000\"]"
示例值："简单文本"
process_typeint否招聘类型
示例值：1
可选值有：
- 1: 社招 - 2: 校招
job_type_idstring否职位类别，可通过获取职位类别列表获取
示例值："6930815272790114324"
job_id_liststring\[\]否关联的职位 ID 列表。注：若企业开启了“招聘需求审批”，未通过审批的需求无法关联职位，请勿传入该字段。
示例值：["6930815272790114324"]
数据校验规则：
- 最大长度：200
employment_job_idstring否职务 ID，可通过获取租户职务列表获取（仅限飞书人事租户使用）
示例值："6807407987381831949"
position_idstring否岗位 ID，可通过查询岗位信息获取（仅限飞书人事租户使用，若链接无法打开，则说明飞书人事未启用岗位，请联系技术支持开通）
示例值："7094136522860922111"

请求体示例 ​

json
{
    "short_code": "R01905",
    "name": "HR部门春季招聘需求",
    "display_progress": 1,
    "head_count": 10,
    "recruitment_type_id": "101",
    "employee_type_id": "6807409776231254285",
    "max_level_id": "6807409776231254286",
    "min_level_id": "6807409776231254287",
    "sequence_id": "6911957338526091536",
    "category": 1,
    "department_id": "od-4e6ac4d14bcd5071a37a39de902c7141",
    "recruiter_id_list": [
        "od-4e6ac4d14bcd5071a37a39de902c7141"
    ],
    "jr_hiring_manager_id_list": [
        "ou_0c9b1b7b9b94146b9df142c349e3c4bf"
    ],
    "direct_leader_id_list": [
        "od-4e6ac4d14bcd5071a37a39de902c7141"
    ],
    "start_time": "1625729379000",
    "deadline": "1625729379000",
    "priority": 1,
    "required_degree": 1,
    "max_salary": "10",
    "min_salary": "5",
    "address_id": "7265901641899311105",
    "description": "部门人力紧缺，需要招聘资深工程师10名",
    "customized_data_list": [
        {
            "object_id": "1213213123123",
            "value": "简单文本"
        }
    ],
    "process_type": 1,
    "job_type_id": "6930815272790114324",
    "job_id_list": [
        "6930815272790114324"
    ],
    "employment_job_id": "6807407987381831949",
    "position_id": "7094136522860922111"
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ job_requirementjob_requirement_dto招聘需求信息
    └ idstring招聘需求 ID
    └ short_codestring招聘需求编号
    └ namestring需求名称
    └ display_progressint需求状态
可选值有：
- 1: 未开始 - 2: 进行中 - 3: 已取消 - 4: 已暂停 - 5: 已完成 - 6: 已超期
    └ head_countint需求人数
    └ recruitment_typeid_name_object职位性质 ，可在枚举常量介绍文档中查看枚举值，建议使用employee_type字段
      └ idstring职位性质 ID
      └ namei18n职位性质名称
        └ zh_cnstring中文名称
        └ en_usstring英文名称
    └ employee_typeid_name_object人员类型
      └ idstring人员类型 ID，与employee_type_id_type类型一致
      └ namei18n人员类型名称
        └ zh_cnstring中文名称
        └ en_usstring英文名称
    └ max_levelid_name_object最高职级
      └ idstring最高职级 ID，与job_level_id_type类型一致
      └ namei18n最高职级名称
        └ zh_cnstring中文名称
        └ en_usstring英文名称
    └ min_levelid_name_object最低职级
      └ idstring最低职级 ID，与job_level_id_type类型一致
      └ namei18n最低职级名称
        └ zh_cnstring中文名称
        └ en_usstring英文名称
    └ sequenceid_name_object职位序列
      └ idstring职位序列 ID，与job_family_id_type类型一致
      └ namei18n职位序列名称
        └ zh_cnstring中文名称
        └ en_usstring英文名称
    └ categoryint需求类型
可选值有：
- 1: 新增 - 2: 替换
    └ departmentid_name_object需求部门
      └ idstring需求部门 ID，与department_id_type类型一致
      └ namei18n需求部门名称
        └ zh_cnstring中文名称
        └ en_usstring英文名称
    └ recruiter_listid_name_object\[\]需求负责人
      └ idstring需求负责人 ID，与user_id_type类型一致
      └ namei18n需求负责人名称
        └ zh_cnstring中文名称
        └ en_usstring英文名称
    └ jr_hiring_managersid_name_object\[\]需求用人经理
      └ idstring需求用人经理 ID，与user_id_type类型一致
      └ namei18n需求用人经理名称
        └ zh_cnstring中文名称
        └ en_usstring英文名称
    └ direct_leader_listid_name_object\[\]直属上级
      └ idstring直属上级 ID，与user_id_type类型一致
      └ namei18n直属上级名称
        └ zh_cnstring中文名称
        └ en_usstring英文名称
    └ start_timestring开始日期，毫秒时间戳
    └ deadlinestring预计完成日期，毫秒时间戳
    └ priorityint招聘优先级
可选值有：
- 1: 高 - 2: 中 - 3: 低
    └ required_degreeint学历要求
可选值有：
- 1: 小学及以上 - 2: 初中及以上 - 3: 专职及以上 - 4: 高中及以上 - 5: 大专及以上 - 6: 本科及以上 - 7: 硕士及以上 - 8: 博士及以上 - 20: 不限
    └ max_salarystring最高月薪，单位：K
    └ min_salarystring最低月薪，单位：K
    └ addressid_name_object工作地址
      └ idstring工作地址 ID，详情请参考：获取地址列表获取
      └ namei18n工作地址名称
        └ zh_cnstring中文名称
        └ en_usstring英文名称
    └ descriptionstring需求描述
    └ customized_data_listjob_requirement_customized_data_dto\[\]自定义字段
      └ object_idstring自定义字段 ID，详情请参考：获取招聘需求模板
      └ namei18n字段名称
        └ zh_cnstring中文名称
        └ en_usstring英文名称
      └ object_typeint字段类型
可选值有：
- 1: 单行文本 - 2: 多行文本 - 3: 单选 - 4: 多选 - 5: 日期 - 6: 月份选择 - 7: 年份选择 - 8: 时间段 - 9: 数字 - 10: 默认字段 - 11: 模块
      └ valuejob_requirement_customized_value自定义字段值
        └ contentstring当字段类型为单行文本、多行文本、模块、默认字段时，从此字段取值
        └ optionjob_requirement_customized_option当字段类型为单选时，从此字段取值
          └ keystring选项 ID
          └ namei18n选项名称
            └ zh_cnstring中文名称
            └ en_usstring英文名称
        └ option_listjob_requirement_customized_option\[\]当字段类型为多选时，从此字段取值
          └ keystring选项 ID
          └ namei18n选项名称
            └ zh_cnstring中文名称
            └ en_usstring英文名称
        └ time_rangejob_requirement_customized_time_range当字段类型为时间段时，从此字段取值
          └ start_timestring开始时间，毫秒时间戳
          └ end_timestring结束时间，毫秒时间戳
        └ timestring当字段类型为日期选择、月份选择、年份选择时，从此字段取值，该字段是毫秒时间戳
        └ numberstring当字段类型为数字时，从此字段取值
    └ process_typeint招聘类型
可选值有：
- 1: 社招 - 2: 校招
    └ job_typejob_type_info职位类别
      └ idstring职位类别 ID
      └ namei18n职位类别名称
        └ zh_cnstring中文名称
        └ en_usstring英文名称
      └ parent_idstring父级职位类别 ID
    └ create_timestring创建时间，毫秒时间戳
    └ creator_idstring创建人 ID，与入参 user_id_type 类型一致
    └ update_timestring更新时间，毫秒时间戳
    └ employment_job_idstring职务ID，详情请查看：查询单个职务
    └ position_idstring岗位ID，详情请查看：查询岗位信息
    └ completion_timestring完成时间，毫秒级时间戳
    └ approval_statusint审批状态
可选值有：
- 1: 未发起 - 2: 审批中 - 3: 审批通过 - 4: 已撤回 - 5: 未通过

响应体示例 ​

json
{
    "code": 0,
    "msg": "SUCCESS",
    "data": {
        "job_requirement": {
            "id": "6949805467799537964",
            "short_code": "R01905",
            "name": "HR部门春季招聘需求",
            "display_progress": 1,
            "head_count": 10,
            "recruitment_type": {
                "id": "101",
                "name": {
                    "zh_cn": "社招-全职",
                    "en_us": "Social recruitment - Full time"
                }
            },
            "employee_type": {
                "id": "6807409776231254285",
                "name": {
                    "zh_cn": "专家",
                    "en_us": "specialist"
                }
            },
            "max_level": {
                "id": "mga5oa8ayjlp9rb",
                "name": {
                    "zh_cn": "高级专家",
                    "en_us": "senior specialist"
                }
            },
            "min_level": {
                "id": "mga5oa8ayjlp9ra",
                "name": {
                    "zh_cn": "专家",
                    "en_us": "specialist"
                }
            },
            "sequence": {
                "id": "mga5oa8ayjlpzjq",
                "name": {
                    "zh_cn": "产品",
                    "en_us": "product manager"
                }
            },
            "category": 1,
            "department": {
                "id": "D096",
                "name": {
                    "zh_cn": "产品部门",
                    "en_us": "product manager department"
                }
            },
            "recruiter_list": [
                {
                    "id": "ou_a586b1865a876389400de162d8d81071",
                    "name": {
                        "zh_cn": "张三",
                        "en_us": "zhangsan"
                    }
                }
            ],
            "jr_hiring_managers": [
                {
                    "id": "ou_a586b1865a876389400de162d8d81071",
                    "name": {
                        "zh_cn": "李四",
                        "en_us": "lisi"
                    }
                }
            ],
            "direct_leader_list": [
                {
                    "id": "ou_a586b1865a876389400de162d8d81071",
                    "name": {
                        "zh_cn": "王五",
                        "en_us": "wangwu"
                    }
                }
            ],
            "start_time": "1625729379000",
            "deadline": "1625729379000",
            "priority": 1,
            "required_degree": 1,
            "max_salary": "10",
            "min_salary": "5",
            "address": {
                "id": "7275291385551945731",
                "name": {
                    "zh_cn": "北京",
                    "en_us": "Beijing"
                }
            },
            "description": "部门人力紧缺，需要招聘资深工程师10名",
            "customized_data_list": [
                {
                    "object_id": "123123123",
                    "name": {
                        "zh_cn": "招聘原因",
                        "en_us": "Recruitment reason"
                    },
                    "object_type": 1,
                    "value": {
                        "content": "人员紧缺程度",
                        "option": {
                            "key": "serious",
                            "name": {
                                "zh_cn": "严重",
                                "en_us": "serious"
                            }
                        },
                        "option_list": [
                            {
                                "key": "serious",
                                "name": {
                                    "zh_cn": "严重",
                                    "en_us": "serious"
                                }
                            }
                        ],
                        "time_range": {
                            "start_time": "1625729379000",
                            "end_time": "1625729380000"
                        },
                        "time": "1625456721000",
                        "number": "100"
                    }
                }
            ],
            "process_type": 1,
            "job_type": {
                "id": "6930815272790114324",
                "name": {
                    "zh_cn": "金融",
                    "en_us": "finance"
                },
                "parent_id": "6930815272790114323"
            },
            "create_time": "1718856006000",
            "creator_id": "ou_e2fc714c4727ee9395f324cd2e7f331f",
            "update_time": "1718856006000",
            "employment_job_id": "6807407987381831949",
            "position_id": "7094136522860922111",
            "completion_time": "1736846689278",
            "approval_status": 1
        }
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
5001002001系统错误请根据实际报错信息定位或咨询技术支持
4001002002参数错误检查参数是否正确，例如类型，大小
5001002701不允许通过OpenAPI进行新建、编辑、删除招聘需求若要通过OpenAPI管理招聘需求，请通过「飞书招聘」-「设置」-「招聘需求管理」-「招聘需求设置」开启「通过API新建、编辑、删除招聘需求」
4001002702招需需求编号重复请检查short_code参数
4001002705已启用招聘需求审批，不可通过API 新建、编辑招聘需求开启招聘需求审批功能后，暂不支持通过API新建、编辑招聘需求。是否开启审批功能，请参考「飞书招聘」-「设置」-「招聘需求管理」-「招聘需求设置」下的「招聘需求审批」配置
4001002708人员类型不存在请检查recruitment_type_id 或者employee_type_id参数
4001002710招聘需求职级已停用请检查min_level_id或max_level_id参数
4001002721需求负责人存在重复、需求用人经理存在重复、或直属上级存在重复请检查recruiter_id_list、jr_hiring_manager_id_list或direct_leader_id_list参数
4001002722「当前招聘需求人数」或「编制关联的所有招聘需求人数」超出空缺编制数，无法创建（该错误码仅对招聘人事一体化客户有效，如客户在编制侧开启创建招聘需求时需校验是否超编，则可能返回此错误码）请比对需求人数与当前编制空缺数
4001002723未填写编制校验的必须内容请按照编制校验要求，传入需要校验的字段内容
4001002724企业开启了招聘需求审批，需求通过审批前无法关联职位。-

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

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