Skip to main content
[Nmbr] will automatically generate payrolls and pay stubs for configured pay schedules and employment profiles. The next payroll in the pay schedule, ordered by 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: Request 
curl --request GET \
     --url https://sandbox.nmbr.co/services/payroll/payrolls \
     --header 'Authorization: Bearer <access_token>' \
     --header 'accept: application/json'
You can retrieve an individual payroll by querying for a specific ID: Request 
curl --request GET \
     --url https://sandbox.nmbr.co/services/payroll/payrolls/:payroll_id \
     --header 'Authorization: Bearer <access_token>' \
     --header 'accept: application/json'
Response 
{
  "id": "01hfvzcp9c5phwfjkcra40rsg4",
  "object": "payroll",
  "data": {
    "type": "regular",
    "period_start": "2023-01-01T00:00:00.000000Z",
    "period_end": "2023-01-15T00:00:00.000000Z",
    "pay_date": "2023-01-13T00:00:00.000000Z",
    "employee_summary": {
      "gross": "1161.54",
      "deductions": null,
      "reimbursements": null,
      "net": "712.31"
    },
    "contractor_summary": {
      "gross": "100.00",
      "reimbursements": "15.00",
      "net": "115.00"
    },
    "company_summary": {
      "taxes_and_contributions": "73.56",
      "benefits": "50.00",
      "total": "123.56"
    },
    "liability": "1150.10",
    "cash_requirement": "1150.10",
    "status": "draft",
    "approved_at": null,
    "created_at": "2023-11-22T16:56:38.000000Z",
    "updated_at": "2023-11-22T16:56:38.000000Z"
  },
  "links": {
    "self": "https://sandbox.nmbr.co/services/payroll/payrolls/01hfvzcp9c5phwfjkcra40rsg4"
  }
}
In order to interact with employees earnings and deductions for a given pay period, you will need to retrieve a list of Pay Stubs for a given payroll. Query the pay stub API endpoint to retrieve a list of pay stubs for a specific payroll id: Request 
curl --request GET \
     --url 'https://sandbox.nmbr.co/services/payroll/pay_stubs?payroll_id=:payroll_id' \
     --header 'Authorization: Bearer <access_token>' \
     --header 'accept: application/json' \
Response 
{
  "id": "01hfwg2784vc1408yhmjp4x81q",
  "object": "pay_stub",
  "data": {
    "has_taxes_calculated": true,
    "employee_gross": "2520",
    "employee_subtractions": "574.91",
    "employee_reimbursements": "10",
    "employee_net": "1815.09",
    "earning_line_items": {
      "object": "list",
      "data": [
        {
          "id": "01hfwg27gtha4m82def3y3spz4",
          "object": "earning_line_item",
          "data": {
            "amount": 2500,
            "line_item_type": "earning",
            "earning": {
              "earning_type": "salary",
              "hours": null,
              "accrued_vacation_pay": null
            },
            "created_at": "2023-11-22T21:48:01.000000Z",
            "updated_at": "2023-11-22T21:48:01.000000Z"
          }
        }
      ]
    },
    "statutory_withholding_line_items": {
      "object": "list",
      "data": [
        {
          "id": "01hfye1vw8wqg7a4x4nwrfmt17",
          "object": "statutory_withholding_line_item",
          "data": {
            "line_item_type": "statutory_withholding",
            "amount": 134.6,
            "statutory_withholding": {
              "statutory_withholding_type": "provincial_income_tax",
              "hours": null
            },
            "created_at": "2023-11-23T15:51:21.000000Z",
            "updated_at": "2023-11-23T15:51:21.000000Z"
          }
        }
      ]
    },
    "allowance_line_items": {
      "object": "list",
      "data": [
        {
          "id": "01hfycrt5cr7vajwaej1yre9q5",
          "object": "allowance_line_item",
          "data": {
            "line_item_type": "allowance",
            "amount": 10,
            "allowance": {
              "allowance_type": "automobile_and_motor_vehicle",
              "recurring_allowance": null
            },
            "created_at": "2023-11-23T15:28:56.000000Z",
            "updated_at": "2023-11-23T15:28:56.000000Z"
          }
        }
      ]
    },
    "reimbursement_line_items": {
      "object": "list",
      "data": [
        {
          "id": "01hfycs5ze4hs2c5erjb6jx4kn",
          "object": "reimbursement_line_item",
          "data": {
            "line_item_type": "reimbursement",
            "amount": 10,
            "reimbursement": {
              "reimbursement_type": "non_taxable_reimbursement",
              "recurring_reimbursement": null
            },
            "created_at": "2023-11-23T15:29:08.000000Z",
            "updated_at": "2023-11-23T15:29:08.000000Z"
          }
        }
      ]
    },
    "benefit_line_items": {
      "object": "list",
      "data": [
        {
          "id": "01hfycn0yy7gs7s5ek2k6j854w",
          "object": "benefit_line_item",
          "data": {
            "line_item_type": "benefit",
            "amount": 30,
            "benefit": {
              "employee_benefit": null,
              "benefit_type": "dental",
              "company_contribution_amount": 10,
              "employee_contribution_amount": 30
            },
            "created_at": "2023-11-23T15:26:52.000000Z",
            "updated_at": "2023-11-23T15:26:52.000000Z"
          }
        }
      ]
    },
    "post_tax_deduction_line_items": {
      "object": "list",
      "data": [
        {
          "id": "01hfycw58xh8pp8j9agw63esgv",
          "object": "post_tax_deduction_line_item",
          "data": {
            "line_item_type": "post_tax_deduction",
            "amount": 10,
            "post_tax_deduction": {
              "post_tax_deduction_type": "income_tax",
              "recurring_post_tax_deduction": null
            },
            "created_at": "2023-11-23T15:30:46.000000Z",
            "updated_at": "2023-11-23T15:30:46.000000Z"
          }
        }
      ]
    },
    "created_at": "2023-11-22T21:48:01.000000Z",
    "updated_at": "2023-11-23T15:51:21.000000Z"
  },
  "links": {
    "self": "https://sandbox.nmbr.co/services/payroll/pay_stubs/01hfwg2784vc1408yhmjp4x81q"
  }
}

