BambooHR Benefits API: Every Endpoint, Permission, and Limit

Key takeaways

• Three benefit endpoints, company_benefit, employee_benefit, and member-benefits, became publicly available on January 23, 2026, alongside older coverage, deduction-type, and dependent endpoints.
• Calling employee_benefit without a filter returns a 400; you need at least one of employeeId, companyBenefitId, or enrollmentStatusEffectiveDate, sent in a JSON body on the GET request.
• member-benefits returns enrollment records for every covered member, employees and dependents, for one calendar year, and returns 403 unless the caller is a benefit admin.
• The API key's owning user determines what comes back: narrower permissions return fewer records, not an error.
• Benefit and dependent changes don't trigger webhooks, so freshness depends on polling member benefit events on your own schedule.
• The API reads enrollment data; it cannot write enrollment or benefit-status changes back to BambooHR.

BambooHR has returned employee records through its API for years. Benefits data hasn't kept the same pace.

Benefits platforms pulling from BambooHR hit the same wall: a stack of single-endpoint reference pages, none of which says which one answers who's covered, for what, at what cost share.

That changed, partly, on January 23, 2026, when BambooHR made three benefit endpoints public: company_benefit, employee_benefit, and member-benefits (BambooHR's Historical Changes to the API log). They sit alongside older coverage, deduction-type, and dependent endpoints that predate that date. Access runs through Basic auth with an API key, or OAuth 2.0 with the benefit scope; the dependents endpoint uses its own employee:dependent scopes.

This page maps every one of them: the verbatim path, what each returns, the filter it requires, and the permission it's gated behind, plus what's still missing and how to migrate a report-based integration onto the new endpoints. Authentication mechanics, the base URL, and pagination are covered in the BambooHR API pillar guide; this page picks up where that one stops.

Last verified against BambooHR's API reference: 2026-09-30.

What the endpoints return: plans, enrollments, coverage, and deductions

BambooHR splits plan-side benefits data across four endpoints. Two of them, company_benefit and employee_benefit, are part of the three that became public in January 2026. (The third, member-benefits, covers the people side and comes up next.) Coverage levels and deduction types were documented well before that date. Here are the exact paths and what each one returns:

Full field-level detail for each endpoint lives on BambooHR's benefits reference; this table covers what's documented at the object level.

Two details the table can't show. First, employee_benefit takes its filters in a JSON body on a GET request, which BambooHR itself calls non-standard: some HTTP clients, proxies, and gateways strip GET bodies, and the symptom is a 400 for a filter you did send. Check that the body survives the trip before you debug anything else.

curl -X GET "https://acme.bamboohr.com/api/v1/benefit/employee_benefit" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -u "APIKEY:x" \
  -d '{"filters": {"employeeId": 1234}}'

# filters takes at least one of: employeeId, companyBenefitId,
# enrollmentStatusEffectiveDate (YYYY-MM-DD)

Second, BambooHR scopes results to whoever owns the API key. Future-dated enrollment records are silently left out when that user can't view scheduled benefit changes, and an empty enrollment list on a known employee can mean either no enrollments or no permission to see them. If your record counts look thin, check the key's permissions before you check your filters.

Who's covered: member benefits and dependents

employee_benefit answers a narrower question than it sounds like it should. It returns enrollment records for employees, and the people those elections cover don't appear in it. A married employee with two kids on a family plan shows up once. Their spouse and children don't.

member-benefits (GET /api/v1/benefits/member-benefits) is built for that gap. It returns paginated enrollment records for every member, employees and dependents alike, for a given calendar year, with each dependent tied to their subscribing employee through subscriberId. It requires a four-digit calendarYear parameter, takes a pageSize from 1 to 99 (default 25; 100 or more returns a 400), and returns 403 if the calling user isn't a benefit admin.

The dependents endpoint itself, List Employee Dependents (GET /api/v1/employeedependents), filters by employeeid. Skip the filter and it returns every dependent in the company. It requires Benefits Administration permissions and the employee:dependent and employee:dependent:ssn OAuth scopes, and it returns SSNs masked (for example, xxx-xx-1234). Paired with member-benefits, it's the combination that answers who is covered, as opposed to who enrolled.

That distinction matters past the API itself. A self-insured employer reporting Form 1095-C Part III has to list every covered individual, meaning the employee plus spouse and dependents, by name, by SSN or TIN, with months of coverage for the calendar year (IRS 2025 Instructions for Forms 1094-C and 1095-C). member-benefits is the endpoint shaped like that requirement. employee_benefit isn't.

What the API still doesn't do

Three limits are worth knowing before you design around this API:

• Enrollment and benefit-status changes aren't writable through the API.
• employee_benefit returns current and scheduled-future enrollments only.
• Annual contribution limits are yours to apply.

The API reads enrollment; BambooHR states that enrollment and benefit status changes aren't supported through it. A platform that needs to push elections back into BambooHR will need a different path. Dependent records are the exception in this area: BambooHR documents Create and Update Employee Dependent endpoints, and an update replaces every field, so any field you omit is written as empty.

For past enrollments, go to member-benefits, which reports the date ranges each member held each enrollment status within a calendar year. Contribution amounts do come through on employee_benefit: each record carries the employee and employer amounts and their units, any caps and annual maximums, the deduction start and end dates, and occurrences per year. Plan-level detail such as the plan description and ACA fields sits on BambooHR's single-plan "Get a company benefit" endpoint, not the list.

HSA limits are set per calendar year: $4,400 self-only and $8,750 family for 2026, rising to $4,500 and $9,000 for 2027 (IRS Rev. Proc. 2025-19; 2027 figures per Rev. Proc. 2026-24). Checking an elected amount or an annual maximum against the right year's ceiling, and knowing when that ceiling changes, is the reading platform's job.

Keeping benefits data current: how to detect changes

BambooHR's real-time webhooks don't reach benefits. The steps below cover what to poll instead.

1. Rule out webhooks for this data: BambooHR's webhooks are real time for employee fields and custom fields, but benefits, dependents, and time off aren't monitorable, and custom tables aren't supported. Don't build a benefits sync around them.
2. Poll member benefit events: GET /api/v1/benefit/member_benefit is a separate endpoint from member-benefits (they're easy to conflate). It returns a members array covering the past year, one entry per employee or dependent, with each plan's coverage events (eligibility granted, enrolled, or loss of coverage) in date order. It's the closest thing to a benefits changelog the API offers, and it returns 403 without benefit settings access.
3. Pair it with employee change tracking: GET /employees/changed/... tracks what changed on employee records, but it doesn't cover benefit or dependent changes on its own. Run both if you need employee-field and benefits-field freshness together.
4. Set your own interval: open enrollment windows and life events land on their own schedule, so a scheduled poll is the shape this data takes. How often you run it depends on what "current" needs to mean for the platform reading it.

Moving off reports and partner syncs

Most live BambooHR integrations predate these endpoints. If yours runs on a custom report or a Marketplace partner today, the steps below trace the path onto the API directly.

1. Map your legacy report fields: GET /api/v1/custom-reports/legacy-field-map returns each legacyFieldId alongside its new fieldName. Watch the qualifier trap: legacy benefit fields map to a general field name plus a qualifier that has to be applied as a filter. Request the fieldName alone and you get every category back. For benefit plan qualifiers, BambooHR's operator is includes, with the value wrapped in an array.
2. Map your legacy report IDs: GET /api/v1/custom-reports/legacy-id-map maps old custom report IDs to their migrated equivalents, for use with Get Report by ID.
3. Consider the dataset route for broad, report-style reads: Get Data from Dataset v2 accepts a benefit dataset, with fields validated through Get Fields from Dataset. Page size defaults to 100 and maxes at 1000; combining filter operators returns a 422, and dataset access needs elevated permissions of its own (403 otherwise). It's a bridge for report-shaped queries, separate from the benefit endpoints above.

Benefits administration vendors also connect through BambooHR's Marketplace, which lists over 150 integrations. Partner syncs there can run as scheduled, one-directional pulls, which carries the same file-versus-API tradeoff covered in file delivery vs. direct API access: a scheduled pull is only as fresh as its last run.

Reading BambooHR benefits alongside every other HRIS

Everything above is BambooHR-specific: its own paths, its own filters, its own permission model. Build the same read path against Workday, Rippling, or ADP, and you're relearning all of it, per system.

Bindbee is built to absorb that repetition. Instead of a separate map for every HRIS, benefits data comes back in the same four Bindbee models whatever system it came from: Employer Benefit for the plan catalog, Benefit for each employee's enrollment and contributions, Dependent Benefit for which plan covers a dependent, and Benefit Coverage for how much each covered person is insured for. Bindbee's docs list all four as supported for BambooHR, along with the Dependent model.

Under the hood, each connector still runs on a schedule. Bindbee's BambooHR connector syncs every 24 hours by default, adjustable on request, and Bindbee's webhooks notify you when a sync starts, finishes, or fails, or finds created or updated records. That's the polling design from earlier in this page, run on Bindbee's schedule instead of yours.

Two mechanisms handle what the unified models don't cover:

• Custom fields map any value in BambooHR's raw payload onto a unified model with a JMESPath expression.
• Passthrough sends a raw request to BambooHR's own API, using the credentials Bindbee already holds, and returns BambooHR's response untouched.

The BambooHR connector is an API connector: Bindbee calls BambooHR's API with the credentials your customer authorizes, with no screen scraping. That matters for benefits data because member and dependent records carry coverage details and SSNs. Bindbee is SOC 2 Type II and HIPAA compliant, with a BAA available.

If BambooHR is one of several HRIS systems your platform reads benefits from, book a demo to see the connection flow. The endpoint map earlier in this page still applies to every one of those calls. What changes is who has to remember it.

Frequently asked questions

Do I need a BambooHR admin account to read benefits through the API?

Access follows the BambooHR user behind the credential: the API key's owner, or the user who approved the OAuth connection. BambooHR's benefits GET requests require that user to have benefit settings access; coverages, deduction types, and dependents need Benefits Administration permissions; and member-benefits requires a benefit admin, returning 403 otherwise. Check the key owner's permissions in BambooHR before assuming your integration's filters are the problem.

Can I enroll an employee or change a benefit election through the BambooHR API?

No. The API reads enrollment and benefit-status data; it doesn't accept writes to change either one. You can create and update dependent records, which is the one writable piece of BambooHR's benefits area.

Does the BambooHR MCP server or AI connector replace the benefits API for integrations?

No. BambooHR's MCP server connects AI assistants such as Claude and ChatGPT to a BambooHR account, runs in beta, and enforces the connecting user's existing BambooHR permissions. It isn't built as a scheduled sync path into another platform. For an integration, the REST endpoints covered on this page, polled on your own interval, are the right building blocks.

Which BambooHR endpoint returns dependents?

List Employee Dependents, GET /api/v1/employeedependents, filtered by employeeid. It needs Benefits Administration permissions and the employee:dependent OAuth scopes, and it returns SSNs masked. Skip the filter and it returns every dependent in the company.

Why does employee_benefit return a 400 when I sent a filter?

The endpoint takes its filters object in a JSON body on a GET request, with at least one of employeeId, companyBenefitId, or enrollmentStatusEffectiveDate. Some HTTP clients, proxies, and gateways strip GET bodies, so check that the body survives the trip.