Financial Hub · Calculation
Tracked mortgage phases and insurance
Projects dated payment, balance and insurance rows for fixed, adjustable, interest-only, balloon and HELOC contracts.
Visitors can explore a sample snapshot. Saved accounts, loans and properties open within the member’s own Financial Hub.
Example result · payoffOn: 2027-02-01 See output
- Cost per success
- 1 calculation credit
- Production plans
- Standard, Business, Scale, Enterprise
Plan allowances - Free sandbox
- Not available
Integration example
Make a request
Use a production key scoped to financial-hub-tracked-mortgage.
Keep the key on your server. A successful call uses 1 calculation credit.
Set HT_PRODUCTION_KEY on your server. Save as example.mjs and run node example.mjs with Node.js 18 or later.
import { randomUUID } from "node:crypto";
const key = process.env.HT_PRODUCTION_KEY;
if (!key) throw new Error("Set HT_PRODUCTION_KEY on your server.");
const endpoint = "https://calc.hasstechapi.com/v2/calc/financial-hub-tracked-mortgage";
const input = {
"terms": {
"kind": "conventional",
"structure": "fixed",
"total_payment": 525,
"includes_escrow": true,
"tax_monthly": 10,
"mi_monthly": 5
},
"current": {
"balance": 1000,
"ratePercent": 12,
"firstDueOn": "2027-01-01",
"dueDay": 1
},
"horizonMonths": 2
};
const requestId = process.env.HT_REQUEST_ID || Date.now() + "." + randomUUID();
// Keep this ID to look up usage if the connection is interrupted.
console.error("Usage lookup ID:", requestId);
const response = await fetch(endpoint, {
method: "POST",
redirect: "error",
headers: {
"Authorization": "Bearer " + key,
"Content-Type": "application/json",
"Idempotency-Key": requestId
},
body: JSON.stringify(input)
});
if (!response.ok) {
const problem = await response.json().catch(() => null);
const code = problem?.error?.code || response.statusText;
const delay = response.headers.get("retry-after");
if (delay) console.error("Retry-After (seconds):", delay);
console.error("HTTP " + response.status + " " + code + ". Usage lookup ID: " + requestId);
if (Array.isArray(problem?.error?.details)) {
for (const issue of problem.error.details) console.error("Input issue:", JSON.stringify(issue));
}
process.exitCode = 1;
} else {
console.log(JSON.stringify(await response.json(), null, 2));
} cURL (shell)
(
set -eu
: "${HT_PRODUCTION_KEY:?Set HT_PRODUCTION_KEY on your server}"
request_id="${HT_REQUEST_ID:-}"
if [ -z "$request_id" ]; then
request_id=$(python3 -c 'import time, uuid; print(str(time.time_ns() // 1000000) + "." + str(uuid.uuid4()))')
fi
printf 'Usage lookup ID: %s\n' "$request_id" >&2
# On INVALID_INPUT, read error.details in the JSON response body.
curl --disable --silent --show-error --fail-with-body --include \
--request POST 'https://calc.hasstechapi.com/v2/calc/financial-hub-tracked-mortgage' \
--header "Authorization: Bearer $HT_PRODUCTION_KEY" \
--header 'Content-Type: application/json' \
--header "Idempotency-Key: $request_id" \
--data-binary @- <<'HT_INPUT'
{
"terms": {
"kind": "conventional",
"structure": "fixed",
"total_payment": 525,
"includes_escrow": true,
"tax_monthly": 10,
"mi_monthly": 5
},
"current": {
"balance": 1000,
"ratePercent": 12,
"firstDueOn": "2027-01-01",
"dueDay": 1
},
"horizonMonths": 2
}
HT_INPUT
) If your request fails
400 INVALID_INPUT-
Read
error.detailswhen present. Node prints each issue. cURL returns the JSON body. Eachpathpoints into your request. An empty path refers to the whole body.Check the accepted inputs for required fields, units and ranges. Send the corrected JSON as a new request.
401or403- Check that the server has the bearer key for the endpoint’s environment and that the key includes
financial-hub-tracked-mortgage. 429- Read the service error code, check your allowance, and wait for the
Retry-Afterinterval when supplied before trying again. - Lost response,
409or503 - Open Request lookup, select the same environment and enter the printed usage lookup ID. A settled ID has already consumed credits. To retry the same calculation, set
HT_REQUEST_IDto the original ID and reuse the same inputs. A settled request does not return its result again. Unset the variable for a new request, which can consume credits.
The usage lookup ID is the Idempotency-Key your server sends. The response’s x-request-id identifies the HTTP exchange for support.
Output
Example result
These values come from running this operation on the example inputs.
payoffOn- 2027-02-01
maturityOn- 2027-02-01
insurance.kind- pmi
Example status: incomplete
Result warnings
- Insurance outlook needs additional inputs: original_value.
How to interpret this result
- Escrow and insurance never amortize principal. ARM projections use the supplied index and margin with note caps, floor and eighth-point rounding. Insurance rules use the app’s November 2026 source.
Full example response (JSON)
{
"status": "incomplete",
"result": {
"rows": [
{
"n": 1,
"date": "2027-01-01",
"rate": 12,
"phase": "amortizing",
"scheduled": 510,
"payment": 510,
"interest": 10,
"principal": 500,
"balance": 500,
"nonLoan": 15
},
{
"n": 2,
"date": "2027-02-01",
"rate": 12,
"phase": "amortizing",
"scheduled": 510,
"payment": 505,
"interest": 5,
"principal": 500,
"balance": 0,
"nonLoan": 15
}
],
"changes": [],
"payoffOn": "2027-02-01",
"maturityOn": "2027-02-01",
"maturityImplied": true,
"needsMaturity": false,
"insurance": {
"kind": "pmi",
"monthly": 5,
"endsOn": null,
"firstPaymentWithoutOn": null,
"lifeOfLoan": false,
"requestOn": null,
"basis": "none",
"rule": "Add the home value at purchase to see when PMI ends.",
"needs": [
"original_value"
]
},
"principalInterest": 510,
"extraPrincipal": 0
},
"formulaVersion": "financial-hub-tracked-mortgage-1.0.0",
"units": {
"money": "USD",
"rate": "percent per year",
"dates": "UTC date-only"
},
"assumptions": [
"Escrow and insurance never amortize principal. ARM projections use the supplied index and margin with note caps, floor and eighth-point rounding. Insurance rules use the app’s November 2026 source."
],
"warnings": [
"Insurance outlook needs additional inputs: original_value."
],
"creditCost": 1
}Request contract
Accepted inputs
Fields for this example. Expand the schema for all supported combinations and limits.
FieldType, units and limits
termsRequiredterms.kindRequiredProgram or lien type.
Allowed: "conventional", "jumbo", "fha", "va", "usda", "second", "heloc"terms.structureRequiredLoan structure; use fixed for HELOC.
Allowed: "fixed", "arm", "interest_only", "balloon"terms.total_paymentRequiredTotal billed payment including entered mortgage insurance and escrow per month (USD, to the cent).
Min 0 · Max 10000000000 · Step 0.01terms.includes_escrowRequiredPayment includes property tax and homeowners insurance.
terms.tax_monthlyOptionalEscrowed property tax per month (USD, to the cent).
Min 0 · Max 10000000000 · Step 0.01terms.insurance_monthlyOptionalEscrowed homeowners insurance per month (USD, to the cent).
Min 0 · Max 10000000000 · Step 0.01terms.mi_monthlyOptionalBilled mortgage insurance or USDA fee per month (USD, to the cent).
Min 0 · Max 10000000000 · Step 0.01terms.extra_principalOptionalAdditional principal per month (USD, to the cent).
Min 0 · Max 10000000000 · Step 0.01terms.biweeklyOptionalModel 26 half payments per year as extra principal.
terms.original_amountOptionalOriginal financed note amount (USD, to the cent).
Min 0.01 · Max 10000000000 · Step 0.01terms.original_valueOptionalOriginal property value (USD, to the cent).
Min 0.01 · Max 10000000000 · Step 0.01terms.first_payment_onOptionalFirst payment at origination
Format: date · Min length 10 · Max length 10terms.term_monthsOptionalOriginal mortgage term (whole months).
Min 1 · Max 1200terms.original_rateOptionalOriginal APR (percentage points, up to six decimals).
Min 0 · Max 100 · Step 0.000001terms.maturity_onOptionalLast scheduled payment or balloon due date
Format: date · Min length 10 · Max length 10terms.fha_ltv_at_most_90OptionalFHA LTV was at most 90 percent at closing.
terms.fha_case_assigned_onOptionalFHA case assignment date
Format: date · Min length 10 · Max length 10terms.io_ends_onOptionalFinal interest-only payment date
Format: date · Min length 10 · Max length 10terms.draw_ends_onOptionalFinal draw-period payment date
Format: date · Min length 10 · Max length 10terms.repay_monthsOptionalHELOC amortizing repayment term (whole months).
Min 1 · Max 1200terms.armOptionalterms.arm.productOptionalARM product (default 5/6).
Allowed: "5/6", "7/6", "10/6", "5/1", "7/1", "10/1", "other"terms.arm.next_change_onRequiredNext interest-rate change date in the note.
Format: date · Min length 10 · Max length 10terms.arm.adjust_every_monthsOptionalReset interval (whole months).
Min 1 · Max 1200terms.arm.initial_capOptionalFirst reset cap (percentage points, up to six decimals).
Min 0 · Max 100 · Step 0.000001terms.arm.periodic_capOptionalSubsequent reset cap (percentage points, up to six decimals).
Min 0 · Max 100 · Step 0.000001terms.arm.lifetime_capOptionalLifetime increase cap (percentage points, up to six decimals).
Min 0 · Max 100 · Step 0.000001terms.arm.marginOptionalContract margin (percentage points, up to six decimals).
Min 0 · Max 100 · Step 0.000001terms.arm.index_valueOptionalCaller-assumed index (percentage points, up to six decimals).
Min 0 · Max 100 · Step 0.000001terms.arm.floor_rateOptionalContractual floor (percentage points, up to six decimals).
Min 0 · Max 100 · Step 0.000001terms.arm.initial_rateOptionalInitial note rate (percentage points, up to six decimals).
Min 0 · Max 100 · Step 0.000001terms.arm.adjusted_beforeOptionalA first reset has already occurred.
currentRequiredcurrent.balanceRequiredPrincipal on the valuation date (USD, to the cent).
Min 0.01 · Max 10000000000 · Step 0.01current.ratePercentRequiredCurrent annual note rate (percentage points, up to six decimals).
Min 0 · Max 100 · Step 0.000001current.firstDueOnRequiredNext due date
Format: date · Min length 10 · Max length 10current.dueDayRequiredContractual payment day (clamped at month end).
Min 1 · Max 31current.anchorOnOptionalAs-of date of the current balance
Format: date · Min length 10 · Max length 10horizonMonthsOptionalMaximum rows, default 600. A missing future date outside the horizon stays null. (whole months).
Min 1 · Max 1200Example request body (JSON)
{
"terms": {
"kind": "conventional",
"structure": "fixed",
"total_payment": 525,
"includes_escrow": true,
"tax_monthly": 10,
"mi_monthly": 5
},
"current": {
"balance": 1000,
"ratePercent": 12,
"firstDueOn": "2027-01-01",
"dueDay": 1
},
"horizonMonths": 2
} Full JSON schema
{
"type": "object",
"properties": {
"terms": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"description": "Program or lien type.",
"enum": [
"conventional",
"jumbo",
"fha",
"va",
"usda",
"second",
"heloc"
]
},
"structure": {
"type": "string",
"description": "Loan structure; use fixed for HELOC.",
"enum": [
"fixed",
"arm",
"interest_only",
"balloon"
]
},
"total_payment": {
"type": "number",
"description": "Total billed payment including entered mortgage insurance and escrow per month (USD, to the cent).",
"minimum": 0,
"maximum": 10000000000,
"multipleOf": 0.01
},
"includes_escrow": {
"type": "boolean",
"description": "Payment includes property tax and homeowners insurance."
},
"tax_monthly": {
"type": "number",
"description": "Escrowed property tax per month (USD, to the cent).",
"minimum": 0,
"maximum": 10000000000,
"multipleOf": 0.01
},
"insurance_monthly": {
"type": "number",
"description": "Escrowed homeowners insurance per month (USD, to the cent).",
"minimum": 0,
"maximum": 10000000000,
"multipleOf": 0.01
},
"mi_monthly": {
"type": "number",
"description": "Billed mortgage insurance or USDA fee per month (USD, to the cent).",
"minimum": 0,
"maximum": 10000000000,
"multipleOf": 0.01
},
"extra_principal": {
"type": "number",
"description": "Additional principal per month (USD, to the cent).",
"minimum": 0,
"maximum": 10000000000,
"multipleOf": 0.01
},
"biweekly": {
"type": "boolean",
"description": "Model 26 half payments per year as extra principal."
},
"original_amount": {
"type": "number",
"description": "Original financed note amount (USD, to the cent).",
"minimum": 0.01,
"maximum": 10000000000,
"multipleOf": 0.01
},
"original_value": {
"type": "number",
"description": "Original property value (USD, to the cent).",
"minimum": 0.01,
"maximum": 10000000000,
"multipleOf": 0.01
},
"first_payment_on": {
"type": "string",
"description": "First payment at origination",
"format": "date",
"minLength": 10,
"maxLength": 10,
"pattern": "^[1-9][0-9]{3}-[0-9]{2}-[0-9]{2}$"
},
"term_months": {
"type": "integer",
"description": "Original mortgage term (whole months).",
"minimum": 1,
"maximum": 1200
},
"original_rate": {
"type": "number",
"description": "Original APR (percentage points, up to six decimals).",
"minimum": 0,
"maximum": 100,
"multipleOf": 0.000001
},
"maturity_on": {
"type": "string",
"description": "Last scheduled payment or balloon due date",
"format": "date",
"minLength": 10,
"maxLength": 10,
"pattern": "^[1-9][0-9]{3}-[0-9]{2}-[0-9]{2}$"
},
"fha_ltv_at_most_90": {
"type": "boolean",
"description": "FHA LTV was at most 90 percent at closing."
},
"fha_case_assigned_on": {
"type": "string",
"description": "FHA case assignment date",
"format": "date",
"minLength": 10,
"maxLength": 10,
"pattern": "^[1-9][0-9]{3}-[0-9]{2}-[0-9]{2}$"
},
"io_ends_on": {
"type": "string",
"description": "Final interest-only payment date",
"format": "date",
"minLength": 10,
"maxLength": 10,
"pattern": "^[1-9][0-9]{3}-[0-9]{2}-[0-9]{2}$"
},
"draw_ends_on": {
"type": "string",
"description": "Final draw-period payment date",
"format": "date",
"minLength": 10,
"maxLength": 10,
"pattern": "^[1-9][0-9]{3}-[0-9]{2}-[0-9]{2}$"
},
"repay_months": {
"type": "integer",
"description": "HELOC amortizing repayment term (whole months).",
"minimum": 1,
"maximum": 1200
},
"arm": {
"type": "object",
"properties": {
"product": {
"type": "string",
"description": "ARM product (default 5/6).",
"enum": [
"5/6",
"7/6",
"10/6",
"5/1",
"7/1",
"10/1",
"other"
]
},
"next_change_on": {
"type": "string",
"description": "Next interest-rate change date in the note.",
"format": "date",
"minLength": 10,
"maxLength": 10,
"pattern": "^[1-9][0-9]{3}-[0-9]{2}-[0-9]{2}$"
},
"adjust_every_months": {
"type": "integer",
"description": "Reset interval (whole months).",
"minimum": 1,
"maximum": 1200
},
"initial_cap": {
"type": "number",
"description": "First reset cap (percentage points, up to six decimals).",
"minimum": 0,
"maximum": 100,
"multipleOf": 0.000001
},
"periodic_cap": {
"type": "number",
"description": "Subsequent reset cap (percentage points, up to six decimals).",
"minimum": 0,
"maximum": 100,
"multipleOf": 0.000001
},
"lifetime_cap": {
"type": "number",
"description": "Lifetime increase cap (percentage points, up to six decimals).",
"minimum": 0,
"maximum": 100,
"multipleOf": 0.000001
},
"margin": {
"type": "number",
"description": "Contract margin (percentage points, up to six decimals).",
"minimum": 0,
"maximum": 100,
"multipleOf": 0.000001
},
"index_value": {
"type": "number",
"description": "Caller-assumed index (percentage points, up to six decimals).",
"minimum": 0,
"maximum": 100,
"multipleOf": 0.000001
},
"floor_rate": {
"type": "number",
"description": "Contractual floor (percentage points, up to six decimals).",
"minimum": 0,
"maximum": 100,
"multipleOf": 0.000001
},
"initial_rate": {
"type": "number",
"description": "Initial note rate (percentage points, up to six decimals).",
"minimum": 0,
"maximum": 100,
"multipleOf": 0.000001
},
"adjusted_before": {
"type": "boolean",
"description": "A first reset has already occurred."
}
},
"required": [
"next_change_on"
],
"additionalProperties": false
}
},
"required": [
"kind",
"structure",
"total_payment",
"includes_escrow"
],
"additionalProperties": false
},
"current": {
"type": "object",
"properties": {
"balance": {
"type": "number",
"description": "Principal on the valuation date (USD, to the cent).",
"minimum": 0.01,
"maximum": 10000000000,
"multipleOf": 0.01
},
"ratePercent": {
"type": "number",
"description": "Current annual note rate (percentage points, up to six decimals).",
"minimum": 0,
"maximum": 100,
"multipleOf": 0.000001
},
"firstDueOn": {
"type": "string",
"description": "Next due date",
"format": "date",
"minLength": 10,
"maxLength": 10,
"pattern": "^[1-9][0-9]{3}-[0-9]{2}-[0-9]{2}$"
},
"dueDay": {
"type": "integer",
"description": "Contractual payment day (clamped at month end).",
"minimum": 1,
"maximum": 31
},
"anchorOn": {
"type": "string",
"description": "As-of date of the current balance",
"format": "date",
"minLength": 10,
"maxLength": 10,
"pattern": "^[1-9][0-9]{3}-[0-9]{2}-[0-9]{2}$"
}
},
"required": [
"balance",
"ratePercent",
"firstDueOn",
"dueDay"
],
"additionalProperties": false
},
"horizonMonths": {
"type": "integer",
"description": "Maximum rows, default 600. A missing future date outside the horizon stays null. (whole months).",
"minimum": 1,
"maximum": 1200
}
},
"required": [
"terms",
"current"
],
"additionalProperties": false
}Production endpoint: POST https://calc.hasstechapi.com/v2/calc/financial-hub-tracked-mortgage
Formula: financial-hub-tracked-mortgage-1.0.0