钉钉开发文档

获取员工花名册字段信息

更新时间: 2019-1-11

接口功能:根据员工userid,批量访问员工花名册字段信息。

接口权限如果你是企业内部开发者(将自己公司的HR、OA、客户管理、业务管理等系统接入钉钉),则有权限调用。如果你是ISV(应用服务商,将开发的应用上架到钉钉应用市场,提供给其他企业用户使用),则默认无调用权限。本接口属于高权限接口,ISV如想调用,需要上ISV沟通组提交权限申请"查询钉钉HRM个人信息的权限"权限包。此外,该接口针对ISV做了字段访问权限控制,ISV调用需要联系智能人事走审批申请字段权限。

请求方式: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参见附录(大小写敏感)。不传入该参数时,isv可获取已申请权限范围内字段信息,企业可获取所有字段信息。

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
}

FAQ:
Q: 为什么查出来没有xx字段?
A: 对于ISV,确定已申请该接口的字段权限,无某字段权限不会返回对应信息。此外,确定企业已开通智能人事,且已维护员工档案信息中对应的字段内容。

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

字段code
业务含义
sys00-name
姓名 (ISV不可申请该字段权限)
sys00-email
邮箱(ISV不可申请该字段权限)
sys00-dept
部门(ISV不可申请该字段权限)
(查该字段时,会返回部门名称列表sys00-dept和部门id列表sys00-deptIds)
sys00-mainDept
主部门
(查该字段时,会返回主部门名称sys00-mainDept和主部门id sys00-mainDeptId)
sys00-position
职位(ISV不可申请该字段权限)
sys00-mobile
手机号(ISV不可申请该字段权限)
sys00-jobNumber
工号(ISV不可申请该字段权限)
sys00-tel
分机号(ISV不可申请该字段权限)
sys00-workPlace
办公地点
sys00-remark
备注(ISV不可申请该字段权限)
sys00-confirmJoinTime
入职时间(ISV不可申请该字段权限)
sys01-employeeType
员工类型
sys01-employeeStatus
员工状态
sys01-probationPeriodType
试用期
sys01-regularTime
转正日期
sys01-positionLevel
岗位职级
sys02-realName
身份证姓名(ISV不可申请该字段权限)
sys02-certNo
证件号码(ISV不可申请该字段权限)
sys02-birthTime
出生日期(ISV不可申请该字段权限)
sys02-sexType
性别
sys02-nationType
民族
sys02-certAddress
身份证地址(ISV不可申请该字段权限)
sys02-certEndTime
证件有效期(ISV不可申请该字段权限)
sys02-marriage
婚姻状况
sys02-joinWorkingTime
首次参加工作时间
sys02-residenceType
户籍类型
sys02-address
住址
sys02-politicalStatus
政治面貌
sys09-personalSi
个人社保账号
sys09-personalHf
个人公积金账号
sys03-highestEdu
最高学历
sys03-graduateSchool
毕业院校
sys03-graduationTime
毕业时间
sys03-major
所学专业
sys04-bankAccountNo
银行卡号(ISV不可申请该字段权限)
sys04-accountBank
开户行
sys05-contractCompanyName
合同公司
sys05-contractType
合同类型
sys05-firstContractStartTime
首次合同起始日
sys05-firstContractEndTime
首次合同到期日
sys05-nowContractStartTime
现合同起始日
sys05-nowContractEndTime
现合同到期日
sys05-contractPeriodType
合同期限
sys05-contractRenewCount
续签次数
sys06-urgentContactsName
紧急联系人姓名(ISV不可申请该字段权限)
sys06-urgentContactsRelation
联系人关系(ISV不可申请该字段权限)
sys06-urgentContactsPhone
联系人电话(ISV不可申请该字段权限)
sys07-haveChild
有无子女
sys07-childName
子女姓名
sys07-childSex
子女性别
sys07-childBirthDate
子女出生日期
sys08-forntIDcard
身份证(人像面)(ISV不可申请该字段权限)
sys08-rearIDcard
身份证(国徽面)(ISV不可申请该字段权限)
sys08-academicCertificate
学历证书
sys08-diplomaCertificate
学位证书
sys08-releaseLetter
前公司离职证明
sys08-personalPhoto
员工照片(ISV不可申请该字段权限)
customField
自定义字段(ISV不可申请该字段权限)
以上内容是否对您有帮助:
在文档使用中是否遇到以下问题(多选):
  • 内容错误
  • 更新不及时
  • 链接错误
  • 缺少代码/图片示例
  • 太简单/步骤待完善
手机号
更多建议
提交成功,感谢您的反馈!