​

Assign Attendance Members: Batch Addition and Precise Management

​

Overview

​

Background

​

Key Benefits

• Automated batch member management: Add, query, update, and delete members through APIs with no manual intervention.
• Precise API selection: Choose the best query API for individual, department, or mixed members to retrieve complete and accurate data.
• Real-time verification: Check whether a user belongs to a specific attendance group, and verify results immediately after each update to keep data consistent.
• Unified cross-system data: Sync attendance group member data in real time across your HR system, OA system, and DingTalk to eliminate data silos.

​

Use Cases

• Employee onboarding: After HR enters a new employee in the HR system, add the employee to the attendance group of the corresponding department automatically.
• Employee offboarding: After the OA resignation approval is approved, remove the employee from all attendance groups automatically.
• Role transfers: When an employee transfers, remove the employee from the original attendance group and add them to the new department’s attendance group automatically.
• Batch member adjustments: After an Organization Structure change, update the member lists of multiple attendance groups in batches.

​

Typical Business Scenarios

​

Scenario 1: Add New Employees to Attendance Groups Automatically

​

Pain Points

​

Value

• Automated flow The automated flow runs in five steps:
  1. HR enters the new Employee record (name, Department, position).
  2. Match the target attendance group by the employee’s department ID and look up its groupKey.
  3. Call the batch-add-employees API to add the new employee’s userId to the attendance group.
  4. Call the query-members-by-id API to verify that the employee was added successfully.
  5. Clock-in permission takes effect the same day and attendance recording begins.
• Key advantages
  • Fully automatic trigger: After HR enters a new employee, the HR system calls the API to add the employee to an attendance group. No manual action is required.
  • Precise matching: The system matches the attendance group to the employee’s department automatically, which prevents wrong selections.
  • Immediate effect: The system verifies the result right after the addition, so new employees can clock in on their first day.
  • Audit trail: Each action records the operator, timestamp, and attendance group ID to meet compliance requirements.

​

Scenario 2: Remove Departing Employees from Attendance Groups Automatically

​

Pain Points

​

Value

• Automated flow The automated flow runs in five steps:
  1. The OA Approval resignation request is approved, and the system captures the event to trigger the Automation.
  2. Call the queries-a-user-attendance-group API to retrieve the IDs of all attendance groups the Employee belongs to.
  3. Iterate over those groups and call the batch-delete-employees API to remove the Employee in bulk.
  4. Call the query-members-by-id API to verify, one by one, that the Employee has been removed from every attendance group.
  5. The Employee’s clock-in permission is revoked and attendance recording stops.
• Key advantages
  • Fully automatic trigger: After the OA resignation approval is approved, the removal runs automatically with no manual intervention.
  • Full coverage: Query and remove the employee from all attendance groups in a single pass to avoid omissions.
  • Immediate effect: The system verifies the result right after removal, so departing employees can no longer clock in.
  • Complete audit logs: Every removal records detailed information to meet compliance audit and traceability requirements.

​

Implementation Guide

​

Technical Architecture

• Authentication layer: Get an access_token with your Client ID and Client Secret to secure API calls.
• Member management layer: Provides complete API capabilities to add, query, update, and delete attendance group members in batches.
• Smart routing layer: Selects the best query API based on member type (individual, department, or mixed) to retrieve complete data.
• Error handling layer: A complete error code system and retry mechanism help you locate and resolve issues quickly.

​

Prerequisites

• App setup: Create and configure an Internal app. For details, see Create and Configure an App.
• Permissions: You have DingTalk Organization Admin or Sub Admin permissions, and you have applied for the following API permissions:
  • qyapi_attendance_group_manage (attendance group management permission)
  • qyapi_attendance_group_read (attendance group read permission)
• Development environment: A Java development environment (JDK 1.6 or later) and the Maven build tool are installed.
• SDK: Download the DingTalk Server-side SDK. For details, see Download the Server-side SDK. The SDK supports multiple languages, including Java, Python, and Go.

​

Code Implementation

1. Call the Server API Batch Add Attendance Members to add attendance members to an attendance group.
2. Call the Server API Get a User’s Attendance Group to get information about the attendance group a user belongs to.
3. Get attendance member information for an attendance group:
   • Call the Server API Get the User IDs of Attendance Members to get the user IDs of attendance members.
   • Call the Server API Get Attendance Members to get attendance member information.
   • Call the Server API Query the List of Attendance Members to get the list of attendance members.
