---
title: "Income & tax at the first spouse's death"
method: POST
path: "/v1/retirement/survivor-scenario"
tags: ["Retirement income"]
---

# Income & tax at the first spouse's death

`POST /v1/retirement/survivor-scenario`

## Request

- Base URL: `https://api.numeratica.com`
- URL: `https://api.numeratica.com/v1/retirement/survivor-scenario`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Models the survivor's cliff: the surviving spouse keeps the larger Social Security benefit (the smaller stops — the SS survivor step-down), loses the deceased's own income, and switches from MFJ to single filing, whose narrower brackets tax the remaining income harder (bracket compression). Composes the tax and (optional) IRMAA engines. Deterministic.

## Request body

- SurvivorRequest
  - `tax_year` 2025 | 2026, required
  - `deceased_spouse` 'a' | 'b': Which spouse dies first.
  - `spouse_a` SurvivorSpouse, required
    - `social_security` number: Annual SS benefit.
    - `other_income` number: The spouse's own ordinary income; stops at their death.
  - `spouse_b` SurvivorSpouse, required
    - `social_security` number: Annual SS benefit.
    - `other_income` number: The spouse's own ordinary income; stops at their death.
  - `shared_ordinary_income` number: Income that continues to the survivor (portfolio, joint annuity).
  - `on_medicare` boolean: Report IRMAA surcharges in both scenarios.

## Response `200`

Survivor comparison

- SurvivorResponse
  - `result_id` string
  - `engine_version` string
  - `inputs` SurvivorRequest
    - `tax_year` 2025 | 2026, required
    - `deceased_spouse` 'a' | 'b': Which spouse dies first.
    - `spouse_a` SurvivorSpouse, required
      - `social_security` number: Annual SS benefit.
      - `other_income` number: The spouse's own ordinary income; stops at their death.
    - `spouse_b` SurvivorSpouse, required
      - `social_security` number: Annual SS benefit.
      - `other_income` number: The spouse's own ordinary income; stops at their death.
    - `shared_ordinary_income` number: Income that continues to the survivor (portfolio, joint annuity).
    - `on_medicare` boolean: Report IRMAA surcharges in both scenarios.
  - `result` object
    - `both_alive` SurvivorScenarioLine
      - `filing_status` string
      - `ordinary_income` number
      - `tax` number
      - `effective_rate` number
      - `marginal_rate` number
      - `irmaa_surcharge` number: Annual; 0 unless on Medicare.
      - `after_tax_income` number
    - `survivor` SurvivorScenarioLine
      - `filing_status` string
      - `ordinary_income` number
      - `tax` number
      - `effective_rate` number
      - `marginal_rate` number
      - `irmaa_surcharge` number: Annual; 0 unless on Medicare.
      - `after_tax_income` number
    - `social_security_lost` number: The smaller SS benefit, which stops.
    - `income_drop` number
    - `tax_change` number: Survivor tax minus both-alive tax.
    - `after_tax_income_drop` number
  - `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)