---
title: "ACA premium-tax-credit withdrawal optimizer (pre-65 early retirees)"
method: POST
path: "/v1/healthcare/aca-optimize"
tags: ["Healthcare"]
---

# ACA premium-tax-credit withdrawal optimizer (pre-65 early retirees)

`POST /v1/healthcare/aca-optimize`

## Request

- Base URL: `https://api.numeratica.com`
- URL: `https://api.numeratica.com/v1/healthcare/aca-optimize`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

For a pre-65 early retiree, finds the account-withdrawal mix that funds a spending need while minimizing MAGI — maximizing the ACA premium tax credit and staying under the 400%-of-FPL subsidy cliff (which returns in 2026). Each source adds different MAGI per dollar (Roth 0, taxable only the gain fraction, tax-deferred full), so the MAGI-optimal order is Roth → taxable → tax-deferred. Compares that plan to a naive proportional draw and reports each plan's draw mix / MAGI / FPL% / PTC / net premium / income tax / total cost, plus the savings, cliff headroom, and any shortfall. Composes the healthcare and tax engines. Deterministic; not tax advice.

## Request body

- ACAOptimizeRequest
  - `tax_year` 2025 | 2026, required: ACA-supported years (2026 reintroduces the 400%-FPL cliff).
  - `filing_status` 'single' | 'mfj' | 'mfs' | 'hoh', required
  - `age` integer, required: Under 65 (the ACA marketplace is the pre-Medicare context).
  - `household_size` integer, required
  - `state` string: FPL region: "AK" / "HI", or empty for the 48 contiguous states + DC.
  - `benchmark_annual_premium` number, required: Second-lowest-cost Silver plan, annual.
  - `spending_need` number, required: Gross withdrawal to fund from the accounts.
  - `taxable_balance` number
  - `taxable_gain_fraction` number: Share of a taxable withdrawal that is realized LTCG.
  - `deferred_balance` number: Traditional IRA/401(k) — withdrawals are ordinary income.
  - `roth_balance` number: Roth — withdrawals add no MAGI.
  - `base_income` number: Other ordinary income already in MAGI (pension, interest).
  - `tax_exempt_interest` number: Added to MAGI for the ACA.

## Response `200`

The optimized vs naive draw comparison

- ACAOptimizeResponse
  - `result_id` string
  - `engine_version` string
  - `inputs` ACAOptimizeRequest
    - `tax_year` 2025 | 2026, required: ACA-supported years (2026 reintroduces the 400%-FPL cliff).
    - `filing_status` 'single' | 'mfj' | 'mfs' | 'hoh', required
    - `age` integer, required: Under 65 (the ACA marketplace is the pre-Medicare context).
    - `household_size` integer, required
    - `state` string: FPL region: "AK" / "HI", or empty for the 48 contiguous states + DC.
    - `benchmark_annual_premium` number, required: Second-lowest-cost Silver plan, annual.
    - `spending_need` number, required: Gross withdrawal to fund from the accounts.
    - `taxable_balance` number
    - `taxable_gain_fraction` number: Share of a taxable withdrawal that is realized LTCG.
    - `deferred_balance` number: Traditional IRA/401(k) — withdrawals are ordinary income.
    - `roth_balance` number: Roth — withdrawals add no MAGI.
    - `base_income` number: Other ordinary income already in MAGI (pension, interest).
    - `tax_exempt_interest` number: Added to MAGI for the ACA.
  - `result` object
    - `optimized` ACADrawPlan: One withdrawal plan and its resulting tax + premium picture (annual dollars).
      - `draw_roth` number
      - `draw_taxable` number
      - `draw_deferred` number
      - `magi` number
      - `fpl_percent` number
      - `premium_tax_credit` number
      - `net_premium` number: Benchmark minus PTC.
      - `income_tax` number: Federal income tax + NIIT on the draws.
      - `total_cost` number: income_tax + net_premium.
      - `above_cliff` boolean: At/above 400% FPL with no subsidy (2026+).
    - `naive` ACADrawPlan: One withdrawal plan and its resulting tax + premium picture (annual dollars).
      - `draw_roth` number
      - `draw_taxable` number
      - `draw_deferred` number
      - `magi` number
      - `fpl_percent` number
      - `premium_tax_credit` number
      - `net_premium` number: Benchmark minus PTC.
      - `income_tax` number: Federal income tax + NIIT on the draws.
      - `total_cost` number: income_tax + net_premium.
      - `above_cliff` boolean: At/above 400% FPL with no subsidy (2026+).
    - `savings` number: Naive total cost minus optimized total cost.
    - `cliff_magi` number: The 400%-of-FPL MAGI threshold.
    - `cliff_headroom` number: cliff_magi minus the optimized MAGI (negative = unavoidably over).
    - `shortfall` number: spending_need not coverable from the balances (0 if funded).
  - `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)