Skip to main content

​
Updating hours worked

The Nmbr API surfaces an endpoint that can be used to import hours for many employees at once.

​
Supported Earning Types

Any earning type that can carry a pay rate or an overtime rate accepts imported hours. Scoped by pay rate. When an employee has more than one line item of the type, send a pay_rate_id and/or an earned_on date to say which one the hours belong to.
  • Regular earnings: wage and salary
  • Vacation pay: vacation_pay, vacation_pay_employee_terminated, vacation_pay_time_taken, vacation_pay_no_time_taken
  • Time off: time_off_in_lieu
  • Unpaid leave: leave_unpaid
  • Paid leave: leave_sick, leave_sick_discretionary, leave_general, leave_personal, leave_bereavement, leave_domestic_and_sexual_violence, leave_paternity, leave_voting, leave_wedding, leave_citizenship, leave_jury_duty, leave_organ_donor, leave_parental, leave_maternity
Scoped by overtime rate. Send an overtime_rate_id or a rate_multiplier, and an earned_on date if you track hours per day.
  • overtime
  • time_off_in_lieu_overtime
Paid leave hours pay at the rate you associate them with. On an hourly pay rate that is hours times the rate. On a salary pay rate it is hours times the salary’s hourly equivalent, so reduce the salary line item’s hours by the same amount in the same request, or the period is paid twice. leave_unpaid is the exception. It records hours and always pays $0.

​
Simple Scenario

In this simple scenario, each employee has been configured with a single Pay Rate. To run payroll accurately, you will be required to update the hours for each Earning Line Item generated from the Pay Rates. To cut down on API calls, use the POST /payrolls/{payroll}/hours endpoint to import hours for multiple employees at once.

​
A More Complex Scenario

In some cases, employees may have multiple Pay Rates and Overtime Rates, resulting in many Earning Line Items. In order for the system to know which hours correspond with each Earning Line Item, the API requires you to provide either a pay_rate_id, overtime_rate_id, or rate_multiplier, depending on the type of earning.

​
Tracking Hours by Date

If you track hours per day (or any other date granularity within the payroll period), you can attach an earned_on date to each entry. This is supported on every earning type. The earned_on value:
  • Must be a date that falls within the payroll’s pay period.
  • Is part of the entry’s scoping key, so you can submit multiple entries against the same pay_rate_id (or overtime_rate_id / rate_multiplier) as long as their earned_on dates differ.

​
Targeting a Business Preset

When you import hours for distinct configured workflows that share an earning type and rate, include business_preset_id on each earning entry. The preset identifies which line item to update or create. The preset must belong to the payroll’s business entity, have the earning type, and match the entry’s earning type when the preset has a subtype.
The preset is part of the matching key. Re-send the same earning type, rate, date, and preset to update the same line item. Use a different compatible preset to keep the line items separate. Requests without business_preset_id keep their existing matching behaviour. See Presets to create and manage Business Presets.