Get Clock-In Details

Call this API to get the actual clock-in details of employees in your organization.

API Call Description

This API does not support querying data older than 180 days.
If you need only clock-in results and not detailed data, call the Get Clock-In Results API instead.
Attendance data synchronization may be delayed. If data is missing, try again later.
If a user has a scheduled shift on a given day but does not clock in, this API returns empty data.
This API returns all clock-in details, including clock-in data for scenarios that require secondary confirmation, such as late arrivals. These records are invalid clock-ins. Filter them based on your business scenario after retrieval. Pay attention to the output parameters invalidRecordType, isLegal, and invalidRecordMsg.

For example, an organization schedules an employee to clock in at 9:00 and 18:00. If the employee clocks in multiple times during that period, this API returns all clock-in records. To view the same raw clock-in data in the Attendance console, go to Attendance Statistics > Report Management > Raw Records. Each record lists the following columns: Name, Attendance group, Department, Job number, Position, Attendance date, Attendance time (scheduled shift time), Clock-in time, and Clock-in result. A result such as makeup clock-in approved indicates that the record came from an approved correction rather than a direct clock-in.

Request

Basic Information
HTTP URL	https://oapi.dingtalk.io/attendance/listRecord
HTTP Method	POST
Supported app types	appType-Internal app　appType-Third-party enterprise app
Required permissions	permission-qyapi_get_attendance_data-Attendance data read permission

Query Parameters

Name	Type	Required	Example	Description
access_token	String	Yes	bE74xxxx	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 Get the access_token of a Third-Party Enterprise API to obtain it.

Request Body

Name	Type	Required	Example	Description
userIds	List	Yes	[“user456”,“user123”]	The list of employee IDs in your organization. Maximum: 50. Important Make sure the userId values are correct. Otherwise, this API returns empty data.
checkDateFrom	String	Yes	2020-09-07 00:00:00	The start workday for querying attendance clock-in records. Format: yyyy-MM-dd hh:mm:ss. For example, if you pass “2021-12-01 10:00:00”, the employee’s 09:00 clock-in is not returned. Important The workDateFrom and workDateTo parameters can be at most 7 days apart (inclusive).
checkDateTo	String	Yes	2020-09-08 00:00:00	The end workday for querying attendance clock-in records. Format: yyyy-MM-dd hh:mm:ss. For example, if you pass “2021-12-01 18:00:00”, the employee’s 19:00 clock-in is not returned. Important The workDateFrom and workDateTo parameters can be at most 7 days apart (inclusive).
isI18n	Boolean	No	true	Specifies whether the organization is an overseas organization: - true: Used on the overseas platform - false (default): Used on the China platform

Request Example

curl -X POST "https://oapi.dingtalk.io/attendance/listRecord" \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'access_token=7258e1c9-af43-411c-b3f4-bcb069bfbb93' \
-d 'checkDateFrom=2018-01-01' \
-d 'checkDateTo=2018-01-01' \
-d 'isI18n=true' \
-d 'userIds=%221%22%2C%222%22'

Java

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/attendance/listRecord");
OapiAttendanceListRecordRequest req = new OapiAttendanceListRecordRequest();
req.setUserIds(Arrays.asList("user123","user456"));
req.setCheckDateFrom("2020-11-07 08:00:00");
req.setCheckDateTo("2020-11-12 08:00:00");
req.setIsI18n(false);
OapiAttendanceListRecordResponse rsp = client.execute(req, access_token);
System.out.println(rsp.getBody());

Python

import dingtalk.api

req=dingtalk.api.OapiAttendanceListRecordRequest("https://oapi.dingtalk.io/attendance/listRecord")

req.userIds="[\"1\",\"2\"]"
req.checkDateFrom="2018-01-01"
req.checkDateTo="2018-01-01"
req.isI18n=true
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 OapiAttendanceListRecordRequest;
$req->setUserIds("[\"1\",\"2\"]");
$req->setCheckDateFrom("2018-01-01");
$req->setCheckDateTo("2018-01-01");
$req->setIsI18n("true");
$resp = $c->execute($req, $access_token, "https://oapi.dingtalk.io/attendance/listRecord");

IDingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/attendance/listRecord");
OapiAttendanceListRecordRequest req = new OapiAttendanceListRecordRequest();
req.UserIds = "[\"1\",\"2\"]";
req.CheckDateFrom = "2018-01-01";
req.CheckDateTo = "2018-01-01";
req.IsI18n = true;
OapiAttendanceListRecordResponse rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);

Response

Response Body

