The Timesheets API is how you record and pay out the earnings that hourly W-2 employees earn on the clock. Hours on a worker's timesheet are recorded either as "shifts" or as "pay period hours", and we process hours for payout on employees' regular payroll cycles. To pay contractors, see the Payables API.

We automatically handle the whole process of converting timeclock punch times, and pre-classified pay period hours, into accurate gross wages. This includes overtime classification, multiple pay rates, multiple work locations, tax jurisdiction determination, automated corrections when errors occur, and more, depending on what data you provide and the setup of an Everee instance.

We support a variety of features and configurations in this API. They're all documented below and in the API endpoints in this section of the documentation. Just let us know at support@everee.com if you need any help.

⌚️ Work period, breaks, and pay stub compliance

The Timesheets API supports two different ways to send us timesheet hours for payroll: shift hours and pay period hours.

A “shift” refers to a whole continuous work period. It could be worked straight through, or there could be break hours in between. If an employee works a period in two parts, like one part before a lunch break and another part after, the lunch break can be specified within the shift's overall period. If this is the kind of data you can provide, you'll send it to us with the Create a shift API endpoint.

You can also provide pre-classified hours for an entire pay period, rather than individual shifts. You'll provide the hours classified into chunks of regular, over-, and double-time, split up by where the shift was worked, its Workers' Comp class code, and any other factors that are meaningful to you. If this is the kind of data you can provide, you'll use the Update classified hours for pay period API endpoint.

Regardless of whether you provide shift hours or pay period hours, the features and requirements outlined below are the same. The critical difference is that when you provide shift hours, Everee is able to display the details of shifts worked by employees on their pay stubs. This is an important labor law compliance requirement in some locations, like the state of California.

📘
Send us break hours if you can
In the example above, where an employee takes a lunch break in the middle of their shift, it's better (and safer!) to record the lunch break as an unpaid break in Everee, rather than recording two separate shifts, one before lunch and one after.
Recording real break times, coded to the correct break type, creates a more accurate audit trail, allows us to display the employee's actual break time on their pay stub, and satisfies legal compliance requirements in many localities. However, you're currently only able to record breaks in Everee if you provide data on a shift-by-shift basis, not if you're providing pre-classified hours for pay periods.

We automatically provide a default break type for unpaid breaks. The default segmentConfigCode value for this break type is "DEFAULT_UNPAID". We support both paid and unpaid breaks, and we can configure additional break types for paid or unpaid breaks upon request. You can have as many break types as you need.

You can create break periods within shifts by populating the createBreaks field in the shift parameters.

We automatically update our pay stubs to comply as state labor law changes. Everee's pay stub is compliant with labor law in all 50 states. Just let us know at support@everee.com if you have any questions or need a sample pay stub to reference as part of your implementation.

📍 Work locations

When workers could be staffed at different work locations from shift to shift, it's critical to assign the correct work location for each shift or chunk of pay period hours to ensure the correct tax liability is determined for each location where work is performed. Providing a value for the parameter workLocationId assigns timesheet hours to a specific work location for tax purposes. You'll use that parameter for both shift hours and pay period hours: no matter which approach you use to send us timesheet hours, it's likely you'll want to use this parameter.

📘
Working from home
If you need to pay staff who work "on location" (at client facilities, for instance) and also from home, you should specify the parameter workLocationId for the "on location" hours to attribute them accurately, and leave it blank for the at-home hours.
If you leave the workLocationId parameter blank on some hours, Everee will apply the worker's home address (or other default work location) from their Everee payroll profile as the taxable work location for those hours.

Work location records must be created before you can assign shifts to them. There are no restrictions on how many work locations you can create. See the Work Locations API for more information about creating work locations.

⚠️
Are you in the staffing industry? This is an integration requirement
While there are cases in the staffing industry where employees work permanently or semi-permanently at the same location, it's generally a requirement when integrating with Everee to create work locations and assign shifts to them appropriately. Failing to manage work locations accurately will lead to serious tax consequences, so you should plan to include this in your integration.

If no value is provided, the work location assigned to the worker's profile is used by default.

When a work location is assigned to hours, gross wages for those hours are subject to all employee– and employer–side taxes in effect for that location on the date the hours were worked. These taxes are automatically applied to the payment that pays out wages for those hours, typically in the next payroll batch.

If an employee's payroll payment holds multiple shifts or chunks of pay period hours, each with different work locations, we automatically determine all appropriate taxes for each work location, and apply them all appropriately when calculating gross-to-net.

🧾 Workers' Compensation

