---
title: "Health-plan comparison — HDHP+HSA vs PPO total cost"
method: POST
path: "/v1/benefits/health-plan"
tags: ["Healthcare"]
---

# Health-plan comparison — HDHP+HSA vs PPO total cost

`POST /v1/benefits/health-plan`

## Request

- Base URL: `https://api.numeratica.com`
- URL: `https://api.numeratica.com/v1/benefits/health-plan`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Compares the total annual cost of a high-deductible health plan with an HSA against a traditional PPO, for an expected level of medical spending. Each plan's cost is its premium plus the member's cost-sharing (spend up to the deductible, then coinsurance, capped at the out-of-pocket max); the HDHP nets out the employer HSA seed and the tax saving on the HSA contribution, and the PPO nets any health-FSA tax saving. Returns each plan's cost breakdown, the recommendation, and the difference. Deterministic; not insurance advice.

## Request body

- HealthPlanRequest
  - `expected_medical_spend` number, required: Expected covered claims for the year.
  - `marginal_tax_rate` number, required: For pre-tax HSA/FSA savings (income + FICA).
  - `hdhp` HealthPlanDesign, required
    - `premium` number: Annual employee premium.
    - `deductible` number
    - `oop_max` number: Out-of-pocket maximum (>= deductible).
    - `coinsurance` number: Member share after the deductible.
  - `ppo` HealthPlanDesign, required
    - `premium` number: Annual employee premium.
    - `deductible` number
    - `oop_max` number: Out-of-pocket maximum (>= deductible).
    - `coinsurance` number: Member share after the deductible.
  - `employer_hsa_seed` number: Employer's HSA contribution (free money; HDHP).
  - `hsa_contribution` number: Employee HSA contribution (its tax saving reduces net cost).
  - `ppo_fsa_contribution` number: A PPO health-FSA contribution (its tax saving reduces net cost).

## Response `200`

The plan-cost comparison

- HealthPlanResponse
  - `result_id` string
  - `engine_version` string
  - `inputs` HealthPlanRequest
    - `expected_medical_spend` number, required: Expected covered claims for the year.
    - `marginal_tax_rate` number, required: For pre-tax HSA/FSA savings (income + FICA).
    - `hdhp` HealthPlanDesign, required
      - `premium` number: Annual employee premium.
      - `deductible` number
      - `oop_max` number: Out-of-pocket maximum (>= deductible).
      - `coinsurance` number: Member share after the deductible.
    - `ppo` HealthPlanDesign, required
      - `premium` number: Annual employee premium.
      - `deductible` number
      - `oop_max` number: Out-of-pocket maximum (>= deductible).
      - `coinsurance` number: Member share after the deductible.
    - `employer_hsa_seed` number: Employer's HSA contribution (free money; HDHP).
    - `hsa_contribution` number: Employee HSA contribution (its tax saving reduces net cost).
    - `ppo_fsa_contribution` number: A PPO health-FSA contribution (its tax saving reduces net cost).
  - `result` object
    - `hdhp` HealthPlanCost
      - `premium` number
      - `member_care` number: Cost-sharing paid on the expected spend.
      - `tax_savings` number: HSA (HDHP) or FSA (PPO) pre-tax saving.
      - `employer_seed` number: HDHP only.
      - `net_cost` number: premium + member care − seed − tax savings.
    - `ppo` HealthPlanCost
      - `premium` number
      - `member_care` number: Cost-sharing paid on the expected spend.
      - `tax_savings` number: HSA (HDHP) or FSA (PPO) pre-tax saving.
      - `employer_seed` number: HDHP only.
      - `net_cost` number: premium + member care − seed − tax savings.
    - `recommended` 'hdhp' | 'ppo' | 'either'
    - `savings` number: Net-cost difference (absolute).
    - `hsa_contribution` number: Echoed — it also builds a tax-advantaged balance beyond this year.
  - `disclaimer` string

## Other responses

- `400`: Invalid request
- `401`: Missing or invalid API key.
- `405`: Method not allowed
- `429`: The key's per-minute request budget is exceeded. Retry after the delay in the Retry-After header.
- `503`: A dependency (e.g. the key store) is temporarily unavailable, or the request exceeded its compute deadline. Retryable.

---

[API](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api.md) · [All operations](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api/llms.txt) · [OpenAPI document](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api/revisions/075bcfbd1ebf?raw)