curatedapi
Browse the docs

Guides

Finance

Excel functions

Late payments

E-invoices

Accounting

Number checks

VAT and GST

Billing and pricing

Money and currencies

Dates and time

Math

Unit conversion

Everyday

Health

Savings goal API

How much to save each month (or week, or year) to reach a goal, or how long it takes with a given contribution.

POST https://api.curatedapi.com/v1/calc/finance/savings-goal

Solves the future-value-of-annuity equation either for the regular contribution or for the number of contributions. Interest compounds once per contribution period. The final balance is recomputed exactly with the rounded contribution, so you can see whether it lands on, above or below the goal.

Formula

FV = PV·(1+i)^n + PMT·((1+i)^n − 1)/i  [× (1+i) when paid at the start], i = annual rate ÷ periods per year
  • Amounts are plain numbers in any single currency; no currency conversion is done.

Inputs

Send numbers as strings to keep every digit. options sets precision and rounding (see numbers and rounding).

InputTypeDescription
goal_amount required decimal (string) The amount you want to reach. Allowed: > 0 and <= 1000000000000000. Unit: currency.
current_savings decimal (string)
default 0
Amount already saved. Allowed: >= 0 and <= 1000000000000000. Unit: currency.
annual_rate_percent required decimal (string) Expected annual interest or return in percent. Allowed: >= 0 and <= 100. Unit: percent.
solve_for contribution | time
default contribution
What to calculate. Options: contribution: the contribution needed to reach the goal in a given time; time: how many contributions are needed with a given contribution
years decimal (string) Time to reach the goal, in years (solve_for = contribution). Allowed: > 0 and <= 100. Unit: years.
contribution decimal (string) Contribution per period (solve_for = time). Allowed: > 0 and <= 1000000000000000. Unit: currency.
contribution_frequency monthly | semimonthly | biweekly | weekly | quarterly | annually
default monthly
How often you contribute. Options: monthly: 12 contributions a year; semimonthly: 24 contributions a year; biweekly: 26 contributions a year; weekly: 52 contributions a year; quarterly: 4 contributions a year; annually: 1 contribution a year
contribution_timing end | beginning
default end
When in each period you contribute. Options: end: at the end of each period (ordinary annuity); beginning: at the start of each period (annuity due)
options.rounding half_even | half_up | half_down | up | down | ceiling | floor Rounding mode applied once to each result. Default half_even.
options.decimals integer Round results to this many digits after the decimal point.

Result

Under result in the answer, next to exactness, precision, inputs, formula, references and warnings.

ResultTypeDescription
contributiondecimal (string)Contribution per period. Unit: currency.
number_of_contributionsintegerNumber of contributions.
yearsstringNumber of contributions ÷ contributions per year.
total_contributionsdecimal (string)Contribution × number of contributions. Unit: currency.
interest_earneddecimal (string)Final balance minus savings and contributions. Unit: currency.
final_balancedecimal (string)Balance after the last contribution. Unit: currency.

Examples

20,000 in 3 years at 4%, monthly

Requestcurl
curl https://api.curatedapi.com/v1/calc/finance/savings-goal \
  -H "Authorization: Bearer $CURATEDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "goal_amount": "20000",
    "annual_rate_percent": "4",
    "years": "3"
  }'
200 OKResponse
{
  "calculator": "finance/savings-goal@1",
  "result": {
    "contribution": "523.81",
    "number_of_contributions": 36,
    "years": "3",
    "total_contributions": "18857.16",
    "interest_earned": "1142.72",
    "final_balance": "19999.88"
  },
  "exactness": {
    "contribution": "exact",
    "total_contributions": "exact",
    "interest_earned": "rounded",
    "final_balance": "rounded"
  },
  "precision": {
    "rounding": "half_even",
    "decimals": 2
  },
  "inputs": {
    "goal_amount": "20000",
    "current_savings": "0",
    "annual_rate_percent": "4",
    "solve_for": "contribution",
    "years": "3",
    "contribution_frequency": "monthly",
    "contribution_timing": "end"
  },
  "formula": "FV = PV·(1+i)^n + PMT·((1+i)^n − 1)/i  [× (1+i) when paid at the start], i = annual rate ÷ periods per year",
  "references": [
    {
      "title": "Future value of an annuity (ordinary annuity and annuity due)",
      "url": "https://en.wikipedia.org/wiki/Annuity#Valuation"
    }
  ],
  "warnings": [
    {
      "code": "ROUNDED_SHORT",
      "message": "With the contribution rounded to 523.81, the final balance is 0.12 short of the goal; use options.rounding = 'ceiling' to stay at or above it."
    }
  ]
}

References

Results follow each calculator's documented rules and the sources listed. They are not financial, tax or legal advice. Check that the rules fit your case before you rely on a result. See the terms.

Errors share one format; see errors. Billing, retries and batches work the same for every endpoint.