飞书开放平台 Server API 文档

主题

创建雇佣信息 ​

创建人员的雇佣信息，需要先创建个人信息。

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

  • 若开启工号自动编码规则则无需输入人员“工号”，系统将自动进行工号生成；若手动输入工号，则会按照手动输入工号内容进行人员档案建立

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/corehr/v1/employments
HTTP MethodPOST
接口频率限制1000 次/分钟、50 次/秒
支持的应用类型custom
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可corehr:corehr 更新核心人事信息 corehr:employment:write 读写雇佣信息

请求头 ​

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

查询参数 ​

名称类型必填描述
client_tokenstring否根据client_token是否一致来判断是否为同一请求
示例值：12454646

请求体 ​

名称类型必填描述
seniority_datestring否资历起算日期
示例值："2020-01-01"
employee_numberstring否员工编号（工号） - 开启自动编码时由系统自动生成，填写值不生效 - 未开启自动编码，请主动传递： - 由数字或字母组成，请勿使用特殊字符 - 请保证唯一
示例值："1000000"
effective_timestring是入职日期
示例值："2020-01-01 00:00:00"
expiration_timestring否离职日期，不能早于入职日期
示例值："2020-01-01 00:00:00"
employment_typeenum是雇佣类型 - 可通过【获取字段详情】接口查询，查询参数如下： - object_api_name：employment - custom_api_name：employment_type
  └ enum_namestring是枚举值
示例值："employee"
person_idstring是个人信息ID，由【创建个人信息】时生成 - 当 rehire 值为 yes 时，该个人信息的【姓名信息】必须有值
示例值："6919733936050406926"
primary_employmentboolean是是否是主雇佣信息
示例值：true
employment_statusenum是雇佣状态 - 可通过【获取字段详情】接口查询，查询参数如下： - object_api_name：employment - custom_api_name：employment_status
  └ enum_namestring是枚举值
示例值："hired"
custom_fieldsobject_field_data\[\]否自定义字段 - 请参考【自定义字段说明】
  └ field_namestring是字段名
示例值："name"
  └ valuestring是字段值，是json转义后的字符串，根据元数据定义不同，字段格式不同(如123, 123.23, "true", ["id1","id2"], "2006-01-02 15:04:05")
示例值：""Sandy""
work_email_listemail\[\]否工作邮箱列表 - 只有当满足下面所有条件时，才在工作信息页面可见： - is_primary = "true" - is_public = "true" - email_usage = "work"
  └ emailstring是邮箱号
示例值："12456@test.com"
  └ is_primaryboolean否是否为主要邮箱
示例值：true
  └ is_publicboolean否是否为公开邮箱
示例值：true
  └ email_usageenum否邮箱用途 - 可通过【获取字段详情】接口查询，查询参数如下： - object_api_name: email - custom_api_name：email_usage - 请勿填写 home 枚举
    └ enum_namestring是枚举值
示例值："work"
  └ custom_fieldsobject_field_data\[\]否自定义字段 - 请参考【自定义字段说明】
    └ field_namestring是字段名
示例值："name"
    └ valuestring是字段值，是json转义后的字符串，根据元数据定义不同，字段格式不同(如123, 123.23, "true", ["id1","id2"], "2006-01-02 15:04:05")
示例值：""Sandy""
reason_for_offboardingenum否离职原因 - 可通过【获取字段详情】接口查询，查询参数如下： - object_api_name：employment - custom_api_name：reason_for_offboarding
  └ enum_namestring是枚举值
示例值："voluntary"
ats_application_idstring否招聘投递 ID ，详细信息可以通过【获取投递信息】接口查询获得
示例值："6838119494196871234"
rehireenum否是否离职重聘 - to_be_confirmed：待确认，系统会判断该员工是否存在历史雇佣记录，如果存在且需要二次确认时会调用失败，并返回历史雇佣记录 - no：否，系统直接标为非离职重聘人员，不再做重复判断 - yes：是，要求历史雇佣信息 ID 必填
示例值：no
默认值：to_be_confirmed
  └ enum_namestring是枚举值
示例值："yes"
rehire_employment_idstring否历史雇佣信息 ID，可通过【批量查询员工信息】获得；类型不跟随 user_id_type
示例值："7051837122449425964"

请求体示例 ​

