Accrual Policies (Early Access)

Intro

Accrual Policies represent policies that can be accrued by and assigned to workers. Typical Accrual Policies include PTO and sick leave. However, Zeal offers the ability for custom Accrual Policies for specific use cases to be created and assigned to workers as well. These Accrual Policies, when attached to a worker, contain an accrual balance that is automatically tracked and updated by Zeal based on the worker's shifts as well as their specific Accrual Policy specifications.

Note: Accrual Policies is an early access feature. Please contact your Zeal team for more information on this feature

In this guide

• Which endpoints are needed to create and assign workers to Accrual Policies.
• A step by step explanation on utilizing these endpoints.

Accrual Policies APIs

Accrual Policies are currently only available for integration via API.

The Accrual Policy Object

The Accrual Policy object outlines the fields that represent an Accrual Policy. Accrual Policies are created and assigned at the company level and rely on three main required attributes:

Other attributes can be passed to further configure the accrual policy such as a policy_effective_date, accrual_rate_hours. Please review the afore-linked Accrual Policy object reference for all accepted attributes and their respective details. Below is a JSON example of an Accrual Policy object:

{
  "companyID": "123er534efrerwwe3444e",
  "policy_code": "001",
  "policy_type": "pto",
  "policy_name": "test name",
  "policy_effective_date": "2023-03-01",
  "accrual_rate_hours": 10,
  "accrual_period_hours": 40,
  "immediate_balance": 0,
  "include_doubletime": true,
  "include_overtime": true,
  "accrual_waiting_period": 0,
  "accrual_cap": 40,
  "rollover_cap": 40,
  "rollover_date": "01-01",
  "policy_status": "live"
}

Creating an Accrual Policy

To create an Accrual Policy, utilize the Create Accrual Policy or POST /accrualPolicy endpoint. The endpoint requires the following body parameters:

• companyID: Zeal Company ID
• policy_code: Custom code that can be assigned for the policy
• policy_type: Type of the accrual policy (accepts: pto, sickleave, or custom).
  _Note: The accrual policy type has no effects on other parameters other than classification of the accrual policy. Therefore, a pto policy type does not differ from a sick_leave type other than in classification.

Other parameters:

As mentioned in the Accrual Policy object reference, the POST endpoint accepts other body parameters to further specify the Accrual Policy being created:

Below is the JSON response of a successful POST /accrualPolicy request specifically for a PTO policy_type:

{
  "success": true,
  "data": {
    "companyID": "123er534efrerwwe3444e",
    "policy_type": "pto",
    "policy_name": "test name",
    "policy_code": "001",
    "policy_effective_date": "2023-03-20",
    "accrual_rate_hours": 0.5,
    "accrual_period_hours": 10,
    "immediate_balance": 10,
    "include_doubletime": false,
    "include_overtime": false,
    "accrual_waiting_period": 28,
    "accrual_cap": 50,
    "rollover_cap": 20,
    "rollover_date": "05-01",
    "policy_status": "live"
  }
}

Updating or Fetching Accrual Policies

The accrual policy can be subsequently updated or fetched using the corresponding Update Accrual Policy or PATCH /accrualPolicy endpoint to update or the Get Accrual Policy GET /accrualPolicy endpoint to fetch a specific Accrual Policy by passing a companyID and an option policy_code or policy_status.

Adding/Removing Workers to/from Accrual Policies

In order to assign workers to an Accrual Policy, utilize the Add/Remove Employees to Accrual Policy or POST /accrualPolicyEmployees endpoint. To assign or remove workers to or from an Accrual Policy, the companyID and specific Accrual Policy policy_code need to be passed as required parameters. To add employee(s), the add_employees array of strings would be passed containing the specific employeeID(s) of the worker(s) to be added to the policy. Below is a JSON body example of a POST /accrualPolicyEmployees request adding workers to an Accrual Policy:

{
  "companyID": "cc3344747eee494857rrc9458nb3948",
  "policy_code": "001",
  "add_employees": [
    "3343eericree4394785ec3334cc",
    "322324eceree4394785ec3334cc"
  ]
}

After a successful request assigning worker(s) to an Accrual Policy, the worker(s) are now associated with the corresponding Accrual Policy object and its respective specifications.

Accrual Policy Balances

When creating an Accrual Policy, a balance such as a worker's starting PTO balance can initially be declared by the immediate_balance parameter. However, this balance can be updated or fetched at any time after Accrual Policy using creation by utilizing the respective Update Accrual Balance (PATCH /accrualBalance) or Get Accrual Balance (GET /accrualBalance) endpoints. Additionally, Zeal automatically tracks and updates balances based on attached workers' shifts and payroll. Below is a JSON body example of a PATCH /accrualBalance request:

{
  "companyID": "cc3344747eee494857rrc9458nb3948",
  "policy_code": "001",
  "employees": [
    {
      "employeeID": "3343eericree4394785ec3334cc",
      "accrual_balance": 40
    },
    {
      "employeeID": "322324eceree4394785ec3334cc",
      "accrual_balance": 35
    }
  ]
}

Accrual Policy Usage

The Accrual Policy Usage allows the management of usage amounts, that will be applied to an employee's accrual balance, based on the specific accrual policies within a company. This feature enables the application of a policy's usage data onto past checks within a specified date range, provided that the employees did receive at least one paycheck during that period.

Call Create Accrual Policy Usage or POST https://api.zeal.com/accrualPolicy/:{policyCode}/usage supplying a list of employees for whom usage is being applied for. The endpoint supports both regular usage entries and corrections, allowing flexibility in managing employee accrual balances.

Below is a JSON body example of a POST /usage request in the amount of 4 to an employee for a specific date range:

{
    "companyID": "7735961dd7c54215a97c8e2f8cabadbd",
    "employees": [{
        "employeeID": "6685ae9da865216fe9ea2f9f",
        "start_date": "2024-06-23",
        "end_date": "2024-06-29",
        "amount": 4
    }]
}

This request will take an amount of 4 off the employee's current accrued balance for the policy specified. If you need to make a correction for this amount later you can make a similar call to adjusting the balance.

Below is a JSON body example of a POST /usage request to apply a correction of 2, reducing the employee's usage within the same date range used above:

{  
    "companyID": "7735961dd7c54215a97c8e2f8cabadbd",  
    "employees": [{  
        "employeeID": "6685ae9da865216fe9ea2f9f",  
        "start_date": "2024-06-23",  
        "end_date": "2024-06-29",  
        "correction": true,  
        "amount": 2  
    }]  
}

After this request is applied, the total usage for the employee within the specified date range (2024-06-23 to 2024-06-29) would be calculated to 2.

Recap

• Accrual Policies are created via the API for specific use-cases (the most common being PTO and sick leave)
• Workers can be assigned to or removed from specific Accrual Policies
• Accrual Policy balances are automatically tracked and updated by Zeal yet can be updated as needed even via API after Accrual Policy creation
• Accrual Policy Usage allows the management of an employee's accrual balance usage on past checks, and supports corrections.