​

Leave and Attendance Approval Integration: Automatically Sync Leave and Attendance Data to DingTalk Attendance

​

Overview

​

Background

• Inefficient manual makeup clock-ins: After employees clock in on your own system, they must submit a makeup clock-in in DingTalk. This process is tedious, and employees often forget.
• Out-of-sync data: Attendance data is split between your own system and DingTalk. HR must cross-check attendance records across systems.
• Poor timeliness: Employees expect to see their attendance status in DingTalk right after they clock in. They do not want to wait for a batch sync the next day.

​

Core Value

• Automatic clock-in sync: Clock-in records from your own system upload to DingTalk automatically, with no manual work.
• Single management entry point: All attendance data flows into DingTalk. HR handles attendance statistics and analysis on one platform.
• Fast, low-cost integration: Only 2 core APIs are required, which keeps development costs low.

​

Use Cases

• Integration with your own attendance system: Connect your in-house attendance system or third-party attendance devices (access card readers, fingerprint scanners, facial recognition terminals, and more) to DingTalk Attendance to sync clock-in data automatically.
• Consolidation of data from multiple devices: Your organization runs different attendance devices across work locations and needs all clock-in records in DingTalk for central management.
• Real-time attendance status: Employees expect to see their attendance status in DingTalk right after they clock in, instead of waiting for a batch sync the next day.
• No more cross-system checks for HR: HR no longer needs to manually compare data between your own attendance system and DingTalk, which speeds up attendance statistics.

​

Typical Business Scenarios

​

Scenario 1: Sync Clock-In Data from Your Own Attendance System

​

Pain Points

​

Value

• Automated workflow The real-time clock-in data sync flow has 5 steps:
  1. The employee clocks in on your own system.
  2. Your own attendance system calls the DingTalk API to establish a data channel.
  3. Your system retrieves the employee’s unique identifier in DingTalk (userId) through the API.
  4. Your system uploads the clock-in record to DingTalk Attendance.
  5. The DingTalk Attendance app displays the clock-in status in real time.
  Sample parameters for the upload: userid, userCheckTime, deviceId.
• Key benefits
  • No duplicate work: After employees clock in on your own attendance system, the data syncs to DingTalk Attendance through the API. Employees no longer submit makeup clock-ins or re-enter data.
  • Less manual review: Clock-in records sync in real time, so HR no longer reviews makeup clock-in requests one by one. This greatly reduces manual review work and saves time.
  • More accurate data: Automatic sync eliminates manual intervention and data entry errors. Attendance data stays authentic, accurate, and traceable.
  • Better user experience: Employees see their clock-in status in real time and no longer worry about missed clock-ins or forgotten makeup clock-ins.

​

Scenario 2: Consolidate Data from Multiple Attendance Devices

​

Pain Points

​

Value

• Automated workflow Data flow for consolidating clock-in data from multiple attendance devices into DingTalk:
  1. Employees clock in on various attendance devices.
  2. Each device uploads its data in real time to your own attendance system.
  3. Your own system calls the DingTalk Open Platform API to batch-upload the attendance data.
  4. DingTalk receives all clock-in data and consolidates it for unified storage and management.
  5. HR views unified attendance reports and analytics in the DingTalk workbench.
  The traditional approach requires signing in to multiple systems, exporting Excel data, and manually merging data to build reports. This flow instead aggregates data into DingTalk automatically and generates reports in one click.
• Key benefits
  • Unified multi-source data: Consolidate clock-in data from fingerprint scanners, facial recognition terminals, GPS location, and other attendance devices into one standard format in DingTalk, eliminating data silos.
  • One-stop management: HR views every employee’s attendance records in DingTalk in real time, with no need to sign in to multiple systems, export Excel files, and merge them manually.
  • Faster statistics: The system aggregates data and generates reports automatically, which greatly shortens the attendance statistics cycle.
  • Less manual work: Automation replaces repetitive manual exporting, cleaning, and merging. This lowers labor costs and reduces the risk of human error.

​

Implementation Guide

​

Technical Architecture

• Authentication layer: Use the Client ID / Client Secret to get the access_token and secure API calls.
• Permission management layer: Apply for Contacts and attendance API permissions.
• User ID retrieval layer: Call the Contacts Server API to get department user details and retrieve each employee’s user ID in the DingTalk Organization Structure.
• Clock-in upload layer: Call the attendance Server API to upload clock-in records, including the clock-in date and time from your own system, to the DingTalk Attendance app.

​

Prerequisites

• App: Create and configure an Internal app. For details, see Create and Configure an App.
• Permissions: Have DingTalk Organization Admin or Sub Admin permissions, and apply for the following API permissions:
  • qyapi_get_department_member (read permission for Contacts department members)
  • Pro.AttendanceRecord.Write (write permission for attendance clock-in records)
