API Reference
Start typing to search…

Update classified hours for pay period (bulk)

post https://api.everee.com/integration/v1/labor/classified-hours/bulk

This endpoint allows you to specify the classified hours, on a per-worker 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 workers' 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 "sync" 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.

We'll automatically determine any differences and apply them correctly.

Adding and editing hours

This endpoint accepts a list of objects representing the complete status of all payable classified hours for workers. It is an explicit update action, so you control whether or not we update existing hours. If you provide hours for a worker, we will update their existing hours, and if you don't provide hours for a worker, 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 worker, that worker'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 a worker, we won't make any changes to that worker'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 workers, you will need to call this endpoint multiple times until you have provided hours for all workers with hours in the period.

Language
Credentials
Header