飞书开放平台 Server API 文档

主题

搜索离职信息 ​

该接口支持根据员工ID、离职审批发起时间和离职日期等字段搜索离职信息，可获取包括离职日期、离职原因、离职状态和流程审批状态等信息。

Tip: 注意：该接口会按照应用拥有的「员工数据」的权限范围返回数据，请确定在「开发者后台 - 权限管理 - 数据权限-飞书人事（企业版）数据权限」中申请了「员工资源」权限范围。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/corehr/v1/offboardings/search
HTTP MethodPOST
接口频率限制100 次/分钟
支持的应用类型custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可corehr:offboarding:read 获取员工离职信息 corehr:offboarding:write 读写员工离职信息
字段权限要求> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 corehr:employment.offboarding_reason:read 获取员工离职原因 corehr:offboarding.custom_field:read 获取离职信息自定义字段信息 corehr:offboarding.block_list:read 获取离职屏蔽名单 corehr:offboarding.block_list:write 读写离职屏蔽名单 contact:user.employee_id:readonly 获取用户 user ID corehr:offboarding.last_attendance_date:read 获取离职申请的最后出勤日 corehr:offboarding.noncompete_agreement:read 获取离职申请的竞业信息 corehr:offboarding.retain_account:read 获取离职后是否保留账号字段 corehr:offboarding.retain_account:write 读写离职后是否保留账号字段 corehr:offboarding.signature:read 获取离职申请的电子签相关字段 corehr:offboarding.social_insurance:read 获取离职申请的社保信息

请求头 ​

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

查询参数 ​

名称类型必填描述
page_sizeint是分页大小，最大 100
示例值：100
数据校验规则：
- 取值范围：1 ～ 100
page_tokenstring否分页标记，第一次请求不填，表示从头开始遍历；分页查询结果还有更多项时会同时返回新的 page_token，下次遍历可采用该 page_token 获取查询结果
示例值：6891251722631890445
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？ - people_corehr_id: 以飞书人事的 ID 来识别用户
默认值：open_id
当值为 user_id，字段权限要求： contact:user.employee_id:readonly 获取用户 user ID

请求体 ​

名称类型必填描述
employment_idsstring\[\]否雇佣 ID 列表，ID类型与查询参数 user_id_type取值一致：
- 当user_id_type取值为open_id时，ID获取方式参考如何获取自己的Open ID。
- 当user_id_type取值为user_id时，ID获取方式参考如何获取自己的 User ID。
- 当user_id_type取值为union_id时，ID获取方式参考如何获取自己的 Union ID。
- 当user_id_type取值为people_corehr_id时，先参考如何获取自己的 User ID获取User ID。然后通过ID 转换获取雇佣ID。
示例值：["7140964208476371111"]
apply_initiating_time_startstring否离职审批发起时间（搜索的起始范围），请按照秒级时间戳格式传入。该字段非必填，需要与离职审批发起时间（搜索的结束范围）一同使用。
示例值："1672578336"
apply_initiating_time_endstring否离职审批发起时间（搜索的结束范围），请按照秒级时间戳格式传入。该字段非必填，需要与离职审批发起时间（搜索的起始范围）一同使用。
示例值："1674133537"
apply_finished_time_startstring否离职审批结束时间（搜索的起始范围），请按照秒级时间戳格式传入。该字段非必填，需要与离职审批结束时间（搜索的结束范围）一同使用。
示例值："1641007353"
apply_finished_time_endstring否离职审批结束时间 （搜索的结束范围），请按照秒级时间戳格式传入。该字段非必填，需要与离职审批结束时间（搜索的起始范围）一同使用。
示例值："1641007353"
expected_offboarding_date_startstring否期望离职日期（搜索的起始范围），请按日期格式传入。该字段非必填，需要与期望离职日期（搜索的结束范围）一同使用
示例值："2022-01-01"
expected_offboarding_date_endstring否期望离职日期（搜索的结束范围），请按日期格式传入。该字段非必填，需要与期望离职日期（搜索的起始范围）一同使用。
示例值："2022-01-01"
offboarding_date_startstring否离职日期（搜索的起始范围），请按日期格式传入。该字段非必填，需要与离职日期（搜索的结束范围）一同使用。
示例值："2022-01-01"
offboarding_date_endstring否离职日期（搜索的结束范围），该字段非必填，需要与离职日期（搜索的起始范围）一同使用。
示例值："2022-01-01"
statusesstring\[\]否离职状态，多个状态之间为「或」的关系。为空时默认搜索所有状态的离职信息。
示例值：["Approving"]
可选值有：
- Approving: 审批中 - Approved: 审批通过 - Offboarded: 已离职 - Rejected: 已拒绝 - Withdrawn: 已撤销 - NoNeedApproval: 无需审批
数据校验规则：
- 最大长度：10
reasonsstring\[\]否离职原因列表 , 可以通过【查询员工离职原因列表】接口获取 ，查询时不返回下级原因相关的离职信息。为空时默认搜索所有离职数据。
字段权限要求： corehr:employment.offboarding_reason.search:read 按照离职原因搜索corehr:employment.offboarding_reason.search:read，确认已开通该权限。
示例值：["voluntary"]
employee_reasonsstring\[\]否离职原因（员工）列表 , 可以通过【查询员工离职原因列表】接口获取，查询时不返回下级原因相关的离职信息。为空时默认搜索所有离职数据。
字段权限要求： corehr:employment.offboarding_reason.search:read 按照离职原因搜索
示例值：["voluntary"]

