Recording and Retrieving External PTO Balances with the API
If you collect employee PTO accrual and usage data in an external system, you can use two API endpoints to import this data into PrismHR and retrieve your most recent imports. This external PTO data then displays on the appropriate employee check stubs during payroll processing.
The new endpoints are:
| • | PayrollService.getExternalPtoBalance |
| • | PayrollService.setExternalPtoBalance |
Relationship with PrismHR Features
The external PTO endpoints work in combination with client-level features in PrismHR. To enable these features, you must select External PTO Used in the Other tab of Client Details.
This article summarizes the most important points about the PrismHR external PTO features in relation to the API. For additional details about how these features process PTO data, review the online help topic "Recording External PTO Balances on Check Pay Stubs".
After you enable the feature set for a particular client:
| • | The client submits the PTO data from their external system using PayrollService.setExternalPtoBalance (see below).
|
| • | During payroll processing, the system checks for each employee's external PTO data and writes this data on check stubs. |
| • | The system also ignores any other PTO accruals, requests, or internal (PrismHR) settings related to this client. |
Using setExternalPtoBalance
setExternalPtoBalance accepts the external PTO data in JSON format:
Note: PTO balances must be numbers with up to two decimal places.
{
"sessionId": "API session token",
"clientId": "ID of the relevant client",
"batchId": "payroll batch to associate with the PTO data",
"importId": "Optional import ID, calculated and returned by the first call to this endpoint. This is provided in case you want to check the status of the data import.",
"employeePTO": [
{
"employeeId": "employee ID; you can submit up to 20 data objects in the pto array",
"pto": [
{
"ptoDescription": "description of PTO plan associated with this data",
"balance": "(Optional) PTO balance amount",
"accrued": "(Optional) PTO accrued amount",
"taken": "(Optional) PTO taken amount",
"carryOver": "(Optional) PTO carryover amount"
}
]
}
]
}Model setExternalPto Request
Please consider the following important notes about this endpoint:
| • | When you initiate a new import, this endpoint returns a new importId and an importStatus. To check the status of an existing import, call this endpoint again and include the importId in your request. |
| • | The payroll batch must be in a compatible status. See the endpoint's implementation notes for a complete list of allowed batch statuses. |
| • | As noted above, each employee can be associated with up to 20 separate PTO data objects. Each object in the array is associated with a PTO plan description and balance data for that plan. |
| • | setExternalPtoBalance does not support appending data unless the existing data is also present in the API request. You must send the complete PTO payload. Any data left off the input will be deleted in PrismHR.
|
After Submitting External PTO Data
During payroll processing for any client with these features enabled, PrismHR automatically reads the external PTO data and inserts the balance, accrued, taken, and carryover amounts on the employee's pay stub.
Using getExternalPtoBalance
getExternalPtoBalance enables you to retrieve the most recent external PTO data updates for a particular client and batch.
To view the three (3) most recent external PTO data submissions, set includeHistory to "true".
Note: Whenever you submit a new external PTO object, the system deletes the oldest of the historical objects.
Along with the PTO data itself, this endpoint also returns metadata related to the date and time of the PTO update and/or batch printing.
Contact 