Timecard operations

In this tutorial, we view, add, update, and remove employee punches.

The following operations introduce the powerful Timecard resource, one of the most flexible tools in the API library.

This resource provides a useful introduction to the many ways in which you can pass object references through arrays in the request body to produce different results.

The first set of examples feature viewing, adding, updating, and removing employee punches.

Note: The example request bodies in this section are valid for both the Update Timecard as Manager (POST /v1/timekeeping/timecard) and the Update Timecard as Employee (POST /v1/timekeeping/employee_timecard) operations. For this tutorial, the assumed user is a manager.

View an employee's punches

The manager calls the Timecard operation using the GET HTTP method to view an employee's punches.

  1. Send a GET request to the following URL: https://<<hostName>>/api/v1/timekeeping/timecard
  2. Include the standard Headers.
  3. Include the following Query Parameters:
    • employee_id : <<employeeId>>
    • symbolic_period_id : Previous_Payperiod
    • select : PUNCHES

Example response

{
    "punches": [...]
}

Add an employee's punches

The manager calls the Update Timecard as Manager operation using the POST HTTP method to add a punch to an employee's timecard.

  1. POST a request to the following URL: https://<<hostName>>/api/v1/timekeeping/timecard
  2. Include the standard Headers.
  3. Include an appropriate JSON call body. Refer to the examples below.

When constructing the JSON body of your request, keep the following points in mind:

  • Use the punches/added array
    • In the array, provide the employee ID and the punch date and time
  • The operation requires an employee ID with start and end dates and times or a symbolic period
  • Set the property onlyValidate to false, or the punch is not saved

Example request

{
  "where": {
    "employee": {
      "id": 309
    },
    "dateRange": {
      "startDate": "2017-11-06T00:00",
      "EndDate": "2017-11-12T00:00"
    }
  },
  "do":
  {
  "punches": {
    "added": [
      {
        "employee": {
          "id": 309
        },
        "punchDtm": "2017-11-08T10:02:00"
      }
    ]
  },
    "onlyValidate": false
  }
}

Example response

{
    "lastUpdates": [
        {
            "employeeId": 309,
            "updateDateTime": "2018-02-08T02:52:24",
            "updateByPersonFullName": "Ivan, Sean",
            "isEditedInSignedOff": false
        }
    ],
    "projects": [],
    "overtimeApprovals": [
        {
            "existingApprovalsOrDenials": [],
            "unapprovedSegments": [],
            "unapprovedAmount": 0,
            "deniedAmount": 0
        }
    ],
    "punches": [
        {
            "id": 6001,
            "employee": {
                "id": 309,
                "qualifier": "20000",
                "name": "20000"
            },
            "punchDtm": "2017-11-08T10:02:00",
            "timeZone": {
                "id": 134110,
                "qualifier": "(GMT -05:00) Eastern Time (USA; Canada)",
                "name": "(GMT -05:00) Eastern Time (USA; Canada)"
            },
            "enteredOnDtm": "2018-02-08T02:52:24",
            "editByType": {
                "id": -2
            },
            "dataSource": {
                "id": 3275,
                "qualifier": "Ivan, Sean",
                "name": "Ivan, Sean"
            },
            "exceptions": [
                {
                    "employee": {
                        "id": 309,
                        "qualifier": "20000",
                        "name": "20000"
                    },
                    "startDateTime": "2017-11-08T10:02:00",
                    "endDateTime": "2017-11-08T10:02:00",
                    "applyDate": "2017-11-08",
                    "id": -13,
                    "endTimeZone": {
                        "id": 134110
                    },
                    "exceptionType": {
                        "id": 17,
                        "name": "UNSCHEDULED",
                        "description": "UNSCHEDULED_DSC",
                        "displayName": "Unscheduled",
                        "category": "SHIFT_EXCEPTIONS"
                    },
                    "orgJob": {
                        "id": 440
                    },
                    "overLimitInHours": 0,
                    "startTimeZone": {
                        "id": 134110
                    },
                    "violationInHours": 0,
                    "workRule": {
                        "id": 17,
                        "qualifier": "Full Time",
                        "name": "Full Time"
                    },
                    "commentsNotes": [],
                    "punchEvent": {
                        "id": -11
                    },
                    "isExcusedAbsence": false,
                    "isUnExcusedAbsence": false,
                    "reviewed": false,
                    "transfer": false,
                    "eventDate": "2017-11-08",
                    "startException": true,
                    "endException": false
                }
            ],
            "commentsNotes": [],
            "isPhantom": false,
            "isScheduled": false,
            "updatedOnDtm": "2018-02-08T02:52:24",
            "exceptionResolved": false,
            "editable": true
        }
    ],
    "workedShifts": [
        {
            "id": -11,
            "employee": {
                "id": 309
            },
            "startDateTime": "2017-11-08T10:02:00",
            "endDateTime": "2017-11-08T10:02:00",
            "startTimezone": {
                "id": 134110
            },
            "endTimezone": {
                "id": 134110
            },
            "roundedStartDateTime": "2017-11-08T10:02:00",
            "roundedEndDateTime": "2017-11-08T10:02:00",
            "roundedStartTimezone": {
                "id": 134110
            },
            "roundedEndTimezone": {
                "id": 134110
            },
            "unscheduledStartDateTime": "2017-11-08T10:02:00",
            "unscheduledEndDateTime": "2017-11-08T18:02:00",
            "unscheduledWorkRule": {
                "id": 17
            },
            "inProgress": false,
            "workedSpans": [
                ...
                ],
            "shiftTotalHours": 0,
            "scheduledShiftIds": [],
            "projected": false,
            "fromSchedule": false
        }
    ],
    "hoursWorked": [],
    "payCodeEdits": [],
    "historicalCorrections": [],
    "workHolidayCredits": [],
 ...
}

