1. Home
  2. Docs
  3. Payroll / Earned Wage Access
  4. Read Time Punch Data
  5. Understanding the Response

Understanding the Response

Now that you know how to make a basic request to read time punch data and how to use certain filters with it, let’s explore the response. We’ll use this example response to understand what fields are important:

Example Response

{
    "status": "success",
    "total": 3,
    "offset": 0,
    "limit": 20,
    "data": [
        {
            "time_punch": {
                "id": 39132120,
                "user_id": 515743,
                "role_id": 157351,
                "location_id": 25691,
                "department_id": 49151,
                "approved": true,
                "clocked_in": "2020-08-28 14:00:00",
                "clocked_out": "2020-08-28 22:00:00",
                ...
            },
            "time_punch_break": [
                {
                    ...,
                    "paid": false,
                    "in": "2020-08-28 18:00:00",
                    "out": "2020-08-28 18:30:00",
                    ...
                },
                {
                    ...,
                    "paid": true,
                    "in": "2020-08-28 20:00:00",
                    "out": "2020-08-28 20:15:00",
                    ...
                }
            ]
        },
        {
            "time_punch": {
                "id": 39154049,
                ...
            },
            "time_punch_break": [
                {
                    "id": 134507940,
                    ...
                }
            ]
        }
    ]
}

A few things to note:

  • Within the response, every object in the data array represents one time punch
  • Within each object, the time_punch object represents details on the actual punch itself, and every object the time_punch_break array would represent every individual break that was taken during the worked shift
  • If the time_punch_break array is empty, that means that no breaks were taken

Using the location_id, department_id, role_id & user_id fields and pairing that up with the respective mappings that were established through the mapping process, you should be able to determine who a certain time punch was for, and what location, department & role they were working for that shift.

Outside of those identifier fields, you will also need to look at these fields:

time_punch FieldTypeExplanation
clocked_inDatetimeTimestamp denoting when the employee clocked in (UTC)
clocked_outDatetimeTimestamp denoting when the employee clocked out (UTC)
approvedBooleanWhether the punch was approved in 7shifts or not

Here are some things to note on each of the above fields:

  • clocked_in & clocked_out:
    • Subtracting the clocked_in time from the clocked_out time should give you the amount of time that the user worked (excluding breaks)
  • approved:
    • Time punches have the approved field set to true if they were either manually approved by a manager in 7shifts, or were auto-approved since they aligned with the time punch rules, or the punches originated from a POS system that were then brought in through an integration
    • In most cases, you want to ensure that this field is set to true before accounting it for payroll processing
time_punch_break FieldTypeExplanation
paidBooleanWhether the break was a paid break or not
inDatetimeTimestamp denoting when this break started (UTC)
outDatetimeTimestamp denoting when this break ended (UTC)

Here are some things to note on each of the above fields:

  • paid:
    • For every individual break, this boolean field determines whether the break is supposed to be a paid break or not
  • in & out:
    • For each break that has the paid field set to false, subtracting the in time from the out time should give you the amount of time that the user went on a break for
    • Please ensure that breaks with the paid field set to true aren’t being subtracted as paid break time would account for the total hours worked

Putting all the info from these three sub-sections together, the integration should be able to calculate how many hours an employee worked in total, excluding unpaid breaks, within the time range of the pay period you are looking to process payroll for.

You can then use this information with wage information that you may already have in your system to determine how much an employee has earned for their worked hours, which in turn can be used as an input for your payroll processing product.

Tip

You should provide a setting on the configuration page for this integration which would allow an admin to choose whether they wish to include all breaks, only paid breaks or no breaks at all for payroll processing.

You should also provide an option that allows the admin to choose to process only approved time punches in 7shifts for payroll. Changing this option should directly enable/disable the check for the approved field being set to true.

Different managers have different flows on how they approve time punches in 7shifts, and allowing them a setting to choose would help ensure that your payroll integration fits their flow regardless of how they handle time punch approval in 7shifts.