飞书开放平台 Server API 文档

主题

创建任职信息 ​

在系统中第一次创建员工任职数据，通常在员工入职或者做数据批量导入的时候使用，【任职原因】只支持填写“onboarding”。

Tip: - 非必填字段，不传时默认为空

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/corehr/v1/job_datas
HTTP MethodPOST
接口频率限制1000 次/分钟、50 次/秒
支持的应用类型custom
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可corehr:corehr 更新核心人事信息 corehr:job_data:write 读写任职信息
字段权限要求> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 corehr:employment.pathway:read 获取员工通道信息 corehr:employment.pathway:write 读写员工通道 contact:user.employee_id:readonly 获取用户 user ID corehr:job_data.compensation_type:read 获取薪资类型 corehr:job_data.service_company:read 获取任职公司 corehr:job_data.work_shift:read 获取排班信息

请求头 ​

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

查询参数 ​

名称类型必填描述
client_tokenstring否操作的唯一标识，用于幂等的进行更新操作，格式为标准的 UUIDV4。此值为空表示将发起一次新的请求，此值非空表示幂等的进行更新操作。
示例值："fe599b60-450f-46ff-b2ef-9f6675625b97"
user_id_typestring否用户 ID 类型
示例值：people_corehr_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？ - people_corehr_id: 以飞书人事的 ID 来识别用户
默认值：people_corehr_id
当值为 user_id，字段权限要求： contact:user.employee_id:readonly 获取用户 user ID
department_id_typestring否此次调用中使用的部门 ID 类型
示例值：open_department_id
可选值有：
- open_department_id: 【飞书】用来在具体某个应用中标识一个部门，同一个 department_id 在不同应用中的 open_department_id 相同。 - department_id: 【飞书】用来标识租户内一个唯一的部门。 - people_corehr_department_id: 【飞书人事】用来标识「飞书人事」中的部门。
默认值：people_corehr_department_id

请求体 ​

名称类型必填描述
job_level_idstring否职务级别 ID，枚举值及详细信息可通过【批量查询职级】接口查询获得
示例值："6890452208593372679"
job_grade_idstring否职等 ID，枚举值及详细信息可通过【查询职等】接口查询获得
示例值："6890452208593372679"
employee_type_idstring是人员类型 ID，枚举值及详细信息可通过【批量查询人员类型】接口查询获得
示例值："6890452208593372679"
working_hours_type_idstring否工时制度 ID，枚举值及详细信息可通过【批量查询工时制度】接口查询获得
示例值："6890452208593372679"
work_location_idstring否工作地点 ID，枚举值及详细信息可通过【批量查询地点】接口查询获得
示例值："6890452208593372679"
department_idstring是部门 ID，枚举值及详细信息可通过【批量查询部门】接口查询获得 与 department_id_type 类型一致
示例值："6890452208593372679"
job_idstring否职务 ID，枚举值及详细信息可通过【批量查询职务】接口查询获得
示例值："6890452208593372679"
probation_start_datestring否试用期开始日期
示例值："2018-03-16"
probation_end_datestring否试用期结束日期（实际结束日期）
示例值："2019-05-24"
primary_job_databoolean是是否为主任职 - 该字段已废弃，默认为 true，不可更改
示例值：true
employment_idstring是雇佣 ID，详细信息可以通过【搜索员工信息】接口查询获得 与 user_id_type 类型一致
示例值："6893014062142064135"
effective_timestring是生效时间
示例值："2020-05-01 00:00:00"
expiration_timestring否失效时间
示例值："2020-05-02 00:00:00"
job_family_idstring否职务序列 ID，枚举值及详细信息可通过【批量查询序列】接口查询获得
示例值："1245678"
assignment_start_reasonenum是业务类型（原：任职原因） - 可通过【获取字段详情】接口查询，查询参数如下： - object_api_name：job_data - custom_api_name：assignment_start_reason - 这里只支持填写"onboarding"
示例值：onboarding
  └ enum_namestring是枚举值