Update an employee's punches

The manager calls the Update Timecard as Manager operation using the POST HTTP method to update an employee's punch.

  1. POST a request to the following URL: https://<<hostName>>/api/v1/timekeeping/timecard
  2. Include the standard Headers.
  3. Include an appropriate JSON call body. Refer to the examples below.

When constructing the JSON body of your request, keep the following points in mind:

  • Use the punches/updated array
    • In the array, provide the employee ID, punch ID, and the new punch date and time for each punch you want to update
  • The operation requires an employee ID with start and end dates and times or a symbolic period
  • Set the property onlyValidate to false, or the punch is not saved

Example request

{
  "where": {
    "employee": {
      "id": 309
    },
    "dateRange": {
      "startDate": "2017-11-06T00:00",
      "EndDate": "2017-11-12T00:00"
    }
  },
  "do":
  {
  "punches": {
    "updated": [
      {
        "id": 7051,
        "employee": {
          "id": 309
        },
        "punchDtm": "2017-11-08T10:05:00"
      }
    ]
  },
    "onlyValidate": false
  }
}

Example response

{
    "lastUpdates": [
        {
            "employeeId": 309,
            "updateDateTime": "2018-02-08T03:14:02",
            "updateByPersonFullName": "Ivan, Sean",
            "isEditedInSignedOff": false
        }
    ],
    "projects": [],
    "overtimeApprovals": [
        {
            "existingApprovalsOrDenials": [],
            "unapprovedSegments": [],
            "unapprovedAmount": 0,
            "deniedAmount": 0
        }
    ],
    "punches": [
        {
            "id": 6001,
            "employee": {
                "id": 309,
                "qualifier": "20000",
                "name": "20000"
            },
            "punchDtm": "2017-11-08T10:02:00",
            "timeZone": {
                "id": 134110,
                "qualifier": "(GMT -05:00) Eastern Time (USA; Canada)",
                "name": "(GMT -05:00) Eastern Time (USA; Canada)"
            },
            "enteredOnDtm": "2018-02-08T02:52:24",
            "editByType": {
                "id": -2
            },
            "dataSource": {
                "id": 3275,
                "qualifier": "Ivan, Sean",
                "name": "Ivan, Sean"
            },
            "exceptions": [
                {
                    "employee": {
                        "id": 309,
                        "qualifier": "20000",
                        "name": "20000"
                    },
                    "startDateTime": "2017-11-08T10:02:00",
                    "endDateTime": "2017-11-08T10:05:00",
                    "applyDate": "2017-11-08",
                    "id": 26456,
                    "endTimeZone": {
                        "id": 134110
                    },
                    "exceptionType": {
                        "id": 17,
                        "name": "UNSCHEDULED",
                        "description": "UNSCHEDULED_DSC",
                        "displayName": "Unscheduled",
                        "category": "SHIFT_EXCEPTIONS"
                    },
                    "orgJob": {
                        "id": 440
                    },
                    "overLimitInHours": 0,
                    "startTimeZone": {
                        "id": 134110
                    },
                    "violationInHours": 0,
                    "workRule": {
                        "id": 17,
                        "qualifier": "Full Time",
                        "name": "Full Time"
                    },
                    "commentsNotes": [],
                    "punchEvent": {
                        "id": 30401
                    },
                    "isExcusedAbsence": false,
                    "isUnExcusedAbsence": false,
                    "reviewed": false,
                    "transfer": false,
                    "eventDate": "2017-11-08",
                    "startException": true,
                    "endException": false
                }
            ],
            "commentsNotes": [],
            "isPhantom": false,
            "isScheduled": false,
            "updatedOnDtm": "2018-02-08T02:52:24",
            "exceptionResolved": false,
            "editable": true
        },
        {
            "id": 7051,
            "employee": {
                "id": 309,
                "qualifier": "20000",
                "name": "20000"
            },
            "punchDtm": "2017-11-08T10:05:00",
            "timeZone": {
                "id": 134110,
                "qualifier": "(GMT -05:00) Eastern Time (USA; Canada)",
                "name": "(GMT -05:00) Eastern Time (USA; Canada)"
            },
            "enteredOnDtm": "2018-02-08T03:14:02",
            "editByType": {
                "id": -2
            },
            "dataSource": {
                "id": 3278,
                "qualifier": "Ivan, Sean",
                "name": "Ivan, Sean"
            },
            "exceptions": [
                {
                    "employee": {
                        "id": 309,
                        "qualifier": "20000",
                        "name": "20000"
                    },
                    "startDateTime": "2017-11-08T10:05:00",
                    "endDateTime": "2017-11-08T14:02:00",
                    "applyDate": "2017-11-08",
                    "id": -14,
                    "endTimeZone": {
                        "id": 134110
                    },
                    "exceptionType": {
                        "id": 13,
                        "name": "SHORT_SHIFT",
                        "description": "SHORT_SHIFT_DSC",
                        "displayName": "Short Shift",
                        "category": "SHIFT_EXCEPTIONS"
                    },
                    "orgJob": {
                        "id": 440
                    },
                    "overLimitInHours": 3.95,
                    "startTimeZone": {
                        "id": 134110
                    },
                    "violationInHours": 0.05,
                    "workRule": {
                        "id": 17,
                        "qualifier": "Full Time",
                        "name": "Full Time"
                    },
                    "commentsNotes": [],
                    "punchEvent": {
                        "id": 30401
                    },
                    "isExcusedAbsence": false,
                    "isUnExcusedAbsence": false,
                    "reviewed": false,
                    "transfer": false,
                    "eventDate": "2017-11-08",
                    "startException": false,
                    "endException": true
                }
            ],
            "commentsNotes": [],
            "isPhantom": false,
            "isScheduled": false,
            "updatedOnDtm": "2018-02-08T03:14:02",
            "exceptionResolved": false,
            "editable": true
        }
    ],
    "workedShifts": [
        {
            "id": 30401,
            "employee": {
                "id": 309
            },
            "startDateTime": "2017-11-08T10:02:00",
            "endDateTime": "2017-11-08T10:05:00",
            "startTimezone": {
                "id": 134110
            },
            "endTimezone": {
                "id": 134110
            },
            "roundedStartDateTime": "2017-11-08T10:02:00",
            "roundedEndDateTime": "2017-11-08T10:05:00",
            "roundedStartTimezone": {
                "id": 134110
            },
            "roundedEndTimezone": {
                "id": 134110
            },
            "unscheduledStartDateTime": "2017-11-08T10:02:00",
            "unscheduledEndDateTime": "2017-11-08T18:02:00",
            "unscheduledWorkRule": {
                "id": 17
            },
            "inProgress": false,
            "workedSpans": [
                {
                    "id": 30401,
                    "startDateTime": "2017-11-08T10:02:00",
                    "endDateTime": "2017-11-08T10:05:00",
                    "startTimezone": {
                        "id": 134110
                    },
                    "endTimezone": {
                        "id": 134110
                    },
                    "primaryOrgJob": {
                        "id": 440
                    },
                    "workRule": {
                        "id": 17
                    },
                    "primaryWorkRule": {
                        "id": 440
                    },
                    "orderNumber": 1,
                    "startPunch": {
                        "id": 6001,
                        "employee": {
                            "id": 309,
                            "qualifier": "20000",
                            "name": "20000"
                        },
                        "punchDtm": "2017-11-08T10:02:00",
                        "timeZone": {
                            "id": 134110,
                            "qualifier": "(GMT -05:00) Eastern Time (USA; Canada)",
                            "name": "(GMT -05:00) Eastern Time (USA; Canada)"
                        },
                        "enteredOnDtm": "2018-02-08T02:52:24",
                        "editByType": {
                            "id": -2
                        },
                        "dataSource": {
                            "id": 3275,
                            "qualifier": "Ivan, Sean",
                            "name": "Ivan, Sean"
                        },
                        "exceptions": [
                            {
                                "employee": {
                                    "id": 309,
                                    "qualifier": "20000",
                                    "name": "20000"
                                },
                                "startDateTime": "2017-11-08T10:02:00",
                                "endDateTime": "2017-11-08T10:05:00",
                                "applyDate": "2017-11-08",
                                "id": 26456,
                                "endTimeZone": {
                                    "id": 134110
                                },
                                "exceptionType": {
                                    "id": 17,
                                    "name": "UNSCHEDULED",
                                    "description": "UNSCHEDULED_DSC",
                                    "displayName": "Unscheduled",
                                    "category": "SHIFT_EXCEPTIONS"
                                },
                                "orgJob": {
                                    "id": 440
                                },
                                "overLimitInHours": 0,
                                "startTimeZone": {
                                    "id": 134110
                                },
                                "violationInHours": 0,
                                "workRule": {
                                    "id": 17,
                                    "qualifier": "Full Time",
                                    "name": "Full Time"
                                },
                                "commentsNotes": [],
                                "punchEvent": {
                                    "id": 30401
                                },
                                "isExcusedAbsence": false,
                                "isUnExcusedAbsence": false,
                                "reviewed": false,
                                "transfer": false,
                                "eventDate": "2017-11-08",
                                "startException": true,
                                "endException": false
                            }
                        ],
                        "commentsNotes": [],
                        "isPhantom": false,
                        "isScheduled": false,
                        "updatedOnDtm": "2018-02-08T02:52:24",
                        "exceptionResolved": false,
                        "editable": true
                    },
                    "endPunch": {
                        "id": 7051,
                        "employee": {
                            "id": 309,
                            "qualifier": "20000",
                            "name": "20000"
                        },
                        "punchDtm": "2017-11-08T10:05:00",
                        "timeZone": {
                            "id": 134110,
                            "qualifier": "(GMT -05:00) Eastern Time (USA; Canada)",
                            "name": "(GMT -05:00) Eastern Time (USA; Canada)"
                        },
                        "enteredOnDtm": "2018-02-08T03:14:02",
                        "editByType": {
                            "id": -2
                        },
                        "dataSource": {
                            "id": 3278,
                            "qualifier": "Ivan, Sean",
                            "name": "Ivan, Sean"
                        },
                        "exceptions": [
                            {
                                "employee": {
                                    "id": 309,
                                    "qualifier": "20000",
                                    "name": "20000"
                                },
                                "startDateTime": "2017-11-08T10:05:00",
                                "endDateTime": "2017-11-08T14:02:00",
                                "applyDate": "2017-11-08",
                                "id": -14,
                                "endTimeZone": {
                                    "id": 134110
                                },
                                "exceptionType": {
                                    "id": 13,
                                    "name": "SHORT_SHIFT",
                                    "description": "SHORT_SHIFT_DSC",
                                    "displayName": "Short Shift",
                                    "category": "SHIFT_EXCEPTIONS"
                                },
                                "orgJob": {
                                    "id": 440
                                },
                                "overLimitInHours": 3.95,
                                "startTimeZone": {
                                    "id": 134110
                                },
                                "violationInHours": 0.05,
                                "workRule": {
                                    "id": 17,
                                    "qualifier": "Full Time",
                                    "name": "Full Time"
                                },
                                "commentsNotes": [],
                                "punchEvent": {
                                    "id": 30401
                                },
                                "isExcusedAbsence": false,
                                "isUnExcusedAbsence": false,
                                "reviewed": false,
                                "transfer": false,
                                "eventDate": "2017-11-08",
                                "startException": false,
                                "endException": true
                            }
                        ],
                        "commentsNotes": [],
                        "isPhantom": false,
                        "isScheduled": false,
                        "updatedOnDtm": "2018-02-08T03:14:02",
                        "exceptionResolved": false,
                        "editable": true
                    },
                    "scheduledOrgJob": false,
                    "scheduledWorkRule": false,
                    "userEnteredOrgJob": false,
                    "transferOrgJob": false,
                    "userEnteredWorkRule": false,
                    "transferWorkRule": false,
                    "projected": false
                }
            ],
            "shiftTotalHours": 180,
            "scheduledShiftIds": [],
            "projected": false,
            "fromSchedule": false
        }
    ],
    "hoursWorked": [],
    "payCodeEdits": [],
    "historicalCorrections": [],
    "workHolidayCredits": [],
    "exceptions": [
        {
            "employee": {
                "id": 309,
                "qualifier": "20000",
                "name": "20000"
            },
            "startDateTime": "2017-11-08T10:02:00",
            "endDateTime": "2017-11-08T10:05:00",
            "applyDate": "2017-11-08",
            "id": 26456,
            "endTimeZone": {
                "id": 134110
            },
            "exceptionType": {
                "id": 17,
                "name": "UNSCHEDULED",
                "description": "UNSCHEDULED_DSC",
                "displayName": "Unscheduled",
                "category": "SHIFT_EXCEPTIONS"
            },
            "orgJob": {
                "id": 440
            },
            "overLimitInHours": 0,
            "startTimeZone": {
                "id": 134110
            },
            "violationInHours": 0,
            "workedShift": {
                "id": -12
            },
            "workRule": {
                "id": 17,
                "qualifier": "Full Time",
                "name": "Full Time"
            },
            "commentsNotes": [],
            "punchEvent": {
                "id": 30401
            },
            "isExcusedAbsence": false,
            "isUnExcusedAbsence": false,
            "reviewed": false,
            "transfer": false,
            "eventDate": "2017-11-08",
            "startException": true,
            "endException": false
        },
        ...
    ],
    "extendedExceptions": [
        {
            "employee": {
                "id": 309,
                "qualifier": "20000",
                "name": "20000"
            },
            "startDateTime": "2017-11-08T10:02:00",
            "endDateTime": "2017-11-08T10:05:00",
            "applyDate": "2017-11-08",
            "id": 26456,
            "endTimeZone": {
                "id": 134110
            },
            "exceptionType": {
                "id": 17,
                "name": "UNSCHEDULED",
                "description": "UNSCHEDULED_DSC",
                "displayName": "Unscheduled",
                "category": "SHIFT_EXCEPTIONS"
            },
            "orgJob": {
                "id": 440
            },
            "overLimitInHours": 0,
            "startTimeZone": {
                "id": 134110
            },
            "violationInHours": 0,
            "workedShift": {
                "id": -12
            },
            "workRule": {
                "id": 17,
                "qualifier": "Full Time",
                "name": "Full Time"
            },
            "commentsNotes": [],
            "punchEvent": {
                "id": 30401
            },
            "isExcusedAbsence": false,
            "isUnExcusedAbsence": false,
            "actualDateTime": "2017-11-08T10:02:00",
            "comments": "",
            "reviewed": false,
            "transfer": false,
            "eventDate": "2017-11-08",
            "startException": true,
            "endException": false
        },
        ...
    ],
    "dailyTotals": [
        {
            "id": 30401,
            "durationInHours": 0.05,
            "wages": 1.65,
            "durationInDays": 0,
            "timeItemId": 30401,
            "amountType": "HOUR",
            "employee": {
                "id": 309,
                "qualifier": "20000",
                "name": "20000"
            },
            "applyDate": "2017-11-08",
            "fromShift": true,
            "totalType": "HOURSANDCOST"
        },
        ...
    ],
    "totals": [
        {
            "employeeContext": {
                "employee": {
                    "id": 309,
                    "qualifier": "20000",
                    "name": "20000"
                },
                "timezone": {
                    "id": 13411,
                    "qualifier": "(GMT -05:00) Eastern Time (USA; Canada)",
                    "name": "(GMT -05:00) Eastern Time (USA; Canada)"
                }
            },
            "totalContext": {
                "totalType": "Actual totals",
                "totalAggregationType": "All",
                "totalGroupByType": "All"
            },
            "aggregatedTotals": [
                {
                    "employee": {
                        "id": 309,
                        "qualifier": "20000",
                        "name": "20000"
                    },
                    "location": {
                        "id": 440,
                        "qualifier": "Organization/Metropolitan Hospital/Clin Op/WMNB/Labor/Nurse",
                        "name": "Organization/Metropolitan Hospital/Clin Op/WMNB/Labor/Nurse"
                    },
                    "job": {
                        "id": 440,
                        "qualifier": "RN",
                        "name": "RN"
                    },
                    "payCode": {
                        "id": 320,
                        "qualifier": "Regular",
                        "name": "Regular"
                    },
                    "amount": 0.05,
                    "wages": 0,
                    "jobTransfer": false,
                    "laborCategoryTransfer": false,
                    "timeItemType": {}
                },
                {
                    "employee": {
                        "id": 309,
                        "qualifier": "20000",
                        "name": "20000"
                    },
                    "location": {
                        "id": 440,
                        "qualifier": "Organization/Metropolitan Hospital/Clin Op/WMNB/Labor/Nurse",
                        "name": "Organization/Metropolitan Hospital/Clin Op/WMNB/Labor/Nurse"
                    },
                    "job": {
                        "id": 440,
                        "qualifier": "RN",
                        "name": "RN"
                    },
                    "payCode": {
                        "id": 2000000010,
                        "qualifier": "Actual combined hours",
                        "name": "Actual combined hours"
                    },
                    "amount": 0.05,
                    "wages": 0,
                    "jobTransfer": false,
                    "laborCategoryTransfer": false,
                    "timeItemType": {}
                },
                {
                    "employee": {
                        "id": 309,
                        "qualifier": "20000",
                        "name": "20000"
                    },
                    "location": {
                        "id": 440,
                        "qualifier": "Organization/Metropolitan Hospital/Clin Op/WMNB/Labor/Nurse",
                        "name": "Organization/Metropolitan Hospital/Clin Op/WMNB/Labor/Nurse"
                    },
                    "job": {
                        "id": 440,
                        "qualifier": "RN",
                        "name": "RN"
                    },
                    "payCode": {
                        "id": 677,
                        "qualifier": "All Regular",
                        "name": "All Regular"
                    },
                    "amount": 0.05,
                    "wages": 0,
                    "jobTransfer": false,
                    "laborCategoryTransfer": false,
                    "timeItemType": {}
                },
                {
                    "employee": {
                        "id": 309,
                        "qualifier": "20000",
                        "name": "20000"
                    },
                    "location": {
                        "id": 440,
                        "qualifier": "Organization/Metropolitan Hospital/Clin Op/WMNB/Labor/Nurse",
                        "name": "Organization/Metropolitan Hospital/Clin Op/WMNB/Labor/Nurse"
                    },
                    "job": {
                        "id": 440,
                        "qualifier": "RN",
                        "name": "RN"
                    },
                    "payCode": {
                        "id": 809,
                        "qualifier": "Total Hours Worked Retail",
                        "name": "Total Hours Worked Retail"
                    },
                    "amount": 0.05,
                    "wages": 0,
                    "jobTransfer": false,
                    "laborCategoryTransfer": false,
                    "timeItemType": {}
                },
                {
                    "employee": {
                        "id": 309,
                        "qualifier": "20000",
                        "name": "20000"
                    },
                    "location": {
                        "id": 440,
                        "qualifier": "Organization/Metropolitan Hospital/Clin Op/WMNB/Labor/Nurse",
                        "name": "Organization/Metropolitan Hospital/Clin Op/WMNB/Labor/Nurse"
                    },
                    "job": {
                        "id": 440,
                        "qualifier": "RN",
                        "name": "RN"
                    },
                    "payCode": {
                        "id": 2000000013,
                        "qualifier": "Scheduled combined hours",
                        "name": "Scheduled combined hours"
                    },
                    "amount": 0.05,
                    "wages": 0,
                    "jobTransfer": false,
                    "laborCategoryTransfer": false,
                    "timeItemType": {}
                }
            ]
        }
    ],
    "dailyTotalSummary": [
        {
            "employee": {
                "id": 309,
                "qualifier": "20000",
                "name": "20000"
            },
            "applyDate": "2017-11-08",
            "cumulativeTotal": 180,
            "dailyTotalAmount": {
                "HOUR": 180
            },
            "hoursAndCostSummaries": {
                "HOUR": [
                    {
                        "id": 30401,
                        "durationInHours": 0.05,
                        "wages": 1.65,
                        "durationInDays": 0,
                        "timeItemId": 30401,
                        "amountType": "HOUR",
                        "employee": {
                            "id": 309,
                            "qualifier": "20000",
                            "name": "20000"
                        },
                        "applyDate": "2017-11-08",
                        "fromShift": true,
                        "totalType": "HOURSANDCOST"
                    }
                ]
            }
        },
        ...
    ],
    "itemTotals": [
        {
            "employee": {
                "id": 309,
                "qualifier": "20000",
                "name": "20000"
            },
            "itemId": 30401,
            "startApplyDate": "2017-11-08",
            "endApplyDate": "2017-11-08",
            "itemHours": 180
        },
        ...
    ]
}

