新增人员入职花名册

基本信息

权限标识 | employee:onboarding:register

请求参数

顶层字段

字段名	类型	必填	说明
`corpId`	string	✅	企业ID
`onBoardingRoughness`	`OnBoardingRoughness`	✅	入职概况，具体字段见下方说明
`basicInfo`	`Map<string, DynamicFieldValue>`	✅	基本信息动态Map，key为字段编码
`workInfo`	`Map<string, DynamicFieldValue>`	✅	任职信息动态Map，key为字段编码
`workStatusInfo`	`Map<string, DynamicFieldValue>`	✅	任职状态信息动态Map，key为字段编码
`dingTalkSyncInfo`	`DingTalkSyncInfo`	✅	钉钉通讯录同步信息，具体字段见下方说明

DynamicFieldValue 的可用类型：

string | number | boolean | string[]

实际类型由字段元数据中的 fieldType 和 multiSelect 决定：

字段类型	DynamicFieldValue实际类型
文本、日期、单选、员工、组织、成本中心等单值字段	`string`
数字	`number`，也兼容可转换为数字的 `string`
布尔值	`boolean`
多选、地址	`string[]`

onBoardingRoughness（入职概况）

字段名	类型	必填	说明
`name`	string	✅	姓名
`mobileNumber`	string	✅	手机号码，需符合手机号格式
`onBoardingDate`	string	✅	预计入职日期，格式 `yyyy-MM-dd`
`source`	string	❌	来源，建议传系统支持的来源编码
`responsible`	string	❌	提交人，建议传员工ID

source 枚举值

枚举值	含义
`scan`	扫码入职
`manual`	手动添加
`approval`	审批入职
`ding_talk_add`	钉钉添加
`system`	系统添加
`recruit`	招聘
`batch_import`	批量导入
`single_add`	单人新增

registerState 不是当前接口支持的请求字段。即使请求中携带该字段，也不能用它控制员工状态。

basicInfo（基本信息）

动态 Map 结构，key 为系统配置的字段编码，以下为内置字段和校验字段：

字段名	类型	必填	说明
`employeeNumber`	string	按企业配置	工号
`idType`	string	✅	证件类型，传选项编码
`idNumber`	string	✅	证件号码
`idName`	string	❌	证件姓名
`validPeriodOfId`	string	❌	证件有效期，格式 `yyyy-MM-dd`；长期可传 `长期` 或 `9999-12-31`
`idAddress`	string	❌	证件地址
`dateOfBirth`	string	❌	出生日期，格式 `yyyy-MM-dd`
`ethnicity`	string	❌	民族，传选项编码
`gender`	string	❌	性别，传选项编码
`nativeRegion`	string	❌	籍贯
`currentResidentialAddress`	string	❌	现居住地址
`maritalStatus`	string	❌	婚姻状况，传选项编码
`politicalStatus`	string	❌	政治面貌，传选项编码
`hukouType`	string	❌	户口类型，传选项编码
`hukouLocation`	`string[]`	❌	户口所在地行政区编码数组
`dateEnteredWorkforce`	string	❌	参加工作日期，格式 `yyyy-MM-dd`
`email`	string	❌	工作邮箱
`personalEmail`	string	❌	个人邮箱
`socialSecurityAccount`	string	❌	社保账号
`providentFundAccount`	string	❌	公积金账号

除上述字段外，可直接传入其他企业自定义字段，key 使用字段元数据中的 fieldId，不需要额外嵌套 customizeData。

workInfo（任职信息）

动态 Map 结构，key 为系统配置的字段编码，以下为内置字段和校验字段：

字段名	类型	必填	说明
`mainDepartment`	string	✅	主部门ID
`jobTitle`	string	按企业配置	职位ID
`jobLevel`	string	按企业配置	职级ID
`jobGrade`	string	按企业配置	职等ID
`manager`	string	按企业配置	直属主管员工ID
`workLocation`	string	按企业配置	办公地点选项编码
`costCenter`	string	按企业配置	成本中心ID
`contractCompany`	string	按企业配置	合同公司ID