请求体示例 ​

json
{
    "employment_ids": [
        "7140964208476371111"
    ],
    "apply_initiating_time_start": "1672578336",
    "apply_initiating_time_end": "1674133537",
    "apply_finished_time_start": "1641007353",
    "apply_finished_time_end": "1641007353",
    "expected_offboarding_date_start": "2022-01-01",
    "expected_offboarding_date_end": "2022-01-01",
    "offboarding_date_start": "2022-01-01",
    "offboarding_date_end": "2022-01-01",
    "statuses": [
        "Approving"
    ],
    "reasons": [
        "voluntary"
    ],
    "employee_reasons": [
        "voluntary"
    ]
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ itemsoffboarding\[\]查询的员工离职信息
    └ initiating_typestring离职发起类型，可选项包括：
-offboarding_initiated_by_self：员工申请离职
-offboarding_initiated_by_others：代发起离职申请
-offboarding_directly：直接离职
    └ statusstring离职状态
可选值有：
- Approving: 审批中 - Approved: 审批通过 - Offboarded: 已离职 - Rejected: 已拒绝 - Withdrawn: 已撤销 - NoNeedApproval: 无需审批
    └ application_infoapplication_info离职审批信息
      └ apply_initiator_idstring离职审批发起人的雇佣 ID。ID 类型与查询参数 user_id_type 的取值一致。例如，当user_id_type为user_id时，该字段取员工的user_id，若user_id_type为people_corehr_id时，则取该员工的人事雇佣ID。
      └ apply_initiating_timestring离职申请流程发起时间
      └ apply_finish_timestring离职申请流程结束时间
      └ process_idstring流程 ID。可用于查询流程相关信息，例如：作为获取单个流程详情的process_id查询流程详情。
    └ offboarding_infooffboarding_info员工离职信息
      └ employment_idstring离职员工的雇佣 ID，ID类型与查询参数 user_id_type取值一致：
1、当user_id_type取值为open_id时，ID获取方式参考如何获取自己的Open ID。
2、当user_id_type取值为user_id时，ID获取方式参考如何获取自己的 User ID。
3、当user_id_type取值为union_id时，ID获取方式参考如何获取自己的 Union ID。
4、当user_id_type取值为people_corehr_id时，先参考如何获取自己的 User ID获取User ID。然后通过ID 转换获取雇佣ID。
      └ hrbp_idstring\[\]员工的 hrbp 列表，ID类型与查询参数 user_id_type取值一致：
1、当user_id_type取值为open_id时，ID获取方式参考如何获取自己的Open ID。
2、当user_id_type取值为user_id时，ID获取方式参考如何获取自己的 User ID。
3、当user_id_type取值为union_id时，ID获取方式参考如何获取自己的 Union ID。
4、当user_id_type取值为people_corehr_id时，先参考如何获取自己的 User ID获取User ID。然后通过ID 转换获取雇佣ID。
      └ expected_offboarding_datestring期望离职日期
      └ offboarding_datestring离职日期
      └ reasonenum离职原因
字段权限要求： corehr:employment.offboarding_reason:read 获取员工离职原因
        └ enum_namestring枚举值
        └ displayi18n\[\]枚举多语展示
          └ langstring语言
          └ valuestring内容
      └ reason_explanationstring离职原因说明
字段权限要求： corehr:employment.offboarding_reason:read 获取员工离职原因
      └ employee_reasonenum离职原因（员工）
字段权限要求： corehr:employment.offboarding_reason:read 获取员工离职原因
        └ enum_namestring枚举值
        └ displayi18n\[\]枚举多语展示
          └ langstring语言
          └ valuestring内容
      └ employee_reason_explanationstring离职原因说明（员工）
字段权限要求： corehr:employment.offboarding_reason:read 获取员工离职原因
      └ add_block_liststring是否加入离职屏蔽名单。注意：该字段为字符类型。可选值有：
-true：是
-false：否
字段权限要求（满足任一）： corehr:offboarding.block_list:read 获取离职屏蔽名单 corehr:offboarding.block_list:write 读写离职屏蔽名单
      └ block_reasonenum屏蔽原因，枚举值可查询 【获取字段详情】接口获取,按如下参数查 询即可:
object_api_name= "offboarding_info"
custom_api_name= "block_reason"
字段权限要求（满足任一）： corehr:offboarding.block_list:read 获取离职屏蔽名单 corehr:offboarding.block_list:write 读写离职屏蔽名单
        └ enum_namestring枚举值
        └ displayi18n\[\]枚举多语展示
          └ langstring语言
          └ valuestring内容
      └ block_reason_explanationstring屏蔽原因说明
字段权限要求（满足任一）： corehr:offboarding.block_list:read 获取离职屏蔽名单 corehr:offboarding.block_list:write 读写离职屏蔽名单
      └ custom_fieldscustom_field_data\[\]自定义字段
字段权限要求： corehr:offboarding.custom_field:read 获取离职信息自定义字段信息
        └ custom_api_namestring自定义字段的唯一标识
        └ namecustom_name自定义字段名称
          └ zh_cnstring中文
          └ en_usstring英文
        └ typeint自定义字段类型。可选值有：
-1：文本类型，包括超链接字段
-2：布尔类型
-3：数字类型
-4：枚举类型
-5：Lookup类型，如离职人员、竞业公司等
-8：时间类型
-9：附件类型
注意：不支持的字段类型未给出说明。
        └ valuestring字段值，是 json 转义后的字符串，根据元数据定义不同，字段格式不同（如 123, 123.23, "true", ["id1","id2"], "2006-01-02 15:04:05"）
      └ retain_accountboolean离职是否保留飞书账号
字段权限要求（满足任一）： corehr:offboarding.retain_account:read 获取离职后是否保留账号字段 corehr:offboarding.retain_account:write 读写离职后是否保留账号字段
      └ social_insurance_end_datestring社保停保年月，按YYYY-MM的日期格式返回
字段权限要求： corehr:offboarding.social_insurance:read 获取离职申请的社保信息
      └ provident_fund_end_datestring公积金截止年月，按YYYY-MM的日期格式返回
字段权限要求： corehr:offboarding.social_insurance:read 获取离职申请的社保信息
      └ enforce_noncompete_agreementboolean是否启动竞业
字段权限要求： corehr:offboarding.noncompete_agreement:read 获取离职申请的竞业信息
      └ noncompete_agreement_idstring竞业合同ID，可以通过查询单个合同获取详细的合同信息
字段权限要求： corehr:offboarding.noncompete_agreement:read 获取离职申请的竞业信息
      └ noncompete_agreement_companystring竞业公司ID，可以通过查询单个公司获取详细的公司信息
字段权限要求： corehr:offboarding.noncompete_agreement:read 获取离职申请的竞业信息
      └ noncompete_agreement_start_datestring竞业开始日期
字段权限要求： corehr:offboarding.noncompete_agreement:read 获取离职申请的竞业信息
      └ noncompete_agreement_end_datestring竞业结束日期
字段权限要求： corehr:offboarding.noncompete_agreement:read 获取离职申请的竞业信息
      └ sign_typeenum签署方式，枚举值可查询 【获取字段详情】接口获取,按如下参数查 询即可:
object_api_name= "offboarding_info"
custom_api_name= "sign_type"
字段权限要求： corehr:offboarding.signature:read 获取离职申请的电子签相关字段
        └ enum_namestring枚举值
        └ displayi18n\[\]枚举多语展示
          └ langstring语言
          └ valuestring内容
      └ signature_filestring签署文件ID列表
字段权限要求： corehr:offboarding.signature:read 获取离职申请的电子签相关字段
      └ last_attendance_datestring最后出勤日
字段权限要求： corehr:offboarding.last_attendance_date:read 获取离职申请的最后出勤日
      └ is_transfer_with_workforceboolean是否带编转移
    └ offboarding_checklistoffboarding_checklist离职办理流程信息
      └ checklist_statusstring离职流转状态，可选值有： - AntiBegin：未发起 - Approving：进行中 - Finished：已完成 - Rejected：已拒绝 - Withdrawn：已撤销
      └ checklist_start_timestring离职流转开始时间
      └ checklist_finish_timestring离职流转结束时间
      └ checklist_process_idstring离职流转流程实例 ID。可用于查询流程相关信息，例如：作为获取单个流程详情的process_id查询流程详情。
    └ offboarding_idstring离职唯一标识
  └ page_tokenstring分页标记，当 has_more 为 true 时，会同时返回新的 page_token，否则不返回 page_token
  └ has_moreboolean是否还有更多项

响应体示例 ​

json
{
  "code": 0,
  "data": {
    "has_more": false,
    "items": [
      {
        "application_info": {
          "apply_finish_time": "2022-02-03 11:22:33",
          "apply_initiating_time": "2022-02-03 11:22:33",
          "apply_initiator_id": "6838119494196871234",
          "process_id": "6838119494196871234"
        },
        "initiating_type": "offboarding_directly",
        "offboarding_checklist": {
          "checklist_finish_time": "2022-02-03 11:22:33",
          "checklist_process_id": "6838119494196871234",
          "checklist_start_time": "2022-02-03 11:22:33",
          "checklist_status": "AntiBegin"
        },
        "offboarding_id": "7298499290417251879",
        "offboarding_info": {
          "add_block_list": "false",
          "block_reason": {
            "display": [
              {
                "lang": "zh-CN",
                "value": "刘梓新"
              },
              {
                "lang": "zh-CN",
                "value": "刘梓新"
              }
            ],
            "enum_name": "phone_type"
          },
          "block_reason_explanation": "xx 年 xx 月 xx 日因 xx 原因红线",
          "custom_fields": [
            {
              "custom_api_name": "name",
              "name": {
                "en_us": "Custom Name",
                "zh_cn": "自定义姓名"
              },
              "type": 1,
              "value": "\"231\""
            },
            {
              "custom_api_name": "name",
              "name": {
                "en_us": "Custom Name",
                "zh_cn": "自定义姓名"
              },
              "type": 1,
              "value": "\"231\""
            }
          ],
          "employee_reason": {
            "display": [
              {
                "lang": "zh-CN",
                "value": "刘梓新"
              },
              {
                "lang": "zh-CN",
                "value": "刘梓新"
              }
            ],
            "enum_name": "phone_type"
          },
          "employee_reason_explanation": "升学",
          "employment_id": "6893014062142064135",
          "enforce_noncompete_agreement": false,
          "expected_offboarding_date": "2022-02-08",
          "hrbp_id": [
            "6893014062142064135",
            "6893014062142064135"
          ],
          "is_transfer_with_workforce": false,
          "last_attendance_date": "2022-02-08",
          "noncompete_agreement_company": "123",
          "noncompete_agreement_end_date": "2022-02-08",
          "noncompete_agreement_id": "123",
          "noncompete_agreement_start_date": "2022-02-08",
          "offboarding_date": "2022-02-08",
          "provident_fund_end_date": "2022-02",
          "reason": {
            "display": [
              {
                "lang": "zh-CN",
                "value": "刘梓新"
              },
              {
                "lang": "zh-CN",
                "value": "刘梓新"
              }
            ],
            "enum_name": "phone_type"
          },
          "reason_explanation": "升学",
          "retain_account": false,
          "sign_type": {
            "display": [
              {
                "lang": "zh-CN",
                "value": "刘梓新"
              },
              {
                "lang": "zh-CN",
                "value": "刘梓新"
              }
            ],
            "enum_name": "phone_type"
          },
          "signature_file": "[\"123\",\"456\"]",
          "social_insurance_end_date": "2022-02"
        },
        "status": "Approving"
      },
      {
        "application_info": {
          "apply_finish_time": "2022-02-03 11:22:33",
          "apply_initiating_time": "2022-02-03 11:22:33",
          "apply_initiator_id": "6838119494196871234",
          "process_id": "6838119494196871234"
        },
        "initiating_type": "offboarding_directly",
        "offboarding_checklist": {
          "checklist_finish_time": "2022-02-03 11:22:33",
          "checklist_process_id": "6838119494196871234",
          "checklist_start_time": "2022-02-03 11:22:33",
          "checklist_status": "AntiBegin"
        },
        "offboarding_id": "7298499290417251879",
        "offboarding_info": {
          "add_block_list": "false",
          "block_reason": {
            "display": [
              {
                "lang": "zh-CN",
                "value": "刘梓新"
              },
              {
                "lang": "zh-CN",
                "value": "刘梓新"
              }
            ],
            "enum_name": "phone_type"
          },
          "block_reason_explanation": "xx 年 xx 月 xx 日因 xx 原因红线",
          "custom_fields": [
            {
              "custom_api_name": "name",
              "name": {
                "en_us": "Custom Name",
                "zh_cn": "自定义姓名"
              },
              "type": 1,
              "value": "\"231\""
            },
            {
              "custom_api_name": "name",
              "name": {
                "en_us": "Custom Name",
                "zh_cn": "自定义姓名"
              },
              "type": 1,
              "value": "\"231\""
            }
          ],
          "employee_reason": {
            "display": [
              {
                "lang": "zh-CN",
                "value": "刘梓新"
              },
              {
                "lang": "zh-CN",
                "value": "刘梓新"
              }
            ],
            "enum_name": "phone_type"
          },
          "employee_reason_explanation": "升学",
          "employment_id": "6893014062142064135",
          "enforce_noncompete_agreement": false,
          "expected_offboarding_date": "2022-02-08",
          "hrbp_id": [
            "6893014062142064135",
            "6893014062142064135"
          ],
          "is_transfer_with_workforce": false,
          "last_attendance_date": "2022-02-08",
          "noncompete_agreement_company": "123",
          "noncompete_agreement_end_date": "2022-02-08",
          "noncompete_agreement_id": "123",
          "noncompete_agreement_start_date": "2022-02-08",
          "offboarding_date": "2022-02-08",
          "provident_fund_end_date": "2022-02",
          "reason": {
            "display": [
              {
                "lang": "zh-CN",
                "value": "刘梓新"
              },
              {
                "lang": "zh-CN",
                "value": "刘梓新"
              }
            ],
            "enum_name": "phone_type"
          },
          "reason_explanation": "升学",
          "retain_account": false,
          "sign_type": {
            "display": [
              {
                "lang": "zh-CN",
                "value": "刘梓新"
              },
              {
                "lang": "zh-CN",
                "value": "刘梓新"
              }
            ],
            "enum_name": "phone_type"
          },
          "signature_file": "[\"123\",\"456\"]",
          "social_insurance_end_date": "2022-02"
        },
        "status": "Approving"
      }
    ],
    "page_token": ""
  },
  "msg": "success"
}

错误码 ​

HTTP状态码错误码描述排查建议
4001160102Param is invalid请检查分页大小、分页标记和离职审批发起时间的时间戳格式后重试
4001160103No permission on param无权限使用离职原因或离职原因（员工）进行筛选，请确认应用申请按照离职原因搜索(corehr:employment.offboarding_reason.search:read)后重试
4001160104Missing query parametert请确保离职审批发起时间、期望离职日期和离职日期的结束开始时间都传入后请求
4001160999general internal server error code系统出现问题，如需帮助，请咨询技术支持。

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

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