Skip to main content
Four models carry benefits data with names close enough that picking the wrong one is easy, and a wrong pick returns a plausible number rather than an error. Each answers for a different party - the employer, one employee, one dependent, or one covered person.

​
The models

An employer benefit is a catalog entry that exists whether or not anyone enrolls. A benefit is one employee’s enrollment in it. Benefit coverage is BETA - field names and shapes can still change, so pin what you depend on.
A dependent is not a benefits model. It is a person attached to an employee, read from Get Dependents and covered in Employee data. Dependent benefit is that person’s coverage, not the person.

​
How they connect

Benefit coverage attaches to the enrollment. Dependent benefit attaches to the plan. So there is no direct link from a dependent’s coverage to the employee’s enrollment in the same plan - join both on employer_benefit, then reach the person through the dependent’s own employee relation. The employee pays for the plan, so dependent benefit carries no money at all - contributions sit on the enrollment, and a dependent’s coverage extends it rather than being a separate financial record. The employer benefit also holds payroll_codes and deduction_code, which is how a deduction line on a payroll run matches back to the plan - by ID, not by comparing code strings. Both fields can be empty, so check before relying on the link - see Payroll.

​
How many per employee

Amounts are not on the enrollment. Read only the benefit and you get the contribution and the tier, no insured sums, and nothing to tell you they are missing. Where a plan insures different amounts for the employee, the spouse and each child, each covered person gets a benefit coverage record. Enrollments accumulate rather than update. An employee in their third year has three medical enrollments, not one record edited twice, so an unfiltered read returns history rather than what is true now. Two dates on one enrollment are not the same day. A plan elected during open enrollment carries a start_date at election and an effective_date at the plan year boundary. Renewal also creates new plan records instead of editing old ones, so a plan ID stored last year will not resolve this year.

​
What you can write

All four models are read-only. Enrollment changes happen in the source system and reach you on the next sync.