---
title: "Disability-income protection gap analysis"
method: POST
path: "/v1/insurance/disability-needs"
tags: ["Insurance"]
---

# Disability-income protection gap analysis

`POST /v1/insurance/disability-needs`

## Request

- Base URL: `https://api.numeratica.com`
- URL: `https://api.numeratica.com/v1/insurance/disability-needs`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Sizes the gap between the income a household needs if the earner is disabled and what existing coverage pays after tax. Its main value is netting benefits correctly: an employer-paid group LTD benefit is taxable, so "60% of pay" nets far less at a given marginal rate, while an individually-owned (after-tax) policy pays tax-free. Reports the monthly target (a replacement fraction of income, or an essential-expense floor), the net value of group / individual / SSDI benefits, the remaining monthly gap and the additional benefit to buy, plus the current replacement ratio. Deterministic; not insurance advice.

## Request body

- DisabilityNeedsRequest
  - `gross_annual_income` number, required: The income to protect.
  - `target_replacement_fraction` number: Share of gross income to replace. Omit for 0.65.
  - `essential_monthly_expenses` number: When > 0, overrides the fractional target with a monthly floor.
  - `employer_group_fraction` number: Fraction of income the group LTD plan replaces (e.g. 0.60).
  - `employer_group_monthly_max` number: Group benefit cap (0 = uncapped).
  - `employer_paid_premium` boolean: True ⇒ the group benefit is taxable.
  - `marginal_tax_rate` number: Applied to any taxable benefit.
  - `individual_monthly_benefit` number: Individually-owned policy benefit (tax-free).
  - `ssdi_monthly_benefit` number: Estimated SSDI monthly benefit (treated as tax-free).
  - `ssdi_offsets_group` boolean: Whether the group LTD contract reduces its benefit dollar-for-dollar by SSDI (the common 'other income' offset). Default true; set false for a rare non-offsetting plan or when there is no group coverage.

## Response `200`

The protection-gap analysis

- DisabilityNeedsResponse
  - `result_id` string
  - `engine_version` string
  - `inputs` DisabilityNeedsRequest
    - `gross_annual_income` number, required: The income to protect.
    - `target_replacement_fraction` number: Share of gross income to replace. Omit for 0.65.
    - `essential_monthly_expenses` number: When > 0, overrides the fractional target with a monthly floor.
    - `employer_group_fraction` number: Fraction of income the group LTD plan replaces (e.g. 0.60).
    - `employer_group_monthly_max` number: Group benefit cap (0 = uncapped).
    - `employer_paid_premium` boolean: True ⇒ the group benefit is taxable.
    - `marginal_tax_rate` number: Applied to any taxable benefit.
    - `individual_monthly_benefit` number: Individually-owned policy benefit (tax-free).
    - `ssdi_monthly_benefit` number: Estimated SSDI monthly benefit (treated as tax-free).
    - `ssdi_offsets_group` boolean: Whether the group LTD contract reduces its benefit dollar-for-dollar by SSDI (the common 'other income' offset). Default true; set false for a rare non-offsetting plan or when there is no group coverage.
  - `result` object
    - `gross_monthly_income` number
    - `target_fraction_used` number: Replacement fraction the target reflects — the input fraction, or the fraction essential_monthly_expenses implies when that override is set.
    - `monthly_target` number: The income to replace.
    - `employer_group_gross` number: Group benefit before tax, net of any SSDI offset.
    - `employer_group_ssdi_offset` number: SSDI amount the group plan offset (0 if not offsetting).
    - `employer_group_net` number: After tax if employer-paid.
    - `employer_benefit_taxable` boolean
    - `individual_net` number
    - `ssdi_net` number
    - `total_existing_net` number: Net monthly benefits already in place.
    - `monthly_gap` number: max(0, target − existing net).
    - `annual_gap` number
    - `recommended_additional_monthly` number: = monthly gap.
    - `current_replacement_ratio` number: Existing net / gross monthly.
    - `coverage_adequate` boolean
  - `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)