Skip to content

Financial Hub · Calculation

Tracked mortgage phases and insurance

Projects dated payment, balance and insurance rows for fixed, adjustable, interest-only, balloon and HELOC contracts.

Open Financial Hub in HT Calc

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.

Production request

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 HT_PRODUCTION_KEY on your server. Run in a POSIX shell with cURL 7.76+ and Python 3.7+ to create a request ID.

(
  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.details when present. Node prints each issue. cURL returns the JSON body. Each path points 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.

401 or 403
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-After interval when supplied before trying again.
Lost response, 409 or 503
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_ID to 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

termsRequired
object
terms.kindRequired
string

Program or lien type.

Allowed: "conventional", "jumbo", "fha", "va", "usda", "second", "heloc"
terms.structureRequired
string

Loan structure; use fixed for HELOC.

Allowed: "fixed", "arm", "interest_only", "balloon"
terms.total_paymentRequired
number

Total billed payment including entered mortgage insurance and escrow per month (USD, to the cent).

Min 0 · Max 10000000000 · Step 0.01
terms.includes_escrowRequired
boolean

Payment includes property tax and homeowners insurance.

terms.tax_monthlyOptional
number

Escrowed property tax per month (USD, to the cent).

Min 0 · Max 10000000000 · Step 0.01
terms.insurance_monthlyOptional
number

Escrowed homeowners insurance per month (USD, to the cent).

Min 0 · Max 10000000000 · Step 0.01
terms.mi_monthlyOptional
number

Billed mortgage insurance or USDA fee per month (USD, to the cent).

Min 0 · Max 10000000000 · Step 0.01
terms.extra_principalOptional
number

Additional principal per month (USD, to the cent).

Min 0 · Max 10000000000 · Step 0.01
terms.biweeklyOptional
boolean

Model 26 half payments per year as extra principal.

terms.original_amountOptional
number

Original financed note amount (USD, to the cent).

Min 0.01 · Max 10000000000 · Step 0.01
terms.original_valueOptional
number

Original property value (USD, to the cent).

Min 0.01 · Max 10000000000 · Step 0.01
terms.first_payment_onOptional
string

First payment at origination

Format: date · Min length 10 · Max length 10
terms.term_monthsOptional
integer

Original mortgage term (whole months).

Min 1 · Max 1200
terms.original_rateOptional
number

Original APR (percentage points, up to six decimals).

Min 0 · Max 100 · Step 0.000001
terms.maturity_onOptional
string

Last scheduled payment or balloon due date

Format: date · Min length 10 · Max length 10
terms.fha_ltv_at_most_90Optional
boolean

FHA LTV was at most 90 percent at closing.

terms.fha_case_assigned_onOptional
string

FHA case assignment date

Format: date · Min length 10 · Max length 10
terms.io_ends_onOptional
string

Final interest-only payment date

Format: date · Min length 10 · Max length 10
terms.draw_ends_onOptional
string

Final draw-period payment date

Format: date · Min length 10 · Max length 10
terms.repay_monthsOptional
integer

HELOC amortizing repayment term (whole months).

Min 1 · Max 1200
terms.armOptional
object
terms.arm.productOptional
string

ARM product (default 5/6).

Allowed: "5/6", "7/6", "10/6", "5/1", "7/1", "10/1", "other"
terms.arm.next_change_onRequired
string

Next interest-rate change date in the note.

Format: date · Min length 10 · Max length 10
terms.arm.adjust_every_monthsOptional
integer

Reset interval (whole months).

Min 1 · Max 1200
terms.arm.initial_capOptional
number

First reset cap (percentage points, up to six decimals).

Min 0 · Max 100 · Step 0.000001
terms.arm.periodic_capOptional
number

Subsequent reset cap (percentage points, up to six decimals).

Min 0 · Max 100 · Step 0.000001
terms.arm.lifetime_capOptional
number

Lifetime increase cap (percentage points, up to six decimals).

Min 0 · Max 100 · Step 0.000001
terms.arm.marginOptional
number

Contract margin (percentage points, up to six decimals).

Min 0 · Max 100 · Step 0.000001
terms.arm.index_valueOptional
number

Caller-assumed index (percentage points, up to six decimals).

Min 0 · Max 100 · Step 0.000001
terms.arm.floor_rateOptional
number

Contractual floor (percentage points, up to six decimals).

Min 0 · Max 100 · Step 0.000001
terms.arm.initial_rateOptional
number

Initial note rate (percentage points, up to six decimals).

Min 0 · Max 100 · Step 0.000001
terms.arm.adjusted_beforeOptional
boolean

A first reset has already occurred.

currentRequired
object
current.balanceRequired
number

Principal on the valuation date (USD, to the cent).

Min 0.01 · Max 10000000000 · Step 0.01
current.ratePercentRequired
number

Current annual note rate (percentage points, up to six decimals).

Min 0 · Max 100 · Step 0.000001
current.firstDueOnRequired
string

Next due date

Format: date · Min length 10 · Max length 10
current.dueDayRequired
integer

Contractual payment day (clamped at month end).

Min 1 · Max 31
current.anchorOnOptional
string

As-of date of the current balance

Format: date · Min length 10 · Max length 10
horizonMonthsOptional
integer

Maximum rows, default 600. A missing future date outside the horizon stays null. (whole months).

Min 1 · Max 1200
Example 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