List Employee Benefits

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

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params

Filters that scope the results. The filters object is required, and at least one of employeeId, companyBenefitId, or enrollmentStatusEffectiveDate must be provided. Any combination of the three is accepted.

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.

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.

Language
Credentials
:
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json