---
title: "Taxation of Social Security benefits (§86) + the tax torpedo"
method: POST
path: "/v1/tax/social-security-benefits"
tags: ["Tax"]
---

# Taxation of Social Security benefits (§86) + the tax torpedo

`POST /v1/tax/social-security-benefits`

## Request

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

The federally taxable portion of Social Security retirement benefits under IRC §86 (the provisional / "combined income" worksheet, IRS Pub. 915): provisional income = other income (AGI excluding SS) + tax-exempt interest + ½ of benefits, taxed in two tiers (up to 50%, then up to 85%) above the statutory base amounts ($25k/$34k single, $32k/$44k joint). Surfaces the "tax torpedo" — the band where each extra dollar of other income also drags $0.50 or $0.85 of benefits into tax, so an optional marginal_ordinary_rate yields the true effective marginal rate (e.g. a 22% bracket becomes 40.7%). The §86 thresholds are statutory and not inflation-indexed, so this engine is not year-keyed. Deterministic; not tax advice.

## Request body

- SSTaxRequest
  - `filing_status` 'single' | 'mfj' | 'mfs' | 'hoh', required: mfs assumes lived-with-spouse (§86 $0 base); a separated filer should use single.
  - `social_security_benefits` number, required: Gross annual Social Security benefit.
  - `other_income` number, required: AGI excluding Social Security (pensions, IRA/401k distributions, wages, gains, etc.).
  - `tax_exempt_interest` number: Optional. Added back into provisional income under §86(b)(2).
  - `marginal_ordinary_rate` number: Optional. When set, the response reports the tax-torpedo effective marginal rate on the next dollar of other income.

## Response `200`

Taxable Social Security + torpedo metrics

- SSTaxResponse
  - `result_id` string
  - `engine_version` string
  - `inputs` SSTaxRequest
    - `filing_status` 'single' | 'mfj' | 'mfs' | 'hoh', required: mfs assumes lived-with-spouse (§86 $0 base); a separated filer should use single.
    - `social_security_benefits` number, required: Gross annual Social Security benefit.
    - `other_income` number, required: AGI excluding Social Security (pensions, IRA/401k distributions, wages, gains, etc.).
    - `tax_exempt_interest` number: Optional. Added back into provisional income under §86(b)(2).
    - `marginal_ordinary_rate` number: Optional. When set, the response reports the tax-torpedo effective marginal rate on the next dollar of other income.
  - `result` object
    - `provisional_income` number: other_income + tax_exempt_interest + ½ benefits.
    - `base_1` number: §86 first threshold for the filing status.
    - `base_2` number: §86 second threshold.
    - `taxable_social_security` number: §86(a) taxable portion (≤ 85% of benefits).
    - `nontaxable_social_security` number
    - `taxable_percent` number: taxable / benefits (0…0.85).
    - `tier` integer: 0 none · 1 50% band · 2 85% band · 3 capped at 85%.
    - `marginal_inclusion_rate` number: §86 benefits pulled into tax by the next dollar of other income (0, 0.5, or 0.85).
    - `effective_marginal_rate` number: marginal_ordinary_rate × (1 + marginal_inclusion_rate); the tax torpedo. 0 if no rate supplied.
  - `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)