示例值："onboarding"
probation_expected_end_datestring否预计试用期结束日期
示例值："2006-01-02"
direct_manager_idstring否直属上级的任职记录 ID，详细信息可通过【批量查询员工任职信息】接口查询获得
示例值："6890452208593372679"
dotted_line_manager_id_liststring\[\]否虚线上级的任职记录 ID，详细信息可通过【批量查询员工任职信息】接口查询获得
示例值：["6890452208593372681"]
second_direct_manager_idstring否第二直属上级的任职记录 ID，详细信息可通过【批量查询员工任职信息】接口查询获得
示例值："6890452208593372679"
cost_center_ratesupport_cost_center_item\[\]否成本中心分摊信息
  └ cost_center_idstring否支持的成本中心 ID，详细信息可通过【搜索成本中心信息】接口查询获得
示例值："6950635856373745165"
  └ rateint否分摊比例
示例值：100
work_shiftenum否排班类型，枚举值 api_name 可通过【获取字段详情】接口查询，查询参数如下： - object_api_name = "job_data" - custom_api_name = "work_shift"
  └ enum_namestring是枚举值。需自定义
示例值："example"
compensation_typeenum否薪资类型，枚举值 api_name 可通过【获取字段详情】接口查询，查询参数如下： - object_api_name = "job_data" - custom_api_name = "compensation_type"
  └ enum_namestring是枚举值。需自定义
示例值："example"
service_companystring否任职公司 ID，详细信息可通过【批量查询公司】接口查询获得
示例值："6890452208593372680"
position_idstring否岗位 ID，枚举值及详细信息可通过【查询单个岗位】接口查询获得
示例值："6890452208593372679"
pathway_idstring否通道 ID
示例值："6890452208593372671"

请求体示例 ​