json
{
    "seniority_date": "2020-01-01",
    "employee_number": "1000000",
    "effective_time": "2020-01-01 00:00:00",
    "expiration_time": "2020-01-01 00:00:00",
    "employment_type": {
        "enum_name": "employee"
    },
    "person_id": "6919733936050406926",
    "primary_employment": true,
    "employment_status": {
        "enum_name": "hired"
    },
    "custom_fields": [
        {
            "field_name": "name",
            "value": "\"Sandy\""
        }
    ],
    "work_email_list": [
        {
            "email": "12456@test.com",
            "is_primary": true,
            "is_public": true,
            "email_usage": {
                "enum_name": "work"
            },
            "custom_fields": [
                {
                    "field_name": "name",
                    "value": "\"Sandy\""
                }
            ]
        }
    ],
    "reason_for_offboarding": {
        "enum_name": "voluntary"
    },
    "ats_application_id": "6838119494196871234",
    "rehire": {
        "enum_name": "yes"
    },
    "rehire_employment_id": "7051837122449425964"
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ employmentemployment_create创建人员的雇佣信息成功返回信息
    └ prehire_idstring待入职ID，可通过【查询单个待入职】获取详细信息
    └ employee_type_idstring人员类型，可通过【查询单个人员类型】获取详细信息
    └ tenurestring司龄
    └ department_idstring部门 ID，可通过【查询单个部门】获取详细信息；类型不跟随department_id_type
    └ job_level_idstring职级 ID，可通过【查询单个职级】获取详细信息
    └ work_location_idstring工作地点 ID，可通过【查询单个地点】获取详细信息
    └ job_family_idstring职务序列 ID，可通过【查询单个序列】获取详细信息
    └ job_idstring职务 ID，可通过【查询单个职务】获取详细信息
    └ company_idstring法人主体 ID，可通过【查询单个公司】获取详细信息
    └ working_hours_type_idstring工时制度 ID，可通过【查询单个工时制度】获取详细信息
    └ idstring雇佣ID，实体在CoreHR内部的唯一键；可通过【批量查询员工信息】获取更多信息
    └ seniority_datestring资历起算日期
    └ employee_numberstring员工编号
    └ effective_timestring入职日期
    └ expiration_timestring离职日期
    └ employment_typeenum雇佣类型 - 可通过【获取字段详情】接口查询，查询参数如下： - object_api_name：employment - custom_api_name：employment_type
      └ enum_namestring枚举值
      └ displayi18n\[\]枚举多语展示
        └ langstring名称信息的语言
        └ valuestring名称信息的内容
    └ person_idstring个人信息ID，可通过【批量查询员工信息】获取详细信息
    └ probation_periodint试用期时长
    └ on_probationstring是否在试用期中
    └ probation_end_datestring试用期结束日期
    └ primary_employmentboolean是否是主雇佣信息
    └ employment_statusenum雇佣状态 - 可通过【获取字段详情】接口查询，查询参数如下： - object_api_name：employment - custom_api_name：employment_status
      └ enum_namestring枚举值
      └ displayi18n\[\]枚举多语展示
        └ langstring名称信息的语言
        └ valuestring名称信息的内容
    └ custom_fieldsobject_field_data\[\]自定义字段 - 请参考【自定义字段说明】
      └ field_namestring字段名
      └ valuestring字段值，是json转义后的字符串，根据元数据定义不同，字段格式不同(如123, 123.23, "true", ["id1","id2"], "2006-01-02 15:04:05")
    └ work_email_listemail\[\]工作邮箱列表，只有当邮箱下面所有条件时，才在个人信息页面可见： - is_primary = "true" - is_public = "true" - email_usage = "work"
      └ emailstring邮箱号
      └ is_primaryboolean是否为主要邮箱
      └ is_publicboolean是否为公开邮箱
      └ email_usageenum邮箱用途 - 可通过【获取字段详情】接口查询，查询参数如下： - object_api_name: email - custom_api_name：email_usage
        └ enum_namestring枚举值
        └ displayi18n\[\]枚举多语展示
          └ langstring名称信息的语言
          └ valuestring名称信息的内容
      └ custom_fieldsobject_field_data\[\]自定义字段 - 请参考【自定义字段说明】
        └ field_namestring字段名
        └ valuestring字段值，是json转义后的字符串，根据元数据定义不同，字段格式不同(如123, 123.23, "true", ["id1","id2"], "2006-01-02 15:04:05")
    └ email_addressstring邮箱
    └ reason_for_offboardingenum离职原因 - 可通过【获取字段详情】接口查询，查询参数如下： - object_api_name：employment - custom_api_name：reason_for_offboarding
      └ enum_namestring枚举值
      └ displayi18n\[\]枚举多语展示
        └ langstring名称信息的语言
        └ valuestring名称信息的内容
    └ cost_center_listjob_data_cost_center\[\]成本中心id列表
      └ cost_center_idstring成本中心id，可以通过【搜索成本中心信息】获取详细信息
      └ rateint分摊比例
      └ custom_fieldsobject_field_data\[\]自定义字段 - 请参考【自定义字段说明】
        └ field_namestring字段名
        └ valuestring字段值，是json转义后的字符串，根据元数据定义不同，字段格式不同(如123, 123.23, "true", ["id1","id2"], "2006-01-02 15:04:05")
    └ ats_application_idstring招聘投递 ID ，详细信息可以通过【获取投递信息】接口查询获得
    └ rehireenum是否离职重聘
- to_be_confirmed：待确认 - no：否 - yes：是
      └ enum_namestring枚举值
      └ displayi18n\[\]枚举多语展示
        └ langstring名称信息的语言
        └ valuestring名称信息的内容
    └ rehire_employment_idstring历史雇佣信息 ID，可通过【批量查询员工信息】、 【搜索员工信息】获取详细信息

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "employment": {
            "prehire_id": "1",
            "employee_type_id": "1",
            "tenure": "1",
            "department_id": "6893014062142064135",
            "job_level_id": "6893014062142064135",
            "work_location_id": "6893014062142064135",
            "job_family_id": "6893014062142064135",
            "job_id": "6893014062142064135",
            "company_id": "6893014062142064135",
            "working_hours_type_id": "6893014062142064135",
            "id": "6893014062142064135",
            "seniority_date": "2020-01-01",
            "employee_number": "1000000",
            "effective_time": "2020-01-01 00:00:00",
            "expiration_time": "2020-01-01 00:00:00",
            "employment_type": {
                "enum_name": "type_1",
                "display": [
                    {
                        "lang": "zh-CN",
                        "value": "张三"
                    }
                ]
            },
            "person_id": "6919733936050406926",
            "probation_period": 9999,
            "on_probation": "true",
            "probation_end_date": "2022-01-01",
            "primary_employment": true,
            "employment_status": {
                "enum_name": "type_1",
                "display": [
                    {
                        "lang": "zh-CN",
                        "value": "张三"
                    }
                ]
            },
            "custom_fields": [
                {
                    "field_name": "name",
                    "value": "\"Sandy\""
                }
            ],
            "work_email_list": [
                {
                    "email": "12456@test.com",
                    "is_primary": true,
                    "is_public": true,
                    "email_usage": {
                        "enum_name": "type_1",
                        "display": [
                            {
                                "lang": "zh-CN",
                                "value": "张三"
                            }
                        ]
                    },
                    "custom_fields": [
                        {
                            "field_name": "name",
                            "value": "\"Sandy\""
                        }
                    ]
                }
            ],
            "email_address": "test@163.com",
            "reason_for_offboarding": {
                "enum_name": "type_1",
                "display": [
                    {
                        "lang": "zh-CN",
                        "value": "张三"
                    }
                ]
            },
            "cost_center_list": [
                {
                    "cost_center_id": "6950635856373745165",
                    "rate": 100,
                    "custom_fields": [
                        {
                            "field_name": "name",
                            "value": "\"Sandy\""
                        }
                    ]
                }
            ],
            "ats_application_id": "6838119494196871234",
            "rehire": {
                "enum_name": "type_1",
                "display": [
                    {
                        "lang": "zh-CN",
                        "value": "张三"
                    }
                ]
            },
            "rehire_employment_id": "7051837122449425964"
        }
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
4001160011Duplicate employment existed该员工疑似离职重聘，你可以： 1. 通过传 rehire = no，强制生成「非离职重聘」的雇佣信息 2. 选择正确的历史雇佣记录填入后重新提交
4001160012Rehire person is in the onboarding process该人员有一条疑似待入职记录 ，你可以： 1. 通过传 rehire = no，强制生成「非离职重聘」的雇佣信息 2. 继续在飞书人事中完成该人员的入职操作 3. 填入其他历史雇佣信息，重新调用接口创建雇佣信息
4001160013Param is invalid请检查参数是否符合要求
4001160014Rehire information abnormal.历史雇佣记录填写不正确，需要为该人员最新的已离职雇佣信息
4001160015function is not open yet.重聘功能还未开放，敬请期待
4001160016--根据报错处理
4001160004request ID repeat传入的参数client_token重复
4001160010ats_application_id should be 19 digit stringats_application_id格式不正确
5001160025record not found检查入参

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

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