Validation is necessary, but not sufficient

Each payload in these cases is individually valid, so the API accepts it. The problem is modeling: an HDHP submitted as a standard plan, carve-out prescription data stranded on a separate record, or an HRA that is not netted out of the deductible all validate cleanly but benchmark against the wrong peer group. The logic below transforms your source data so the plan is represented correctly.

Edge case 1

HDHP / HSA-eligible plan identification

HDHP and HSA-eligible plans are benchmarked separately in Bnchmrk, so correct identification and field mapping matter. In agency management systems, the fields that indicate HDHP/HSA status are often incomplete or inconsistently filled in, which makes automated identification difficult. HRA plans (edge case 3) are a distinct plan type and should not be conflated with HDHPs or HSAs.

Identifying the plan

Primary signal, plan type field: if a plan type or product type field is explicitly set to HDHP or HSA-eligible, treat it as authoritative.
Secondary signal, plan name: if the plan type field is blank, check the plan name for keywords such as “HDHP”, “HSA”, or “High Deductible”. Flag any match for review rather than submitting automatically.
HDHP plans undergo additional validation; Bnchmrk rejects (with notes) any plan that does not meet government-mandated HSA plan regulations.

Fields to set, in order

Plan type

Set type to HDHP. This is the most critical field: it tells Bnchmrk to benchmark the plan in the HDHP category rather than as a standard medical plan.

HSA account offered

Set hsa to TRUE if the employer offers an HSA account to employees. This applies whether or not the employer funds the HSA; the field only indicates that the account is available.

Employer HSA funding (if applicable)

If the employer offers an HSA account and contributes employer dollars to it, populate the annual employer contribution by tier: t1_ercdhp (Tier 1, typically Employee Only), t2_ercdhp (Tier 2, Employee + Spouse), t3_ercdhp (Tier 3, Employee + Child(ren)), and t4_ercdhp (Tier 4, Family).

If the employer does not fund the HSA, leave these fields blank. Do not populate them with zeroes.

Testing recommendation

Submit one known HDHP plan using the primary signal and one using the secondary (plan name) signal. Also test a scenario where employer HSA funding is provided, to validate the t1–t4 fields.

Edge case 2

Prescription drug carve-out plans

Some employers use a separate PBM or carrier for prescription coverage. When they do, agency management systems often hold two records for the same employer: a medical plan (with Rx fields missing or null) and a standalone Rx-only carve-out plan. The Bnchmrk API expects a single medical plan record that includes all Rx fields, so the carve-out Rx data must be merged into the medical plan before you submit.

Detect a carve-out condition

Employer level: the clearest signal is a separate Rx-only policy record. When processing an employer, first check whether a standalone Rx policy exists; if it does, flag the employer as a potential carve-out case and carry that context forward.

Plan level: for each medical plan of a carve-out employer, check whether both rx1_ded_apply and rx1_mail_ded_apply are null or missing. If both are empty, apply the carve-out Rx data to this plan. If they are already populated, the plan carries its own Rx data; leave it as-is and proceed normally.

Locate the carve-out Rx plan

Pull the standalone Rx policy identified at the employer level as the data source for the merge. If it cannot be confidently matched to the employer (for example, multiple Rx records exist), flag for manual review before proceeding.

Merge Rx data into the medical plan

Apply all available Rx field values from the carve-out policy into the medical plan record: copays, coinsurance, deductible applicability, and mail-order fields.

Do not submit the carve-out Rx policy as a standalone record. Only the merged medical plan record goes to the API.

Edge case 3

HRA plans

HRA (Health Reimbursement Arrangement) plans are the most complex edge case and are separate from HDHPs and HSAs. The logic depends on how your users enter HRA plans in their system of record; until that data entry is consistent, some steps may require manual handling.

Identify the plan as an HRA

Set hra to true. This is the foundational step; without it, none of the downstream logic applies. Identification depends on how HRA plans are tagged or named in the system of record (plan type field, plan name keywords).

Apply the HRA benefit to plan design fields

Determine the annual HRA contribution the employer provides, separately for single and family tiers, then deduct those amounts from the in-network fields before submitting:

in_ded_single — subtract the single HRA amount from the single deductible
in_ded_family — subtract the family HRA amount from the family deductible
in_max_single — subtract the single HRA amount from the single out-of-pocket maximum
in_max_family — subtract the family HRA amount from the family out-of-pocket maximum

The goal is to reflect what the employee is responsible for after the HRA benefit is applied, which is what makes the plan comparable for benchmarking.

Adjust the premium for HRA cost

Reflect the employer’s cost of the HRA in the gross premium. Determine the expected annual HRA cost per employee for each tier and add it to each gross premium field:

t1_gross — Tier 1 (typically Employee Only)
t2_gross — Tier 2 (Employee + Spouse)
t3_gross — Tier 3 (Employee + Child(ren))
t4_gross — Tier 4 (Family)

Add the HRA cost to the employer’s gross premium only. Do not add it to the employee contribution fields; the EE cost reflects what the employee pays out of pocket and is not affected by HRA funding.

Open the Field Dictionary API reference