钉钉开发文档

智能人事

更新时间: 2019-3-18

开发前必读

智能人事相关的接口需要企业开通了钉钉官方的“智能人事”应用之后才可以调用。
您可以在手机端工作台打开应用中心,搜索智能人事,然后开通应用。

获取员工花名册字段信息

根据员工userid,批量访问员工花名册字段信息。

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/topapi/smartwork/hrm/employee/list?access_token=ACCESS_TOKEN
入参说明

名称 类型 必须 示例值 描述
userid_list String 1, 2, 3 员工userid列表,最大列表长度:20
field_filter_list String sys01-name, sys01-dept 需要获取的花名册字段列表,最大列表长度:20。具体业务字段的code参见附录(大小写敏感)。不传入该参数时,企业可获取所有字段信息。

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/smartwork/hrm/employee/list");
OapiSmartworkHrmEmployeeListRequest req = new OapiSmartworkHrmEmployeeListRequest();
req.setUseridList("123, 234");
req.setFieldFilterList("sys00-name,sys00-email");
OapiSmartworkHrmEmployeeListResponse rsp = client.execute(req, access_token);
System.out.println(rsp.getBody());

出参说明:

参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
success 调用是否成功
result 员工花名册信息结果列表
└ userid 员工唯一标识ID
└ field_list 花名册字段列表
└└ group_id 字段分组id
└└ value 字段的值(详见结果示例)
└└ label 对应value的文本值(value枚举值时,label取值为value的文本翻译;否则,label取值同value。详见结果示例)
└└ field_code 字段编码
└└ field_name 字段业务名称

返回结果示例

{
  "result": [
    {
      "userid": "123",
      "field_list": [
        {
          "fieldName": "字段值为空",
          "fieldCode": "sys03-graduationTime",
          "groupId": "sys03"
        },
        {
          "fieldName": "枚举类型或下拉框字段",
          "fieldCode": "sys01-employeeStatus",
          "groupId": "sys01",
          "label": "正式",
          "value": "3"
        },
        {
          "fieldName": "部门id",
          "fieldCode": "sys00-deptIds",
          "groupId": "sys00",
          "label": "11501281",
          "value": "11501281"
        },
        {
          "fieldName": "部门",
          "fieldCode": "sys00-dept",
          "groupId": "sys00",
          "label": "前端研发",
          "value": "前端研发"
        },
        {
          "fieldName": "下拉框类型自定义字段",
          "fieldCode": "c3cd750c-a544-4749-ad88-73b8d6e0136b",
          "groupId": "sys00",
          "label": "摩羯座",
          "value": "11"
        },
        {
          "fieldName": "文本类型自定义字段",
          "fieldCode": "c54836a9-67ac-49da-9aca-f3bdcc3c7f18",
          "groupId": "sys00",
          "label": "三牛",
          "value": "三牛"
        }
      ]
    },
    {
      "userid": "234",
      "field_list": [
        {
          "fieldName": "字段值为空",
          "fieldCode": "sys03-graduationTime",
          "groupId": "sys03"
        },
        {
          "fieldName": "枚举类型或下拉框字段",
          "fieldCode": "sys01-employeeStatus",
          "groupId": "sys01",
          "label": "正式",
          "value": "3"
        },
        {
          "fieldName": "部门id",
          "fieldCode": "sys00-deptIds",
          "groupId": "sys00",
          "label": "11501281",
          "value": "11501281"
        },
        {
          "fieldName": "部门",
          "fieldCode": "sys00-dept",
          "groupId": "sys00",
          "label": "前端研发",
          "value": "前端研发"
        },
        {
          "fieldName": "下拉框类型自定义字段",
          "fieldCode": "c3cd750c-a544-4749-ad88-73b8d6e0136b",
          "groupId": "sys00",
          "label": "摩羯座",
          "value": "11"
        },
        {
          "fieldName": "文本类型自定义字段",
          "fieldCode": "c54836a9-67ac-49da-9aca-f3bdcc3c7f18",
          "groupId": "sys00",
          "label": "三牛",
          "value": "三牛"
        }
      ]
    }
  ],
  "errcode": 0,
  "errmsg": "成功",
  "success": true
}

附录:
花名册自定义字段业务code