When workers could be staffed in different job roles from shift to shift, it's critical to assign the correct Workers' Comp class code for each shift to ensure the right amount of Workers' Comp expense is calculated. Just provide a value for the parameter workersCompClassCode to assign a shift to a specific Workers' Comp class, and Everee will automatically determine the expense when payroll is run.

⚠️
Are you in the staffing industry? This is an integration requirement
It's extremely common in the staffing industry for employers to be legally mandated to pay Workers' Comp insurance. In order to calculate and reconcile the premium accurately, the correct Workers' Comp class codes must be assigned in payroll. The most effective way is to send it to us alongside other timesheet details like pay rate and work location. That way everything is calculated and tracked together.
If it's not feasible for you to send us Workers' Comp class codes alongside timesheet hours, you'll need another strategy to make sure the correct class codes are assigned in payroll. Contact support@everee.com for help.

The value of workersCompClassCode is the class code itself, not the name of the class or any other details. In many cases, Workers' Comp rate statements include lines like this:

State       Rate          Class Details
CA          1.880000      3028 - Pipe Or Tube Manufacturing
CA          3.170000      4299 - Printing

In this example, the class codes are 3028 and 4299. These are the values you should provide for the workersCompClassCode parameter. Note that when we're matching a class code you've provided to the details of the Workers' Comp class in Everee, we look it up by the state in which the shift was worked. If we can't find a class with that code in the correct state, we'll return an error letting you know. See below for the error details.

These Workers' Comp classes (and their codes!) are entered in the Everee admin portal under the Organization section as part of company onboarding, and updated each year during coverage renewal.

🏋️‍♀️ Overtime classification

By default, we will automatically classify all shifts for overtime and double time in compliance with federal and state law, in all 50 states.

We support the FLSA overtime rule and rules for the states that have additional overtime rules. We apply overtime rules based on a worker's legal work location as specified on their profile. We also support custom overtime classification rules, and the rules can be different for each state. Let us know at support@everee.com if you need help configuring special overtime rules.

We also support an alternative approach called Fully-Classified Shifts. When this is enabled, we allow API-integrated clients to provide the complete classification of hours for each shift, and we'll use that classification directly when calculating payroll. This bypasses our built-in automatic shift hours classification entirely.

To use Fully Classified Shifts, you'll provide the fully-classified hours in the fullyClassifiedHours field in the shift create & update parameters. This feature can be enabled upon request: just let us know at support@everee.com.

💵 Pay rates

You can set a shift-specific pay rate using the field effectiveHourlyPayRate. This is the regular rate at which the shift should be paid.

If a shift's regular rate is $20, you should pass 20.00 for its effectiveHourlyPayRate. We'll calculate regular hours at $20/hr, overtime hours at $30/hr, and double-time hours at $40/hr (unless any special overtime rules apply). These calculated rates are used to determine the gross wages for a shift.

If you don't set a shift-specific pay rate, we'll use the hourly pay rate on the worker's profile as a fallback.

⚠️
Are you in the staffing industry? This is an integration requirement
It's nearly universal in the staffing industry for pay & bill rates to be different per client, per job, per placement, or based on many other factors. As a result, while Everee does support a fallback pay rate, it's unusual to want that. Instead, you should provide the correct pay rate for all hours provided to Everee. Both shift hours and pay period hours support custom pay rates at a granular level, and this is a critical data field to provide when integrating with the Timesheets API.

You can optionally set a "display pay rate" for each shift as well. This is the rate that we'll display on the worker's pay stub, but is not used to calculate gross wages for a shift—it's for display only. This field is useful in cases where you need to adjust the effectiveHourlyPayRate based on business policy or regulations.

For example, if you need to calculate a weighted-average pay rate, you should set the calculated average rate using effectiveHourlyPayRate (i.e. $21.23) and set the quoted rate for the shift (i.e. $20.00) using displayHourlyPayRate. We'll calculate gross wages using $21.23/hr, but display $20.00/hr on the pay stub.

✂️ Correcting timesheet errors

When timesheet hours are missed or entered incorrectly in Everee, you can add, edit, or delete them freely until their pay period is paid out. When payroll is approved and finalized, the pay period is marked as "paid" and its timesheet hours are locked.

At this point, it's no longer possible to directly change the timesheet hours for that pay period, because those hours were used to transact a payment to a worker and must be preserved permanently.

However, the reality is that errors and changes can arise after a worker is paid out. When this happens, you can create what we call a "timesheet correction": a change to an otherwise "paid" (locked) timesheet.

Everee can automatically handle the consequences of changing "paid" timesheets. Keep reading for the details.

