Authentication, input and response

Calculate Mortgage for a Dutch Residential Property

POST https://api.altum.ai/v1/mortgage-calculator

Headers

Name	Type	Description
x-api-key*	string	Unique API Key from Altum. Create one via Mopsus (https://mopsus.altum.ai)
Content-Type	string	application/json

Request Body

Name	Type	Description
postcode	string	Zipcode of the object in 4-digit + 2-letter format (e.g. "1234AB")
housenumber	number	House number of the object
houseaddition	string	House letter and addition of the object
gross_annual_income*	number	Primary applicant's gross annual income (in €)
partner_gross_income	number	Partner's gross annual income (in €). Defaults to 0
applicant_type	string	"single" or "couple". Affects the €17,000 single-applicant bonus. Defaults to "single"
existing_debts	number	Monthly existing debt obligations (in €). Reduces borrowable amount. Defaults to 0
student_loan	number	Monthly student loan payment (in €). Reduces borrowable amount. Defaults to 0
interest_rate*	number	Annual interest rate as a percentage (e.g. 3.5 for 3.5%)
mortgage_type*	string	"annuity" or "linear"
loan_term_years*	number	Loan term in years. Maximum is 30
purchase_price	number	Purchase price (in €). Used as market value if address enrichment cannot find a WOZ value. Required if no address is provided
down_payment	number	Own funds to reduce principal (in €). Defaults to 0
fixed_rate_period	number	Years the interest rate is fixed
nhg_eligible	boolean	Whether NHG applies. If omitted, derived automatically: true when purchase price ≤ €470,000
first_time_buyer	boolean	True if the primary applicant is a first-time buyer. Affects transfer tax. Defaults to false
applicant_age	number	Primary applicant age. Required for first-time buyer transfer tax exemption

200: OK Successful response

{
	"postcode": "1234AB",
	"housenumber": "5",
	"houseaddition": null,
	"max_mortgage_amount": "180000.0",
	"max_mortgage_by_income": "197000.0",
	"principal": "180000.0",
	"monthly_payment_gross": "828.51",
	"monthly_payment_net": "620.05",
	"total_interest_paid": "118263.37",
	"total_costs": "304063.37",
	"transfer_tax": "3600.0",
	"transfer_tax_rate_used": "0.02",
	"affordability_ratio": "0.2486",
	"nhg_compliance": "True",
	"rate_used": "3.7",
	"loan_term_years": "30",
	"mortgage_type": "annuity",
	"single_bonus_applied": "17000.0",
	"debt_deduction_applied": "0.0",
	"data_enrichment_status": "fallback",
	"enrichment_data": {
		"found": "False",
		"woz_latest": null,
		"woz_latest_year": null
	},
	"warnings": [
		"Income allows a higher mortgage, but you are capped at the NHG limit of €450,000."
	],
	"metadata": {
		"nhg_price_limit": "470000",
		"nhg_cap": "450000",
		"income_multiplier": "4.5",
		"mortgage_interest_deduction_rate": "0.3756",
		"notary_cost": "1500",
		"appraisal_cost": "700",
		"market_value_source": "purchase_price",
		"market_value_used": "180000.0",
		"market_value_note": "purchase_price used — no WOZ found",
		"evaluation_date": "20260331"
	}
}

400: Bad Request

401: Unauthorized

403: Forbidden

500: Internal Server Error Service is not available and/or down

422: Unprocessable Entity

Request body

Example Request

{
  "postcode": "9636AA",
  "housenumber": 5,
  "gross_annual_income": 65000,
  "interest_rate": 3.5,
  "mortgage_type": "annuity",
  "loan_term_years": 30
}