4. Call the Server API Check Whether a User Is in the Attendance Group to check whether a department or employee belongs to an attendance group.
5. Call the Server API Update Attendance Members to update the attendance members of an attendance group.
6. Call the Server API Batch Delete Attendance Members to delete attendance members.

​

Implementation Steps

​

Step 1: Get the App Credential

1. Sign in to the DingTalk Developer Console.
2. Select the target app to open its 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. Enter the following permission identifiers in the permission search box and apply for them:
   • qyapi_attendance_group_manage (attendance group management permission): Create, update, and delete attendance groups.
   • qyapi_attendance_group_read (attendance group query permission): Query attendance group summaries and details.

​

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: An access_token is valid for 2 hours. Cache it in memory or Redis, and refresh it 5 minutes before it expires.
• Concurrency control: Prevent conflicts caused by multiple threads refreshing the token at the same time. Use a distributed lock.
• Retry on error: Retry automatically during network fluctuations, up to 3 times, with increasing intervals (1s → 2s → 4s).

​

Step 4: Call the Core APIs

1. Batch add attendance members: Call the Server API Batch Add Attendance Members to add attendance members to an attendance group.
   public void  addAttendanceMembers() throws ApiException {
           DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/group/users/add");
           OapiAttendanceGroupUsersAddRequest req = new OapiAttendanceGroupUsersAddRequest();
           req.setOpUserid("manager7675");
     			//Get the groupKey: convert the groupId to a groupKey. See the attendance group management workflow
           req.setGroupKey("2A5**********24");
           req.setUserIdList("085218*********9877041");
           OapiAttendanceGroupUsersAddResponse rsp = client.execute(req, "access_token");
           System.out.println(rsp.getBody());
       }
   
2. Get a user’s attendance group: Call the Server API Get a User’s Attendance Group to get information about the attendance group a user belongs to.
    public void attendanceUserGroup() throws ApiException {
           DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/getusergroup");
           OapiAttendanceGetusergroupRequest req = new OapiAttendanceGetusergroupRequest();
           req.setUserid("0852**********72");
           OapiAttendanceGetusergroupResponse rsp = client.execute(req, "access_token");
           System.out.println(rsp.getBody());
       }
   
3. Get attendance member information for an attendance group The following three member query APIs differ mainly when an attendance group includes departments as attendance members. In the admin console, open Attendance > Attendance Group Management and edit an attendance group. The attendance members field can hold both a whole Department and an individual User at the same time. A separate non-attendance members field is also available.

   API	John’s user ID	Test department ID	User IDs of test department employees
   Get the User IDs of Attendance Members	✅	❎	✅
   Get Attendance Members	✅	✅	❎
   Query the List of Attendance Members	✅	❎	❎

   Note: ✅ means the data can be retrieved. ❎ means the data cannot be retrieved.
   • Get the user IDs of attendance members: Call the Server API Get the User IDs of Attendance Members to get the user IDs of attendance members.
      public void attendanceGroupMemberUsers() throws ApiException {
             DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/group/memberusers/list");
             OapiAttendanceGroupMemberusersListRequest req = new OapiAttendanceGroupMemberusersListRequest();
             req.setCursor(0L);
             req.setOpUserId("ma********75");
             req.setGroupId(1001290520L);
             OapiAttendanceGroupMemberusersListResponse rsp = client.execute(req, "access_token");
             System.out.println(rsp.getBody());
         }
     
   • Get attendance member information: Call the Server API Get Attendance Members to get attendance member information.
      public void groupMemberList() throws ApiException {
             DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/group/member/list");
             OapiAttendanceGroupMemberListRequest req = new OapiAttendanceGroupMemberListRequest();
             req.setCursor(0L);
             req.setOpUserId("ma*******5");
             req.setGroupId(1001290520L);
             OapiAttendanceGroupMemberListResponse rsp = client.execute(req, "access_token");
             System.out.println(rsp.getBody());
         }
     
   • Query the list of attendance members (with pagination): Call the Server API Query the List of Attendance Members to get the list of attendance members.
       public void groupUsersQuery() throws ApiException {
             DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/group/users/query");
             OapiAttendanceGroupUsersQueryRequest req = new OapiAttendanceGroupUsersQueryRequest();
             req.setSize(50L);
             req.setCursor("");
             req.setOpUserid("m*******75");
             req.setGroupKey("2A5B6**********EF24");
             OapiAttendanceGroupUsersQueryResponse rsp = client.execute(req, "access_token");
             System.out.println(rsp.getBody());
         }
     