• Development environment: Install a Java development environment (JDK 1.6 or later) and the Maven build tool.
• SDK: Download the DingTalk Server-side SDK. For details, see the Server-side SDK download page. The SDK supports Java, Python, Go, and other languages.

​

Code Implementation

1. Call the Contacts Server API Get Department User Details to retrieve each employee’s user ID in the DingTalk Organization Structure.
2. Call the attendance Server API Upload Clock-In Records to upload employee clock-in dates, times, and other details from your own system to the DingTalk Attendance app. This syncs attendance data.

​

Implementation Steps

​

Step 1: Get the App Credential

1. Sign in to the DingTalk Developer Console.
2. Select the target app to open the app details page.
3. Click Basic Information > Credentials and Basic Information.
4. Record the app’s Client ID and Client Secret.

​

Note

​

Step 2: Add API Permissions

1. On the app details page, click Manage Permissions.
2. In the permission search box, enter the following permission identifiers and apply for them:
   • qyapi_get_department_member (read permission for Contacts department members): Gets department user details to retrieve user IDs.
   • Pro.AttendanceRecord.Write (write permission for attendance clock-in records): Uploads clock-in records to the DingTalk Attendance app.

​

Step 3: Get the Access Credential (access_token)

public void getAccessToken() throws ApiException {
  DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/gettoken");
  OapiGettokenRequest req = new OapiGettokenRequest();
  req.setAppkey("dingxxxxxxxxxhgn");
  req.setAppsecret("9G_xxxxxxxxxxxxxxx1JDf0Qq3nexxxxxxxxGIO");
  req.setHttpMethod("GET");
  OapiGettokenResponse rsp = client.execute(req);
  System.out.println(rsp.getBody());
}

• Caching: The access_token is valid for 2 hours. Cache it in memory or Redis, and refresh it 5 minutes before it expires.
• Concurrency control: Prevent multiple threads from refreshing the token at the same time and causing conflicts. Use a distributed lock.
• Retry on error: Retry automatically on network fluctuations, up to 3 times, with increasing intervals (1s → 2s → 4s).

​

Step 4: Call the Core APIs

1. Get department user details: Call the Contacts Server API Get Department User Details to retrieve each employee’s user ID in the DingTalk Organization Structure.
   public void deptInfo() throws ApiException {
       DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/v2/user/list");
       OapiV2UserListRequest req = new OapiV2UserListRequest();
       req.setDeptId(1L);
       req.setCursor(0L);
       req.setSize(10L);
       req.setOrderField("entry_asc");
       req.setContainAccessLimit(false);
       req.setLanguage("zh_CN");
       OapiV2UserListResponse rsp = client.execute(req, "access_token");
       System.out.println(rsp.getBody());
   }
   
2. Upload clock-in records: Call the attendance Server API Upload Clock-In Records to upload employee clock-in dates, times, and other details from your own system to the DingTalk Attendance app. This syncs attendance data.
   public void attendanceRecordUpload() throws ApiException {
       DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/record/upload");
       OapiAttendanceRecordUploadRequest req = new OapiAttendanceRecordUploadRequest();
       req.setUserid("01472825524039877041");
       req.setDeviceName("East Gate Time Clock");
       req.setDeviceId("dingTalk_one");
       req.setPhotoUrl("https://xxx.com/xxx.png");
       req.setUserCheckTime(1665363600000L);
       OapiAttendanceRecordUploadResponse rsp = client.execute(req, "access_token");
       System.out.println(rsp.getBody());
   }
   

• The App credential (Client ID / Client Secret) is retrieved.
• The Contacts and attendance permissions are granted.
• The access_token is retrieved.
• The Get Department User Details API call succeeded and returned the correct list of user IDs.
• The Upload Clock-In Records API call succeeded, and the DingTalk Attendance app displays the synced clock-in data.

​

FAQ

• Q1: Which parameters are required when I upload clock-in records? A: The required parameters are:
  • userid: The employee’s user ID in the DingTalk Organization Structure
  • userCheckTime: The clock-in time (Unix timestamp, in milliseconds)
  • deviceId: The attendance device ID
  • deviceName: The attendance device name Optional parameters include photoUrl (the URL of the image attached to the clock-in record, which must be publicly accessible).
• Q2: What are common causes of clock-in data sync failures? A: Common causes include:
  • An incorrect user ID (it must belong to an employee in the DingTalk Organization Structure)
  • An invalid userCheckTime format or a time in the future
  • An invalid or expired access_token
  • The app has not applied for attendance permissions
  • A network request timeout or a server error
• Q3: What are the best practices for batch-uploading clock-in data for multiple employees? A: The API currently accepts one clock-in record per call. To upload in batches, call the API in a loop at the business layer, and control the call frequency to avoid hitting the rate limit. You can also contact DingTalk technical support about batch upload options.