👍
Timesheet corrections are opt-in
Processing corrections via your API integration is easy, but corrections are historical adjustments to workers' pay. As a result, corrections are only permitted when you opt into them by passing the query parameter correction-authorized=true to endpoints in the Timesheets API.
This prevents any unintentional corrections from being created. Without passing that parameter, you could drive a day-to-day Timesheets integration that doesn't include correction scenarios, and use a manual workflow to process corrections in the Everee portal as needed.

You can process corrections using the same "shift hours" and "pay period hours" endpoints in the Timesheets API as you use to send us hours in the first place—there are no separate APIs for this. We automatically determine the difference between what was paid out for that date already (based on the existing timesheet) and what should have been paid (based on any new or changed hours you provide).

The difference results in either an overpayment or underpayment scenario.

When an overpayment has occurred, we automatically record a payroll deduction on the worker's profile that will withhold the overpaid amount from their next payroll payment. This deduction is visible on the Job tab of the worker's profile in the Everee portal, under Benefits & Deductions.

When an underpayment has occurred, the worker needs to be paid the missing amount. You can tell us which approach you want to use, based on the correctionPaymentTimeframe field in those API endpoints:

NEXT_PAYROLL_PAYMENT: we include the underpaid amount on the worker's next payroll payment. Default.
IMMEDIATELY: we create a payment to transact the underpaid amount immediately, off-cycle from payroll.

📘
Choosing an approach for underpayments
You should choose a "timeframe" approach for underpayments that aligns with your company policy and legal regulations. We recommend choosing one approach and sticking to it whenever possible: this makes it easier to set expectations with workers and communicate how timesheet errors are resolved.
You can specify which approach you want to use by including the correctionPaymentTimeframe field when you add or update timesheet hours.
This field is only meaningful when a correction is an underpayment, because there's money to be paid out. If a correction is an overpayment, this field has no effect: you can still provide it, but it won't do anything since nothing will be paid out.
The default setting is NEXT_PAYROLL_PAYMENT. If you leave that field blank, we'll include the underpaid amount on the worker's next payroll payment.

Regardless of which underpayment approach you choose, the corrected hours will appear on the worker's pay stub marked as a "Prior Period Correction", so they can clearly see the difference between how they were originally paid and their corrected pay. That way, there's no confusion about what happened, even if the worker goes back to older pay stubs to review.

❗ Error codes

These error codes are specific to endpoints in the Timesheets API that make changes to workers' timesheets, including Create a shift on an employee’s timesheet and Update classified hours for pay period (bulk).

Error	Cause	HTTP Code
Resource Not Found	The referenced worker, work location, workers' comp class, or break config code is not found. (see specific message for details)	404
Invalid Request	A required parameter field is missing or its format is invalid. Check the documentation.	400
Employee Not Active	The referenced employee is not active on the date of the shift. Can occur if you attempt to create a shift for a date after the employee's recorded termination date.	400
Employee Is Not Hourly	The referenced employee is not paid on an hourly basis. Can occur if you attempt to create a shift for a salaried employee.	400
Already Finalized Payments	The timesheet (i.e. a week) containing the shift is locked because it was already paid out in payroll, and corrections have not been explicitly authorized with the `correction-authorized` parameter.	400
Shift Exists In The Future	The shift's start or end times are located in the future.	400
Negative Duration	The shift has a negative duration. This usually occurs because its start and end times have been accidentally swapped.	400
Minimum Duration Not Met	The shift is shorter than the required minimum length of 1 minute.	400
Overlapping Break Segments	The shift's breaks overlap with each other. Breaks must be non-overlapping periods of time.	400
Break Segments Are Escaping	The shift's breaks are not fully contained by the start & end times of the shift. Breaks can only occur during the on-the-clock time for the shift. If you need to record unpaid break time, Everee can set up a unpaid break code for you.	400
Overlapping Classified Hours	The shift's fully-classified hours overlap with each other. Fully-classified hours must be non-overlapping periods of time.	400
Classified Hours Are Escaping	The shift's fully-classified hours are not fully contained by the start & end times of the shift. Classified hours can only cover the on-the-clock time of the shift.	400
Punch Change Too Large	The change being made to the shift's start or end times is greater than the maximum of 48 hours. If you need to move a shift's start or end time more than 48 hours forward or backward, you should instead delete the shift and create a new one with the correct start and end times.	400
Tax Calculation Config Can't Be Changed	The tax calculation configuration specified on these hours can no longer be changed because it was already applied when paying-out the hours to the worker. The field `taxCalculationConfigCode` cannot be changed when sending us corrected hours.	400