4. Check whether a user is in the attendance group: Call the Server API Check Whether a User Is in the Attendance Group to confirm whether an employee belongs to a specific attendance group.
   public void checkGroupMember() throws ApiException {
           DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/group/member/listbyids");
           OapiAttendanceGroupMemberListbyidsRequest req = new OapiAttendanceGroupMemberListbyidsRequest();
           req.setOpUserId("m*******75");
           req.setMemberIds("085**********272");
           req.setMemberType(0L);
           req.setGroupId(1001290520L);
           OapiAttendanceGroupMemberListbyidsResponse rsp = client.execute(req, "access_token");
           System.out.println(rsp.getBody());
       }
   
5. Update attendance members: Call the Server API Update Attendance Members to adjust the attendance group member list (add or remove employees or departments).
    public void updateGroupMember() throws ApiException {
           DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/group/member/update");
           OapiAttendanceGroupMemberUpdateRequest req = new OapiAttendanceGroupMemberUpdateRequest();
           req.setOpUserId("man*****75");
           req.setGroupId(1001290520L);
           req.setScheduleFlag(0L);
           OapiAttendanceGroupMemberUpdateRequest.TopGroupMemberUpdateParam updateParam = new OapiAttendanceGroupMemberUpdateRequest.TopGroupMemberUpdateParam();
   //        updateParam.setAddDepts(Arrays.asList("123"));
   //        updateParam.setRemoveDepts(Arrays.asList("456"));
           updateParam.setAddUsers(Arrays.asList("012**********197"));
   //        updateParam.setAddExtraUsers(Arrays.asList("user456"));
   //        updateParam.setRemoveExtraUsers(Arrays.asList("user789"));
   //        updateParam.setRemoveUsers(Arrays.asList("user121"));
           req.setUpdateParam(updateParam);
           OapiAttendanceGroupMemberUpdateResponse rsp = client.execute(req, "access_token");
           System.out.println(rsp.getBody());
       }
   
6. Batch delete attendance members: Call the Server API Batch Delete Attendance Members to remove departing or transferred employees from an attendance group.
    public void deleteGroupMember() throws ApiException {
           DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/group/users/remove");
           OapiAttendanceGroupUsersRemoveRequest req = new OapiAttendanceGroupUsersRemoveRequest();
           req.setOpUserid("ma******75");
           req.setGroupKey("2A5************F24");
           req.setUserIdList("012*********3197");
           OapiAttendanceGroupUsersRemoveResponse rsp = client.execute(req, "access_token");
           System.out.println(rsp.getBody());
       }
   

• ✅ All API calls return a success status code (errcode=0).
• ✅ After each add or delete action, call the verification API to confirm the result.
• ✅ Error logs are complete for issue tracing.
• ✅ Attendance group member data in the HR system and DingTalk is compared regularly and stays consistent.

​

FAQ

• Q1: What are the differences between the three member query APIs? A: Each API fits a different member type scenario:
  • Get the User IDs of Attendance Members: Returns only a list of user IDs. Use it when you only need to check whether members exist in an attendance group.
  • Get Attendance Members: Returns detailed member information (name, department, and more). Use it when you need to display member details.
  • Query the List of Attendance Members: Supports paginated queries. Use it to retrieve members in batches when an attendance group has many members.
  When an attendance group includes department members, note the following: a query by an individual user ID returns that employee’s information. A query by department ID does not return details of the employees in that department directly. Call the department member query API separately.
• Q2: How do I handle partial failures when adding members in batches? A: The batch add API uses a “best effort” strategy and returns successful and failed members separately. Follow these steps:
  1. Parse the response to extract the user IDs of failed members and the error reasons.
  2. Log the failures and analyze the causes (for example, the user does not exist or is already in the attendance group).
  3. Retry recoverable errors (for example, a newly created user has not synced yet).
  4. Skip and log unrecoverable errors (for example, the user has already left the organization).
• Q3: How do I make sure a departing employee is fully removed? A: Follow these steps to ensure complete removal:
  1. After the OA resignation approval is approved, call the Get a User’s Attendance Group API to get the IDs of all attendance groups the employee belongs to.
  2. Iterate over all attendance groups and call the Batch Delete Attendance Members API to remove the employee.
  3. Call the Check Whether a User Is in the Attendance Group API to confirm that the employee has been removed from all attendance groups.
  4. Log the action, including the list of attendance group IDs, the time of the action, and the operator.