> For the complete documentation index, see [llms.txt](https://docs.altum.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.altum.ai/verduurzamen/duurzaamheid-subsidies-api/authentication-input-and-response.md).
# Authenticatie, invoer en resultaat
### Endpoint
**`POST`** `https://api.altum.ai/subsidy`
**Request headers**
| Header | Verplicht | Waarde |
| -------------- | --------- | ----------------------- |
| `x-api-key` | Ja | Je Altum AI API-sleutel |
| `Content-Type` | Ja | `application/json` |
De snelste manier om de API werkend te zien, is door één veld te sturen, `postcode`, en het antwoord te bekijken.
```bash
curl -X POST https://api.altum.ai/subsidy \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"postcode": "3511 AA"
}'
```
Dit geeft alle beschikbare subsidies voor de postcode terug (gemeentelijk, provinciaal en landelijk), met `Loans.eligible_programs` leeg en zonder `isde_2026`-blok.
Vanaf hier zijn er drie gebruiksflows die het verzoek uitbreiden:
| Flow | Toevoegen aan verzoek | Geeft terug |
| -------------------------------- | ------------------------ | -------------------------------------------- |
| Subsidies ontdekken | `level`, `limit`, `tags` | Alleen gefilterde subsidies |
| Leningseligibiliteit controleren | `applicant`-object | Geschikte leningprogramma's met berekeningen |
| ISDE-subsidie schatten | `isde`-object | `isde_2026`-berekeningsblok |
Je kunt alle drie combineren in één verzoek.
Geeft subsidies, leningseligibiliteit en ISDE 2026-schattingen terug voor een opgegeven postcode. De objecten `applicant` en `isde` zijn optioneel. Het antwoord heeft altijd dezelfde structuur op het hoogste niveau. Secties die je niet hebt opgevraagd zijn leeg of ontbreken.
#### Request body - hoogste niveau
| Veld | Type | Verplicht | Beschrijving |
| ------------------------ | ----------------- | --------- | --------------------------------------------------------------------------------------------------------- |
| `postcode` | string | Ja | Nederlandse postcode in het formaat `1234 AB` (met spatie). |
| `level` | array van strings | Nee | Filtert subsidies op niveau. Eén of meer van `municipality`, `province`, `national`. Standaard alle drie. |
| `limit` | integer | Nee | Maximumaantal subsidies per niveau. |
| `tags` | array van strings | Nee | Filtert subsidies op onderwerp. Zie [Tags-referentie](#tags-referentie). |
| `loan_applicant_profile` | object | Nee | Persoonlijke en financiële gegevens voor leningseligibiliteit. Zie het aanvragerobject. |
| `isde` | object | Nee | Projectgegevens voor de ISDE 2026-berekening. Zie het ISDE-object. |
**Volledig verzoekvoorbeeld**
```json
{
"postcode": "3511 AA",
"level": ["municipality", "national"],
"limit": 5,
"tags": ["Isolatie", "Warmtepompen"],
"loan_applicant_profile": {
"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": 15000,
"existing_nwf_loan_balance": 0,
"specific_target_group": false,
"collective_neighborhood": false,
"has_mortgage_security": false,
"business_part_connected": null,
"gross_household_income": 55000,
"desired_loan_period_years": 10
},
"isde_rvo": {
"measures": [
{ "code": "WB002a", "area_m2": 80 },
{ "code": "WB212a", "area_m2": 40 },
{ "code": "WB019b", "area_m2": 50 },
{ "code": "WB149c" },
{ "code": "WB157" },
{ "code": "WB405" },
{ "code": "WB142a" }
]
}
}
```
### Gebruiksflows
#### Flow 1 - Alleen subsidies ophalen
Stuur `postcode` met optioneel `level`, `limit` en `tags`. Het antwoord geeft subsidies terug, gegroepeerd per niveau. `Loans.eligible_programs` is leeg en het `isde_2026`-blok ontbreekt.
**Request**
```json
{
"postcode": "3511 AA",
"level": ["municipality", "province", "national"],
"limit": 5,
"tags": ["Isolatie", "Warmtepompen"]
}
```
**Response (ingekort)**
```json
{
"postal_code": "3511 AA",
"municipality": "Utrecht",
"province": "Utrecht",
"disclaimer": "These subsidies were available at the moment of scraping and may have closed since. Please verify on official websites.",
"Loans": { "eligible_programs": [] },
"subsidies": {
"municipality_subsidies": [
{
"location_name": "Utrecht",
"name": "Vraag subsidie isoleren kleine vve",
"description": "Deze subsidie van de gemeente Utrecht is bedoeld voor kleine Verenigingen van Eigenaren (VvE's)...",
"eligibility": "Eigenaar zijn van een woning in een kleine VvE...",
"application_deadlines": "until:31 december 2026",
"subsidy_amounts": "min:€8.000 max:€8.000",
"budget_ceilings": null,
"application_process": "Maak eventueel een afspraak voor hulp bij de aanvraag...",
"url": "https://loket.digitaal.utrecht.nl/nl/producten/kleine-vve-isoleren-extra-subsidie-aanvragen",
"contact_info": "subsidie@utrecht.nl, 030 – 286 33 36",
"level": "municipality"
}
],
"province_subsidies": [
{
"location_name": "Utrecht",
"name": "Subsidieregeling Bereikbaarheid",
"description": "De Subsidieregeling Bereikbaarheid van de provincie Utrecht...",
"eligibility": "Fiets: Wegbeheerders binnen de provincie Utrecht...",
"application_deadlines": "from:7 januari 2026 to:30 september 2026",
"subsidy_amounts": null,
"budget_ceilings": null,
"application_process": "Dien een projectplanning in met duidelijke mijlpalen...",
"url": "https://www.provincie-utrecht.nl/loket/subsidies/subsidieregeling-bereikbaarheid",
"contact_info": "Voor algemene vragen: subsidies@provincie-utrecht.nl...",
"level": "province"
}
],
"national_subsidies": [
{
"location_name": "Netherlands",
"name": "ISDE: Warmtepomp woningeigenaren",
"description": "Met de Investeringssubsidie duurzame energie en energiebesparing (ISDE)...",
"eligibility": "U laat de warmtepomp eerst installeren, daarna vraagt u de subsidie aan...",
"application_deadlines": "Aanvragen tot en met 31 december 2030.",
"subsidy_amounts": null,
"budget_ceilings": null,
"application_process": "Voor uw aanvraag heeft u de DigiD-app nodig...",
"url": "https://www.rvo.nl/subsidies-financiering/isde/woningeigenaren/warmtepomp",
"contact_info": "Ministerie van Economische Zaken en Klimaat",
"level": "national"
}
]
}
}
```
**Velden van een subsidie-item**
| Veld | Type | Beschrijving |
| ----------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------- |
| `location_name` | string | Naam van gemeente, provincie of land. |
| `name` | string | Naam van het programma (Nederlands). |
| `description` | string | Beschrijving van het programma (Nederlands). |
| `eligibility` | string | Voorwaarden gescheiden door puntkomma's (Nederlands). |
| `application_deadlines` | string | Deadlinestring. Formaten: `until:` of `from: to:`. Datums in het Nederlands (bv. `31 december 2026`). |
| `subsidy_amounts` | string | Bedragenrange als string. Formaat: `min:€ max:€`. |
| `budget_ceilings` | string | Totaal budgetplafond voor het programma, indien opgegeven. |
| `application_process` | string | Hoe aan te vragen (Nederlands). |
| `url` | string | Officiële programmapagina. |
| `contact_info` | string | Contactgegevens van de uitgevende instantie. |
| `level` | string | Eén van `municipality`, `province`, `national`. |
#### Flow 2 - Leningseligibiliteit
Voeg het `applicant`-object toe aan het verzoek. Het antwoord geeft passende leningsprogramma's terug met berekeningen toegespitst op de aanvrager, zoals rentepercentage, maandlast en totale kosten.
Alle velden zijn verplicht wanneer `applicant` is opgegeven, tenzij anders vermeld.
| Veld | Type | Beschrijving |
| ---------------------------------- | --------------- | -------------------------------------------------------------------------------------------------- |
| `age` | integer | Leeftijd van de aanvrager in jaren. Sommige programma's, zoals NWF 1, hanteren een leeftijdsgrens. |
| `is_homeowner` | boolean | Of de aanvrager eigenaar is van de woning. |
| `is_occupant` | boolean | Of de aanvrager in de woning woont. |
| `residence_country` | string | Land van verblijf. De meeste programma's vereisen `Netherlands`. |
| `property_use_residential_percent` | integer | Percentage van de woning dat residentieel wordt gebruikt (`0`–`100`). |
| `credit_approved` | boolean | Of de aanvrager een kredietcheck heeft doorstaan. |
| `previously_rejected_nwf1` | boolean | Of de aanvrager eerder is afgewezen voor een NWF 1-lening. |
| `rejection_reason` | string \| null | Reden van een eerdere afwijzing, indien van toepassing. |
| `requested_amount` | number | Gevraagd leningbedrag in euro. |
| `existing_nwf_loan_balance` | number | Huidig openstaand saldo op bestaande NWF-leningen, in euro. |
| `specific_target_group` | boolean | Of de aanvrager tot een specifieke doelgroep behoort met bijzondere voorwaarden. |
| `collective_neighborhood` | boolean | Of de aanvraag onderdeel is van een collectief buurtproject. |
| `has_mortgage_security` | boolean | Of er een hypothecaire zekerheid is. |
| `business_part_connected` | boolean \| null | Geeft een verbinding aan met een zakelijk deel van het pand. |
| `gross_household_income` | number | Bruto jaarinkomen van het huishouden in euro. Dit bepaalt inkomensafhankelijke renteklassen. |
| `desired_loan_period_years` | integer | Gewenste aflossingsperiode in jaren. |
**Request**
```json
{
"postcode": "3511 AA",
"loan_applicant_profile": {
"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": 15000,
"existing_nwf_loan_balance": 0,
"specific_target_group": false,
"collective_neighborhood": false,
"has_mortgage_security": false,
"business_part_connected": null,
"gross_household_income": 55000,
"desired_loan_period_years": 10
}
}
```
**Response**
```json
{
"postal_code": "3511 AA",
"municipality": "Utrecht",
"province": "Utrecht",
"disclaimer": "These subsidies were available at the moment of scraping and may have closed since. Please verify on 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": 15000,
"loan_period_years": 10,
"applied_interest_rate_percent": 0,
"total_interest": 0,
"total_cost": 15000,
"monthly_payment": 125
},
{
"program_name": "Sustainability Loan (Duurzaamheidslening)",
"description": "A low-interest loan offered through municipalities in collaboration with SVn...",
"min_max_loan_amount": [2500, 25000],
"max_loan_period_years": 15,
"interest_type": "Fixed rate: typically 1.7% for 10 years (loans ≤€7,500) or 15 years (loans >€7,500)",
"repayment": "Monthly annuity payments; early repayment allowed without penalty.",
"key_features": [
"Available only in participating municipalities",
"Loan amount depends on local program limits",
"Funds are managed through an SVn building depot for direct payment to contractors",
"Fixed interest rate for the entire loan term",
"Requires prior approval (Toewijzingsbrief) from the municipality before applying at SVn",
"Intended for sustainability measures improving energy efficiency"
],
"applied_interest_rate_percent": 1.7,
"loan_amount": 15000,
"loan_period_years": 10,
"total_interest": 1321.7,
"total_cost": 16321.7,
"monthly_payment": 136.01
}
]
},
"subsidies": {
"municipality_subsidies": [],
"province_subsidies": [],
"national_subsidies": []
}
}
```
**Velden van een passend programma**
| Veld | Type | Beschrijving |
| ------------------------------- | ------------------ | --------------------------------------------------------------------------------------------- |
| `program_name` | string | Naam van het leningsproduct. |
| `description` | string | Korte samenvatting van het leningsproduct. |
| `min_max_loan_amount` | array `[min, max]` | Toegestane leningrange in euro. |
| `max_loan_period_years` | integer | Maximale looptijd in jaren. |
| `interest_type` | string | Tekstuele beschrijving van hoe de rente wordt bepaald. |
| `repayment` | string | Tekstuele beschrijving van de aflossingsvoorwaarden. |
| `key_features` | array van strings | Bullets met kenmerken van het programma. |
| `loan_amount` | number | Bedrag dat is gebruikt in deze berekening (echo van `applicant.requested_amount`). |
| `loan_period_years` | integer | Looptijd die is gebruikt in deze berekening (echo van `applicant.desired_loan_period_years`). |
| `applied_interest_rate_percent` | number | Rentepercentage dat voor deze specifieke aanvrager is toegepast. |
| `total_interest` | number | Totale rente over de looptijd (€). |
| `total_cost` | number | Hoofdsom + totale rente (€). |
| `monthly_payment` | number | Maandelijkse annuïteit (€), afgerond op twee decimalen. |
#### Flow 3 - ISDE 2026-berekening
Voeg het `isde`-object toe aan het verzoek. Het antwoord geeft een `isde_2026`-blok terug met de totale subsidieschatting en een uitsplitsing per categorie.
| Maatregel | Codes |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Isolatie | `WB002a`, `WB002b`, `WB002c`, `WB002d`, `WB002f`, `WB143`, `WB001e`, `WB009a`, `WB009b`, `WB009c`, `WB392`, `WB207`, `WB242`, `WB268`, `WB361`, `WB362`, `WB363`, `WB004`, `WB005`, `WB145`, `WB212a`, `WB214b` |
| Beglazing | `WB019a`, `WB019b`, `WB161a`, `WB147b`, `WB147c` |
| Warmtepomp | `WB112`, `WB149a`, `WB149b`, `WB149c`, `WB159`, `WB198`, `WB199` |
| Zonneboiler | `WB136`, `WB138`, `WB157` |
| Ventilatie | `WB405`, `WB418` |
| Aansluiting op warmtenet | `WB131` |
| Elektrisch koken | `ES001` |
Voor isolatie en beglazing hoef je standaard alleen `area_m2` op te geven.
**Request**
```json
{
"postcode": "3511 AA",
"isde_rvo": {
"measures": [
{ "code": "WB002a", "area_m2": 80 },
{ "code": "WB212a", "area_m2": 40 },
{ "code": "WB019b", "area_m2": 50 },
{ "code": "WB149c" },
{ "code": "WB157" },
{ "code": "WB405" },
{ "code": "WB142a" }
]
}
}
```
**Response**
```json
{
"postal_code": "3511 AA",
"municipality": "Utrecht",
"province": "Utrecht",
"disclaimer": "These subsidies were available at the moment of scraping and may have closed since. Please verify on official websites.",
"Loans": { "eligible_programs": [] },
"subsidies": {
"municipality_subsidies": [],
"province_subsidies": [],
"national_subsidies": []
},
"isde_2026": {
"total_subsidy_euro": 8525,
"category_count": 5,
"eligibility": {
"insulation": [
"apply <24 months after installation",
"only receive one subsidy for cavity wall, facade, floor, roof, attic or attic floor insulation"
],
"glazing": [
"apply <24 months after installation",
"you can apply for glass insulation 2 times"
],
"heat_pump": [
"apply <24 months after installation",
"entire installation is done by a building installation company",
"not second-hand products"
],
"solar_boiler": [
"apply <24 months after installation",
"entire installation is done by a (construction) installation company",
"not second-hand products"
],
"ventilation": [
"installed on or after 1 January 2026",
"apply <24 months after installation"
]
},
"breakdown": {
"insulation": {
"amount_WB002a": 0,
"amount_WB212a": 1300
},
"glazing": {
"amount_WB019b": 2250
},
"ventilation": {
"amount_WB405": 400
},
"heat_pump_primary": {
"amount_WB149c": 2825
},
"solar_boiler": {
"amount_WB157": 1750
}
},
"unrecognized_codes": [
"No ISDE subsidy available for code: WB142a"
]
}
}
```
**Velden op het hoogste niveau van `isde_2026`**
| Veld | Type | Beschrijving |
| -------------------- | ------- | ----------------------------------------------- |
| `total_subsidy_euro` | number | Som van alle categoriebedragen (€). |
| `category_count` | integer | Aantal categorieën dat een bedrag > 0 oplevert. |
| `eligibility` | object | Geschiktheid en voorwaarden per categoriegroep. |
| `breakdown` | object | Uitsplitsing per categorie. Zie hieronder. |
**`breakdown`**
Elke categorie (`insulation`, `glazing`, `ventilation`, `heat_pump_primary`, `heat_pump_extra`, `solar_boiler`, `district_heating`, `electric_cooking`) gebruikt dezelfde vorm:
```json
"breakdown": {
"category1": { "amount_RVO-code1": 400 },
"category2": { "amount_RVO-code2": 1750 }
}
```
| Veld | Type | Beschrijving |
| ----------------- | ------ | ----------------------------------------------------- |
| `amount_RVO-code` | number | Berekend subsidiebedrag voor deze categorie, in euro. |
Sommige RVO-codes komen niet in aanmerking voor ISDE-subsidie. Dan kan deze waarschuwing verschijnen:
```json
"unrecognized_codes": [
"No ISDE subsidy available for code: WB142a"
]
```
#### Flow 4 - Gecombineerd
Stuur `postcode`, `applicant` en `isde` in één verzoek om subsidies, leningen en de ISDE-berekening tegelijk te ontvangen. De antwoordstructuur op het hoogste niveau is dezelfde als in het volledige verzoekvoorbeeld.
### Tags-referentie
Het `tags`-veld filtert subsidies op onderwerp. Geef één of meer waarden op, exacte hoofdlettergevoelige overeenkomst, alleen in het Nederlands.
**Duurzaamheid (algemeen)** Duurzaamheid, Duurzaamheid en samenleving, Duurzaam ondernemen, Duurzaam bouwen en verbouwen, Duurzaam en slim rijden, Duurzaam financieren, Duurzaam produceren, Duurzaam voedsel, Verduurzamen
**Klimaat en emissies** Klimaatadaptatie, Klimaatakkoord, Klimaatbeleid, Klimaatneutraal, Klimaatverandering, CO2, CO2-neutraal, CO2-opslag, CO2-reductie, Emissiereductie, Emissie, Emissiehandel, Niet-CO2-broeikasgassen
**Luchtkwaliteit** Fijn stof, Luchtkwaliteit, NOx-beperkende technieken, Stikstof
**Hernieuwbare energie** Hernieuwbare energie, Duurzame energie, Duurzame energievoorziening, Duurzame elektriciteit, Zonnepanelen, Zon-PV-installaties, Zonneboilers, Wind, Wind op land, Wind op zee, Windmolens, Windturbines, Waterstof, Waterstofcellen, Biomassaketels, Groen gas, Aardgasvrij, Energie uit water, Bodemenergie
**Energiebesparing en gebouwen** Energiebesparing, Energieopslag, Opslag van elektriciteit, Netcongestie, Isolatie, Isoleren, Warmtepompen, Warmte Koude Opslag, Duurzame warmte en koude, Ledverlichting, Ventilatie en binnenmilieu, Gebouwde omgeving
**Circulaire economie en materialen** Circulair ondernemen, Biobased economy, Biobased materialen, Afval, Grondstoffen, Valorisatie
**Natuur en milieu** Natuur, Natuurbeheer, Natuurterreinen, Bodem, Oppervlaktewater, Grondwater, Verontreiniging, Lucht, Milieu, Milieuzorg, Eco-activiteiten
**Mobiliteit en innovatie** Duurzame mobiliteit, Duurzame ontwikkeling, Duurzame technologie, Duurzame innovatie, Elektrisch rijden, Mobiliteit en ruimte
**SDG's van de VN** SDG7 Betaalbare en duurzame energie, SDG11 Duurzame steden en gemeenschappen, SDG12 Verantwoorde consumptie en productie, SDG13 Klimaatactie, SDG14 Leven in het water, SDG15 Leven op het land
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.altum.ai/verduurzamen/duurzaamheid-subsidies-api/authentication-input-and-response.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.