---
title: "Run one verified repayment projection"
method: POST
path: "/v1/projection"
tags: ["Finology.PublicApi"]
---

# Run one verified repayment projection

`POST /v1/projection`

## Request

- Base URL: `https://api.finology.tech` (the document declares no server; this is the origin it was published from)
- URL: `https://api.finology.tech/v1/projection`
- Auth: API key in header `X-Api-Key`

Computes the year-1 payment, payoff/forgiveness date, amount forgiven, forgiveness tax, total out-of-pocket and weighted-average rate for the supplied loans under one repayment plan. Calc-only; no stored client data is read or returned. Send "includeYearly": true to add `yearly` to each projection: year 0 is the loan book as sent; year n covers repayment months 12(n-1) to 12n-1 and gives the principal and interest balance after that year's last payment, the payments that year, the cumulative paid and any balance forgiven that year (date = that month). The series ends at the payoff or forgiveness month. Payments sum to totalOutOfPocket and forgiven amounts to amountForgiven. Money in cents. Default false: the field is then absent and the response is unchanged. A plan whose answer is an artifact of the prior-month count (nothing left to pay, the whole balance in one payment, or forgiveness before any payment) is a 400 naming the plan, the same plans the free calculator at /v1/calculators/loan leaves out.

## Request body

- ProjectionRequest
  - `scenario` ScenarioRequest, required
    - `planType` string, required
    - `adjustedGrossIncome` number, double, required
    - `spouseAdjustedGrossIncome` number, double, nullable
    - `spouseFederalLoanBalance` number, double, nullable
    - `filingStatus` string, required
    - `dependents` integer, required
    - `state` string, required
    - `workingTowardsPslf` boolean, required
    - `annualIncomeGrowth` number, double
    - `label` string, nullable
  - `loans` LoanRequest[], required
    - `loanType` string, required
    - `principalBalance` number, double, required
    - `interestBalance` number, double
    - `interestRate` number, double, required
    - `disbursedAmount` number, double
    - `idrMonthsInRepayment` integer
    - `pslfCount` integer
  - `includeYearly` boolean: Optional, default false. Send "includeYearly": true to add `yearly` to each projection: year 0 is the loan book as sent; year n covers repayment months 12(n-1) to 12n-1 and gives the principal and interest balance after that year's last payment, the payments that year, the cumulative paid and any balance forgiven that year (date = that month). The series ends at the payoff or forgiveness month. Payments sum to totalOutOfPocket and forgiven amounts to amountForgiven. Money in cents. Default false: the field is then absent and the response is unchanged.

## Response `200`

OK

- ProjectionResult
  - `label` string, nullable
  - `planType` string, nullable
  - `year1MonthlyPayment` number, double
  - `payoffOrForgivenessDate` string, date-time, nullable
  - `monthsToFinish` integer, nullable
  - `totalOutOfPocket` number, double
  - `amountForgiven` number, double
  - `forgivenessTaxesOwed` number, double
  - `forgivenessType` 'Pslf' | 'TimeBased' | 'Teacher' | 'None': Which forgiveness program the projection reaches: Pslf, TimeBased, Teacher or None. Keyed routes wrote the integer before 2026-10-14; that value is still sent as forgivenessTypeCode (0 Pslf, 1 TimeBased, 2 Teacher, 3 None), deprecated.
  - `forgivenessTypeCode` integer
  - `weightedAverageInterestRate` number, double
  - `yearly` YearlyPoint[], nullable: Present only when the request sent includeYearly: true. Send "includeYearly": true to add `yearly` to each projection: year 0 is the loan book as sent; year n covers repayment months 12(n-1) to 12n-1 and gives the principal and interest balance after that year's last payment, the payments that year, the cumulative paid and any balance forgiven that year (date = that month). The series ends at the payoff or forgiveness month. Payments sum to totalOutOfPocket and forgiven amounts to amountForgiven. Money in cents. Default false: the field is then absent and the response is unchanged.
    - `year` integer: 0 for the opening balance, then 1, 2, ... per year of repayment.
    - `date` string, date-time: The month the balances are read.
    - `principalBalance` number, double: Outstanding principal across the loan book at date.
    - `interestBalance` number, double: Outstanding unpaid interest across the loan book at date.
    - `paymentsThisYear` number, double: What the borrower paid during this year (0 for year 0).
    - `cumulativePaid` number, double: Paid from the repayment start through this year. The last point equals totalOutOfPocket.
    - `forgivenThisYear` number, double: Balance forgiven during this year; sums to amountForgiven.
  - `provenance` EngineProvenance
    - `computedBy` string, nullable
    - `engine` string, nullable
    - `parityVerified` boolean
    - `computedAtUtc` string, date-time
    - `ruleVersion` string, nullable
    - `citations` RuleCitation[], nullable
      - `id` string, nullable
      - `label` string, nullable
      - `authority` string, nullable
      - `url` string, nullable
      - `effectiveDate` string, nullable
      - `lastVerified` string, nullable
    - `knownOmissions` RuleOmissionNote[], nullable
      - `id` string, nullable
      - `label` string, nullable
      - `detail` string, nullable
      - `authority` string, nullable
      - `url` string, nullable
      - `effectiveDate` string, nullable
      - `expiresDate` string, nullable
      - `lastVerified` string, nullable
    - `answerId` string, uuid, nullable
    - `verifyUrl` string, nullable

## Other responses

- `400`: Bad Request

---

[API](https://skmtc.dev/finology/apis/finology-public-api.md) · [All operations](https://skmtc.dev/finology/apis/finology-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/finology/apis/finology-public-api/revisions/ed0522429715?raw)