​
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 by type=regular and status=draft, and sort by pay_date: Request 
curl --request GET \
     --url 'https://sandbox.nmbr.co/services/payroll/payrolls?business_entity_id=:business_entity_id&type=regular&status=draft&sort=pay_date:asc' \
     --header 'Authorization: Bearer <access_token>' \
     --header 'accept: application/json'
The first payroll in the response is the upcoming regular draft payroll.
📘 Why not use next_payrolls? The next_payrolls=only filter returns the current payroll being handled by Nmbr for each Pay Schedule — which may be an approved, processing, or failed payroll, not necessarily one that is ready for editing. Filtering by type=regular&status=draft and sorting by pay_date ensures you always get the next editable regular payroll.
You 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. 
curl --request PUT \
     --url https://sandbox.nmbr.co/services/payroll/earnings/:earning_id \
     --header 'Authorization: Bearer <access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
                "id": "01hc2p95nqdbz1ss6b90yf8zjv",
                "earning_type": "hourly",
                "amount": 100,
                "hours": 10,
                "accrued_vacation_pay": 2
            }'

​
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. 
curl --request POST \
     --url https://sandbox.nmbr.co/services/payroll/payrolls/:payroll_id/approve \
     --header 'Authorization: Bearer <access_token>' \
     --header 'accept: application/json'
📘 Rejected Approvals If a payroll is in an invalid state when the /approve endpoint is called, the approval will fail, returning a 422 Unprocessable Entity response. 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 draft status.
Once 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 four statuses: draft, pending, processing, and paid. Below is an overview of these statuses, what they mean, and how payrolls transition between them.
📘 Payroll status webhooks When a payroll makes status transitions from pending 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 still reopen the payroll (via the /payrolls/<payroll_id>/reopen endpoint), which will move it back into the draft status. Once reopened, a draft payroll can again be modified, previewed, and even deleted. Ultimately, if and when it is approved again, the payroll will move 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 reopened. If you require a change to a processing payroll, reach out to us directly. 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

Unfortunately, there will be times when an ACH payment to an employee or a contractor is returned. This can happen for a number of reasons, but the most common is an invalid account/routing number or frozen bank account. In cases like these, it is important that you have insight into the exact state of the payments. To handle this, Nmbr will mark the returned payroll item or contractor payment as failed, and mark the parent payroll as partially_paid. This status means that we have attempted to send out employee or contractor payments and one or more of these payments failed. If you need to resolve a failure, please reach out to us directly. After the employee or contractor payment failure has been handled you will see the payroll’s status flip back to paid.

​
failed

Just as we will unfortunately see times that an employee’s payment will fail, there will also be times when the ACH transaction to debit the cash requirement for an employer’s payroll will be returned. One common reason this occurs is because there are insufficient funds for the transaction in an employer’s bank account at the time of request. When this happens, Nmbr sets the payroll’s status to be failed and, if possible, pauses in-flight employee and contractor payments for that payroll. Our team then works with you to quickly wire the cash requirement for the failed payroll before unpausing and delivering the payroll’s employee and contractor payments.