Skip to main content
Most organizations have their own rules for granting leave. For example, an organization may grant different leave balances based on an employee’s job title. DingTalk leave rules do not currently support this type of custom logic. DingTalk provides Open leave APIs so organizations can support these custom scenarios.
Before you call the leave APIs, request the required API permissions in the Developer Console.

​
Request Permissions

Request API permissions before you call the leave management APIs:
  1. Sign in to the Developer Console and click the target App.
  2. Click Manage permissions, and then click Attendance.
  3. Add the leave management API permissions, and then click Request permission or Batch request.

​
Note

If a permission request is declined, find the leave management API permission in the Request column. Hover over Declined to view the reason. In the App console, go to Basic Information > Manage permissions and find the leave management permissions in the list: Click Request permission next to each permission.

​
Scenario 1: Sync Leave Rules

Use the leave APIs to sync your organization’s existing leave rules to the DingTalk leave management system (DingTalk Admin Console > Workbench > App Management > OA Approval). In the OA Approval Admin Console, go to Leave Management > Leave Rules and click Add leave to define leave rules. Configure each rule with the following columns: Then, in the form design of the leave request Form, add the Approval attendance kit provided by DingTalk. The kit automatically calculates leave balances and syncs them to the DingTalk Attendance App. The OA Approval Form editor has four steps: Basic Settings > Form Design > Process Design > Advanced Settings. On the Form Design step, open the Kits tab. Under Attendance kits, add the Leave/Time-off kit to the Form.

​
Scenario 2: Sync Internal Leave Balances to DingTalk Approval

If your organization has its own leave rules and needs to sync internal leave balances to DingTalk Approval, use the following APIs (an Internal app is used as an example):
  1. Call the Initialize leave balance API.
  2. As an Admin, go to DingTalk Admin Console > Workbench > App Management > OA Approval > Leave Management > Employee Leave Balance to view the updated Employee balances.
On the Employee Leave Balance page, click Set Employee Leave Rules or Batch Edit Balances via Excel. Filter by organization scope, and optionally select Include employees who left within 90 days. Each Record lists one Employee with the following columns: Name, Department, Join Date, First Work Date, Personal Leave (hours), Time Off in Lieu (hours), Sick Leave (hours), Annual Leave (days), and Maternity Leave (days).