--- title: "List Employee Benefits" method: GET path: "/api/v1/benefit/employee_benefit" tags: ["Benefits", "Public API"] --- # List Employee Benefits `GET /api/v1/benefit/employee_benefit` Returns current and scheduled-future benefit enrollment records, grouped by employee. The response is a JSON object with a single `employeeBenefits` array where each entry contains the internal employee ID, the employee's current pay frequency (null when no pay schedule is set), and an `employeeBenefit` array of per-plan records that includes both the current enrollment record and any scheduled future-change records for that plan. Each record includes enrollment status, deduction date range, currency, occurrences-per-year, and the full employee/employer cost-sharing fields. A JSON request body with a `filters` object is required, and the `filters` object must contain at least one of `employeeId`, `companyBenefitId`, or `enrollmentStatusEffectiveDate`. Any combination is accepted. Providing no `filters` object or an empty `filters` object returns a 400 validation error. Filtering by `companyBenefitId` or `enrollmentStatusEffectiveDate` returns enrollments for every accessible employee, so the response can contain many entries. Use **List Company Benefits** (`list-company-benefits`) to look up valid `companyBenefitId` values. Future-enrollment records are silently omitted when the authenticated user lacks permission to view scheduled benefit changes. Current enrollment records continue to be returned. An empty `employeeBenefit` array on a known employee can mean either no enrollments or that the caller cannot view them. Note: This endpoint accepts filters inside a JSON request body on a `GET` request, which is non-standard. Some HTTP clients, proxies, and gateways may strip request bodies from GET requests, which can produce confusing missing-filter behavior. Callers experiencing validation errors should verify that the request body is being preserved. A query-parameter-based endpoint will be released in the future. OAuth Scopes: benefit ## Request body - EmployeeBenefitFilters - `filters` object, required — Scope filters for the request. At least one of `employeeId`, `companyBenefitId`, or `enrollmentStatusEffectiveDate` must be provided; none of the three is individually required, but omitting all three returns a 400 validation error. Any combination of the three is accepted. - `employeeId` integer — Return benefit enrollments for a specific employee identified by their internal employee ID. Optional unless neither `companyBenefitId` nor `enrollmentStatusEffectiveDate` is supplied. - `companyBenefitId` integer — Return benefit enrollments for a specific company benefit plan identified by its numeric ID. Optional unless neither `employeeId` nor `enrollmentStatusEffectiveDate` is supplied. - `enrollmentStatusEffectiveDate` string, date — Return benefit enrollments whose enrollment status became effective on this date. Must be in `YYYY-MM-DD` format. Optional unless neither `employeeId` nor `companyBenefitId` is supplied. ## Response `200` An object containing an employeeBenefits array, each item representing one employee's benefit enrollments. - object - `employeeBenefits` object[] — List of per-employee benefit enrollment records. - `employeeId` integer — The internal employee ID. - `payFrequency` string, nullable — The employee's current pay frequency (e.g., 'semi-monthly', 'biweekly'), or null if no pay schedule is set. - `employeeBenefit` object[] — The employee's benefit plan enrollments, including both current and future scheduled changes. - `companyBenefitId` string — The ID of the company benefit plan. - `companyBenefitName` string — The name of the company benefit plan. - `coverageLevel` string, nullable — The coverage level for this enrollment, or null if not applicable. - `deductionEndDate` string, date, nullable — The date deductions end for this enrollment (YYYY-MM-DD), or null. - `deductionStartDate` string, date, nullable — The date deductions begin for this enrollment (YYYY-MM-DD), or null. - `enrollmentStatus` 'Eligible' | 'Enrolled' | 'Waived' | 'Withdrew' | 'Terminated' | 'Ineligible' — The current or scheduled enrollment status. - `enrollmentStatusEffectiveDate` string, date — The date the enrollment status takes effect (YYYY-MM-DD). - `currencyCode` string, nullable — ISO 4217 currency code for deduction amounts, or null if not applicable. - `employeeAmount` number, nullable — The employee-paid deduction amount. - `employeeAmountType` string, nullable — The unit for employeeAmount (e.g., '%', '$'). - `employeePercentBasedOn` string, nullable — The basis for percent-based employee deductions (e.g., 'Gross'), or null. - `employeeCapAmount` number, nullable — The cap on employee deductions, or null if none. - `employeeCapAmountType` string, nullable — The unit for employeeCapAmount, or null. - `employeeAnnualMax` number, nullable — The annual maximum employee contribution, or null if none. - `companyAmount` number, nullable — The employer-paid contribution amount. - `companyAmountType` string, nullable — The unit for companyAmount (e.g., '%', '$'). - `companyPercentBasedOn` string, nullable — The basis for percent-based employer contributions (e.g., 'Gross'), or null. - `companyCapAmount` number, nullable — The cap on employer contributions, or null if none. - `companyCapAmountType` string, nullable — The unit for companyCapAmount, or null. - `companyAnnualMax` number, nullable — The annual maximum employer contribution, or null if none. - `occurrencesPerYear` integer — The number of deduction occurrences per year based on the employee's pay schedule. ## Other responses - `400` — Bad request. The request body is missing or not valid JSON, the `filters` object is missing, none of `employeeId`, `companyBenefitId`, or `enrollmentStatusEffectiveDate` was provided, or `enrollmentStatusEffectiveDate` is not in `YYYY-MM-DD` format. - `401` — Unauthorized. Invalid or missing authentication credentials. - `403` — Forbidden. The authenticated caller does not have permission to view benefit data. - `500` — Internal server error. --- [API](https://skmtc.net/bamboohr/apis/bamboohr-api.md) · [All operations](https://skmtc.net/bamboohr/apis/bamboohr-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bamboohr/bamboohr-api/revisions/19ebf391a399/schema)