Leave Policies

A Leave Policy is a structured set of rules that define how employees can take time off. There are three main types:

Statutory leave policies which are mandated by national laws and include common types like PTO, sick leave, and parental leave. Some countries also have unique policies like ex-festività in Italy and RTT in France, etc.
Custom leave policies are more company-specific, providing additional leave beyond statutory requirements. These policies are not governed by national laws, do not impact payroll, and outline key details such as accrual methods, waiting periods, and carryover rules.

List leave policies summary

The list leave policies summary endpoint retrieves a detailed list of all leaves and time off data related to a given employment.

ℹ️ This endpoint replaces the now deprecated show time off balance endpoint and provides a more accurate representation of the time off data.

To make a call, provide the employment_id of the employee of interest and you will receive a response similar to the one shown below.

{
  "data": [
    {
      "annual_balance": {
        "days": 1,
        "hours": 3,
        "type": "limited"
      },
      "annual_entitlement": {
        "days": 1,
        "hours": 3,
        "type": "limited"
      },
      "balance": {
        "days": 1,
        "hours": 3,
        "type": "limited"
      },
      "current_entitlement": {
        "days": 1,
        "hours": 3,
        "type": "limited"
      },
      "leave_policy": {
        "description": "The employee is entitled to these additional leaves.",
        "leave_type": "sick_leave",
        "name": "Self-Care",
        "unit": "days"
      },
      "pending_approval": {
        "days": 1,
        "hours": 3,
        "type": "limited"
      },
      "taken": {
        "days": 1,
        "hours": 3,
        "type": "limited"
      },
      "upcoming_approved": {
        "days": 1,
        "hours": 3,
        "type": "limited"
      },
      "upcoming_requested": {
        "days": 1,
        "hours": 3,
        "type": "limited"
      },
      "used": {
        "days": 1,
        "hours": 3,
        "type": "limited"
      },
      "working_hours_per_day": 8
    }
  ]
}

🗒️ Below, we will talk about what each field in this response corresponds to. Some fields will have the following object responses:
unlimiteddaysandhoursresponse that indicates unlimited time off.
limiteddaysandhoursresponse which is an object of type `limited, including requested time offs (both past and future, whether approved or not). The format of this object is:
{
  "days": <integer>,
  "hours": <integer>,
  "type": "limited"
}

In the above response,

annual_balance: Represents the total balance for the current entitlement period. Unlike regular time off balance, it does not account for accrued value but considers only the annual entitlement. Possible response include either unlimiteddaysandhoursresponse or limiteddaysandhoursresponse.
annual_entitlement: Represents the employee's entitlement for the current period without accounting for accrues value. The response will either be unlimiteddaysandhoursresponse or limiteddaysandhoursresponse.
balance: The current available balance, calculated as "annual_entitlement-taken". For example, if annual_entitlement of an employee is 20 days and 5 are already taken by the employee, then the balance will be 15 days.
current_entitlement: The accrued entitlement, including any additional entitlements (e.g. carryovers). Possible responses are:
- If the policy type is limited, then the response will be limiteddaysandhoursresponse.
- If the policy type is unlimited but the employee's start date is in the future, then the response will change to: { "days": 0, "hours": 0, "type": "limited" }.
- If the policy type is unlimited and the employee's start date is in the past, then the response will be unlimiteddaysandhoursresponse.
leave_policy: A detailed representation of the employee's leave policy, including:
- name: The policy name.
- description: A brief explanation of the policy.
- leave_type: The category of leave. Possible values are: paid_time_off, sick_leave, public_holiday, unpaid_leave, extended_leave, in_lieu_time, maternity_leave, paternity_leave, parental_leave, bereavement, military_leave, or other.
- unit: The measurement unit for the leave. Possible values are days, hours, unlimited.
pending_approval: Lists all requested time offs that have not yet been approved (both past and future). The returned object is limiteddaysandhoursresponse.
taken: Lists all used time offs, including both past and future, whether pending or approved. The returned object is limiteddaysandhoursresponse.
upcoming_approved: Displays all future approved time offs. The returned object is limiteddaysandhoursresponse.
upcoming_requested: Displays all pending requests for future time offs. The returned object is limiteddaysandhoursresponse.
used: Shows the number of approved time offs taken by the employee in the past. The returned object is limiteddaysandhoursresponse.
working_hours_per_day: Number of hours the employee is required to work daily, as per their contract.