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.
  • Regular earnings: wage and salary
  • Overtime: overtime and time_off_in_lieu_overtime
  • 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
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.

​
Naming the Rate

When an employee has more than one line item of an earning type, each entry names the rate its hours are paid at. If you keep Pay Rates in Nmbr, name the employee’s Pay Rate. If you don’t, send a custom rate. When they have only one, an entry can leave the rate out, and it updates that line item whether it’s paid under a Pay Rate or a custom rate. Each earning type takes these fields: * A salary amount is calculated from the employee’s salary Pay Rate, so it can’t be paid at a custom rate. Without a Pay Rate, set custom_amount on the salary earning line item instead. leave_unpaid always pays $0, so it has no amount for a custom rate to calculate. custom_rate is the hourly rate, such as 25.00. custom_rate_multiplier multiplies it, such as 1.5, the same way an Overtime Rate multiplies its Pay Rate. See Custom Rates. An entry uses one or the other, never both. An entry that mixes them, such as custom_rate with pay_rate_id, or custom_rate_multiplier with overtime_rate_id, is rejected with a 422. An entry also only matches line items paid the same way: a pay_rate_id entry never updates a custom-rate line item, and a custom_rate entry never updates a line item with a Pay Rate. The rate is part of the matching key:
  • An entry updates the line item of its earning type at the same rate: the same pay_rate_id or overtime_rate_id, or the same custom_rate and custom_rate_multiplier. An overtime entry without a custom_rate_multiplier only matches a line item without one.
  • If no line item matches, Nmbr creates one at that rate.
  • If more than one line item matches, the request is rejected with a 422. Send an earning_line_item_id to say which one to update.

​
With Pay Rates

​
With Custom Rates

​
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 at the same rate 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.