# Authentication, input and response

### Headers

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

This is the main endpoint of the API. It retrieves a list of subsidies based on a user's postcode and, if provided, their personal and financial details for loan eligibility checking.

<mark style="color:green;">**`POST`**</mark> `https://api.altum.ai/subsidy`&#x20;

### Request body

**Subsidy Request Model**

| **Field**                                  | **Type**       | **Description**                                                                                      |
| ------------------------------------------ | -------------- | ---------------------------------------------------------------------------------------------------- |
| postcode<mark style="color:red;">\*</mark> | string         | **Required**. The Dutch postcode (e.g., "3511 AA").                                                  |
| level                                      | Array\[string] | Optional. A list of levels to filter subsidies by. Can be \["national", "province", "municipality"]. |
| limit                                      | integer        | Optional. The maximum number of subsidies to return for each level. Default is 10. Min 1, Max 100.   |
| applicant                                  | Applicant      | Optional. An object containing the applicant's details for loan eligibility checking.                |

**Applicant Model**

| **Field**                                                             | **Type**        | **Description**                                                                                                                                                 |
| --------------------------------------------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| age<mark style="color:red;">\*</mark>                                 | integer         | **Required**. The applicant's age.                                                                                                                              |
| is\_homeowner<mark style="color:red;">\*</mark>                       | boolean         | **Required**. Whether the applicant is a homeowner.                                                                                                             |
| is\_occupant<mark style="color:red;">\*</mark>                        | boolean         | **Required**. Whether the applicant is an occupant of the property.                                                                                             |
| residence\_country<mark style="color:red;">\*</mark>                  | string          | **Required**. The applicant's country of residence.                                                                                                             |
| property\_use\_residential\_percent<mark style="color:red;">\*</mark> | integer         | **Required**. The percentage of the property used for residential purposes.                                                                                     |
| credit\_approved<mark style="color:red;">\*</mark>                    | boolean         | **Required**. Whether the applicant has been approved for credit.                                                                                               |
| previously\_rejected\_nwf1<mark style="color:red;">\*</mark>          | boolean         | **Required**. Whether the applicant was previously rejected for an NWF1 loan.                                                                                   |
| rejection\_reason                                                     | RejectionReason | Optional. The reason for a previous rejection. Can be "income" or "other".                                                                                      |
| requested\_amount<mark style="color:red;">\*</mark>                   | integer         | **Required**. The amount of the loan the applicant is requesting.                                                                                               |
| existing\_nwf\_loan\_balance                                          | integer         | Optional. The applicant's existing NWF loan balance. Defaults to 0.                                                                                             |
| specific\_target\_group                                               | boolean         | Optional. Whether the applicant belongs to a specific target group for NWF2 loans. Defaults to false.                                                           |
| collective\_neighborhood                                              | boolean         | Optional. Whether the applicant is part of a collective neighborhood initiative for EBH loans. Defaults to false.                                               |
| has\_mortgage\_security                                               | boolean         | Optional. Whether the applicant has mortgage security for EBH loans. Defaults to false.                                                                         |
| business\_part\_connected                                             | boolean         | Optional. Whether the business part of the property is connected to the residential part. Required if property\_use\_residential\_percent is between 75 and 99. |
| gross\_household\_income<mark style="color:red;">\*</mark>            | integer         | **Required**. The gross annual household income in EUR.                                                                                                         |
| desired\_loan\_period\_years<mark style="color:red;">\*</mark>        | integer         | **Required**. The desired loan period in years (1-20).                                                                                                          |

**Example Complete Input**

A valid `POST` request body would look like this:

```
{
  "postcode": "9400 AA",
  "level": ["municipality", "national"],
  "limit": 10,
  "applicant": {
    "age": 45,
    "is_homeowner": true,
    "is_occupant": true,
    "residence_country": "Netherlands",
    "property_use_residential_percent": 100,
    "credit_approved": true,
    "previously_rejected_nwf1": false,
    "rejection_reason": null,
    "requested_amount": 10000,
    "existing_nwf_loan_balance": 0,
    "specific_target_group": false,
    "collective_neighborhood": false,
    "has_mortgage_security": false,
    "business_part_connected": null,
    "gross_household_income": 75000,
    "desired_loan_period_years": 12
  }
}
```

Upon a successful `POST` request, the API returns a `200 OK` status with a JSON object containing the results.

### Subsidies API Response Model

