> ## Documentation Index
> Fetch the complete documentation index at: https://help.dingtalk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Learn how to request permissions for leave management APIs, and how to sync leave rules and internal leave balances to DingTalk Approval.

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.

> [!WARNING]
>
> 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](https://open-dev.dingtalk.io/#/appMgr/provider/eapp/53642/1) 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:

| Permission | Code | APIs included |
| - | - | - |
| DingTalk leave management | `qyapi_holiday_manage` | Add leave rule, Update leave rule, Delete leave rule |
| DingTalk leave query | `qyapi_holiday_readonly` | Query leave rule list, Query leave balance, Batch query employee leave balance change records |

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](https://oa.dingtalk.io/?lang=en_US) **> 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:

| Column | Description |
| - | - |
| **Leave name** | For example, Personal Leave, Compensatory Leave, Sick Leave, Annual Leave, Maternity Leave, Paternity Leave, or Marriage Leave |
| **Leave unit** | By hour, by half-day, or by day |
| **Duration calculation** | For example, by working day |
| **Paid** | Whether the leave is paid |
| **Balance rule** | For example, unlimited balance |
| **Scope** | For example, entire company |
| **Actions** | Edit or Delete |

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](https://help.dingtalk.io/open/development/initialize-holiday-balance.md) API.
2. As an Admin, go to [DingTalk Admin Console](https://oa.dingtalk.io/?lang=en_US) **> 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)**.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.