Sign in

KeyPay provides an API for the bulk submission of timesheets.

HTTP Methods:

  • POST will add new timesheets for the specified employees for the specified time period.
  • PUT will replace the existing timesheets for the specified employees for the specified period. That is, any existing timesheets between ‘fromDate’ and ‘todate’ for any employees contained in this request will be removed and replaced by these new ones.

Note: when submitting JSON data to the web service, an additional header is required on the HTTP request:

Content-type: application/json

Request Format:

The format of a ‘submit timesheets’ request is shown below:

{
  "fromDate": "Date",
  "toDate": "Date",
  "approved": "boolean",
  "employeeIdType": "string",
  "locationIdType": "string",
  "workTypeIdType": "string",
  "timesheets": "Dictionary"
}

Remarks:

  • employeeIdType , workTypeIdType and locationIdType : These fields can have a value of ‘Standard’ or ‘External’. Standard being the ‘natural’ ids that are assigned to the entities, while external id can be assigned in the UI (or via the API).
  • approved : If set to true, it signifies that the timesheet lines are pre-approved. Otherwise, they will must be approved via the KeyPay approval UI prior to import into a pay run.
  • The timesheets property is a dictionary of employee ID → (array of timesheets). The employee ID key is either a standard ID or an external ID (as specified above).

The schema for a single timesheet is:

{
  "startTime": "DateTime",
  "endTime": "DateTime",
  "units": "decimal",
  "rate": "decimal",
  "workTypeId": "string",
  "locationId": "string",  
  "comments": "string",
  "externalId": "string",
  "payCategoryId": "string",
  "leaveCategoryId": "string",
  "classificationId": "string",
  "breaks": [{
    "startTime": "DateTime",
    "endTime": "DateTime"
  }]
}

Remarks:

  • DateTime fields (startTime, endTime , break startTime and break endTime) should be specified in ISO-8601 format but with  no timezone information. For example, 2013-07-03T12:23:00
  • locationId is optional. And if location is not specified, the work will be allocated to the employees default location. This must be either the ‘natural’ id or the ‘external’ id as dictated by the locationIdType field above.
  • workTypeId is optional. If it is not specified, the work will be allocated to the employee’s primary pay category. This must be either the ‘natural’ id or the ‘external’ id as dictated by the workTypeIdType field above.
  • Either a payCategoryId or leaveCategoryId may be specified rather than a work type however it is not recommended – it is preferred to that you utilise a work type to link to the appropriate pay category or leave category. The ID types of the payCategoryId and leaveCategoryId  fields must be according to the workTypeIdType specified.
  • classificationId should only be specified if the classification is higher than the employee’s normal classification. It will be disregarded if it is the same or less than the employee’s normal classification. The ID type of the classificationId field must be according to the workTypeIdType specified.
  • units are required for work types that link to a unit based (or day based) pay category. They may also be specified for normal start/stop time based shifts and will take precedence over the duration that is inferred by the start/stop times.
  • rate is optional. If it is not specified, the pay rate in the employee file for the relevant type of work will be used.
  • Multiple breaks may be specified for a single shift.

Limits:

In order to maintain control over the load imposed on the system, there is a limit of100 employees that can be submitted per request.

Examples:

Submitting Timesheets

The following request contains multiple timesheets for multiple employees, one of which contains shift breaks. These timesheets are pre-approved and will not be passed through an additional approval process.

{
   'fromDate':'2013-01-01',
   'toDate':'2013-01-08',
   'approved':'true',
   'employeeIdType':'External',
   'workTypeIdType':'Standard',
   'locationIdType':'Standard',
   'timesheets':{
      'AB-132':[
         {
            'startTime':'2013-01-02T08:00:00',
            'endTime':'2013-01-02T16:00:00',
            'workTypeId':'',
            'locationId':'23',
            'comments':null,
            'breaks':[
               {
                  'startTime':'2013-01-02T12:00:00',
                  'endTime':'2013-01-02T13:00:00'
               }
            ]
         },
         {
            'startTime':'2013-01-03T07:00:00',
            'endTime':'2013-01-03T15:00:00',
            'workTypeId':'',
            'locationId':'',
            'comments':null
         }
      ],
      'AB-133':[
         {
            'startTime':'2013-01-02T08:00:00',
            'endTime':'2013-01-02T16:00:00',
            'workTypeId':'',
            'locationId':'23',
            'comments':null
         },
         {
            'startTime':'2013-01-03T07:00:00',
            'endTime':'2013-01-03T15:00:00',
            'workTypeId':'',
            'locationId':'',
            'comments':null
         }
      ]
   }
}
Deleting timesheets

The following request is used to remove the timesheets for a specific employee (the employee with an external id of ‘AB-132’) for a period of time (i.e. from 1/1/2013 to 8/1/2013)

{
   "fromDate":"2013-01-01",
   "toDate":"2013-01-08",
   "approved":"true",
   "employeeIdType":"External",
   "workTypeIdType":"Standard",
   "locationIdType":"Standard",
   "timesheets":{
      "AB-132":[
      ]
   }
}