| **Field**    | **Type** | **Description**                                      |
| ------------ | -------- | ---------------------------------------------------- |
| postal\_code | string   | The postcode used for the search.                    |
| municipality | string   | The municipality resolved from the postcode.         |
| province     | string   | The province resolved from the postcode.             |
| disclaimer   | string   | A disclaimer about the freshness of the data.        |
| Loans        | object   | An object containing eligible loan programs.         |
| subsidies    | object   | An object containing subsidies categorized by level. |

**Loans Object**

| Field              | Type           | Description                                                                                                                                                      |
| ------------------ | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| eligible\_programs | Array\[object] | A list of loan programs for which the applicant is eligible. Each object contains detailed information about the loan program, including financial calculations. |

**subsidies Object**

| Field                   | Type           | Description                                            |
| ----------------------- | -------------- | ------------------------------------------------------ |
| municipality\_subsidies | Array\[object] | A list of subsidies available at the municipal level.  |
| province\_subsidies     | Array\[object] | A list of subsidies available at the provincial level. |
| national\_subsidies     | Array\[object] | A list of subsidies available at the national level.   |

### Output <a href="#id-5.-output" id="id-5.-output"></a>

Upon a successful `POST` request, the API returns a `200 OK` status with a JSON object containing the results.

**Example Complete Output**

```
{
"postal_code": "9400 AA",
"municipality": "Assen",
"province": "Drenthe",
"disclaimer": "These subsidies were available at the moment of scraping and may have closed since. Please verify the status on the official websites.",
"Loans": {
 	"eligible_programs": [
		{
		"program_name": "Energy Savings Loan (NWF 1)",
		"description": "Standard loan for homeowners (≤75 years old) to finance energy-saving home improvements.",
		"min_max_loan_amount": [1000,28000],
		"max_loan_period_years": 20,
		"interest_type": "Income-based: 0% if household income ≤€60,000, otherwise 3.61% fixed",
		"repayment": "Monthly annuity (up to 20 years; 15 years for heat pumps/batteries if >33% of loan)",
		"key_features": [
		"Requires professional contractor installation",
		"Applies to 18 defined energy-saving measures",
		"Early repayment allowed without penalty (min €250)",
		"No mortgage required; construction deposit used"],
		"loan_amount": 10000,
		"loan_period_years": 12,
		"applied_interest_rate_percent": 3.61,
		"total_interest": 2336.7,
		"total_cost": 12336.7,
		"monthly_payment": 85.67},
		{
		 ... (more loans)
		]
	},
"subsidies": {
		"municipality_subsidies": [
			{
			"name": "Fixteams en advies",
			"description": "De subsidie 'Fixteams en advies' is bedoeld voor stichtingen, coöperaties en andere maatschappelijke organisaties die inwoners in bepaalde wijken van Amersfoort helpen om energie te besparen. De subsidie kan worden gebruikt voor de installatie van kleine energiebesparende maatregelen en het geven van advies over mogelijke oplossingen en geldregelingen. Het doel is om de energiezuinigheid van woningen te verbeteren.",
			"url": "https://www.amersfoort.nl/subsidieregeling-fixteams-en-advies",
			"level": "municipality",
			"location_name": "Amersfoort",
			"eligibility": "De organisatie moet een stichting, coöperatie of andere maatschappelijke organisatie zijn; De organisatie moet ingeschreven staan bij de KvK; De organisatie moet een zakelijk bankrekeningnummer hebben; De organisatie moet contacten hebben in de wijk; De organisatie moet kantoor houden in de wijk; De organisatie moet ervaring hebben met het begeleiden van vrijwilligers en/of mensen op een stage- of werkervaringsplaats; De organisatie moet ervaring hebben met het toepassen van energiebesparende maatregelen"
			} 
			{
			... (municipality subsidies)
			}
		],
		"province_subsidies": [],
		"national_subsidies": [
			{
				"name": "Circulaire economie en MIA\\Vamil",
				"description": "In een circulaire economie bestaat geen afval en worden grondstoffen steeds opnieuw gebruikt. Investeert u in bedrijfsmiddelen die de circulaire economie bevorderen?&nbsp;Dan heeft u mogelijk belastingvoordeel met de MIA\\Vamil. Dit voordeel kan oplopen tot ruim 14% van de investeringskosten.\n",
				"url": "https://www.rvo.nl/subsidies-financiering/mia-vamil/ondernemers/circulaire-economie",
				"level": "national",
				"location_name": "Netherlands",
				"eligibility": "Grootbedrijf, MKB (ook zzp)"
			},
			{
			... (national subsidies)
			}
}
```

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

