Configuring Benefits

Benefits represent payroll contributions tied to employer or employee plans. These contributions may be monetary or calculated based on earnings, and may be shared between the employer and the employee. Benefits are configured using two distinct entities:

Employer Benefits: Contributions paid by the employer towards employee benefit plans.
Employee Benefits: Contributions deducted from the employees earnings to contribute to their benefits.

Both types can generate line items during payroll, which represent actual contributions applied per pay period.

Employer Contributions

Employer Benefits

Employer Benefits represent the configuration of recurring contributions made by the employer towards benefit plans, such as health insurance or retirement contributions.

Employer Benefits are contributions made by the employer towards employee benefit plans.
They can be fixed amounts or calculated based on employee earnings.
During the effective dates, these contributions are automatically applied to the payroll as an Employer Benefit Line Item.
Employer Benefits can be inherited from a Business Preset, allowing for consistent benefit configurations across multiple work assignments.

Field	Description
`work_assignment_id`	Required. The work assignment this benefit applies to. Must belong to a work assignment associated with an entity of type Employee.
`business_preset_id`	Optional Business Preset to inherit from.
`employer_benefit_type`	The type of benefit (e.g. `health`, `pension_rrsp`, `group_term_life_insurance`). Required unless inherited from a Business Preset.
`employee_benefit_id`	Optional reference to an employee_benefit used solely for display.
`title`	Label for identifying the benefit.
`effective_from`	Start date of the Benefit.
`effective_to`	The end date for this plan (optional)
`frequency`	How often the benefit applies (e.g. `once`, `per_payroll`, `per_month`)
`income_basis`	Income basis used for percentage-based benefits (`regular_earnings`, `total_income`)
`income_includes`	Narrows which earnings count towards percentage-based benefits. Each entry sets a `type` (`earning`, `allowance`, or `reimbursement`) and a `subtype`.
`amount`	Fixed contribution amount (optional)
`percent`	Percent of eligible earnings (optional)
`max_annual_contribution`	Optional annual contribution cap
`max_annual_contribution_basis`	What the annual cap applies to. `this_benefit` caps this benefit on its own. `all_line_items_of_type` shares one cap across every benefit of the same type (for example, two separate RRSP plans count toward a single yearly limit).
`coverage_multiplier`	Coverage multiplier used for life insurance plans.
`remittance_account_id`	The remittance account these contributions are paid out to.
`expense_accounting_code_id`	Accounting code that routes the expense side of this benefit.
`liability_accounting_code_id`	Accounting code that routes the liability side of this benefit.

For the complete list of accepted fields, see the Create an Employer Benefit API reference.

🔍 Note: employee_benefit_id is used only for UI grouping. No values are inherited, and changes to one do not affect the other.

Employee Contributions

Employee Benefits represent the configuration of recurring contributions deducted from the employees earnings towards benefit plans, such as health insurance or retirement contributions.

They can be fixed amounts or calculated based on employee earnings.
During the effective dates, these contributions are automatically applied to the payroll as an Employee Benefit Line Item.
Employee Benefits can be inherited from a Business Preset, allowing for consistent benefit configurations across multiple work assignments.

Key Fields

Field	Description
`work_assignment_id`	Required. The work assignment this benefit applies to. Must belong to a work assignment associated with an entity of type Employee.
`business_preset_id`	Optional Business Preset to inherit from.
`employee_benefit_type`	The type of benefit (e.g. `health`, `pension_rrsp`, `group_term_life_insurance`). Required unless inherited from a Business Preset.
`employer_benefit_id`	Optional reference to an employer_benefit used solely for display.
`title`	Label for identifying the benefit.
`effective_from`	Start date of the benefit.
`effective_to`	The end date for this plan (optional)
`frequency`	How often the benefit applies (e.g. `once`, `per_payroll`, `per_month`)
`income_basis`	Income basis used for percentage-based benefits (`regular_earnings`, `total_income`)
`income_includes`	Narrows which earnings count towards percentage-based benefits. Each entry sets a `type` (`earning`, `allowance`, or `reimbursement`) and a `subtype`.
`amount`	Fixed contribution amount (optional)
`percent`	Percent of eligible earnings (optional)
`max_annual_contribution`	Optional annual contribution cap
`max_annual_contribution_basis`	What the annual cap applies to. `this_benefit` caps this benefit on its own. `all_line_items_of_type` shares one cap across every benefit of the same type (for example, two separate RRSP plans count toward a single yearly limit).
`coverage_multiplier`	Coverage multiplier used for life insurance plans.
`remittance_account_id`	The remittance account these contributions are paid out to.
`expense_accounting_code_id`	Accounting code that routes the expense side of this benefit.
`liability_accounting_code_id`	Accounting code that routes the liability side of this benefit.

For the complete list of accepted fields, see the Create an Employee Benefit API reference.

🔍 Note: employer_benefit_id is used only for UI grouping. No values are inherited, and changes to one do not affect the other.

Validations

