Create a payroll

Authorizations

Authorization

string

header

required

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

Body

application/json

pay_schedule_id

string

required

type

enum<string>

required

The type of payroll. regular payrolls are generated automatically on the Pay Schedule. off_cycle Payrolls are created manually against a source regular payroll. historical and correction payrolls are used to record or correct prior periods.

Available options:

correction,

historical,

off_cycle,

regular

source_payroll_id

string

The ID of the source regular payroll for off_cycle payrolls.

Only allowed when creating a Payroll of type off_cycle. The source payroll must be a regular payroll on the same pay-schedule.

note

string | null

An optional note on the payroll, visible to the partner.

period_start

string<date>

The start date of the pay period.

When creating a payroll of type historical or correction, a period_start date is required. A period_start date is prohibited on a off_cycle payroll.

period_end

string<date>

The end date of the pay period.

When creating a payroll of type historical or correction, a period_end date is required. A period_end date is prohibited on a off_cycle payroll.

custom_pay_frequency

enum<string>

For payrolls on a custom-frequency Pay Schedule, the pay frequency for this specific pay period.

Only allowed when creating a regular payroll on a custom frequency pay schedule where frequency is defined per payroll.

Available options:

bi-weekly,

monthly,

semi-monthly,

weekly

pay_date

string<date>

The date on which Employees and Contractors are paid.

original_pay_date

string<date>

For payrolls on a custom-frequency Pay Schedule, the originally scheduled pay date before any movement for weekends or bank holidays. Used for year-to-date calculations and tax year assignment.

Only allowed when creating a regular payroll on a custom frequency pay schedule.

external_ref

string

Maximum string length: 255

Response

201 - application/json

Created

string

read-only

The unique identifier of the object in Nmbr.

object

string

read-only

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

data

Payroll · object

Hide child attributes

data.business_entity

object

Hide child attributes

data.business_entity.id

string

read-only

The unique identifier of the object in Nmbr.

data.business_entity.object

string

read-only

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

data.pay_schedule

object

Hide child attributes

data.pay_schedule.id

string

read-only

The unique identifier of the object in Nmbr.

data.pay_schedule.object

string

read-only

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

data.type

enum<string>

Available options:

correction,

historical,

off_cycle,

regular

data.period_number

integer | null

The sequential number of this pay period within the calendar year of its pay_date, counting only regular payrolls. null for off-cycle, historical, and correction payrolls.

data.period_label

string | null

A human-readable label for this pay period.

data.period_start

string<date>

The start date of the pay period.

data.period_end

string<date>

The end date of the pay period.

data.pay_date

string<date>

The date on which Employees and Contractors are paid.

data.original_pay_date

string<date> | null

For payrolls on a custom-frequency Pay Schedule, the originally scheduled pay date before any movement for weekends or bank holidays. Used for year-to-date calculations and tax year assignment.

data.debit_date

string | null

The expected date the company's account will be debited the cash_requirement amount.

data.approval_due_at

string<dateTime> | null

read-only

The date and time, in UTC, by which the payroll must be approved to be processed on time.

data.regular_periods_count

integer | null

The total number of regular pay periods in this Pay Schedule whose pay_date falls in the same calendar year as this payroll's pay_date. Used for year-to-date calculations.

data.is_impacted_by_weekend_or_holiday

boolean

Whether pay_date or approval_due_at has been moved to avoid falling on a weekend or bank holiday.

data.is_blocked_by_draft

boolean

Whether this payroll is blocked from being approved because an earlier payroll on the same Pay Schedule is still in draft status.

data.note

string | null

An optional note on the payroll, visible to the partner.

data.employee_summary

object

A summary of pay across all Employees in this payroll.

Hide child attributes

data.employee_summary.gross

any

The sum of all earnings and allowances.

data.employee_summary.subtractions

any

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

data.employee_summary.reimbursements

any

The total of non-taxable reimbursements.

data.employee_summary.net

any

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

data.contractor_summary

object

A summary of pay across all Contractors in this payroll.

Hide child attributes

data.contractor_summary.gross

any

The sum of all earnings.

data.contractor_summary.reimbursements

any

The total of non-taxable reimbursements.

data.contractor_summary.net

any

The Contractor net pay.

data.company_summary

object

A summary of the company's obligations in this payroll.

Hide child attributes

data.company_summary.taxes_and_contributions

any

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

data.company_summary.benefits

any

The total of employer benefit contributions.

data.company_summary.total

any

The company's total obligations.

data.liability

number<decimal> | null

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

data.cash_requirement

number<decimal> | null

The total amount that will be debited from the company's account when this payroll is approved.

data.status

enum<string>

The current status of the payroll.

Available options:

approved,

draft,

failed,

paid,

partially_paid,

processing

data.approved_at

string<date> | null

The date on which the payroll was approved.

data.is_stale

boolean

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

data.stale_since

string<dateTime> | null

read-only

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

data.source_payroll

any

data.warnings

object

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

Hide child attributes

data.warnings.object

string | null

data.warnings.data

object

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.created_at

string<dateTime>

read-only

The date and time the object was created in Nmbr.

data.updated_at

string<dateTime>

read-only

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