Create an employee benefit

curl --request POST \
  --url https://sandbox.nmbr.co/services/payroll/employee_benefits \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "work_assignment_id": "<id>",
  "employee_benefit_type": "dental",
  "frequency": "per_month",
  "amount": "325.5",
  "amount_type": "fixed",
  "income_basis": "regular_earnings",
  "max_annual_contribution": "2500.5",
  "max_annual_contribution_basis": "this_benefit",
  "coverage_multiplier": "1",
  "effective_from": "2026-01-01",
  "effective_to": "2026-12-31",
  "apply_sales_tax": false,
  "title": "Dental",
  "title_translations": {
    "en": "Dental",
    "fr": "Assurance dentaire"
  },
  "external_ref": "01KG003XG877R33YKHA40HJP84",
  "tag_assignment": {
    "unit": "percentage",
    "tag_allocations": [
      {
        "tags": [
          "<id>"
        ],
        "value": 100
      }
    ]
  },
  "date_basis": "by_period_start_date",
  "pay_period_cadence": [
    1
  ]
}
'

{
  "id": "<id>",
  "object": "employee_benefit",
  "data": {
    "work_assignment": {
      "id": "<id>",
      "object": "work_assignment",
      "links": {
        "self": "/work_assignments/<id>"
      }
    },
    "business_preset": null,
    "employee_benefit_type": {
      "id": "<id>",
      "object": "employee_benefit_type",
      "data": {
        "type": "dental",
        "label": "Dental"
      },
      "links": {
        "self": "/employee_benefit_types/dental"
      }
    },
    "employer_benefit": null,
    "title": "Dental",
    "title_translations": {
      "en": "Dental",
      "fr": "Assurance dentaire"
    },
    "title_translated": "Dental",
    "income_basis": "regular_earnings",
    "income_includes": [],
    "max_annual_contribution_basis": "this_benefit",
    "apply_sales_tax": false,
    "remittance_account_id": null,
    "remittance_account": null,
    "amount": 325.5,
    "amount_type": "fixed",
    "coverage_multiplier": 1,
    "max_annual_contribution": 2500.5,
    "frequency": "per_month",
    "date_basis": "by_period_start_date",
    "pay_period_cadence": [
      1
    ],
    "effective_from": "2026-01-01",
    "effective_to": "2026-12-31",
    "expense_accounting_code": null,
    "liability_accounting_code": null,
    "external_ref": "01KG003XG877R33YKHA40HJP84",
    "created_at": "2026-01-01T00:00:00.000000Z",
    "updated_at": "2026-01-01T00:00:00.000000Z"
  },
  "links": {
    "self": "/employee_benefits/<id>"
  }
}

POST

employee_benefits

curl --request POST \
  --url https://sandbox.nmbr.co/services/payroll/employee_benefits \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "work_assignment_id": "<id>",
  "employee_benefit_type": "dental",
  "frequency": "per_month",
  "amount": "325.5",
  "amount_type": "fixed",
  "income_basis": "regular_earnings",
  "max_annual_contribution": "2500.5",
  "max_annual_contribution_basis": "this_benefit",
  "coverage_multiplier": "1",
  "effective_from": "2026-01-01",
  "effective_to": "2026-12-31",
  "apply_sales_tax": false,
  "title": "Dental",
  "title_translations": {
    "en": "Dental",
    "fr": "Assurance dentaire"
  },
  "external_ref": "01KG003XG877R33YKHA40HJP84",
  "tag_assignment": {
    "unit": "percentage",
    "tag_allocations": [
      {
        "tags": [
          "<id>"
        ],
        "value": 100
      }
    ]
  },
  "date_basis": "by_period_start_date",
  "pay_period_cadence": [
    1
  ]
}
'