json
{
    "job_level_id": "6890452208593372679",
    "job_grade_id": "6890452208593372679",
    "employee_type_id": "6890452208593372679",
    "working_hours_type_id": "6890452208593372679",
    "work_location_id": "6890452208593372679",
    "department_id": "6890452208593372679",
    "job_id": "6890452208593372679",
    "probation_start_date": "2018-03-16",
    "probation_end_date": "2019-05-24",
    "primary_job_data": true,
    "employment_id": "6893014062142064135",
    "effective_time": "2020-05-01 00:00:00",
    "expiration_time": "2020-05-02 00:00:00",
    "job_family_id": "1245678",
    "assignment_start_reason": {
        "enum_name": "onboarding"
    },
    "probation_expected_end_date": "2006-01-02",
    "direct_manager_id": "6890452208593372679",
    "dotted_line_manager_id_list": [
        "6890452208593372681"
    ],
    "second_direct_manager_id": "6890452208593372679",
    "cost_center_rate": [
        {
            "cost_center_id": "6950635856373745165",
            "rate": 100
        }
    ],
    "work_shift": {
        "enum_name": "example"
    },
    "compensation_type": {
        "enum_name": "example"
    },
    "service_company": "6890452208593372680",
    "position_id": "6890452208593372679",
    "pathway_id": "6890452208593372671"
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ job_datajob_data创建成功返回job data信息
    └ idstring任职信息 ID，用于后续更新和查询
    └ version_idstring任职记录版本 ID，可用于指定版本更新
    └ job_level_idstring职务级别 ID，枚举值及详细信息可通过【查询单个职级】接口查询获得
    └ job_grade_idstring职等 ID，枚举值及详细信息可通过【查询职等】接口查询获得
    └ employee_type_idstring人员类型 ID，枚举值及详细信息可通过【查询单个人员类型】接口查询获得
    └ working_hours_type_idstring工时制度 ID，枚举值及详细信息可通过【查询单个工时制度】接口查询获得
    └ work_location_idstring工作地点 ID，枚举值及详细信息可通过【查询单个地点】接口查询获得
    └ department_idstring部门 ID，枚举值及详细信息可通过【查询单个部门】接口查询获得 与 department_id_type 类型一致
    └ job_idstring职务 ID，枚举值及详细信息可通过【查询单个职务】接口查询获得
    └ probation_start_datestring试用期开始日期
    └ probation_end_datestring试用期结束日期（实际结束日期）
    └ primary_job_databoolean是否为主任职
    └ employment_idstring雇佣 ID，详细信息可以通过【搜索员工信息】接口查询获得 与 user_id_type 类型一致
    └ effective_timestring任职记录版本的生效时间
    └ expiration_timestring任职记录版本的失效时间
    └ job_family_idstring职务序列 ID，枚举值及详细信息可通过【查询单个序列】接口查询获得
    └ assignment_start_reasonenum业务类型（原：任职原因） - 可通过【获取字段详情】接口查询，查询参数如下： - object_api_name：job_data - custom_api_name：assignment_start_reason
      └ enum_namestring枚举值
      └ displayi18n\[\]枚举多语展示
        └ langstring名称信息的语言
        └ valuestring名称信息的内容
    └ probation_expected_end_datestring预计试用期结束日期
    └ weekly_working_hoursint周工作时长
    └ direct_manager_idstring直属上级的任职记录 ID，详细信息可通过【批量查询员工任职信息】接口查询获得
    └ dotted_line_manager_id_liststring\[\]虚线上级的任职记录 ID，详细信息可通过【批量查询员工任职信息】接口查询获得
    └ second_direct_manager_idstring第二直属上级的任职记录 ID，详细信息可通过【批量查询员工任职信息】接口查询获得
    └ cost_center_ratesupport_cost_center_item\[\]成本中心分摊信息
      └ cost_center_idstring支持的成本中心 ID，详细信息可通过【搜索成本中心信息】接口查询获得
      └ rateint分摊比例
    └ weekly_working_hours_v2number(float)周工作时长
    └ work_shiftenum排班类型
字段权限要求： corehr:job_data.work_shift:read 获取排班信息
      └ enum_namestring枚举值
      └ displayi18n\[\]枚举多语展示
        └ langstring语言
        └ valuestring内容
    └ compensation_typeenum薪资类型
字段权限要求： corehr:job_data.compensation_type:read 获取薪资类型
      └ enum_namestring枚举值
      └ displayi18n\[\]枚举多语展示
        └ langstring语言
        └ valuestring内容
    └ service_companystring任职公司，枚举值及详细信息可通过【查询单个序列】接口查询获得
字段权限要求： corehr:job_data.service_company:read 获取任职公司
    └ pathway_idstring通道 ID
字段权限要求（满足任一）： corehr:employment.pathway:read 获取员工通道信息 corehr:employment.pathway:write 读写员工通道

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "job_data": {
            "id": "6890452208593372679",
            "version_id": "6890452208593372697",
            "job_level_id": "6890452208593372679",
            "job_grade_id": "6890452208593372679",
            "employee_type_id": "6890452208593372679",
            "working_hours_type_id": "6890452208593372679",
            "work_location_id": "6890452208593372679",
            "department_id": "6890452208593372679",
            "job_id": "6890452208593372679",
            "probation_start_date": "2018-03-16",
            "probation_end_date": "2019-05-24",
            "primary_job_data": true,
            "employment_id": "6893014062142064135",
            "effective_time": "2020-05-01 00:00:00",
            "expiration_time": "2020-05-02 00:00:00",
            "job_family_id": "1245678",
            "assignment_start_reason": {
                "enum_name": "onboarding",
                "display": [
                    {
                        "lang": "zh-CN",
                        "value": "张三"
                    }
                ]
            },
            "probation_expected_end_date": "2006-01-02",
            "weekly_working_hours": 30,
            "direct_manager_id": "6890452208593372679",
            "dotted_line_manager_id_list": [
                "6890452208593372681"
            ],
            "second_direct_manager_id": "6890452208593372679",
            "cost_center_rate": [
                {
                    "cost_center_id": "6950635856373745165",
                    "rate": 100
                }
            ],
            "weekly_working_hours_v2": 37.5,
            "work_shift": {
                "enum_name": "example",
                "display": [
                    {
                        "lang": "zh-CN",
                        "value": "刘梓新"
                    }
                ]
            },
            "compensation_type": {
                "enum_name": "example",
                "display": [
                    {
                        "lang": "zh-CN",
                        "value": "刘梓新"
                    }
                ]
            },
            "service_company": "6890452208593372680",
            "pathway_id": "6890452208593372671"
        }
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
4001160004request ID repeat请检查输入参数的client_tokne
4001160019The sum of cost center apportionment ratio should be 100.分摊比例之和必须是100
4001160003record is deleted by others数据被删除，请检查数据
5001160999unknown error请联系技术支持
5001160997unknown meta rpc error请重试，重试仍失败请联系技术支持
5001160998unknown vault rpc error请重试，重试仍失败请联系技术支持

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

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