> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bindbee.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Read Benefit Enrollments

> Read which plans an employer offers and who is enrolled in them.

Employer benefits are the plans an employer offers, and benefits are the enrollments in them. A dependent is only covered when a dependent benefit says so.

## What you'll use

**Models** - [employer benefit](/hris/employer-benefits/get-employer-benefits), [benefit](/hris/benefits/get-benefits), [dependent](/hris/dependents/get-dependents), [dependent benefit](/hris/dependent-benefits/get-dependent-benefits)

<Info>
  **Before you start**

  * The connector has synced, and the customer's benefits module is in scope.
</Info>

## Steps

<Steps>
  <Step title="Read the plans the employer offers">
    ```bash theme={null}
    curl --request GET \
      --url 'https://api.bindbee.dev/api/hris/v1/employer-benefits?page_size=200' \
      --header 'Authorization: Bearer <BINDBEE_API_KEY>' \
      --header 'X-Connector-Token: <CONNECTOR_TOKEN>'
    ```

    Filter with `benefit_plan_category` to narrow to medical, dental and so on.

    **Result:** The plan catalog for this customer.
  </Step>

  <Step title="Read enrollments">
    ```bash theme={null}
    curl --request GET \
      --url 'https://api.bindbee.dev/api/hris/v1/benefits?employee_id=<EMPLOYEE_ID>&page_size=200' \
      --header 'Authorization: Bearer <BINDBEE_API_KEY>' \
      --header 'X-Connector-Token: <CONNECTOR_TOKEN>'
    ```

    Filter on `employee_id`, `employer_benefit_id`, `benefit_plan_category` or `coverage_tier`.

    To reconcile these against a customer's own totals, see [Record counts](/guides/troubleshooting/record-counts).

    **Result:** Enrollment records linking employees to plans.
  </Step>

  <Step title="Scope the period with the right date filter">
    | Filter pair                                 | Bounds                            |
    | ------------------------------------------- | --------------------------------- |
    | `start_date_from` / `start_date_to`         | When the enrollment record starts |
    | `end_date_from` / `end_date_to`             | When it ends                      |
    | `effective_date_from` / `effective_date_to` | When coverage takes effect        |

    A plan elected during open enrollment starts on election and becomes effective at the plan year boundary, so the two filters return different sets.

    Enrollments accumulate, so an unfiltered read returns the full history.

    **Result:** Records scoped to the period you mean.
  </Step>

  <Step title="Read dependents and their coverage separately">
    ```bash theme={null}
    # who is a dependent
    curl --request GET \
      --url 'https://api.bindbee.dev/api/hris/v1/dependents?employee_id=<EMPLOYEE_ID>&page_size=200' \
      --header 'Authorization: Bearer <BINDBEE_API_KEY>' \
      --header 'X-Connector-Token: <CONNECTOR_TOKEN>'

    # what they are covered under
    curl --request GET \
      --url 'https://api.bindbee.dev/api/hris/v1/dependent-benefits?dependent_id=<DEPENDENT_ID>&page_size=200' \
      --header 'Authorization: Bearer <BINDBEE_API_KEY>' \
      --header 'X-Connector-Token: <CONNECTOR_TOKEN>'
    ```

    Build coverage from dependent benefits, and use dependents for details like `date_of_birth` and `relationship`.

    **Result:** The dependents actually enrolled.
  </Step>
</Steps>

<Note>
  Enrollment tells you the plan and the contribution, not the sum insured. For amounts, and for which people a plan covers, read benefit coverage - see [Read benefit coverage](/get-started/use-cases/read-benefit-coverage).
</Note>

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Benefits return nothing though the customer has enrollments">
    Benefits are frequently a separately licensed module with its own access grant, and several platforms return an empty set rather than an error. See [Origin-system errors](/guides/troubleshooting/errors#origin-system-errors), then confirm the model is in scope for this connector.
  </Accordion>

  <Accordion title="Dependents exist but no dependent benefits">
    Either they are not enrolled, or dependent coverage is not exposed on this integration. Check `raw_data` on a dependent you know is covered - see [Inspect raw data](/guides/reading-writing/raw-data).
  </Accordion>
</AccordionGroup>

## Related

* [Benefits](/guides/data-models/benefits) - the four models and how they link
* [Read benefit coverage](/get-started/use-cases/read-benefit-coverage) - the amounts behind an enrollment
* [Employee data](/guides/data-models/employee-data) - where dependents live