Authentication, input and response

Calculate Mortgage for a Dutch Residential Property

v1

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.p
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
partner_age	number	Partner age, Required for first-time buyer transfer tax exemption if it's couple
energy_label	string	Energy label of the property (E/F/G/C/D/A/B/A+/A++/A+++/A++++/A++++_warranty). Affects extra mortgage amount and NHG limit
sustainability_measures	boolean	True if sustainability measures from the TRHK list are included in the mortgage. Affects renovation bonus and NHG limit. Defaults to false
table_type	string	Nibud DSTI table to use. One of: "non_aow_box1" (default), "aow_box1", "non_aow_box3", "aow_box3"

200: OK Successful response

{
	"postcode": "9636AA",
	"housenumber": 5,
	"houseaddition": null,
	"max_mortgage_amount": 378000.0,
	"max_mortgage_by_income": 385248.93,
	"principal": 378000.0,
	"monthly_payment_gross": 1731.33,
	"monthly_payment_net": 1299.22,
	"total_interest_paid": 245278.39,
	"total_costs": 633038.39,
	"transfer_tax": 7560.0,
	"transfer_tax_rate_used": 0.02,
	"affordability_ratio": 0.2597,
	"nhg_compliance": true,
	"rate_used": 3.66,
	"rate_fetched_from": "dnb",
	"effective_rate_used": 3.66,
	"loan_term_years": 30,
	"mortgage_type": "annuity",
	"dsti_ratio_used": 0.253,
	"table_type_used": "non_aow_box1",
	"single_bonus_applied": 17000.0,
	"energy_label_bonus": 0.0,
	"renovation_bonus": 0.0,
	"debt_deduction_applied": 0.0,
	"data_enrichment_status": "enriched",
	"enrichment_data": {
		"found": true,
		"woz_latest": 378000.0,
		"woz_latest_year": 2024,
		"energy_label": "F"
	},
	"warnings": [
		"Income allows a higher mortgage, but you are capped at the NHG mortgage cap of €450,000."
	],
	"metadata": {
		"table_type": "non_aow_box1",
		"dsti_ratio_used": 0.253,
		"effective_rate_used": 3.66,
		"nhg_price_limit": 470000,
		"nhg_mortgage_cap": 450000.0,
		"energy_label_bonus": 0.0,
		"renovation_bonus": 0.0,
		"single_bonus_applied": 17000.0,
		"mortgage_interest_deduction_rate": 0.3748,
		"notary_cost": 1500.0,
		"appraisal_cost": 700.0,
		"market_value_source": "woz",
		"market_value_used": 378000.0,
		"market_value_note": "WOZ used — no purchase_price provided",
		"evaluation_date": "20260510"
	}
}

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": 80000,
  "mortgage_type": "annuity",
  "loan_term_years": 30
}