Name	Type	Example	Description
errmsg	String	ok	The description of the return code.
errcode	String	0	The return code.
recordresult	Array of Object		The clock-in details.
userAccuracy	String	65	The location accuracy of the user’s clock-in.
classId	Long	677995086	The shift ID.
userLatitude	String	30.285622	The latitude of the user’s clock-in.
userLongitude	String	120.017019	The longitude of the user’s clock-in.
userAddress	String	Hangzhou, Zhejiang	The address of the user’s clock-in.
deviceId	String	67da0fxxxx	The ID of the clock-in device. Note This field is returned when the user clocks in with the DingTalk mobile client.
locationMethod	String	MAP	The location method.
isLegal	String	N	Indicates whether the record is valid: - Y: Valid Note This value is returned when both timeResult and locationResult are Normal. - N: Invalid
userCheckTime	String	1599450909000	The actual clock-in time.
procInstId	String	59f77e82-xxxx	The ID of the associated approval instance. If this field is not empty, the clock-in record is related to an approval such as a leave request or overtime.
baseCheckTime	String	1599442200000	The baseline time used to calculate late arrival and early leave. It can also serve as the scheduled clock-in time.
approveId	String	2376620852	The ID of the associated approval. If this field is not empty, the clock-in record is related to an approval such as a leave request or overtime.
timeResult	String	Normal	The clock-in result: - Normal: Normal - Early: Early leave - Late: Late arrival - SeriousLate: Severe late arrival - Absenteeism: Late arrival counted as absenteeism - NotSigned: Not clocked in
locationResult	String	Normal	The location result: - Normal: Within range - Outside: Out of range - NotSigned: Not clocked in
checkType	String	OnDuty	The attendance type: - OnDuty: Clock in for work - OffDuty: Clock out from work
sourceType	String	USER	The data source: - USER: User clock-in - BOSS: Modified by a manager - APPROVE: Approval system - SYSTEM: Attendance system - AUTO_CHECK: Automatic clock-in
userId	String	manager4220	The userId of the employee who clocked in.
workDate	String	1599321600000	The workday.
corpId	String	dinge8axxxx5384	The organization ID.
planId	String	145342017988	The scheduling ID.
groupId	String	685935028	The attendance group ID.
id	String	101135139831	The attendance ID.
invalidRecordType	String	Other	The type of error message: - Security: Security-related reasons - Other: Other reasons
userSsid	String	xxxx	The Wi-Fi SSID of the user’s clock-in.
userMacAddr	String	192.168.xx.xx	The Wi-Fi MAC address of the user’s clock-in.
planCheckTime	String	1492568497000	The scheduled clock-in time.
baseAddress	String	Hangzhou	The baseline address.
baseLongitude	String	12.109	The baseline longitude.
baseLatitude	String	0.123	The baseline latitude.
baseAccuracy	String	hazdgwrxxxx	The baseline location accuracy.
baseSsid	String	423dsddfxxxx	The baseline Wi-Fi SSID.
baseMacAddr	String	00:27:19:48:58:4c	The baseline MAC address.
gmtCreate	String	1599441505000	The created time of the clock-in record.
invalidRecordMsg	String	Secondary confirmation required	The detailed description of the error indicated by invalidRecordType.
gmtModified	String	1599441505001	The modified time of the clock-in record.
outsideRemark	String	Visiting a client	The clock-in remarks.
deviceSN	String	gd53354xxxx	The serial number of the clock-in device.
bizId	String	E171DCCExxxx	The associated business ID.
photoUrl	String	https://static.dingtalk.io/media/lQDPM369C6xxxxK6PiY	The URL of the clock-in photo. Note - To use this parameter, call this API over HTTP. The SDK does not return this parameter. - If the clock-in details contain a photo, photoUrl is returned. Otherwise, this field is not returned.

Response Body Example

{
  "errcode": 0,
  "errmsg": "ok",
  "recordresult": [
    {
      "gmtModified": 1599454972000,
      "baseCheckTime": 1599442200000,
      "groupId": 685935028,
      "timeResult": "Normal",
      "deviceId": "67da0fxxxx",
      "approveId": 2376620852,
      "userAccuracy": 65,
      "classId": 677995086,
      "workDate": 1599408000000,
      "bizId": "E171DCCExxxx",
      "planId": 144872188720,
      "id": 43047156750,
      "checkType": "OnDuty",
      "planCheckTime": 1599442200000,
      "corpId": "dinge8axxxx5384",
      "locationResult": "Outside",
      "userLongitude": 120.017139,
      "isLegal": "N",
      "procInstId": "59f77e82-xxxx",
      "gmtCreate": 1599441505000,
      "userId": "manager4220",
      "outsideRemark": "Visiting a client",
      "userAddress": "Hangzhou, Zhejiang",
      "userLatitude": 30.285413,
      "sourceType": "USER",
      "userCheckTime": 1599441505000,
      "locationMethod": "MAP"
    },
    {
      "gmtModified": 1599450909000,
      "deviceId": "67da0fxxxx",
      "userAccuracy": 65,
      "workDate": 1599408000000,
      "bizId": "E171DCCExxxx",
      "id": 43055377426,
      "invalidRecordType": "Other",
      "corpId": "dinge8axxxx5384",
      "userLongitude": 120.017019,
      "gmtCreate": 1599450909000,
      "invalidRecordMsg": "Secondary confirmation required",
      "userId": "manager4220",
      "userAddress": "Hangzhou, Zhejiang",
      "userLatitude": 30.285622,
      "sourceType": "USER",
      "userCheckTime": 1599450909000,
      "locationMethod": "MAP"
    }
  ]
}

Error Codes

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

API calling guide

Authentication & authorization

Contacts

Calendar

Conferencing

AI Table

Attendance

Docs & files

IM

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