Life insurance needs calculator

What the DIME-style coverage estimate means

Many households already keep a single outstanding-debts total that folds mortgage and education loans into one line item, so this capability uses a streamlined contract: annual_income, years_of_replacement, and outstanding_debts. Years of replacement must be strictly positive—zero or negative years do not define a meaningful income-replacement horizon and are rejected as invalid_input. On success the response echoes the three inputs, reports income_replacement and recommended_coverage rounded to two decimal places for stable currency-style comparisons, and includes a short method tag and formula string you can show next to the answer.

Input contract, response shape, and error behaviour

Example: seventy-five thousand annual income, ten years of replacement, and fifty thousand of debts yields seven hundred fifty thousand of income replacement and eight hundred thousand of recommended coverage. Failed validation is not billed. POST a JSON body with three required finite numbers. annual_income is the gross yearly income to replace; aliases income, yearly_income, and salary are accepted so forms and spreadsheets can reuse familiar column names. years_of_replacement is the horizon in years; aliases years, replacement_years, and income_years map to the same field, and the value must be greater than zero or the task fails with invalid_input naming years_of_replacement. outstanding_debts is the lump sum of obligations you want the policy to clear—mortgage remainder, car loans, credit cards, personal loans—with aliases debts, total_debt, and debt. Each field may arrive as a JSON number or a numeric string; missing fields, empty strings, and non-finite values fail with invalid_input. Negative annual_income or outstanding_debts are rejected because a coverage estimate cannot start from a negative income base or a negative debt pile in this model. When validation passes, the body returns annual_income, years_of_replacement, outstanding_debts, income_replacement (income times years), recommended_coverage (income_replacement plus debts), method set to a DIME-style label, and formula restating the closed form. The pure parse path never calls a carrier API, never samples randomness, and never depends on the system clock, so goldens and client tests compare byte-for-byte across runtimes when they pin the same three inputs.

Where a life insurance needs API earns its keep

Households use a life insurance needs calculator when a new salary, a home purchase, or a child forces a first conversation about how much cover would keep dependents whole if income stopped. Financial coaches and educators need a deterministic oracle that marks non-positive replacement years as invalid instead of silently returning zero coverage that a buggy form might treat as success. Product teams wire the same contract into onboarding wizards so users see a starter face amount before a human underwriter or agent refines it. Keep requests small, pin rounded recommended_coverage values in tests, and you get reproducible coverage estimates for worksheets, LMS plugins, and edge workers without standing up actuarial infrastructure of your own. When you later add education costs or a separate mortgage field in a spreadsheet, simply include those balances in outstanding_debts here so the DIME-style total stays aligned with the full mnemonic while the API surface remains three fields.