字段code
业务含义
sys00-name
姓名
sys00-email
邮箱
sys00-dept
部门
(查该字段时,会返回部门名称列表sys00-dept和部门id列表sys00-deptIds)
sys00-mainDept
主部门
(查该字段时,会返回主部门名称sys00-mainDept和主部门id sys00-mainDeptId)
sys00-position
职位
sys00-mobile
手机号
sys00-jobNumber
工号
sys00-tel
分机号
sys00-workPlace
办公地点
sys00-remark
备注
sys00-confirmJoinTime
入职时间
sys01-employeeType
员工类型
sys01-employeeStatus
员工状态
sys01-probationPeriodType
试用期
sys01-regularTime
转正日期
sys01-positionLevel
岗位职级
sys02-realName
身份证姓名
sys02-certNo
证件号码
sys02-birthTime
出生日期
sys02-sexType
性别
sys02-nationType
民族
sys02-certAddress
身份证地址
sys02-certEndTime
证件有效期
sys02-marriage
婚姻状况
sys02-joinWorkingTime
首次参加工作时间
sys02-residenceType
户籍类型
sys02-address
住址
sys02-politicalStatus
政治面貌
sys09-personalSi
个人社保账号
sys09-personalHf
个人公积金账号
sys03-highestEdu
最高学历
sys03-graduateSchool
毕业院校
sys03-graduationTime
毕业时间
sys03-major
所学专业
sys04-bankAccountNo
银行卡号
sys04-accountBank
开户行
sys05-contractCompanyName
合同公司
sys05-contractType
合同类型
sys05-firstContractStartTime
首次合同起始日
sys05-firstContractEndTime
首次合同到期日
sys05-nowContractStartTime
现合同起始日
sys05-nowContractEndTime
现合同到期日
sys05-contractPeriodType
合同期限
sys05-contractRenewCount
续签次数
sys06-urgentContactsName
紧急联系人姓名
sys06-urgentContactsRelation
联系人关系
sys06-urgentContactsPhone
联系人电话
sys07-haveChild
有无子女
sys07-childName
子女姓名
sys07-childSex
子女性别
sys07-childBirthDate
子女出生日期
sys08-forntIDcard
身份证(人像面)
sys08-rearIDcard
身份证(国徽面)
sys08-academicCertificate
学历证书
sys08-diplomaCertificate
学位证书
sys08-releaseLetter
前公司离职证明
sys08-personalPhoto
员工照片
customField
自定义字段

查询企业待入职员工列表

分页查询企业待入职员工userid列表

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/topapi/smartwork/hrm/employee/querypreentry?access_token=ACCESS_TOKEN

入参说明

名称 类型 必须 示例值 描述
offset Number 0 分页游标,从0开始
size Number 50 分页大小,最大50

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/smartwork/hrm/employee/querypreentry");
OapiSmartworkHrmEmployeeQuerypreentryRequest req = new OapiSmartworkHrmEmployeeQuerypreentryRequest(); 
req.setOffset(0); 
req.setSize(50); 
OapiSmartworkHrmEmployeeQuerypreentryResponse response = client.execute(req , sessionKey);
System.out.println(rsp.getBody());

返回结果示例

{
    "result":{
        "next_cursor":10,
        "data_list":[
          "123",
          "234"
        ]
    },
    "errcode":0,
    "errmsg":"成功",
    "success":true
}

出参说明:

参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
success 调用是否成功
result 分页结果
└ next_cursor 下一次分页调用的offset值,当返回结果里没有nextCursor时,表示分页结束
└ data_list 员工userid列表

查询企业在职员工列表

分页查询企业在职员工userid列表

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/topapi/smartwork/hrm/employee/queryonjob?access_token=ACCESS_TOKEN

入参说明

名称 类型 必须 示例值 描述
status_list String 2,3,5,-1 在职员工子状态筛选,其他状态无效。2,试用期;3,正式;5,待离职;-1,无状态
offset Number 0 分页游标,从0开始
size Number 20 分页大小,最大20

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/smartwork/hrm/employee/queryonjob");
OapiSmartworkHrmEmployeeQueryonjobRequest req = new OapiSmartworkHrmEmployeeQueryonjobRequest(); 
req.setStatusList("2,3"); 
req.setOffset(15); 
req.setSize(5); 
OapiSmartworkHrmEmployeeQueryonjobResponse response = client.execute(req , sessionKey);

返回结果示例

{
    "result":{
        "next_cursor":10,
        "data_list":[
          "123",
          "234"
        ]
    },
    "errcode":0,
    "errmsg":"成功",
    "success":true
}

出参说明:

参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
success 调用是否成功
result 分页结果
└ next_cursor 下一次分页调用的offset值,当返回结果里没有nextCursor时,表示分页结束
└ data_list 员工userid列表

查询企业离职员工列表

分页查询企业离职员工userid列表

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/topapi/smartwork/hrm/employee/querydimission?access_token=ACCESS_TOKEN

入参说明

名称 类型 必须 示例值 描述
offset Number 0 分页游标,从0开始
size Number 50 分页大小,最大50

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/smartwork/hrm/employee/querydimission");
OapiSmartworkHrmEmployeeQuerydimissionRequest req = new OapiSmartworkHrmEmployeeQuerydimissionRequest(); 
req.setOffset(0); 
req.setSize(50); 
OapiSmartworkHrmEmployeeQuerydimissionResponse rsp = client.execute(req , sessionKey);
System.out.println(rsp.getBody());

返回结果示例

{
    "result":{
        "next_cursor":50,
        "data_list":[
          "123",
          "234"
        ]
    },
    "errcode":0,
    "errmsg":"成功",
    "success":true
}

