---
title: "List employee benefits"
method: GET
path: "/employee_benefits"
tags: ["Employee Benefits"]
---

# List employee benefits

`GET /employee_benefits`

## Query parameters

- `business_entity_id` string
- `pay_schedule_id` string
- `work_assignment_id` string
- `employee_id` string
- `has_business_preset` boolean
- `business_preset_id` string
- `include_types` union
  - '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'
  - string[]
- `exclude_types` union
  - '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'
  - string[]
- `effective_on` string, date
- `not_effective_on` string, date
- `effective_from` object
- `effective_to` object
- `external_ref` string
- `search_payee_names` string
- `sort` 'effective_from' | 'effective_to' | 'work_assignment.payee.default' | 'work_assignment.payee.first_name' | 'work_assignment.payee.last_name'
- `tag_id` string
- `tag_group_id` string
- `expand` string[]

## Response `200`

OK

- object
  - `object` string — The type of the object in Nmbr (`"list"`).
  - `data` object[]
    - `id` string — The unique identifier of the object in Nmbr.
    - `object` string — The type of the object in Nmbr (`"employee_benefit"`).
    - `data` EmployeeBenefit
      - `work_assignment` object
        - `id` string — The unique identifier of the object in Nmbr.
        - `object` string — The type of the object in Nmbr (`"work_assignment"`).
      - `business_preset` unknown
      - `employee_benefit_type` object — The type of employee benefit, which determines how it is taxed and reported.
        - `id` string — The unique identifier of the object in Nmbr.
        - `object` string — The type of the object in Nmbr (`"employee_benefit_type"`).
        - `data` EmployeeBenefitType
          - `type` string, nullable — The string identifier for this employee benefit type.
          - `label` string, nullable — The human-readable display name for this employee benefit type.
          - `features` LineItemTypeFeature[]
            - `type` 'eht' | 'income_tax' | 'insurable' | 'pensionable' | 'stat_payable' | 'vacationable' | 'wcb' — The payroll calculation this entry describes.
            - `label` string — Human-readable name for the payroll calculation.
            - `definitions` object[] — How this type affects the calculation, broken down by jurisdiction. Jurisdictions where it does not apply are omitted.
              - …
          - `form_mappings` LineItemFormMapping[]
            - `form` string — The form code (e.g. `t4`).
            - `form_label` string — Human-readable form name.
            - `mapping` array[] — The boxes on the form this type contributes to.
              - …
      - `employer_benefit` unknown
      - `title` string, nullable
      - `title_translations` Translations, nullable
        - `en` string
        - `fr` string
      - `title_translated` string — 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.
      - `income_basis` 'all_earnings' | 'none' | 'regular_earnings' | 'total_income' — 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.
      - `income_includes` object, nullable — 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`.
      - `max_annual_contribution_basis` 'all_line_items_of_type' | 'this_benefit' — Whether `max_annual_contribution` accumulates across pay periods or applies as a fixed per-period cap.
      - `apply_sales_tax` boolean — Whether provincial sales tax is applied to the benefit amount.
      - `remittance_account_id` string, nullable — The remittance account to which collected benefit amounts are remitted.
      - `remittance_account` unknown
      - `amount` number — 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.
      - `amount_type` 'fixed' | 'percent' — Whether `amount` is a fixed dollar value (`fixed`) or a percentage of the income basis (`percent`).
      - `coverage_multiplier` number — A multiplier applied to the Employee's earnings to determine the benefit coverage amount, used for coverage-based benefits such as life insurance.
      - `max_annual_contribution` number, nullable — The maximum dollar amount that will be contributed in a calendar year. Contributions stop once this limit is reached.
      - `frequency` 'once' | 'per_month' | 'per_payroll' — 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`.
      - `date_basis` 'by_pay_date' | 'by_period_end_date' | 'by_period_start_date', nullable — Which payroll date determines the calendar month for the allocation. Applies only to `per_month` benefits.
      - `pay_period_cadence` object, nullable — 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.
      - `effective_from` string, date — The date from which this benefit is applied to Pay Stubs.
      - `effective_to` string, date, nullable — The date after which this benefit is no longer applied. `null` if the benefit applies indefinitely.
      - `expense_accounting_code` unknown
      - `liability_accounting_code` unknown
      - `external_ref` string, nullable — 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.
      - `created_at` string, dateTime — The date and time the object was created in Nmbr.
      - `updated_at` string, dateTime — The date and time the object was last updated in Nmbr.

---

[API](https://skmtc.net/nmbr/apis/nmbr-api.md) · [All operations](https://skmtc.net/nmbr/apis/nmbr-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nmbr/nmbr-api/versions/01cd9c45a923/schema)