List pay stubs

curl --request GET \
  --url https://sandbox.nmbr.co/services/payroll/pay_stubs \
  --header 'Authorization: Bearer <token>'

{
  "object": "list",
  "data": [
    {
      "id": "<id>",
      "object": "pay_stub",
      "data": {
        "payroll": {
          "id": "<id>",
          "object": "payroll",
          "links": {
            "self": "/payrolls/<id>"
          }
        },
        "work_assignment": {
          "id": "<id>",
          "object": "work_assignment",
          "links": {
            "self": "/work_assignments/<id>"
          }
        },
        "payment_method": "direct_deposit",
        "has_taxes_calculated": true,
        "is_pending_tax_rates": false,
        "employee_summary": {
          "gross": 0,
          "subtractions": 0,
          "reimbursements": 0,
          "net": 0,
          "gross_ytd": 0,
          "subtractions_ytd": 0,
          "reimbursements_ytd": 0,
          "net_ytd": 0
        },
        "contractor_summary": {
          "gross": null,
          "reimbursements": null,
          "net": null,
          "gross_ytd": 0,
          "reimbursements_ytd": 0,
          "net_ytd": 0
        },
        "company_summary": {
          "taxes_and_contributions": 0,
          "benefits": 0,
          "total": 0,
          "taxes_and_contributions_ytd": 0,
          "benefits_ytd": 0,
          "total_ytd": 0
        },
        "vacation_pay_balance": 0,
        "liability": 0,
        "cash_requirement": 0,
        "note": null,
        "line_item_summary": {
          "earnings": {
            "period": 0,
            "period_managed": 0,
            "period_unmanaged": 0,
            "ytd": 0
          },
          "statutory_withholdings": {
            "period": 0,
            "ytd": 0
          },
          "reimbursements": {
            "period": 0,
            "ytd": 0
          },
          "allowances": {
            "period": 0,
            "ytd": 0
          },
          "benefits": {
            "period": 0,
            "ytd": 0
          },
          "employee_benefits": {
            "period": 0,
            "ytd": 0
          },
          "employer_benefits": {
            "period": 0,
            "ytd": 0
          },
          "deductions": {
            "period": 0,
            "ytd": 0
          }
        },
        "is_stale": false,
        "stale_since": null,
        "warnings": {
          "object": "list",
          "data": []
        },
        "external_ref": null,
        "created_at": "2026-01-01T00:00:00.000000Z",
        "updated_at": "2026-01-01T00:00:00.000000Z"
      },
      "links": {
        "self": "/pay_stubs/<id>"
      }
    }
  ],
  "links": {
    "first": "/pay_stubs?payroll_id=<id>&page=1",
    "last": "/pay_stubs?payroll_id=<id>&page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 15,
    "total": 1,
    "has_more": false
  }
}

GET

pay_stubs

List pay stubs

curl --request GET \
  --url https://sandbox.nmbr.co/services/payroll/pay_stubs \
  --header 'Authorization: Bearer <token>'

