---
title: "Filing-status comparator — MFJ vs MFS + marriage penalty/bonus"
method: POST
path: "/v1/tax/filing-status"
tags: ["Tax"]
---

# Filing-status comparator — MFJ vs MFS + marriage penalty/bonus

`POST /v1/tax/filing-status`

## Request

- Base URL: `https://api.numeratica.com`
- URL: `https://api.numeratica.com/v1/tax/filing-status`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

For a married couple, compares total federal tax filing jointly (one combined return) vs married-filing-separately (two returns), and reports the marriage penalty or bonus (the joint tax vs what the two would owe as single filers). Runs the tax engine five times. On base tax MFJ is essentially never worse than MFS; the value is quantifying the gap and the marriage effect. MFS credit disallowances (EITC, education, dependent-care) are not modeled. Deterministic; not tax advice.

## Request body

- FilingStatusRequest
  - `tax_year` 2025 | 2026, required
  - `spouse_a` FilingStatusSpouse, required
    - `ordinary_income` number
    - `qualified_income` number: LTCG + qualified dividends.
    - `itemized_deductions` number: Used if it exceeds the standard deduction.
    - `wages` number: For the Additional Medicare Tax (threshold differs by status).
  - `spouse_b` FilingStatusSpouse, required
    - `ordinary_income` number
    - `qualified_income` number: LTCG + qualified dividends.
    - `itemized_deductions` number: Used if it exceeds the standard deduction.
    - `wages` number: For the Additional Medicare Tax (threshold differs by status).

## Response `200`

The MFJ-vs-MFS comparison and marriage effect

- FilingStatusResponse
  - `result_id` string
  - `engine_version` string
  - `inputs` FilingStatusRequest
    - `tax_year` 2025 | 2026, required
    - `spouse_a` FilingStatusSpouse, required
      - `ordinary_income` number
      - `qualified_income` number: LTCG + qualified dividends.
      - `itemized_deductions` number: Used if it exceeds the standard deduction.
      - `wages` number: For the Additional Medicare Tax (threshold differs by status).
    - `spouse_b` FilingStatusSpouse, required
      - `ordinary_income` number
      - `qualified_income` number: LTCG + qualified dividends.
      - `itemized_deductions` number: Used if it exceeds the standard deduction.
      - `wages` number: For the Additional Medicare Tax (threshold differs by status).
  - `result` object
    - `mfj_tax` number: Total federal tax filing jointly.
    - `mfs_tax_total` number: Spouse A + spouse B filing separately.
    - `mfs_tax_spouse_a` number
    - `mfs_tax_spouse_b` number
    - `recommended` 'mfj' | 'mfs' | 'either'
    - `separate_saving` number: MFJ − MFS (positive ⇒ MFS is cheaper).
    - `single_tax_total` number: What the two would owe as single filers.
    - `marriage_penalty_or_bonus` number: MFJ − single total (>0 penalty, <0 bonus).
    - `marriage_effect` 'penalty' | 'bonus' | 'neutral'
  - `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)