出参说明:

参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
success 调用是否成功
result 分页结果
└ next_cursor 下一次分页调用的offset值,当返回结果里没有nextCursor时,表示分页结束
└ data_list 离职员工userid列表

获取离职员工离职信息

根据员工userid列表,批量查询员工的离职信息。传入非离职员工userid,不会返回信息。

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/topapi/smartwork/hrm/employee/listdimission?access_token=ACCESS_TOKEN

入参说明

名称 类型 必须 示例值 描述
userid_list String 1, 2, 3 员工userid列表,最大长度50

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/smartwork/hrm/employee/listdimission");
OapiSmartworkHrmEmployeeListdimissionRequest req = new OapiSmartworkHrmEmployeeListdimissionRequest(); 
req.setUseridList("123"); 
OapiSmartworkHrmEmployeeListdimissionResponse response = client.execute(req , sessionKey);
System.out.println(rsp.getBody());

返回结果示例

{
  "result": [
    {
      "userid": "123",
      "last_work_day": 1534569419008,
      "dept_list": [
        {
          "dept_path": "门诊部-门诊外科",
          "dept_id": 1234
        },
        {
          "dept_path": "门诊部-门诊外科",
          "dept_id": 1235
        }
      ],
      "reason_memo": "世界太大,想出去看看",
      "reason_type": 1,
      "pre_status": 1,
      "handover_userid": "123456",
      "status": 2,
      "main_dept_name": "门诊外科",
      "main_dept_id": 1234
    }
  ],
  "errcode": 0,
  "errmsg": "成功",
  "success": true
}

出参说明:

参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
success 调用是否成功
result 员工离职信息列表
└ userid 员工唯一标识ID
└ last_work_day 最后工作时间
└ dept_list 部门列表
└└ dept_path 部门路径
└└ dept_id 部门id
└ reason_memo 离职原因备注
└ reason_type 离职原因类型:1,家庭原因;2,个人原因;3,发展原因;4,合同到期不续签;5,协议解除;6,无法胜任工作;7,经济性裁员;8,严重违法违纪;9,其他
└ pre_status 离职前工作状态:1,待入职;2,试用期;3,正式
└ handover_userid 离职交接人
└ status 离职状态:1,待离职;2,已离职
└ main_dept_name 离职前主部门名称
└ main_dept_id 离职前主部门id

添加企业待入职员工

此接口用于添加人员到企业待入职,并不同步员工详细档案信息。

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/topapi/smartwork/hrm/employee/addpreentry?access_token=ACCESS_TOKEN

入参说明

名称
类型
必须
示例值
描述
param
PreEntryEmployeeAddParam
添加待入职入参
└ name
String
张三
员工姓名
└ mobile
String
13712345678
手机号
└ pre_entry_time
Date
2018-08-08 00:00:00
预期入职时间
└ op_userid
String
manager123
操作人userid
└ extend_info
String
{"depts": "123|345|899", "employeeType": 1, "mainDeptId": 123, "mainDeptName": "研发部", "position": "高级工程师", "workPlace": "杭州",
"jobNumber":"1000" }
扩展信息,json串格式,按要求传入有效信息,无效信息不会保存。
有效信息有:
depts--部门id列表,"|"分隔多个;
mainDeptId--主部门id;
mainDeptName--主部门名称;
position--职位;
workPlace--工作地点;
employeeType--员工类型枚举值(0,无类型;1,全职;2,兼职;3,实习;4,劳务派遣;5,退休返聘;6,劳务外包);
jobNumber--工号

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/smartwork/hrm/employee/addpreentry");
OapiSmartworkHrmEmployeeListRequest req = new OapiSmartworkHrmEmployeeListRequest();
PreEntryEmployeeAddParam param = new PreEntryEmployeeAddParam();
param.setPreEntryTime(StringUtils.parseDateTime("2018-08-08 00:00:00"));
param.setName("张三");
param.setExtendInfo("{\"depts\": \"123|345|899\",   \"employeeType\": 1,   \"mainDeptId\": 123,   \"mainDeptName\": \"研发部\",   \"position\": \"高级工程师\",   \"workPlace\": \"杭州\" }");
param.setOpUserid("manager123");
param.setMobile("13712345678");
req.setParam(param);
OapiSmartworkHrmEmployeeAddpreentryResponse rsp = client.execute(req, access_token);
System.out.println(rsp.getBody());

返回结果示例

{
    "userid":"0123456789",
    "errcode":0,
    "errmsg":"成功",
    "success":true
}

出参说明:

参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
success 调用是否成功
userid 创建成功后,返回的员工唯一标识ID
以上内容是否对您有帮助:
在文档使用中是否遇到以下问题(多选):
  • 内容错误
  • 更新不及时
  • 链接错误
  • 缺少代码/图片示例
  • 太简单/步骤待完善
手机号
更多建议
提交成功,感谢您的反馈!