M

Developer API

Contract documentation for MortMe's country-aware mortgage calculation route.

POST /api/v1/mortgage/calculate/

Endpoint status and base URL

The contract in this document is implemented by this Next application at POST /api/v1/mortgage/calculate/. In local development, use http://localhost:3000/api/v1/mortgage/calculate/. This build has NEXT_PUBLIC_SITE_URL configured as https://mortme.com, so the corresponding configured URL is https://mortme.com/api/v1/mortgage/calculate/. Configuring that variable supplies a base URL for links and examples; it does not by itself establish that an endpoint is deployed, publicly reachable, or suitable for production use.

Quick start

For a local application instance, send JSON with a supported country, loan principal, annual rate, and term. Omit paymentFrequency to use monthly. For another environment, replace only the local origin after confirming its route is deployed and reachable.

curl -X POST ${localEndpoint} \
  -H "Content-Type: application/json" \
  -d '{"country":"US","principal":400000,"annualInterestRatePercent":6.5,"termMonths":360}'

Minimal request

{
  "country": "US",
  "principal": 400000,
  "annualInterestRatePercent": 6.5,
  "termMonths": 360
}

Minimal response

A successful response is HTTP 200. This abbreviated example shows fields returned by the route; values depend on your inputs.

{
  "apiVersion": "v1",
  "metadata": { "engineVersion": "0.1.0", "country": "US", "currency": "USD" },
  "result": { "scheduledPaymentPerPeriod": 2528.27, "totalInterest": 510177.2, "provenance": "calculated" },
  "countrySpecific": { "us": { "pmi": null }, "au": null, "ca": null, "uk": null },
  "propertyMetrics": { "label": "LTV", "ltvPercent": null, "provenance": null },
  "provenance": "calculated"
}
Full request schema
{
  "country": "US | AU | CA | UK",
  "principal": 320000,
  "annualInterestRatePercent": 6.5,
  "termMonths": 360,
  "paymentFrequency": "monthly | semi-monthly | weekly | biweekly | fortnightly",
  "mode": "principal-and-interest | interest-only",
  "interestOnlyMonths": 0,
  "firstPaymentDate": "YYYY-MM-DD",
  "propertyValue": 400000,
  "extraPayments": {
    "monthlyAmount": 100,
    "oneTimeLumpSums": [{ "amount": 5000, "paymentNumber": 12 }]
  },
  "countryInputs": {
    "pmiMonthlyAmount": 125,
    "offsetBalance": 50000,
    "redrawAvailable": 3000,
    "lmiEstimate": 2500,
    "contractTermMonths": 60,
    "initialDealPeriodMonths": 24,
    "repaymentStrategy": "Describe the repayment strategy"
  }
}

This is the request contract, not a lender application schema. Only send countryInputs that apply to the selected country. Lump sums may use paymentNumber or date (YYYY-MM-DD), not both.

Full response schema
{
  "apiVersion": "v1",
  "metadata": {
    "engineVersion": "0.1.0", "country": "US", "currency": "USD",
    "countryRuleVersion": "us-2025-01",
    "countryRuleMetadata": { "…": "adapter metadata" },
    "calculation": { "engineVersion": "0.1.0", "country": "US", "currency": "USD", "calculationDate": "YYYY-MM-DD", "assumptionsVersion": "…" }
  },
  "result": {
    "paymentFrequency": "monthly", "paymentsPerYear": 12, "scheduledPaymentPerPeriod": 0,
    "monthlyEquivalentPayment": 0, "payoffDate": "YYYY-MM-DD | null", "monthsToPayoff": 0,
    "totalPrincipal": 0, "totalInterest": 0, "totalExtraPayments": 0, "totalCost": 0, "provenance": "calculated"
  },
  "countrySpecific": { "us": null, "au": null, "ca": null, "uk": null },
  "propertyMetrics": { "label": "LTV | LVR", "ltvPercent": 0, "provenance": "calculated" },
  "provenance": "calculated"
}

This is the response contract for a successful route call. The schedule is intentionally not returned. countrySpecific always has US, AU, CA, and UK keys; non-selected models are null.

Supported countries

  • US: user-provided PMI monthly amount.
  • Australia: offset, redraw, and LMI estimate concepts.
  • Canada: contract term, nominal semi-annual rate convention, and qualifying-rate model.
  • UK: initial deal period and repayment-strategy context.

Validation & limitations

  • Request bodies over 32 KiB are rejected. Money values must be 0–100,000,000; terms must be 1–1200 months; at most 24 lump sums are accepted.
  • Unsupported countries, country/payment-frequency combinations, and inapplicable country inputs return HTTP 400.
  • Error responses use { "apiVersion": "v1", "error": { "code": "...", "message": "..." } }. Validation errors can also include error.details.fields.
  • Production operators are responsible for configuring an appropriate distributed, atomic rate-limit adapter. A limited request returns HTTP 429 and may include Retry-After.
  • Production operators are responsible for CORS configuration appropriate to their environment. Errors do not include stack traces or submitted financial inputs.

Compliance & disclaimers

Results are calculations from submitted inputs and country-specific model assumptions. Present them as estimates: lender terms, payment timing, rounding, taxes, insurance, and program requirements can differ. MortMe is not a lender and this API must not be used to determine approval, eligibility, or a binding credit decision.

Need an embedded calculator?

Use the iframe integration when you do not need a custom interface.

View embed options