Get Leave Data from Attendance Reports

Call this API to get leave data from the DingTalk smart attendance report based on leave names and the user ID. The returned data includes all values in the report’s leave columns within a specified time period. Leave columns are dynamic, so you must specify leave names to get the data.

API Call Description

For more data access and consumption capabilities, go to the Data Asset Platform. The Data Asset Platform (dPaaS) is a unified data management platform for organizations. Built on DingTalk, it provides secure, scalable, and easy-to-maintain data services to support business decisions.

Request

Basic Information
HTTP URL	https://api.dingtalk.io/topapi/attendance/getleavetimebynames
HTTP Method	POST
Supported app types	appType-Internal app　appType-Third-party enterprise app
Required permissions	permission-qyapi_base-Basic permissions required to call organization APIs

Query Parameters

Name	Type	Required	Example	Description
access_token	String	Yes	6d1bxxxx	The app credential used to call this API. - For an internal app, call the Get the access_token of an internal app API to obtain it. - For a third-party enterprise app, call the API for getting the access_token of a third-party organization to obtain it.

Request Body

Name	Type	Required	Example	Description
userid	String	Yes	manager123	The user ID of the user.
leave_names	String	Yes	Annual leave	The leave names. Separate multiple names with commas. Maximum length: 20.
from_date	Date	Yes	2020-09-09 12:12:12	The start time. Data older than 225 days is not supported.
to_date	Date	Yes	2020-09-11 12:12:12	The end time. The interval between the start time and the end time must be within 31 days.

Request Example

curl -X POST "https://api.dingtalk.io/topapi/attendance/getleavetimebynames" \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'access_token=1b8b85xxxxx3ccfdd' \
-d 'from_date=2018-07-11+12%3A12%3A12' \
-d 'leave_names=Annual+leave' \
-d 'to_date=2018-07-11+12%3A12%3A12' \
-d 'userid=zhangsan'

Java

DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/getleavetimebynames");
OapiAttendanceGetleavetimebynamesRequest req = new OapiAttendanceGetleavetimebynamesRequest();
req.setUserid("zhangsan");
req.setLeaveNames("Annual leave");
req.setFromDate(StringUtils.parseDateTime("2020-09-01 00:00:00"));
req.setToDate(StringUtils.parseDateTime("2020-09-30 00:00:00"));
OapiAttendanceGetleavetimebynamesResponse rsp = client.execute(req, access_token);
System.out.println(rsp.getBody());

Python

import dingtalk.api

req=dingtalk.api.OapiAttendanceGetleavetimebynamesRequest("https://api.dingtalk.io/topapi/attendance/getleavetimebynames")

req.userid="zhangsan"
req.leave_names="Annual leave"
req.from_date="2018-07-11 12:12:12"
req.to_date="2018-07-11 12:12:12"
try:
  resp= req.getResponse(access_token)
  print(resp)
except Exception,e:
  print(e)

PHP

include "TopSdk.php";
date_default_timezone_set('Asia/Shanghai');

$c = new DingTalkClient(DingTalkConstant::$CALL_TYPE_OAPI, DingTalkConstant::$METHOD_POST , DingTalkConstant::$FORMAT_JSON);
$req = new OapiAttendanceGetleavetimebynamesRequest;
$req->setUserid("zhangsan");
$req->setLeaveNames("Annual leave");
$req->setFromDate("2018-07-11 12:12:12");
$req->setToDate("2018-07-11 12:12:12");
$resp = $c->execute($req, $access_token, "https://api.dingtalk.io/topapi/attendance/getleavetimebynames");

IDingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/getleavetimebynames");
OapiAttendanceGetleavetimebynamesRequest req = new OapiAttendanceGetleavetimebynamesRequest();
req.Userid = "zhangsan";
req.LeaveNames = "Annual leave";
req.FromDate = DateTime.Parse("2018-07-11 12:12:12");
req.ToDate = DateTime.Parse("2018-07-11 12:12:12");
OapiAttendanceGetleavetimebynamesResponse rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);

Response

Response Body

Name	Type	Example	Description
result	ColumnValListForTopVo		The returned result.
columns	ColumnValForTopVo[]		The column information and column value data.
columnvo	ColumnForTopVo		The column information.
name	String	Personal leave	The leave name.
sub_type	Number	0	The subtype.
status	Number	0	The column status.
alias	String	leave_	The alias.
type	Number	0	The column type.
columnvals	ColumnDayAndVal[]		The column value data.
value	String	1.0	The daily value.
date	Date	2020-09-09 12:12:12	The start time.
errcode	Number	0	The return code.
request_id	String	whv0fhtk8cnc	The request ID.

Response Body Example

{
  "errcode": 0,
  "result": {
    "columns": [
      {
        "columnvals": [
          {
            "date": "2020-09-01 00:00:00",
            "value": "0.0"
          },
          {
            "date": "2020-09-02 00:00:00",
            "value": "0.0"                   
          }
        ],
        "columnvo": {
          "alias": "leave_",
          "name": "Personal leave",
          "status": 0,
          "sub_type": 0,
          "type": 0
        }
      }
    ]
  },
  "request_id": "whv0fhtk8cnc"
}

Error Codes

If the call to this API returns an error, find the solution in the Global Error Codes document based on the error message.

API calling guide

Authentication & authorization

Contacts

Calendar

Conferencing

AI Table

Attendance

Docs & files

IM

Get Leave Data from Attendance Reports

API Call Description

Request

Query Parameters

Request Body

Request Example

Response

Response Body

Response Body Example

Error Codes

​API Call Description

​Request

​Query Parameters

​Request Body

​Request Example

​Response

​Response Body

​Response Body Example

​Error Codes

API Call Description

Request

Query Parameters

Request Body

Request Example

Response

Response Body

Response Body Example

Error Codes