Accrual Policies (Early Access)
Learn how to create and assign workers to set accrual policies using Zeal's respective APIs.
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:
attribute | type | description |
---|---|---|
companyID | string | Zeal Company ID |
policy_code | string | Custom code that can be assigned for the policy |
policy_type | boolean | Type of the accrual policy (accepts: pto, sick_leave, or custom) |
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 IDpolicy_code
: Custom code that can be assigned for the policypolicy_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, apto
policy type does not differ from asick_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:
attribute | type | description |
---|---|---|
policy_name | string | Custom name that can be assigned for the policy |
policy_effective_date | YYYY-MM-DD | The effective start date of the policy |
accrual_rate_hours | float | The rate at which employees will accrue hours |
accrual_period_hours | float | The number of hours employees need to work to accrue accrual_rate_hours |
immediate_balance | float | The immediate hour balance the employee would receive |
include_doubletime | boolean | Include if double-time work is eligible for hour accrual |
include_overtime | boolean | Include if overtime work is eligible for hour accrual |
accrual_waiting_period | float | The number of hours the employees need to work before they are eligible to begin accruing time for policy |
accrual_cap | float | Max hours an employee can accrue in one year until the rollover date |
rollover_cap | float | Max hours an employee can rollover from one year to the next year, on a specified rollover date |
rollover_date | float | Required if the user passes a value for rollover_cap or accrual_cap |
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.
Updated 16 days ago