What you’ll use
Models - employee, dependent, dependent benefit, benefit, employer benefit Events -connector_data_modified, connector_synced
Before you start
- The customer’s benefits module is in scope, and
date_of_birthis available - it is commonly gated behind a separate sensitive-data permission.
Steps
1
Read who is recorded as a dependent
2
Read who is actually covered
3
Page both collections fully
Both are paginated. A partial walk understates coverage, which is the direction that causes problems.Follow the cursor until it stops coming back, and don’t stop on a short page - see Pagination.Result: Complete sets, not first pages.
4
Cross-check against the coverage tier
An employee on a family tier with no dependent records is a data-quality signal worth surfacing.Compare
coverage_tier on the enrollment against the number of covered dependents you found. Report the mismatch rather than reconciling it silently - the discrepancy is usually real and belongs with the customer.Result: Disagreements surfaced instead of averaged away.5
Map attributes the model doesn't carry
Beneficiary designations, allocation percentages, and relationship detail are frequently in the raw payload but not unified.Find the path with the raw-data endpoint, then map it - see Inspect raw data. Read the results with
include_custom_fields=true.Result: The attributes your file format needs.6
Subscribe to changes on both models
Subscribe to
connector_data_modified, not just employee_data_changed - dependent changes may surface under either.Re-read dependents and dependent benefits whenever the employee changes. modified_after is per model, so an employee changing does not mark their dependents as changed - see modified_after.Result: Coverage that stays current as families change.Constraints specific to this combination
Existence is not coverage. A dependent record means the employee has recorded that person. A dependent benefit means they’re enrolled in a specific plan. Employees commonly record dependents who are covered under a spouse’s plan, or who were dropped at a prior enrollment. Build coverage from dependent benefits and use dependents only for demographics - counting dependents as covered lives is the standard cause of an eligibility file with too many people on it. Dependents and beneficiaries are different concepts. A dependent is covered under a health plan; a beneficiary receives a life or retirement benefit and is often neither covered nor a dependent. Most HRIS platforms model them separately or conflate them inconsistently. Checkraw_data to see how the specific platform distinguishes them before assuming the dependent model covers both.
Coverage tier and dependent records disagree more often than they should. An employee on an employee-plus-family tier with no dependent records is common - the tier was elected in benefits administration while dependent details live elsewhere, or were never entered. Treat a mismatch as a data-quality signal to surface, not as something to reconcile silently.
Relationship vocabularies are customer-specific. Spouse, domestic partner, child, stepchild, and legal ward vary in naming and availability across platforms and customer configurations. Map them per connector rather than assuming a standard set.
Dependent changes fire under the parent employee. A dependent added or removed may surface as a change on the employee rather than on the dependent model. Subscribe to data model change rather than employee model change alone, and re-read dependents whenever the employee changes - see modified_after for why the filter alone won’t catch related-model changes.
Frequently Asked Questions
The eligibility file has too many lives on it
The eligibility file has too many lives on it
Dependents were counted as covered. Build the list from dependent benefits.
Dependents exist but no dependent benefits
Dependents exist but no dependent benefits
Either they genuinely aren’t enrolled, or the integration doesn’t expose dependent coverage. Check
raw_data on someone you know is covered - see Inspect raw data.date_of_birth is null for every dependent
date_of_birth is null for every dependent
A sensitive-data permission rather than absence. See Origin-system errors.
A dependent was added but nothing fired
A dependent was added but nothing fired
The change may have surfaced on the employee rather than the dependent. Re-read dependents whenever the employee changes.