Authentication, input and response
Headers
Content-Type
string
application/json
x-api-key*
string
Unique API key from Altum. Obtain one via Mopsus (https://mopsus.altum.ai)
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.
POST https://api.altum.ai/subsidy
Request body
Subsidy Request Model
Field
Type
Description
postcode*
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*
integer
Required. The applicant's age.
is_homeowner*
boolean
Required. Whether the applicant is a homeowner.
is_occupant*
boolean
Required. Whether the applicant is an occupant of the property.
residence_country*
string
Required. The applicant's country of residence.
property_use_residential_percent*
integer
Required. The percentage of the property used for residential purposes.
credit_approved*
boolean
Required. Whether the applicant has been approved for credit.
previously_rejected_nwf1*
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*
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*
integer
Required. The gross annual household income in EUR.
desired_loan_period_years*
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
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? 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)
}
}{
"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? 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)
}
}{
// Applicant validation failure:
{
"detail": "Applicant must be a credit-approved owner-occupier of an existing home in the Netherlands with ≥75% residential use."
}
// Invalid loan period:
{
"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."
}
}{
"detail": "Could not resolve postcode to a municipality."
}
{
"detail": "An unexpected error occurred while resolving the postcode."
}Last updated