Introduction

Simply put, /payroll-payruns has the metadata of the payrun, so range of dates, status, what region is relates to and totals.

 /payroll-payrun-items has the breakdowns, of every single approved shift, who worked it, how many hours, at what rates, for what position etc. 

 So you can use the payroll-payruns entity for summary data and determining status, and payroll-payrun-items to get into the 1:many of the payrun.

Q:Is the payrun-items total the employee's quantity (of hours) multiplied by the rate?

No. For the breakdowns of employees, shifts, quantity of hours and rates, you’ll need to pull from /payroll-payrun-items. You can expand those base records to pull in a lot of extra information too using the “&include=a,b,c” parameter to GET API calls to that endpoints. For database friendliness and performance, including all the relation lists is only available when requesting individual records.

 E.g.

/payroll-payrun-items/14669?payrun.id=659&include=shift.position,shift.position.payrollSetting,employee.employmentProfile.paySettings

Q: Do I request the payrun and use the payrollschedule as an ID for payrun-items?

The history of payruns will be in /payroll-payruns, and you’ll want to get an ID number from one of those before requesting a list of /payroll-payrun-items to then drill down into. Mutable vs immutable data matters, so when calling for payruns I would filter for status=PROCESSED like this:

 [GET] /payroll-payruns?sort=-id&status=PROCESSED

 Also by adding a parameter to sort by highest database index in descending order, the most recent one can be on top. If all you want is one, the most recent, you can even limit the results to just one:

[GET] /payroll-payruns?sort=-id&status=PROCESSED&limit=1 

Q: Does payrollcode indicate the type of work?

There are several ways to label a payable work item:

One is at a basic level (OT, REG, HOL)

payrollCodeLabel

Another is at Position Level and this is tied to the portal’s configuration settings in Settings->View All->PayCodes

payrollCode

Another can be a manual edit directly to a Shift (Shift editing panel, Time Approval Tab, Shift Classification section). There are different fields in the response payloads for each of these for an integrator to take note of.

shift.payCodeLabel