{
  "id": "<id>",
  "object": "employee_benefit",
  "data": {
    "work_assignment": {
      "id": "<id>",
      "object": "work_assignment",
      "links": {
        "self": "/work_assignments/<id>"
      }
    },
    "business_preset": null,
    "employee_benefit_type": {
      "id": "<id>",
      "object": "employee_benefit_type",
      "data": {
        "type": "dental",
        "label": "Dental"
      },
      "links": {
        "self": "/employee_benefit_types/dental"
      }
    },
    "employer_benefit": null,
    "title": "Dental",
    "title_translations": {
      "en": "Dental",
      "fr": "Assurance dentaire"
    },
    "title_translated": "Dental",
    "income_basis": "regular_earnings",
    "income_includes": [],
    "max_annual_contribution_basis": "this_benefit",
    "apply_sales_tax": false,
    "remittance_account_id": null,
    "remittance_account": null,
    "amount": 325.5,
    "amount_type": "fixed",
    "coverage_multiplier": 1,
    "max_annual_contribution": 2500.5,
    "frequency": "per_month",
    "date_basis": "by_period_start_date",
    "pay_period_cadence": [
      1
    ],
    "effective_from": "2026-01-01",
    "effective_to": "2026-12-31",
    "expense_accounting_code": null,
    "liability_accounting_code": null,
    "external_ref": "01KG003XG877R33YKHA40HJP84",
    "created_at": "2026-01-01T00:00:00.000000Z",
    "updated_at": "2026-01-01T00:00:00.000000Z"
  },
  "links": {
    "self": "/employee_benefits/<id>"
  }
}

Authorizations

Authorization

string

header

required

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

Body

application/json

work_assignment_id

string

required

Must belong to a work assignment associated with an entity of type Employee.

frequency

enum<string>

required

The frequency at which this benefit is applied to Pay Stubs. When per_month, the amount is distributed across the selected Payrolls in the calendar month. per_month requires amount_type to be fixed.

Available options:

once,

per_month,

per_payroll

amount

number<decimal>

required

The contribution amount per pay period. When amount_type is percent, this is interpreted as a percentage of the income basis (0-100); otherwise as a fixed dollar amount.

Required range: x >= 0

amount_type

enum<string>

required

Whether amount is a fixed dollar value (fixed) or a percentage of the income basis (percent).

Available options:

fixed,

percent

effective_from

string<date>

required

The date from which this benefit is applied to Pay Stubs.

business_preset_id

string

employee_benefit_type

enum<string>

The type of employee benefit, which determines how it is taxed and reported.

Must be present when business_preset_id is either empty or not set.

Available options:

accident_insurance_plan,

critical_illness,

debt_relief,

dental,

employee_assistance_program,

fondaction,

fondaction_rrsp,

fonds_solidarite_ftq,

fonds_solidarite_ftq_rrsp,

group_dependent_life_insurance,

group_term_life_insurance,

health,

health_spending_account,

long_term_disability,

non_group_long_term_disability,

non_group_short_term_disability,

pension_dbpp,

pension_dcpp,

pension_mfpp,

pension_prpp,

pension_restricted_rrsp,

pension_rrsp,

pension_rrsp_non_periodic,

pension_unregistered_prpp,

pension_vrsp,

profit_sharing_dpsp,

savings_tfsa,

second_opinion_medical_consultation,

short_term_disability,

virtual_health_service,

wellness_spending_account

employer_benefit_id

string

income_basis

enum<string>

Determines the income used as the base for percentage-based benefit calculations. regular_earnings includes only salary and wage earnings. all_earnings includes all earnings. total_income includes all earnings, taxable allowances, and taxable reimbursements. none doesn't include any line items, and can be used with income_includes for completely custom definitions of income.

Available options:

all_earnings,

none,

regular_earnings,

total_income

income_includes

object[]

An optional list of specific earnings, allowances, and other line item types to include in the income calculation in addition to those included via income_basis.

Hide child attributes

income_includes.type

enum<string>

Available options:

allowance,

earning,

reimbursement

income_includes.subtype

string

max_annual_contribution

number<decimal>

The maximum dollar amount that will be contributed in a calendar year. Contributions stop once this limit is reached.

Required range: 0 <= x <= 99999

max_annual_contribution_basis

enum<string>

Whether max_annual_contribution accumulates across pay periods or applies as a fixed per-period cap.

Available options:

all_line_items_of_type,

this_benefit

coverage_multiplier

number<decimal>

A multiplier applied to the Employee's earnings to determine the benefit coverage amount, used for coverage-based benefits such as life insurance.

Required range: 0 <= x <= 100

effective_to

string<date>

The date after which this benefit is no longer applied. null if the benefit applies indefinitely.

apply_sales_tax

boolean

Whether provincial sales tax is applied to the benefit amount.

remittance_account_id

string

