This endpoint allows you to specify the classified hours, on a per-employee basis, for a pay period. You can provide as many or as few hours as you want in a single call (subject to size limitations, below), and we will only apply changes to employee' hours that you tell us to.

How to use this endpoint

The purpose of this endpoint is to allow you to synchronize a timesheet of hours, for many employees, at the same time. To do this simply and accurately, there are some basic implementation rules below for adding, editing, and removing hours.

📘
This is a "synchronize" operation. Here's the principle:
You should send us one or more ClassifiedHoursPerWorker objects for each employee included in the timesheet being synced to Everee, regardless of whether hours have been added, edited, or removed since the last sync. The synchronization happens on a "per-employee, per-pay period" basis.
Here's what that means.
Let's say you send us hours for an employee called Jane Appleseed for the January 3 - January 9 pay period. Then later, you send us a different set of Jane's hours for that pay period. We will remove Jane's hours already on file for that pay period and replace them with the new hours you sent us. We will not combine the previous set of hours with the new hours—you need to provide the complete set of hours for the pay period each time you send them.
Finally, if Jane was already paid for that pay period and you've authorized us to process corrections, we'll determine the difference between the old hours and the new hours, then handle the consequences automatically.

Adding and editing hours

This endpoint accepts a list of objects representing the complete status of all payable classified hours for employees. It is an explicit update action, so you control whether or not we update existing hours. If you provide hours for an employee, we will update their existing hours, and if you don't provide hours for an employee, we will do nothing, leaving any hours in place if they exist.

If a ClassifiedHoursPerWorker object is provided in the classifiedHoursPerWorker list for a given employee, that employee's hours for the pay period will be removed and replaced with the hours you provided.

Removing hours

When calling this endpoint, if you do not provide a ClassifiedHoursPerWorker object for an employee, we won't make any changes to that employee's current set of hours, because you didn't explicitly tell us to remove hours.

If you want to remove hours for an employee, you must provide ClassifiedHoursPerWorker objects with the appropriate ...HoursWorked fields set to "0.00". That explicitly instructs us to remove any hours we may have already recorded.

But what if payroll has already been run?

This endpoint supports our automated Timesheet Corrections system. We can accept changes to hours for pay periods that have already been paid-out and automatically process the resulting additional payout or future reduction of wages. You just need to authorize the change using the correction-authorized=true parameter.

👍
You should consider authorizing corrections!
If you authorize us to process corrections to paid-out periods, it creates a seamless and automated workflow for payroll admins, and eliminates the need for manual double-entry in your system and ours. This is a nice experience!

How to structure the data

Typically, you'll need to send us some combination of regular, overtime, and double-time hours. You specify these in the appropriate field: regularHoursWorked, for instance.

But notice how each ClassifiedHoursPerWorker object also has a payRate field. When using this endpoint, you're expected to provide both a pay rate exactly one of the hoursWorked fields. This allows you to provide the exact pay rate for each set of hours at each classification.

This is important because employers are required to pay overtime and double time at premium rates, and we won't calculate that premium rate automatically on your behalf, since we don't have enough information to do that.

Here are some examples of good and bad inputs:

// 👍 This is good! 👍
{
  "payRate": { "amount": "20.00", "currency": "USD" },
  "regularHoursWorked": "18.00"
}
// => 200 OK



// 👍 This is good! 👍
{
  "payRate": { "amount": "65.00", "currency": "USD" },
  "overtimeHoursWorked": "4.00"
}
// => 200 OK



// ❌ This is ambiguous and confusing. This will produce an error. ❌
{
  "payRate": { "amount": "20.00", "currency": "USD" },  
  "regularHoursWorked": "12.00",
  "overtimeHoursWorked": "2.25"
}
// => 400 Bad Request: "More than one type of hours is not allowed."

In summary: you should split regular, overtime, and double time hours into separate ClassifiedHoursPerWorker objects, to make sure you're sending us exactly the right pay rate + hours combination for each classification.

Data size limitations

This endpoint is limited to a maximum of 200 entries in the classifiedHoursPerWorker list per call. If you need to provide hours for more than 200 employees, you will need to call this endpoint multiple times until you have provided hours for all employees with hours in the period.