Shift Costing API


#1

NOTE this API is currently in the testing phase. This post will be updated once the functionality is live.

There are two methods for evaluating shift costs:

  • at an employee level by passing along a set of shifts to evaluate for the specific employee
  • at an employment agreement level (this can be used without requiring an actual employee record to exist in KeyPay) by passing along some basic employee details and a set of shifts to evaluate

Shift Costing for a specific Employee

Request URL

POST /api/v2/business/{businessId}/employee/{employeeId}/timesheet/shiftcosting

Request Body

The format of the request body is the same as above but without an “Employee” section.

{
  "transactionExternalId": "AE771388BE991",
  "locationIdType": "Standard",
  "workTypeIdType": "Standard",
  "includeEvaluationResults": true,
  "shifts": [
    {
      "startTime": "2014-09-20 09:00:00",
      "endTime": "2014-09-20 17:00:00",
      "breaks": [ ],
      "externalId": "SH-99AAE91234",
      "workTypeId": null,
      "locationId": null,
      "state": "QLD",
      "employmentAgreementId": null
    },
    {
      "startTime": "2014-09-23 10:00:00",
      "endTime": "2014-09-23 16:00:00",
      "breaks": [
        {
          "startTime": "2014-09-23 13:00:00",
          "endTime": "2014-09-23 13:30:00",
        }
      ],
      "externalId": "SH-99AAE91234",
      "workTypeId": null,
      "locationId": null,
      "state": "QLD",
      "employmentAgreementId": null
    }
  ]
}

Response Body

{
  "transactionId": "AD7632C4-4A01-442F-AF20-8D50A60D70D4",
  "transactionExternalId": "AE771388BE991",
  "employmentAgreementId": 193,
  "employmentAgreementName": "Hospitality Level 4 (Casual)",
  "payConditionRuleSetId": 2187,
  "payConditionRuleSetName": "Casual Hospitality",
  "shifts": [
    {
      "externalId": "SH-99AAE91234",
      "startTime": "2014-09-20 09:00:00",
      "endTime": "2014-09-20 17:00:00",
      "cost": 132.225,
      "costBreakdown": [
        {
          "type": "Earnings",
          "payCategoryId": "9871",
          "payCategoryName": "Ordinary Hours",
          "startTime": "2014-09-20 09:00:00",
          "endTime": "2014-09-20 14:00:00",
          "units": 5,
          "rate": 17.23,
          "cost": 86.15
        },
        {
          "type": "break",
          "payCategoryId":  0,
          "payCategoryName": null,
          "startTime": "2014-09-20 14:00:00",
          "endTime": "2014-09-20 14:30:00",
          "units": 0,
          "rate": 0,
          "cost": 0
        },
        {
          "type": "Earnings",
          "payCategoryId":  "9871",
          "payCategoryName": "Ordinary Hours",
          "startTime": "2014-09-20 14:30:00",
          "endTime": "2014-09-20 17:00:00",
          "units": 2.5,
          "rate": 17.23,
          "cost": 43.075
        },
        {
          "type": "Allowance",
          "payCategoryId":  "9872",
          "payCategoryName": "Laundry Allowance",
          "startTime": null,
          "endTime": null,
          "units": 1,
          "rate": 3.00,
          "cost": 3.00
        }
      ]
    },
    {
      "externalId": "SH-99AAE91235",
      "startTime": "2014-09-23 10:00:00",
      "endTime": "2014-09-23 16:00:00",
      "cost": 94.765,
      "costBreakdown": [
        {
          "type": "Earnings",
          "payCategoryId": "9871",
          "payCategoryName": "Ordinary Hours",
          "startTime": "2014-09-23 10:00:00",
          "endTime": "2014-09-23 13:00:00",
          "units": 3,
          "rate": 17.23,
          "cost": 51.69
        },
        {
          "type": "Break",
          "payCategoryId":  0,
          "payCategoryName": null,
          "startTime": "2014-09-23 13:00:00",
          "endTime": "2014-09-23 13:30:00",
          "units": 0,
          "rate": 0,
          "cost": 0
        },
        {
          "type": "Earnings",
          "payCategoryId":  "9871",
          "payCategoryName": "Ordinary Hours",
          "startTime": "2014-09-23 13:30:00",
          "endTime": "2014-09-23 16:00:00",
          "units": 2.5,
          "rate": 17.23,
          "cost": 43.075
        },
        {
          "type": "Allowance",
          "payCategoryId":  "9872",
          "payCategoryName": "Laundry Allowance",
          "startTime": null,
          "endTime": null,
          "units": 1,
          "rate": 3.00,
          "cost": 3.00
        }
      ]
    }
  ]
}

Retrieve Shift Periods for a specific employee

Request URL

POST /api/v2/business/{businessId}/employee/{employeeId}/timesheet/shiftperiods

Request Body

{
  "firstShfitStartTime": "2014-09-20 09:00:00",
  "lastShiftStartTime": "2014-09-26 09:00:00"
}

Response Body

[
  {
    "fromDate": "2014-09-15",
    "toDate": "2014-09-21"
  },
  {
    "fromDate": "2014-09-22",
    "toDate": "2014-09-28"
  }
]

Shift Costing at an Employment Agreement Level

Request URL

POST /api/v2/business/{businessId}/employmentagreement/{id}/shiftcosting

Request Body

The format of the request is the same format as the request for costing at an employee level but with the addition of an “employee” section in the request:

{
  "transactionExternalId": "AE771388BE991",
  "locationIdType": "Standard",
  "workTypeIdType": "Standard",
  "includeEvaluationResults": true,
  "employee": {
    "dateOfBirth": "1981-07-25",
    "anniversaryDate": "2014-08-12",
    "standardHoursPerWeek": 38,
    "tags": [
      "First Aid"
    ]
  },
  "shifts": [
    ...
  ]
}

Response Body

The response is in the same format as the response for the costing API at an employee level

Retrieve Shift Periods at an Employment Agreement level

Request URL

POST /api/v2/business/{businessId}/employmentagreement/{id}/shiftperiods

Request Body

The request is in the same format as the request for the shift periods API at an employee level

Response Body

The response is in the same format as the response for the shift periods API at an employee level


#2

Thanks for the API details. Just a question, what is the status of this API, is it still under testing or is it live?


#3

hi Amiti,

The API is now live but I would consider it in beta. The API is mostly stable although there may be some minor modifications that will be coming out to support additional award features. They won’t be breaking changes though.

cheers,
Paul.


#4

Thanks for your feedback Paul!


#5

The Shift Costing at an Employment Agreement Level API works for me.

Can you tell me why this end point is not working? It always gives me an Internal Server error.
Shift Costing for a specific Employee:
POST /api/v2/business/{businessId}/employee/{employeeId}/timesheet/shiftcosting


#6

Hi Amit,

Would you mind letting us know which business / employee ID you are passing?


#7

Yes, sure. Business Id:41207, Employee Id:599454.