---
title: "Life-insurance needs analysis (capital-needs / DIME + human-life-value)"
method: POST
path: "/v1/insurance/life-needs"
tags: ["Insurance"]
---

# Life-insurance needs analysis (capital-needs / DIME + human-life-value)

`POST /v1/insurance/life-needs`

## Request

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

Sizes how much life insurance a household needs and the gap against coverage already in force. The capital-needs (DIME) method sums final expenses, debts, the mortgage, an education fund, an emergency fund, and the present value of the survivors' income gap over a chosen horizon (default 70% of income, discounted at a real rate), then subtracts existing assets and insurance for the recommended additional coverage. When years_to_retirement is given, it also reports the human-life-value cross-check (present value of future earnings net of self-consumption). Deterministic; not insurance advice.

## Request body

- LifeNeedsRequest
  - `annual_income` number, required: The insured's gross annual income to replace.
  - `income_replace_years` integer, required: Horizon for the income need.
  - `income_replace_fraction` number: Share of income the survivors need. Omit for 0.70.
  - `survivor_annual_income` number: Income the survivor still earns/receives (reduces the gap).
  - `final_expenses` number: Funeral + final medical.
  - `debts` number: Non-mortgage debts to clear.
  - `mortgage_balance` number: Mortgage payoff.
  - `education_fund` number: Lump sum for children's education.
  - `emergency_fund` number: Cash reserve for the survivors.
  - `existing_assets` number: Liquid assets available to survivors.
  - `existing_life_insurance` number: Coverage already in force.
  - `real_return` number: Real rate for present-valuing the income need. Omit for 0.03, or set 0 for a conservative undiscounted need.
  - `years_to_retirement` integer: Remaining working years; > 0 computes the human-life-value cross-check.
  - `self_consumption_fraction` number: Share the insured consumes (HLV). Omit for 0.25.
  - `effective_tax_rate` number: HLV uses after-tax income. Omit for gross (0).

## Response `200`

The needs analysis

- LifeNeedsResponse
  - `result_id` string
  - `engine_version` string
  - `inputs` LifeNeedsRequest
    - `annual_income` number, required: The insured's gross annual income to replace.
    - `income_replace_years` integer, required: Horizon for the income need.
    - `income_replace_fraction` number: Share of income the survivors need. Omit for 0.70.
    - `survivor_annual_income` number: Income the survivor still earns/receives (reduces the gap).
    - `final_expenses` number: Funeral + final medical.
    - `debts` number: Non-mortgage debts to clear.
    - `mortgage_balance` number: Mortgage payoff.
    - `education_fund` number: Lump sum for children's education.
    - `emergency_fund` number: Cash reserve for the survivors.
    - `existing_assets` number: Liquid assets available to survivors.
    - `existing_life_insurance` number: Coverage already in force.
    - `real_return` number: Real rate for present-valuing the income need. Omit for 0.03, or set 0 for a conservative undiscounted need.
    - `years_to_retirement` integer: Remaining working years; > 0 computes the human-life-value cross-check.
    - `self_consumption_fraction` number: Share the insured consumes (HLV). Omit for 0.25.
    - `effective_tax_rate` number: HLV uses after-tax income. Omit for gross (0).
  - `result` object
    - `replacement_fraction_used` number
    - `annual_income_gap` number: Income to replace, net of survivor income.
    - `income_replacement_need` number: Present value of the gap over the horizon.
    - `real_return_used` number
    - `final_expenses` number
    - `debts` number
    - `mortgage_balance` number
    - `education_fund` number
    - `emergency_fund` number
    - `capital_need_total` number: Sum of all needs.
    - `existing_resources` number: Assets + existing insurance.
    - `additional_coverage_needed` number: The recommendation (>= 0).
    - `human_life_value` number: PV of future earnings net of self-consumption (0 without years_to_retirement).
  - `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)