飞书开放平台 Server API 文档

主题

更新雇佣信息 ​

更新人事工作信息下的字段，如：工号、工作邮箱、雇佣类型、自定义字段等

Tip: - 非必填字段，不传时即不做变更

  • 若开启工号自动编码规则则无需输入人员“工号”，系统将自动进行工号生成；若手动输入工号，则会按照手动输入工号内容进行人员档案建立
  • 暂不支持更新时间轴分组对象

请求 ​

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

路径参数 ​

名称类型描述
employment_idstring雇佣 ID - 类型应与 user_id_type 一致
示例值："1616161616"

查询参数 ​

名称类型必填描述
client_tokenstring否根据client_token是否一致来判断是否为同一请求
示例值：12454646
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 类型
示例值：department_id
可选值有：
- open_department_id: 以 open_department_id 来标识部门 - department_id: 以 department_id 来标识部门 - people_corehr_department_id: 以 people_corehr_department_id 来标识部门
默认值：people_corehr_department_id

请求体 ​

名称类型必填描述
seniority_datestring否资历起算日期
示例值："2020-01-01"
employee_numberstring否员工编号（工号） - 开启自动编码时不可以主动更新 - 未开启自动编码，可主动更新： - 由数字或字母组成，请勿使用特殊字符 - 请保证唯一
示例值："1000000"
employment_typeenum否雇佣类型 - 可通过【获取字段详情】接口查询，查询参数如下： - object_api_name：employment - custom_api_name：employment_type
  └ enum_namestring是枚举值
示例值："employee"
person_idstring否个人信息 ID，由【创建个人信息】时生成
示例值："6919733936050406926"
primary_employmentboolean否是否是主雇佣信息
示例值：true
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"

请求体示例 ​

json
{
    "seniority_date": "2020-01-01",
    "employee_number": "1000000",
    "employment_type": {
        "enum_name": "employee"
    },
    "person_id": "6919733936050406926",
    "primary_employment": true,
    "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"
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ employmentemployment雇佣信息
    └ 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；可通过【批量查询员工信息】获取更多信息；类型与 user_id_type 一致
    └ 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是否在试用期中 - 满足以下任一条件时，该字段值为"true"： - 预计试用结束日期非空，且实际结束日期为空 - 预计试用结束日期非空，实际结束日期非空，且当日日期小于等于实际结束日期 - 其余情况下，该字段值为"false"；
    └ 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\[\]工作邮箱列表
      └ 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 ，详细信息可以通过【获取投递信息】接口查询获得

响应体示例 ​

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": "2021-01-01 00:00:00",
            "employment_type": {
                "enum_name": "employee",
                "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": "hired",
                "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": "work",
                        "display": [
                            {
                                "lang": "zh-CN",
                                "value": "张三"
                            }
                        ]
                    },
                    "custom_fields": [
                        {
                            "field_name": "name",
                            "value": "\"Sandy\""
                        }
                    ]
                }
            ],
            "email_address": "test@163.com",
            "reason_for_offboarding": {
                "enum_name": "voluntary",
                "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"
        }
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
5001160025didn't find employment with ID参数错误，请检查入参

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

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