除上述字段外，可直接传入其他企业自定义字段。

workStatusInfo（任职状态信息）

动态 Map 结构，key 为系统配置的字段编码，以下为内置字段和校验字段：

字段名	类型	必填	说明
`employeeStatus`	string	按企业配置	员工状态；传 `probation` 时必须传 `probationDate`
`employeeType`	string	按企业配置	员工类型选项编码
`probationDate`	string	条件必填	试用期到期/转正日期，格式 `yyyy-MM-dd`，不得早于预计入职日期
`probationPeriod`	`number \| string`	❌	试用期月数；字符串必须可以转换为数字

employeeStatus 枚举值

枚举值	含义
`probation`	试用期
`formal`	正式
`working`	在职
`quitted`	已离职，不用于常规新增入职场景

除上述字段外，可直接传入其他企业自定义字段。

dingTalkSyncInfo（钉钉通讯录同步信息）

字段名	类型	必填	说明
`dingSyncType`	string	✅	钉钉通讯录关联类型，枚举值见下方
`userName`	string	条件必填	关联自建企业账号时必填
`password`	string	条件必填	关联自建企业账号时必填
`dingUserId`	string	❌	已有关联钉钉用户时传钉钉userId

dingSyncType 枚举值

枚举值	含义
`notSync`	不关联
`sync_personal_account`	关联个人账号
`sync_corp_account`	关联自建企业账号
`sync_sso_account`	关联SSO企业账号

请求示例

{
  "corpId": "ding4c7c311a701851ac35c2f4657eb6378f",
  "onBoardingRoughness": {
    "name": "zcb开放接口测试6",
    "mobileNumber": "18134839916",
    "onBoardingDate": "2025-10-01",
    "source": "approval",
    "responsible": "emp_4bc9a5e1bd334eb6bf075e4bc8a991d6"
  },
  "basicInfo": {
    "employeeNumber": "rlj1122",
    "idType": "others",
    "idNumber": "ceshi11122",
    "idName": "张三xx",
    "validPeriodOfId": "2020-11-11",
    "idAddress": "xx省 xx市 xx号门牌",
    "dateOfBirth": "2025-06-22",
    "ethnicity": "han",
    "gender": "male",
    "nativeRegion": "xxxx",
    "currentResidentialAddress": "xxx省 xx市 xx县 xx院",
    "maritalStatus": "spinsterhood",
    "politicalStatus": "masses",
    "hukouType": "local_town",
    "hukouLocation": [
      "11",
      "1101"
    ],
    "dateEnteredWorkforce": "2024-11-12",
    "email": "pybsbt.g1x@hotmail.com",
    "personalEmail": "g6nmzi21@yahoo.com.cn",
    "socialSecurityAccount": "velit do non",
    "providentFundAccount": "1111",
    "field_emp_numb_011": 11,
    "field_emp_sele_020": "selection_64b704465fb64bdd84b36a7d34d4d6dc"
  },
  "workInfo": {
    "mainDepartment": "1",
    "jobTitle": "670f8bc82e7ff16dc2800d85",
    "jobLevel": "64632f5703984a612b68e4a8",
    "manager": "emp_e2615c90cfd74fb79bd93194bedab3e4",
    "workLocation": "selection_f37eb133d7a44d3d92b006580908141e",
    "costCenter": "1",
    "field_emp_stri_036": "1111",
    "field_emp_sele_024": "selection_14391b87df9e4d01bb3db07d3bc84eef"
  },
  "workStatusInfo": {
    "employeeStatus": "probation",
    "employeeType": "regular",
    "probationDate": "2026-06-09",
    "probationPeriod": 2,
    "field_emp_addr_008": [
      "11",
      "1101"
    ],
    "field_emp_date_011": "2024-10-01"
  },
  "dingTalkSyncInfo": {
    "dingSyncType": "notSync",
    "userName": "",
    "password": ""
  }
}

响应参数

通用响应字段