```
{
"postal_code": "9400 AA",
"municipality": "Assen",
"province": "Drenthe",
"disclaimer": "These subsidies were available at the moment of scraping and may have closed since. Please verify the status on the official websites.",
"Loans": {
 	"eligible_programs": [
		{
		"program_name": "Energy Savings Loan (NWF 1)",
		"description": "Standard loan for homeowners (≤75 years old) to finance energy-saving home improvements.",
		"min_max_loan_amount": [1000,28000],
		"max_loan_period_years": 20,
		"interest_type": "Income-based: 0% if household income ≤€60,000, otherwise 3.61% fixed",
		"repayment": "Monthly annuity (up to 20 years; 15 years for heat pumps/batteries if >33% of loan)",
		"key_features": [
		"Requires professional contractor installation",
		"Applies to 18 defined energy-saving measures",
		"Early repayment allowed without penalty (min €250)",
		"No mortgage required; construction deposit used"],
		"loan_amount": 10000,
		"loan_period_years": 12,
		"applied_interest_rate_percent": 3.61,
		"total_interest": 2336.7,
		"total_cost": 12336.7,
		"monthly_payment": 85.67},
		{
		 ... (more loans)
		]
	},
"subsidies": {
		"municipality_subsidies": [
			{
			"name": "Fixteams en advies",
			"description": "De subsidie 'Fixteams en advies' is bedoeld voor stichtingen, coöperaties en andere maatschappelijke organisaties die inwoners in bepaalde wijken van Amersfoort helpen om energie te besparen. De subsidie kan worden gebruikt voor de installatie van kleine energiebesparende maatregelen en het geven van advies over mogelijke oplossingen en geldregelingen. Het doel is om de energiezuinigheid van woningen te verbeteren.",
			"url": "https://www.amersfoort.nl/subsidieregeling-fixteams-en-advies",
			"level": "municipality",
			"location_name": "Amersfoort",
			"eligibility": "De organisatie moet een stichting, coöperatie of andere maatschappelijke organisatie zijn; De organisatie moet ingeschreven staan bij de KvK; De organisatie moet een zakelijk bankrekeningnummer hebben; De organisatie moet contacten hebben in de wijk; De organisatie moet kantoor houden in de wijk; De organisatie moet ervaring hebben met het begeleiden van vrijwilligers en/of mensen op een stage- of werkervaringsplaats; De organisatie moet ervaring hebben met het toepassen van energiebesparende maatregelen"
			} 
			{
			... (municipality subsidies)
			}
		],
		"province_subsidies": [],
		"national_subsidies": [
			{
				"name": "Circulaire economie en MIA\\Vamil",
				"description": "In een circulaire economie bestaat geen afval en worden grondstoffen steeds opnieuw gebruikt. Investeert u in bedrijfsmiddelen die de circulaire economie bevorderen?&nbsp;Dan heeft u mogelijk belastingvoordeel met de MIA\\Vamil. Dit voordeel kan oplopen tot ruim 14% van de investeringskosten.\n",
				"url": "https://www.rvo.nl/subsidies-financiering/mia-vamil/ondernemers/circulaire-economie",
				"level": "national",
				"location_name": "Netherlands",
				"eligibility": "Grootbedrijf, MKB (ook zzp)"
			},
			{
			... (national subsidies)
			}
}
```

{% endtab %}

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

<pre><code>{
// Applicant validation failure:
{
  "detail": "Applicant must be a credit-approved owner-occupier of an existing home in the Netherlands with ≥75% residential use."
}

<strong>// Invalid loan period:
</strong>{
  "detail": "Desired loan period must be between 1 and 20 years."
}

// No eligible loan programs:
{
  "detail": "No eligible loan program found for this applicant. Check criteria at www.warmtefonds.nl or contact your municipality for Duurzaamheidslening availability."
}

}
</code></pre>

{% endtab %}

{% tab title="404 Not Found" %}

```
{
  "detail": "Could not resolve postcode to a municipality."
}


```

{% endtab %}

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

```
{
  "detail": "An unexpected error occurred while resolving the postcode."
}
```

{% endtab %}
{% endtabs %}