The remittance account to which collected benefit amounts are remitted.

expense_accounting_code_id

string

liability_accounting_code_id

string

title

string | null

Maximum string length: 255

title_translations

object

Optional translations for the title property.

Hide child attributes

title_translations.en

string

Maximum string length: 255

title_translations.fr

string

Maximum string length: 255

external_ref

string

Maximum string length: 255

tag_assignment

object

Hide child attributes

tag_assignment.unit

enum<string>

Available options:

percentage

tag_assignment.is_component_locked

boolean

tag_assignment.tag_allocations

object[]

Hide child attributes

tag_assignment.tag_allocations.tags

string[]

tag_assignment.tag_allocations.value

number<decimal>

Required range: x >= 0

date_basis

enum<string>

Which payroll date determines the calendar month for the allocation. Applies only to per_month benefits.

Available options:

by_pay_date,

by_period_end_date,

by_period_start_date

pay_period_cadence

integer[]

Which pay periods within the month receive the allocation. An array of 1-based positions; -1 is the final period. Applies only to per_month benefits.

Minimum array length: 1

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 ("employee_benefit").

data

Employee Benefit · object

Hide child attributes

data.work_assignment

object

Hide child attributes

data.work_assignment.id

string

read-only

The unique identifier of the object in Nmbr.

data.work_assignment.object

string

read-only

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

data.business_preset

any

data.employee_benefit_type

object

The type of employee benefit, which determines how it is taxed and reported.

Hide child attributes

data.employee_benefit_type.id

string

read-only

The unique identifier of the object in Nmbr.

data.employee_benefit_type.object

string

read-only

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

data.employee_benefit_type.data

Employee Benefit Type · object

Hide child attributes

data.employee_benefit_type.data.type

string | null

The string identifier for this employee benefit type.

data.employee_benefit_type.data.label

string | null

The human-readable display name for this employee benefit type.

data.employer_benefit

any

data.title

string | null

Maximum string length: 255

data.title_translations

object

Optional translations for the title property.

Hide child attributes

data.title_translations.en

string

Maximum string length: 255

data.title_translations.fr

string

Maximum string length: 255

data.title_translated

string

read-only

The translation of the title property for the request locale. Computed using the values in title and title_translations and the value of the request's Accept-Language header.

data.income_basis

enum<string>

Available options:

all_earnings,

none,

regular_earnings,

total_income

data.income_includes

object

An optional list of specific earnings, allowances, and other line item types to include in the income calculation in addition to those included via income_basis.

data.max_annual_contribution_basis

enum<string>

Whether max_annual_contribution accumulates across pay periods or applies as a fixed per-period cap.

Available options:

all_line_items_of_type,

this_benefit

data.apply_sales_tax

boolean

Whether provincial sales tax is applied to the benefit amount.

data.remittance_account_id

string | null

The remittance account to which collected benefit amounts are remitted.

Maximum string length: 32

data.remittance_account

any

data.amount

number<decimal>

The contribution amount per pay period. When amount_type is percent, this is interpreted as a percentage of the income basis (0-100); otherwise as a fixed dollar amount.

data.amount_type

enum<string>

Whether amount is a fixed dollar value (fixed) or a percentage of the income basis (percent).

Available options:

fixed,

percent

data.coverage_multiplier

number<decimal>

A multiplier applied to the Employee's earnings to determine the benefit coverage amount, used for coverage-based benefits such as life insurance.

data.max_annual_contribution

number<decimal> | null

The maximum dollar amount that will be contributed in a calendar year. Contributions stop once this limit is reached.

data.frequency

enum<string>

Available options:

once,

per_month,

per_payroll

data.date_basis

enum<string> | null

Which payroll date determines the calendar month for the allocation. Applies only to per_month benefits.

Available options:

by_pay_date,

by_period_end_date,

by_period_start_date

data.pay_period_cadence

object

Which pay periods within the month receive the allocation. An array of 1-based positions; -1 is the final period. Applies only to per_month benefits.

data.effective_from

string<date>

The date from which this benefit is applied to Pay Stubs.

data.effective_to

string<date> | null

The date after which this benefit is no longer applied. null if the benefit applies indefinitely.

data.expense_accounting_code

any

data.liability_accounting_code

any

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.

List employee benefits Retrieve an employee benefit

⌘I