---
title: "Compute the contribution required to reach a savings goal"
method: POST
path: "/v1/goal-funding"
tags: ["Utilities"]
---

# Compute the contribution required to reach a savings goal

`POST /v1/goal-funding`

## Request

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

Given a target amount, a horizon, an expected return, and any current savings, computes the periodic contribution needed to reach the goal. Deterministic.

## Request body

- GoalFundingRequest
  - `target_amount` number, required: Future amount to reach (nominal).
  - `current_savings` number
  - `years` number, required: Horizon in years (> 0, <= 200).
  - `annual_return` number, required: Expected nominal annual return (> -1, <= 1).
  - `periods_per_year` integer: Contribution frequency (1–366).
  - `contributions_at_beginning` boolean

## Response `200`

Funding plan

- GoalFundingResponse
  - `result_id` string
  - `engine_version` string
  - `inputs` GoalFundingRequest
    - `target_amount` number, required: Future amount to reach (nominal).
    - `current_savings` number
    - `years` number, required: Horizon in years (> 0, <= 200).
    - `annual_return` number, required: Expected nominal annual return (> -1, <= 1).
    - `periods_per_year` integer: Contribution frequency (1–366).
    - `contributions_at_beginning` boolean
  - `result` object
    - `required_periodic_contribution` number: Saving needed each period to hit the target.
    - `required_annual_contribution` number
    - `periods` number
    - `periods_per_year` integer
    - `total_contributions` number
    - `current_savings_future_value` number: What current savings alone grow to.
    - `projected_value` number
    - `goal_already_funded` boolean: True if current savings alone reach the target.
  - `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)