字段名	类型	说明
`success`	boolean	外层请求处理结果；业务校验失败时仍可能为 `true`
`errorCode`	`string \| null`	全局错误码
`errorMsg`	`string \| null`	全局错误信息
`rid`	`string \| null`	链路追踪ID，部分环境返回
`data`	`OpenEmpOnBoardingInfoResponse \| null`	业务响应数据

data字段

字段名	类型	说明
`empId`	`string \| null`	员工ID，创建成功时返回；部分写入失败场景也可能返回
`jobDataId`	`string \| null`	入职任职历史记录ID，仅完整创建成功时返回
`validateResult`	`Map<string, string> \| null`	校验结果，非空表示校验失败（key为字段名或业务错误码，value为错误信息）

响应示例

创建成功

{
  "data": {
    "empId": "emp_51b97b43e6a2411fab1341c1c9326326",
    "jobDataId": "6821c35b1fae1466ecb4109c",
    "validateResult": null
  },
  "success": true,
  "errorCode": null,
  "errorMsg": null
}

参数校验失败

HTTP 状态码通常仍为 200，且外层 success 可能仍为 true，需要通过 validateResult 是否为空判断业务是否成功。

{
  "data": {
    "empId": null,
    "jobDataId": null,
    "validateResult": {
      "idType": "证件类型不能为空",
      "idNumber": "证件号码不能为空",
      "mainDepartment": "主部门不能为空"
    }
  },
  "success": true,
  "errorCode": null,
  "errorMsg": null
}

注意事项

接口权限：调用方的 OAuth2 Token 必须具备 employee:onboarding:register scope。

日期格式：所有日期字段统一使用 yyyy-MM-dd 格式。

动态字段：basicInfo、workInfo、workStatusInfo 为动态 Map，可传入企业自定义字段；字段编码、必填规则和选项值以 /open/api/v1/employee/roster/meta 返回的元数据为准。

试用期校验：employeeStatus=probation 时必须传 probationDate，且该日期不得早于 onBoardingDate。

钉钉账号校验：dingSyncType=sync_corp_account 时，userName 和 password 必填。

成功判断：完整成功需同时满足外层 success=true、validateResult 为空、empId 非空、jobDataId 非空。

避免重复调用：接口没有幂等键。网络超时或结果不明确时，应先查询员工是否已创建，再决定是否重试。

接口行为：该接口会直接写入员工花名册及任职历史，不是新增待入职记录。

application/json

Bodyapplication/json

示例

{
  "data": {
    "empId": "",
    "jobDataId": "",
    "validateResult": {
      "": ""
    }
  },
  "success": false,
  "errorCode": "",
  "errorMsg": ""
}

新增人员入职花名册

新增人员入职花名册

基本信息

请求参数

顶层字段

onBoardingRoughness（入职概况）

basicInfo（基本信息）

workInfo（任职信息）

workStatusInfo（任职状态信息）

dingTalkSyncInfo（钉钉通讯录同步信息）

请求示例

响应参数

通用响应字段

data字段

响应示例

创建成功

参数校验失败

注意事项

请求参数

请求示例代码

返回响应

新增人员入职花名册

新增人员入职花名册#

基本信息#

请求参数#

顶层字段#

onBoardingRoughness（入职概况）#

basicInfo（基本信息）#

workInfo（任职信息）#

workStatusInfo（任职状态信息）#

dingTalkSyncInfo（钉钉通讯录同步信息）#

请求示例#

响应参数#

通用响应字段#

data字段#

响应示例#

创建成功#

参数校验失败#

注意事项#

请求参数

请求示例代码

返回响应

新增人员入职花名册

基本信息

请求参数

顶层字段

onBoardingRoughness（入职概况）

basicInfo（基本信息）

workInfo（任职信息）

workStatusInfo（任职状态信息）

dingTalkSyncInfo（钉钉通讯录同步信息）

请求示例

响应参数

通用响应字段

data字段

响应示例

创建成功

参数校验失败

注意事项