> ## 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 Coverage

> Find where an employee's existing cover leaves a gap.

You guide employees through the benefits their employer already offers, and that guidance only holds if you know what each person is covered for today. Benefit coverage carries the amount someone is insured for and who that amount covers, which is what turns a gap into a specific recommendation. It hangs off an enrollment rather than replacing it, so every coverage row points back at the benefit it belongs to.

## What you'll use

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

<Info>
  **Before you start**

  * The connector has synced, and the customer's benefits module is in scope.
  * The integration returns benefit coverage - see [Model availability](/get-started/model-availability).
</Info>

## Steps

<Steps>
  <Step title="Read coverage with its enrollment expanded">
    ```bash theme={null}
    curl -G https://api.bindbee.dev/api/hris/v1/benefit-coverages \
      --header 'Authorization: Bearer <BINDBEE_API_KEY>' \
      --header 'X-Connector-Token: <CONNECTOR_TOKEN>' \
      --data-urlencode 'expand=benefit' \
      --data-urlencode 'page_size=200'
    ```

    Expanding `benefit` returns the enrollment inline, which saves a second pass over the benefits endpoint. To narrow to one enrollment, filter on `benefit_id`.

    The endpoint takes no date filters, so scope to what is in force from the expanded enrollment: drop rows whose `end_date` has passed, and rows whose `effective_date` is still ahead.

    **Result:** Coverage amounts with the plan each one belongs to.
  </Step>

  <Step title="Work out who each amount covers">
    `amount` is the resolved coverage figure, and the members on the record define what it applies to. `is_employee_covered` says whether the employee is included, and `covered_dependents` lists the dependent IDs the amount extends to.

    One enrollment can produce several coverage rows. A plan insuring each member for a separate figure returns a row per member, while a plan with a single composite figure returns one row carrying the employee and every covered dependent together.

    | Row shape       | `is_employee_covered` | `covered_dependents`       |
    | --------------- | --------------------- | -------------------------- |
    | Employee only   | `true`                | Empty                      |
    | Dependents only | `false`               | The covered dependent IDs  |
    | Composite       | `true`                | Every covered dependent ID |

    **Result:** Each amount attached to the people it insures.
  </Step>

  <Step title="Turn the gap into a recommendation">
    `covered_dependents` holds IDs. Read [dependents](/hris/dependents/get-dependents) for the ages and relationships behind them, then compare that against every dependent the employee has on record.

    A household insured for less than it needs is the gap, and a family of four sitting on an employee-only row is the clearest version of it. What closes it is a supplemental option already in the employer's menu, such as critical illness, hospital indemnity or accident cover.

    `coverage_tier` on the expanded enrollment is an enum, and a source system can return a value outside the documented set - see [Enum values](/guides/reading-writing/enum-values).

    **Result:** Employees whose existing cover leaves a measurable gap.
  </Step>
</Steps>

<Note>
  Coverage changes at open enrollment, on qualifying life events, and whenever a dependent is added. Re-read with `modified_after` instead of refetching the population - see [modified\_after](/guides/reading-writing/reading-data/modified-after).
</Note>

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="benefit-coverages returns an empty collection">
    Check [Model availability](/get-started/model-availability) for this integration, then confirm the model is in scope for the connector.
  </Accordion>

  <Accordion title="A coverage row has no matching enrollment">
    Join on `benefit`, not on the employee. Going via the employee produces cross-products where someone holds several plans.
  </Accordion>

  <Accordion title="Amounts look implausible">
    Check `currency` before comparing, since a population spread across countries returns several. Then check you are reading coverage rather than contribution: `employee_contribution` and `company_contribution` sit on the enrollment, `amount` sits on the coverage.
  </Accordion>

  <Accordion title="A row shows nobody covered">
    `is_employee_covered` is `false` and `covered_dependents` is empty, so no member is attached to the amount. Report it with the connector ID and the coverage `id`.
  </Accordion>
</AccordionGroup>

## Related

* [Read benefit enrollments](/get-started/use-cases/read-benefit-enrollments) - the plans and enrollments coverage hangs off
* [Benefits](/guides/data-models/benefits) - the four benefit models and how they link
* [Benefit Coverage endpoints](/hris/benefit-coverages/get-benefit-coverages) - the API reference