Only one of amount or percent may be set per benefit. Attempts to set both will result in a validation error.
A benefit must include a *_benefit_type unless inherited from a Business Preset.

Contribution Limits

Each benefit can have a max_annual_contribution defined to set an annual limit, which is enforced during payroll processing.

max_annual_contribution_basis sets what the annual cap applies to. this_benefit (the default) caps this benefit on its own. all_line_items_of_type shares one cap across every benefit of the same type, so two separate RRSP plans count toward a single yearly limit.
The limit resets at the start of each calendar year.
Only paid line items count towards the limit.
Historical Year-To-Date (YTD) contributions are not considered when calculating contributions towards the limit.

Employer Benefit Line Items

Employer Benefit Line Items represent the actual contributions made by the employer towards employee benefit plans during payroll processing. These line items are generated based on the configured Employer Benefits, or can be created directly for one-time contributions.

Field	Description
`business_preset_id`	Optional Business Preset to inherit from.
`employer_benefit_type`	The type of benefit (e.g. `health`, `pension_rrsp`, `group_term_life_insurance`)
`recurrence`	The employer benefit which generated this line item (read-only)
`title`	Label for identifying the benefit line item.
`amount`	Actual dollar value for this line item (read-only)
`custom_amount`	User settable value for the line item amount, always takes precedence over `managed_amount`
`managed_amount`	The calculated value for this line item.
`max_annual_contribution`	Optional annual contribution cap
`coverage_multiplier`	Coverage multiplier used for life insurance plans.

Employee Benefit Line Items

Employee Benefit Line Items represent the actual contributions made by the employee towards benefit plans during payroll processing. These line items are generated based on the configured Employee Benefits, or can be created directly for one-time contributions.

Field	Description
`business_preset_id`	Optional Business Preset to inherit from.
`employee_benefit_type`	The type of benefit (e.g. `health`, `pension_rrsp`, `group_term_life_insurance`)
`recurrence`	The employee benefit which generated this line item (read-only)
`title`	Label for identifying the benefit line item.
`amount`	Actual dollar value for this line item (read-only)
`custom_amount`	User settable value for the line item amount, always takes precedence over `managed_amount`
`managed_amount`	The calculated value for this line item.
`max_annual_contribution`	Optional annual contribution cap
`coverage_multiplier`	Coverage multiplier used for life insurance plans.

Benefit Types

Employee and employer benefits each have their own set of supported benefit types, which may overlap. You can retrieve the lists using the following endpoints:

GET /employee_benefit_types: Returns all employee benefit types
GET /employer_benefit_types: Returns all employer benefit types

Each benefit type object includes:

type: the unique identifier used in the API, e.g. critical_illness, pension_dcpp.
label: a human-readable name for display purposes, e.g “Critical Illness”, “Defined Contribution Pension Plan (DCPP)”.

Example Scenarios

A. One-Time Dental Contribution

Creates a one-time $125 employee-only dental benefit:

curl --request POST \
     --url https://sandbox.nmbr.co/services/payroll/employee_benefits \
     --header 'Authorization: Bearer <access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
        "work_assignment_id": "...",
        "employee_benefit_type": "dental",
        "frequency": "once",
        "amount": 125,
        "effective_from": "2025-04-01",
        "title": "Employee Dental Plan Contribution"
     }'

Recurring Employee RRSP contribution

A recurring RRSP contribution of $150 each payroll with an annual maximum of $600, starting from January 1, 2025:

curl --request POST \
     --url https://sandbox.nmbr.co/services/payroll/employee_benefits \
     --header 'Authorization: Bearer <access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
        "work_assignment_id": "...",
        "employee_benefit_type": "pension_rrsp",
        "frequency": "per_payroll",
        "amount": 150,
        "max_annual_contribution": 600,
        "effective_from": "2025-01-01"
     }'

Shared Health Plan

A recurring Health contribution:

Employer contributes $50 per payroll.
Employee contributes $25 per payroll.
The two benefits are linked, allowing the two benefits to be displayed together in payroll.

curl --request POST \
     --url https://sandbox.nmbr.co/services/payroll/employer_benefits \
     --header 'Authorization: Bearer <access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
        "work_assignment_id": "...",
        "employer_benefit_type": "health",
        "frequency": "per_payroll",
        "amount": 50,
        "effective_from": "2025-01-01"
     }'

curl --request POST \
     --url https://sandbox.nmbr.co/services/payroll/employee_benefits \
     --header 'Authorization: Bearer <access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
        "work_assignment_id": "...",
        "employer_benefit_id": "<Employer Benefit ID>",
        "employee_benefit_type": "health",
        "frequency": "per_payroll",
        "amount": 25,
        "effective_from": "2025-01-01"
     }'

​Employer Contributions

​Employer Benefits

​Employee Contributions

​Key Fields

​Validations

​Contribution Limits

​Employer Benefit Line Items

​Employee Benefit Line Items

​Benefit Types

​Example Scenarios

​A. One-Time Dental Contribution

​Recurring Employee RRSP contribution

​Shared Health Plan