⏰ Start here! Guide to the Timesheets API

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 [email protected] 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 [email protected] 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.

Work locations 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' Comp class codes

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 [email protected] 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 [email protected] 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 [email protected].

💵 Pay rate

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 a shift is missed or entered incorrectly in Everee, you can add, edit, or delete it until the date of the shift is paid-out, at which point the date is marked as "paid". At this point, you can no longer delete shifts on that date, but you can still correct a worker's timesheet by adding missing shifts or editing paid shifts that were entered wrong.

Adding or editing shifts on a paid-out date is called a timesheet correction.

👍

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 of three approaches you want to use, based on the correctionPaymentTimeframe field in those API endpoints:

1. NEXT_PAYROLL_PAYMENT: we include the underpaid amount on the worker's next payroll payment.
2. IMMEDIATELY: we create a one-time payment to pay out the underpaid amount ASAP, off-cycle from payroll.
3. EXTERNALLY_PAID: we record that you have processed the underpaid amount via check or some other method. The amount will appear in the worker's gross wages, but it will not be paid-out via Everee.

📘

Choosing an approach for underpayments

You should choose a "timeframe" approach for underpayments that aligns with your company policy and local regulation. We recommend choosing one approach and sticking to it whenever possible: this makes it easier to set expectations and communicate about resolving the timesheet error.

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).