{
  "object": "list",
  "data": [
    {
      "id": "<id>",
      "object": "pay_stub",
      "data": {
        "payroll": {
          "id": "<id>",
          "object": "payroll",
          "links": {
            "self": "/payrolls/<id>"
          }
        },
        "work_assignment": {
          "id": "<id>",
          "object": "work_assignment",
          "links": {
            "self": "/work_assignments/<id>"
          }
        },
        "payment_method": "direct_deposit",
        "has_taxes_calculated": true,
        "is_pending_tax_rates": false,
        "employee_summary": {
          "gross": 0,
          "subtractions": 0,
          "reimbursements": 0,
          "net": 0,
          "gross_ytd": 0,
          "subtractions_ytd": 0,
          "reimbursements_ytd": 0,
          "net_ytd": 0
        },
        "contractor_summary": {
          "gross": null,
          "reimbursements": null,
          "net": null,
          "gross_ytd": 0,
          "reimbursements_ytd": 0,
          "net_ytd": 0
        },
        "company_summary": {
          "taxes_and_contributions": 0,
          "benefits": 0,
          "total": 0,
          "taxes_and_contributions_ytd": 0,
          "benefits_ytd": 0,
          "total_ytd": 0
        },
        "vacation_pay_balance": 0,
        "liability": 0,
        "cash_requirement": 0,
        "note": null,
        "line_item_summary": {
          "earnings": {
            "period": 0,
            "period_managed": 0,
            "period_unmanaged": 0,
            "ytd": 0
          },
          "statutory_withholdings": {
            "period": 0,
            "ytd": 0
          },
          "reimbursements": {
            "period": 0,
            "ytd": 0
          },
          "allowances": {
            "period": 0,
            "ytd": 0
          },
          "benefits": {
            "period": 0,
            "ytd": 0
          },
          "employee_benefits": {
            "period": 0,
            "ytd": 0
          },
          "employer_benefits": {
            "period": 0,
            "ytd": 0
          },
          "deductions": {
            "period": 0,
            "ytd": 0
          }
        },
        "is_stale": false,
        "stale_since": null,
        "warnings": {
          "object": "list",
          "data": []
        },
        "external_ref": null,
        "created_at": "2026-01-01T00:00:00.000000Z",
        "updated_at": "2026-01-01T00:00:00.000000Z"
      },
      "links": {
        "self": "/pay_stubs/<id>"
      }
    }
  ],
  "links": {
    "first": "/pay_stubs?payroll_id=<id>&page=1",
    "last": "/pay_stubs?payroll_id=<id>&page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 15,
    "total": 1,
    "has_more": false
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

payroll_id

string

business_entity_id

string

Only return pay stubs under the specified business entity.

pay_schedule_id

string

Only return pay stubs on the specified pay schedule.

work_assignment_id

string

sort

enum<string>

Sort order is specified using the format sort=field[:direction][,field[:direction],...] where field is the name of the field to sort by and direction is the optional sort direction (asc or desc).

Available options:

payee.default,

payee.first_name,

payee.last_name,

payroll.pay_date,

work_assignment.payee.default,

work_assignment.payee.first_name,

work_assignment.payee.last_name

next_pay_stubs

enum<string>

Filter paystubs to either include only (only), or exclude (exclude), the upcoming pay stubs.

An upcoming pay stub is defined as: - Any pay stub that belongs to the first Regular payroll in the pay schedule with a payroll status of either draft or approved. - Additionally, all pay stubs from draft or approved Off Cycle payrolls within the pay schedule are considered upcoming pay stubs.

Available options:

exclude,

only

employee_id

string

contractor_id

string

type

enum<string>

Available options:

contractor,

employee

payroll_status

enum<string>

Available options:

approved,

draft,

failed,

paid,

partially_paid,

processing

payroll_type

enum<string>

Available options:

correction,

historical,

off_cycle,

regular

has_accounting_code

boolean

payrolls.period_start

object

Date filters support two formats: Exact Date Match: Provide a well-formatted date in YYYY-MM-DD format for an exact match. Example: payrolls.period_start=2024-01-01 Use an array-like syntax to specify a range with one or more comparison operators:

gt (greater than)
gte (greater than or equal to)
lte (less than or equal to)
lt (less than) Example: payrolls.period_start[gte]=2024-01-01&payrolls.period_start[lt]=2024-12-31

payrolls.period_end

object

Date filters support two formats: Exact Date Match: Provide a well-formatted date in YYYY-MM-DD format for an exact match. Example: payrolls.period_end=2024-01-01 Use an array-like syntax to specify a range with one or more comparison operators:

gt (greater than)
gte (greater than or equal to)
lte (less than or equal to)
lt (less than) Example: payrolls.period_end[gte]=2024-01-01&payrolls.period_end[lt]=2024-12-31

payrolls.pay_date

object

Date filters support two formats: Exact Date Match: Provide a well-formatted date in YYYY-MM-DD format for an exact match. Example: payrolls.pay_date=2024-01-01 Use an array-like syntax to specify a range with one or more comparison operators:

gt (greater than)
gte (greater than or equal to)
lte (less than or equal to)
lt (less than) Example: payrolls.pay_date[gte]=2024-01-01&payrolls.pay_date[lt]=2024-12-31

external_ref

string

has_work_assignment_tag_id

string

expand

enum<string>[]

Available options:

allowance_line_items,

deduction_line_items,

earning_line_items,

employee_benefit_line_items,

employer_benefit_line_items,

employer_statutory_withholding_line_items,

payroll,

reimbursement_line_items,

statutory_withholding_line_items,

work_assignment

Response

200 - application/json

object

string

read-only

The type of the object in Nmbr ("list").

data

object[]

Hide child attributes

data.id

string

read-only

The unique identifier of the object in Nmbr.

data.object

string

read-only

The type of the object in Nmbr ("pay_stub").

data.data

Default · object

Default
With payroll expanded
With work_assignment expanded
With earning_line_items expanded
With statutory_withholding_line_items expanded
With employer_statutory_withholding_line_items expanded
With allowance_line_items expanded
With reimbursement_line_items expanded
With employee_benefit_line_items expanded
With employer_benefit_line_items expanded
With deduction_line_items expanded

Hide child attributes

data.data.payroll

object

Hide child attributes

data.data.payroll.id

string

read-only

The unique identifier of the object in Nmbr.

data.data.payroll.object

string

read-only

The type of the object in Nmbr ("payroll").

data.data.work_assignment

object

Hide child attributes

data.data.work_assignment.id

string

read-only

The unique identifier of the object in Nmbr.

data.data.work_assignment.object

string

read-only

The type of the object in Nmbr ("work_assignment").

data.data.payment_method

enum<string>

The payment method for this pay stub.

Available options:

direct_deposit,

manual,

pad,

wire

data.data.has_taxes_calculated

boolean

Whether tax amounts have been calculated for this pay stub. When false, amounts in the employee_summary and company_summary may be incomplete.

data.data.is_pending_tax_rates

boolean

deprecated

This attribute is deprecated and will be removed.

data.data.employee_summary

object

A summary of pay for the Employee associated with this pay stub. *_ytd fields contain year-to-date totals inclusive of this pay period.

Hide child attributes

data.data.employee_summary.gross

number<decimal> | null

The sum of all earnings and allowances.

data.data.employee_summary.subtractions

number<decimal> | null

The total of all deductions, taxes, and benefit contributions.

data.data.employee_summary.reimbursements

number<decimal> | null

The total of non-taxable reimbursements.

data.data.employee_summary.net

number<decimal> | null

The Employee net pay; when negative, a warning is included.

data.data.employee_summary.gross_ytd

number<decimal> | null

data.data.employee_summary.subtractions_ytd

number<decimal> | null

data.data.employee_summary.reimbursements_ytd

number<decimal> | null

data.data.employee_summary.net_ytd

number<decimal> | null

data.data.contractor_summary

object

A summary of pay for the Contractor associated with this pay stub. *_ytd fields contain year-to-date totals inclusive of this pay period.

Hide child attributes

data.data.contractor_summary.gross

any

The sum of all earnings.

data.data.contractor_summary.reimbursements

any

The total of non-taxable reimbursements.

data.data.contractor_summary.net

any

The Contractor net pay.

data.data.contractor_summary.gross_ytd

number<decimal> | null

data.data.contractor_summary.reimbursements_ytd

number<decimal> | null

data.data.contractor_summary.net_ytd

number<decimal> | null

data.data.company_summary

object

A summary of the company's obligations for this pay stub. *_ytd fields contain year-to-date totals inclusive of this pay period.

Hide child attributes

data.data.company_summary.taxes_and_contributions

number<decimal> | null

The employer share of statutory remittances (CPP and EI).

data.data.company_summary.benefits

number<decimal> | null

The total of employer benefit contributions.

data.data.company_summary.total

number<decimal> | null

The company's total obligations.

data.data.company_summary.taxes_and_contributions_ytd

number<decimal> | null

data.data.company_summary.benefits_ytd

number<decimal> | null

data.data.company_summary.total_ytd

number<decimal> | null

data.data.vacation_pay_balance

number<decimal> | null

The Employee's Vacation Pay balance as of the end of this pay period. null for Contractor pay stubs.

data.data.liability

number<decimal> | null

The total amount owed by the company for this pay stub, including Employee or Contractor net pay, employer tax contributions, and employer benefit contributions.

data.data.cash_requirement

number<decimal> | null

The total amount that will be debited from the company's account for this pay stub when the Payroll is approved.

data.data.note

string | null

An optional note on the pay stub, visible to the partner.

data.data.line_item_summary

object

Totals grouped by line item category for this pay stub. Each category includes a period total for the current pay period and a ytd total for the calendar year to date. Categories: earnings, statutory_withholdings, reimbursements, allowances, employee_benefits, employer_benefits, deductions.

Hide child attributes

data.data.line_item_summary.earnings

object

Hide child attributes

data.data.line_item_summary.earnings.period

number<decimal> | null

data.data.line_item_summary.earnings.period_managed

number<decimal> | null

data.data.line_item_summary.earnings.period_unmanaged

number<decimal> | null

data.data.line_item_summary.earnings.ytd

number<decimal> | null

data.data.line_item_summary.statutory_withholdings

object

Hide child attributes

data.data.line_item_summary.statutory_withholdings.period

number<decimal> | null

data.data.line_item_summary.statutory_withholdings.ytd

number<decimal> | null

data.data.line_item_summary.reimbursements

object

Hide child attributes

data.data.line_item_summary.reimbursements.period

number<decimal> | null

data.data.line_item_summary.reimbursements.ytd

number<decimal> | null

data.data.line_item_summary.allowances

object

Hide child attributes

data.data.line_item_summary.allowances.period

number<decimal> | null

data.data.line_item_summary.allowances.ytd

number<decimal> | null

data.data.line_item_summary.benefits

object

Hide child attributes

data.data.line_item_summary.benefits.period

number<decimal> | null

data.data.line_item_summary.benefits.ytd

number<decimal> | null

data.data.line_item_summary.employee_benefits

object

Hide child attributes

data.data.line_item_summary.employee_benefits.period

number<decimal> | null

data.data.line_item_summary.employee_benefits.ytd

number<decimal> | null

data.data.line_item_summary.employer_benefits

object

Hide child attributes

data.data.line_item_summary.employer_benefits.period

number<decimal> | null

data.data.line_item_summary.employer_benefits.ytd

number<decimal> | null

data.data.line_item_summary.deductions

object

Hide child attributes

data.data.line_item_summary.deductions.period

number<decimal> | null

data.data.line_item_summary.deductions.ytd

number<decimal> | null

data.data.is_stale

boolean

Whether the pay stub's tax calculations are out of date. When true, stale_since indicates when the pay stub became stale.

data.data.stale_since

string<dateTime> | null

read-only

The timestamp at which the pay stub's tax calculations became stale and need to be recalculated. null if the pay stub is up to date.

data.data.warnings

object

A collection of data validation warnings for this pay stub. Warnings indicate incomplete or potentially incorrect data and could prevent payroll processing.

Hide child attributes

data.data.warnings.object

string | null

data.data.warnings.data

object

data.data.external_ref

string | null

A reference to the object in an external system, e.g. the primary key of the object in your application's database. Nmbr doesn't use, validate, parse, or require this value to be unique - it simply stores it for your reference.

Maximum string length: 255

data.data.created_at

string<dateTime>

read-only

The date and time the object was created in Nmbr.

data.data.updated_at

string<dateTime>

read-only

The date and time the object was last updated in Nmbr.

Import historical payroll data from CSV Create a pay stub

⌘I