Remove an employee's punches

The manager calls the Update Timecard as Manager operation using the POST HTTP method to remove an employee's punch.

  1. POST a request to the following URL: https://<<hostName>>/api/v1/timekeeping/timecard
  2. Include the standard Headers.
  3. Include an appropriate JSON call body. Refer to the examples below.

When constructing the JSON body of your request, keep the following points in mind:

  • Use the punches/removed array
    • In the array, provide the employee ID, punch ID, and the new punch date and time for each punch you want to remove
  • The operation requires an employee ID with start and end dates and times or a symbolic period
  • Set the property onlyValidate to false, or the punch is not saved

Example request

{
  "where": {
    "employee": {
      "id": 309
    },
    "dateRange": {
      "startDate": "2017-11-06T00:00",
      "EndDate": "2017-11-12T00:00"
    }
  },
  "do":
  {
  "punches": {
    "removed": [
      {
        "id": 7051,
        "employee": {
          "id": 309
        },
        "punchDtm": "2017-11-08T10:05:00"
      }
    ]
  },
    "onlyValidate": false
  }
}

Example response

{
    "lastUpdates": [
        {
            "employeeId": 309,
            "updateDateTime": "2018-02-08T02:52:24",
            "updateByPersonFullName": "Ivan, Sean",
            "isEditedInSignedOff": false
        }
    ],
    "projects": [],
    "overtimeApprovals": [
        {
            "existingApprovalsOrDenials": [],
            "unapprovedSegments": [],
            "unapprovedAmount": 0,
            "deniedAmount": 0
        }
    ],
    "punches": [
        {
            "id": 6001,
            "employee": {
                "id": 309,
                "qualifier": "20000",
                "name": "20000"
            },
            "punchDtm": "2017-11-08T10:02:00",
            "timeZone": {
                "id": 134110,
                "qualifier": "(GMT -05:00) Eastern Time (USA; Canada)",
                "name": "(GMT -05:00) Eastern Time (USA; Canada)"
            },
            "enteredOnDtm": "2018-02-08T02:52:24",
            "editByType": {
                "id": -2
            },
            "dataSource": {
                "id": 3275,
                "qualifier": "Ivan, Sean",
                "name": "Ivan, Sean"
            },
            "exceptions": [
                {
                    "employee": {
                        "id": 309,
                        "qualifier": "20000",
                        "name": "20000"
                    },
                    "startDateTime": "2017-11-08T10:02:00",
                    "endDateTime": "2017-11-08T10:02:00",
                    "applyDate": "2017-11-08",
                    "id": 26456,
                    "endTimeZone": {
                        "id": 134110
                    },
                    "exceptionType": {
                        "id": 17,
                        "name": "UNSCHEDULED",
                        "description": "UNSCHEDULED_DSC",
                        "displayName": "Unscheduled",
                        "category": "SHIFT_EXCEPTIONS"
                    },
                    "orgJob": {
                        "id": 440
                    },
                    "overLimitInHours": 0,
                    "startTimeZone": {
                        "id": 134110
                    },
                    "violationInHours": 0,
                    "workRule": {
                        "id": 17,
                        "qualifier": "Full Time",
                        "name": "Full Time"
                    },
                    "commentsNotes": [],
                    "punchEvent": {
                        "id": 30401
                    },
                    "isExcusedAbsence": false,
                    "isUnExcusedAbsence": false,
                    "reviewed": false,
                    "transfer": false,
                    "eventDate": "2017-11-08",
                    "startException": true,
                    "endException": false
                }
            ],
            "commentsNotes": [],
            "isPhantom": false,
            "isScheduled": false,
            "updatedOnDtm": "2018-02-08T02:52:24",
            "exceptionResolved": false,
            "editable": true
        }
    ],
    "workedShifts": [
        {
            "id": 30401,
            "employee": {
                "id": 309
            },
            "startDateTime": "2017-11-08T10:02:00",
            "endDateTime": "2017-11-08T10:02:00",
            "startTimezone": {
                "id": 134110
            },
            "endTimezone": {
                "id": 134110
            },
            "roundedStartDateTime": "2017-11-08T10:02:00",
            "roundedEndDateTime": "2017-11-08T10:02:00",
            "roundedStartTimezone": {
                "id": 134110
            },
            "roundedEndTimezone": {
                "id": 134110
            },
            "unscheduledStartDateTime": "2017-11-08T10:02:00",
            "unscheduledEndDateTime": "2017-11-08T18:02:00",
            "unscheduledWorkRule": {
                "id": 17
            },
            "inProgress": false,
            "workedSpans": [
                {
                    "id": 30401,
                    "startDateTime": "2017-11-08T10:02:00",
                    "endDateTime": "2017-11-08T10:02:00",
                    "startTimezone": {
                        "id": 134110
                    },
                    "endTimezone": {
                        "id": 134110
                    },
                    "primaryOrgJob": {
                        "id": 440
                    },
                    "workRule": {
                        "id": 17
                    },
                    "primaryWorkRule": {
                        "id": 440
                    },
                    "orderNumber": 1,
                    "startPunch": {
                        "id": 6001,
                        "employee": {
                            "id": 309,
                            "qualifier": "20000",
                            "name": "20000"
                        },
                        "punchDtm": "2017-11-08T10:02:00",
                        "timeZone": {
                            "id": 134110,
                            "qualifier": "(GMT -05:00) Eastern Time (USA; Canada)",
                            "name": "(GMT -05:00) Eastern Time (USA; Canada)"
                        },
                        "enteredOnDtm": "2018-02-08T02:52:24",
                        "editByType": {
                            "id": -2
                        },
                        "dataSource": {
                            "id": 3275,
                            "qualifier": "Ivan, Sean",
                            "name": "Ivan, Sean"
                        },
                        "exceptions": [
                            {
                                "employee": {
                                    "id": 309,
                                    "qualifier": "20000",
                                    "name": "20000"
                                },
                                "startDateTime": "2017-11-08T10:02:00",
                                "endDateTime": "2017-11-08T10:02:00",
                                "applyDate": "2017-11-08",
                                "id": 26456,
                                "endTimeZone": {
                                    "id": 134110
                                },
                                "exceptionType": {
                                    "id": 17,
                                    "name": "UNSCHEDULED",
                                    "description": "UNSCHEDULED_DSC",
                                    "displayName": "Unscheduled",
                                    "category": "SHIFT_EXCEPTIONS"
                                },
                                "orgJob": {
                                    "id": 440
                                },
                                "overLimitInHours": 0,
                                "startTimeZone": {
                                    "id": 134110
                                },
                                "violationInHours": 0,
                                "workRule": {
                                    "id": 17,
                                    "qualifier": "Full Time",
                                    "name": "Full Time"
                                },
                                "commentsNotes": [],
                                "punchEvent": {
                                    "id": 30401
                                },
                                "isExcusedAbsence": false,
                                "isUnExcusedAbsence": false,
                                "reviewed": false,
                                "transfer": false,
                                "eventDate": "2017-11-08",
                                "startException": true,
                                "endException": false
                            }
                        ],
                        "commentsNotes": [],
                        "isPhantom": false,
                        "isScheduled": false,
                        "updatedOnDtm": "2018-02-08T02:52:24",
                        "exceptionResolved": false,
                        "editable": true
                    },
                    "endPunch": {
                        "employee": {
                            "id": 309,
                            "qualifier": "20000",
                            "name": "20000"
                        },
                        "workRule": {
                            "id": 17,
                            "qualifier": "Full Time",
                            "name": "Full Time"
                        },
                        "typeOverride": {
                            "id": 4,
                            "qualifier": "Out Punch",
                            "typeOverrideId": 4,
                            "description": "Out Punch",
                            "name": "Out Punch"
                        },
                        "exceptions": [
                            {
                                "employee": {
                                    "id": 309,
                                    "qualifier": "20000",
                                    "name": "20000"
                                },
                                "startDateTime": "2017-11-08T10:02:00",
                                "endDateTime": "2017-11-08T18:02:00",
                                "applyDate": "2017-11-08",
                                "id": -14,
                                "exceptionType": {
                                    "id": 16,
                                    "name": "MISSED_OUT_PUNCH",
                                    "description": "MISSED_OUT_PUNCH_DSC",
                                    "displayName": "Missed Out Punch",
                                    "category": "OUT_PUNCH_EXCEPTIONS"
                                },
                                "orgJob": {
                                    "id": 440
                                },
                                "overLimitInHours": 0,
                                "startTimeZone": {
                                    "id": 134110
                                },
                                "violationInHours": 0,
                                "workRule": {
                                    "id": 17,
                                    "qualifier": "Full Time",
                                    "name": "Full Time"
                                },
                                "commentsNotes": [],
                                "punchEvent": {
                                    "id": 30401
                                },
                                "isExcusedAbsence": false,
                                "isUnExcusedAbsence": false,
                                "reviewed": false,
                                "transfer": false,
                                "eventDate": "2017-11-08",
                                "startException": false,
                                "endException": true
                            }
                        ],
                        "commentsNotes": [],
                        "isPhantom": true,
                        "isScheduled": false,
                        "exceptionResolved": false,
                        "editable": true
                    },
                    "scheduledOrgJob": false,
                    "scheduledWorkRule": false,
                    "userEnteredOrgJob": false,
                    "transferOrgJob": false,
                    "userEnteredWorkRule": false,
                    "transferWorkRule": false,
                    "projected": false
                }
            ],
            "shiftTotalHours": 0,
            "scheduledShiftIds": [],
            "projected": false,
            "fromSchedule": false
        }
    ],
    "hoursWorked": [],
    "payCodeEdits": [],
    "historicalCorrections": [],
    "workHolidayCredits": [],
    "exceptions": [
        {
            "employee": {
                "id": 309,
                "qualifier": "20000",
                "name": "20000"
            },
            "startDateTime": "2017-11-08T10:02:00",
            "endDateTime": "2017-11-08T10:02:00",
            "applyDate": "2017-11-08",
            "id": 26456,
            "endTimeZone": {
                "id": 134110
            },
            "exceptionType": {
                "id": 17,
                "name": "UNSCHEDULED",
                "description": "UNSCHEDULED_DSC",
                "displayName": "Unscheduled",
                "category": "SHIFT_EXCEPTIONS"
            },
            "orgJob": {
                "id": 440
            },
            "overLimitInHours": 0,
            "startTimeZone": {
                "id": 134110
            },
            "violationInHours": 0,
            "workedShift": {
                "id": -12
            },
            "workRule": {
                "id": 17,
                "qualifier": "Full Time",
                "name": "Full Time"
            },
            "commentsNotes": [],
            "punchEvent": {
                "id": 30401
            },
            "isExcusedAbsence": false,
            "isUnExcusedAbsence": false,
            "reviewed": false,
            "transfer": false,
            "eventDate": "2017-11-08",
            "startException": true,
            "endException": false
        },
        ...
    ],
    "extendedExceptions": [
        {
            "employee": {
                "id": 309,
                "qualifier": "20000",
                "name": "20000"
            },
            "startDateTime": "2017-11-08T10:02:00",
            "endDateTime": "2017-11-08T10:02:00",
            "applyDate": "2017-11-08",
            "id": 26456,
            "endTimeZone": {
                "id": 134110
            },
            "exceptionType": {
                "id": 17,
                "name": "UNSCHEDULED",
                "description": "UNSCHEDULED_DSC",
                "displayName": "Unscheduled",
                "category": "SHIFT_EXCEPTIONS"
            },
            "orgJob": {
                "id": 440
            },
            "overLimitInHours": 0,
            "startTimeZone": {
                "id": 134110
            },
            "violationInHours": 0,
            "workedShift": {
                "id": -12
            },
            "workRule": {
                "id": 17,
                "qualifier": "Full Time",
                "name": "Full Time"
            },
            "commentsNotes": [],
            "punchEvent": {
                "id": 30401
            },
            "isExcusedAbsence": false,
            "isUnExcusedAbsence": false,
            "actualDateTime": "2017-11-08T10:02:00",
            "comments": "",
            "reviewed": false,
            "transfer": false,
            "eventDate": "2017-11-08",
            "startException": true,
            "endException": false
        },
        ...
    ],
    "dailyTotals": [
        {
            "id": 30401,
            "durationInHours": 0,
            "wages": 0,
            "durationInDays": 0,
            "timeItemId": 30401,
            "amountType": "HOUR",
            "employee": {
                "id": 309,
                "qualifier": "20000",
                "name": "20000"
            },
            "applyDate": "2017-11-08",
            "fromShift": true,
            "totalType": "HOURSANDCOST"
        },
        ...
    ],
    "totals": [
        {
            "employeeContext": {
                "employee": {
                    "id": 309,
                    "qualifier": "20000",
                    "name": "20000"
                },
                "timezone": {
                    "id": 13411,
                    "qualifier": "(GMT -05:00) Eastern Time (USA; Canada)",
                    "name": "(GMT -05:00) Eastern Time (USA; Canada)"
                }
            },
            "totalContext": {
                "totalType": "Actual totals",
                "totalAggregationType": "All",
                "totalGroupByType": "All"
            },
            "aggregatedTotals": []
        }
    ],
    "dailyTotalSummary": [
        {
            "employee": {
                "id": 309,
                "qualifier": "20000",
                "name": "20000"
            },
            "applyDate": "2017-11-08",
            "cumulativeTotal": 0,
            "dailyTotalAmount": {
                "HOUR": 0
            },
            "hoursAndCostSummaries": {
                "HOUR": [
                    {
                        "id": 30401,
                        "durationInHours": 0,
                        "wages": 0,
                        "durationInDays": 0,
                        "timeItemId": 30401,
                        "amountType": "HOUR",
                        "employee": {
                            "id": 309,
                            "qualifier": "20000",
                            "name": "20000"
                        },
                        "applyDate": "2017-11-08",
                        "fromShift": true,
                        "totalType": "HOURSANDCOST"
                    }
                ]
            }
        },
        ...
    ],
    "itemTotals": [
        {
            "employee": {
                "id": 309,
                "qualifier": "20000",
                "name": "20000"
            },
            "itemId": 30401,
            "startApplyDate": "2017-11-08",
            "endApplyDate": "2017-11-08",
            "itemHours": 0
        },
        ...
    ]
}