# Authentication, input and response

### Calculate Mortgage for a Dutch Residential Property

<mark style="color:$success;">**`POST`**</mark> `https://api.altum.ai/v1/mortgage-calculator`

#### Headers

<table><thead><tr><th width="258.1484375">Name</th><th width="199.80078125">Type</th><th>Description</th></tr></thead><tbody><tr><td>x-api-key<mark style="color:red;">*</mark></td><td>string</td><td>Unique API Key from Altum. Create one via Mopsus (https://mopsus.altum.ai)</td></tr><tr><td>Content-Type</td><td>string</td><td>application/json</td></tr></tbody></table>

#### Request Body

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

{% tabs %}
{% tab title="200: OK Successful response" %}

```json
{
	"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"
	}
}
```

{% endtab %}

{% tab title="400: Bad Request" %}

```json
{
  "error": "Unable to process mortgage calculation at this time."
}
```

{% endtab %}

{% tab title="401: Unauthorized" %}

```json
{
  "output": "Please use https://api.altum.ai or visit https://mopsus.altum.ai to make your request."
}
```

{% endtab %}

{% tab title="403: Forbidden" %}

```json
{
  "message": "Forbidden"
}
```

{% endtab %}

{% tab title="500: Internal Server Error Service is not available and/or down" %}

```json
{
  "message": "Internal server error"
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity" %}

```json
{
  "detail": [
    {
      "type": "value_error",
      "msg": "applicant_type must be \"single\" or \"couple\"."
    }
  ]
}
```

{% endtab %}
{% endtabs %}

### Request body

#### Example Request

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