Create a Leave Policy via API
[POST] /leave-policies
{
"customId": "ABLPAPI",
"name": "AB API Leave Policy",
"description": "API Testing",
"region": 2,
"status": "ACTIVE",
"effectiveStartDate": "2023-03-27T00:00:00+00:00",
"payHoursPerDay": 8,
"balanceResetReferenceMonth": "JANUARY",
"balanceResetsPerYear": 1
}The effectiveStartDate must had a date at least one day past the current date or there will be a validation error like:
{
"effectiveStartDate": [
"This value should be greater than or equal to Mar 27, 2023, 12:00 AM."
]
}
If you include definitions for startPeriodDate and endPeriodDate, they will be ignored and without a validation error message. These are calculated fields.
A leave policy will then be created with the values:
{
"customId": "ABLPAPI",
"name": "AB API Leave Policy",
"description": "API Testing",
"region": 2,
"status": "ACTIVE",
"effectiveStartDate": "2023-03-27T00:00:00+00:00",
"payHoursPerDay": 8,
"balanceResetReferenceMonth": "JANUARY",
"balanceResetsPerYear": 1,
"startPeriodDate": "2023-01-01T00:00:00+00:00",
"endPeriodDate": "2023-12-31T00:00:00+00:00",
"id": 6
}The startPeriodDate and endPeriodDate are calculated as the start and end of the CURRENT year no matter what the effectiveStartDate value provided. If it’s 2023 and you provide an effective start date of 2024, the start and end periods will remain defined for 2023.
Web application result:
Create Leave Policy Items via API
[POST] /leave-policy-items
{
"customId": "LPIAPI1",
"name": "Leave Policy Item API 1",
"description": "API test 1",
"entitlementUnit": "DAYS",
"quantity": 18,
"region": 2,
"leaveType": 8,
"accrualRate": null,
"carryOver": true,
"carryOverLimit": 5
}The accrual rate can be provided, or the quantity, but not both. Trying to provide both triggers validation error:
{ "leave-policy-items": [ "Only accrual rate or quantity can be entered." ] }
entitlementUnit is either enum DAYS or HOURS.
leaveType is an integer value of the ID numberof from records available at /leave-types.
E.g.
{
"name": "Bereavement",
"region": null,
"status": "ACTIVE",
"id": 1
},
...
{
"name": "Personal Day",
"region": null,
"status": "ACTIVE",
"id": 8
},
...
Web application result:
Assign Leave Policy Items to a Leave Policy
You need to use the assignment action and provide an array of ID numbers of /leave-policy-items :
[POST] /leave-policies/8/actions/assign-leave-policy-items
{
"leavePolicyItemsIds" : [3,4]
}The ID of the leave policy is in the URI of the API request. It needn’t be included in the body of the request.
Web application result:
And if you enter the Leave Policy to see those two items:
Un-assign Leave Policy Items from a Leave Policy
[POST] /leave-policies/8/actions/unassign-leave-policy-items
{
"leavePolicyItemsIds" : [3,4]
}Web application result:
Create Leave Types via API
[POST] /leave-types
{
"name": "Browncoat Leave",
"region": 2
}The region and status values cannot be changed directly via POST method.
E.g.
[PATCH] /leave-types/12
{ "region": 3 }
Result:
{ "name": "Browncoat Leave", "region": 2, "status": "ACTIVE", "id": 12 }
No validation error message is provided.
You can however archive a Leave Type via an action. See below.
Web application result:
Archive a Leave Type
[POST] /leave-types/12/actions/archive
(No Body required)
Assign Employees to a Leave Policy
[POST] /leave-policies/8/actions/assign-employees
{
"employeesIds" : [1404,1441]
}An employee already assigned to a Leave Type cannot be assigned to a new Leave Type before being unassigned from their previous one. Otherwise this validation error occurs (for however many IDs are provided in the employeesIds array):
{ "assign-employees": [ "1 employees have already been assigned to a policy, please unassign employees first." ] }
Validation
The assign-employees action performs the following validations before it will allow the assignment of a leave policy to an employee:
-
An Employee for whom all Leave Policies assigned to them have an “end- date” → The employee is NOT currently “using” a Leave Policy.
-
An employee AND the HR Admin who has access to the Region where the Leave Policy was created or any child Regions of the Region where the Leave Policy was created.
-
It will count the number of employees found in a query for employees based on the IDs provided in the list vs the number of items in the list. When these mismatch, an error is returned:
Unable to assign leave policy to all selected employees
E.g. This error will be triggered if you provide an Employee ID value that is not an actual Employee ID found in the database, or the Employee is terminated.
Un-assign Employees from a Leave Policy
[POST] /leave-policies/8/actions/unassign-employees
{
"employeesIds" : [1404,1441]
}If you attempt un-assign an employee (via its ID in employeesIds) that is not currently assigned to the Leave Policy ID specified in the URI (8 in the example above), then a validation error is returned and no employee assignments are treated:
{ "unassign-employees": [ "Only 1 employees have been assigned to this policy, please verify employees first." ] }
Leave Balances
If you'd like to see how many days that an employee has for a particular Leave Type, obtain the employee's ID value and call /leave-balances :
[GET] /leave-balances?employee={id}&include=leaveType
{
"id": "1404-10-2023-01-01",
"employee": 1404,
"periodId": "2023-01-01-12",
"balanceDays": 3,
"balanceDaysIncludingPending": 3,
"timeZone": "America/New_York",
"periodStartDateTime": "2023-01-01T00:00:00-05:00",
"periodEndDateTime": "2024-01-01T00:00:00-05:00",
"leaveType": {
"name": "Vacation",
"region": null,
"status": "ACTIVE",
"id": 10
}
}
Updating leave balances
If you know the Leave Policy an employee is assigned to, you can update the balance of hours per Leave Type like so (this changes the total as a new "days" value. It doesn't add/subtract by the "days" value):
E.g. set the balance to 1 day
[POST] /leave-policies/{id}/actions/update-balance
{
"employee": 1404,
"leaveType": 10,
"description": "balance update",
"days": 1,
"hours": 0
}
Result:
[GET] /leave-balances?employee={id}&include=leaveType
----------previous old record with balanceDays = 3 --------
{
"id": "1404-10-2023-01-01",
"employee": 1404,
"periodId": "2023-01-01-12",
"balanceDays": 3,
"balanceDaysIncludingPending": 3,
"timeZone": "America/New_York",
"periodStartDateTime": "2023-01-01T00:00:00-05:00",
"periodEndDateTime": "2024-01-01T00:00:00-05:00",
"leaveType": {
"name": "Vacation",
"region": null,
"status": "ACTIVE",
"id": 10
}
},
----------new entry added with balanceDays = 1 --------
{
"id": "1404-10-2024-01-01",
"employee": 1404,
"periodId": "2024-01-01-12",
"balanceDays": 1,
"balanceDaysIncludingPending": 1,
"timeZone": "America/New_York",
"periodStartDateTime": "2024-01-01T00:00:00-05:00",
"periodEndDateTime": "2025-01-01T00:00:00-05:00",
"leaveType": {
"name": "Vacation",
"region": null,
"status": "ACTIVE",
"id": 10
}
}