pay_date, will automatically have all recurring earnings, allowances, reimbursements, deductions and benefits populated on its Pay Stubs.
Interacting with payrolls
You can retrieve a list of payrolls from the payroll API endpoint: RequestFiltering the payrolls list
GET /payrolls requires either a business_entity_id or a pay_schedule_id. Without one of them, the request returns a 422.
The status filter accepts one or more comma-separated values. Pass several to retrieve everything in flight in a single call:
Request
422.
To retrieve every payroll except certain statuses, use not_status with the same comma-separated form:
Request
not_status are ignored rather than rejected, so check them against the documented statuses.
Retrieving the upcoming regular draft payroll
To retrieve the upcoming regular draft payroll — the next payroll that is ready for editing — filter the payrolls index bytype=regular and status=draft, and sort by pay_date:
Request
type=regular filter returns regular payrolls only. Off-cycle and historical payrolls are excluded, so query them separately if you need them.
📘 Why not useYou can update an individual payroll line item using the API. The example below could be used to enter 10 hours for the given pay rate.next_payrolls? Thenext_payrolls=onlyfilter returns the current payroll being handled by Nmbr for each Pay Schedule — which may be anapproved,processing, orfailedpayroll, not necessarily one that is ready for editing. Filtering bytype=regular&status=draftand sorting bypay_dateensures you always get the next editable regular payroll.
Approving payroll
When a payroll is approved (via the/payrolls/<payroll_id>/approve endpoint), its status changes to approved. Once approved, the payroll can no longer be modified. This is because the taxes, net pay, and benefits have been calculated and saved for the payroll.
📘 Rejected Approvals If a payroll is in an invalid state when theOnce a payroll is approved, Nmbr will automatically collect funds from the employer’s bank account, make sure wages are transferred into employees’ bank accounts on payday, and remit tax payments on time. We handle all of this behind the scenes, but you will still want to keep tabs on your payroll as it moves through each phase of its lifecycle. Nmbr surfaces status information on the payroll objects returned by our API through the status field. A payroll can have one of five statuses: draft, approved, processing, paid, and failed. Below is an overview of these statuses, what they mean, and how payrolls transition between them./approveendpoint is called, the approval will fail, returning a422 Unprocessable Entityresponse. Common reasons for failure include:
- The payroll is past its approval date.
- A pay stub has a negative net amount.
- The payroll is not in the
draftstatus.
📘 Payroll status webhooks When a payroll makes status transitions from approved to processing and from processing to paid, you can receive webhook notifications from our platform. See the webhook documentation for more details about how to set this up.
Payroll Status Lifecycle
draft
When a payroll is first created, it will be in the draft status. You can modify a draft payroll in any way you see fit. Payments to employees can be added and removed, earnings and hours worked can be modified on individual payroll items, etc. You can only delete a payroll while it’s in draft.approved
When a payroll is approved (via the/payrolls/<payroll_id>/approve endpoint), its status changes to approved. Once approved, the payroll can no longer be modified. This is because the taxes, net pay, and benefits have been calculated and saved for the payroll.
If you determine that an error exists in the payroll, you can move it back to the draft status (via the /payrolls/<payroll_id>/unapprove endpoint). Once back in draft, the payroll can again be modified, previewed, and even deleted. If and when it is approved again, the payroll moves back into the approved status.
processing
At the end of each business day at 5pm PT, our system collects all pending payrolls that have an approval deadline on that day and begins the multi-step process of moving money through the banking system to pay them out. The first step in this process is to submit an ACH transaction to debit the cash requirement for a payroll from the employer’s bank account. When a payroll’s debit transaction has been sent to the ACH network, it moves into a new status: processing. Once a payroll is processing, it can no longer be moved back to draft. If you require a change to a processing payroll, reach out to us directly.paid
Due to the nature of the ACH network, the employer debit transaction will take 3 business days to complete. For example, if you approve a payroll with a Friday payday on Monday, we should have the employer’s funds in our bank account by Thursday morning. Once Nmbr has the employer’s cash requirement, we submit ACH transactions to send net pay to each employee who is set up for direct deposit. When these transactions complete, the payroll enters its final status: paid. Once here, the employees’ payments for your payroll have been sent out . The employees are happy, and employers can focus on their business!partially_paid
Deprecated. No payroll reaches this status today, and you should not filter on it. It remains a valid value only for backwards compatibility. When an ACH payment to an employee or a contractor is returned (most often from an invalid account or routing number, or a frozen bank account), Nmbr marks that individual payment as failed and leaves the parent payroll inprocessing. There is no payroll-level “partially paid” signal. To find failures, check the child payment records for a failed status, then reach out to us directly to resolve one.