> 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/english/sustainability/sustainability-subsidy-api/authentication-input-and-response.md). # Authentication, input and response ### Endpoint **`POST`** `https://api.altum.ai/subsidy` **Request headers** | Header | Required | Value | | -------------- | -------- | --------------------- | | `x-api-key` | Yes | Your Altum AI API key | | `Content-Type` | Yes | `application/json` | The fastest way to see the API working is to send a single field, `postcode`, and inspect the response. ```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" }' ``` This returns all available subsidies for the postcode (municipal, provincial, and national) with `Loans.eligible_programs` empty and no `isde_2026` block. From here, three usage flows extend the request: | Flow | Add to request | Returns | | -------------------------- | ------------------------ | ---------------------------------------- | | **Discover subsidies** | `level`, `limit`, `tags` | Filtered subsidies only | | **Check loan eligibility** | `applicant` object | Eligible loan programs with calculations | | **Estimate ISDE subsidy** | `isde` object | `isde_2026` calculation block | You can combine all three in a single request. Returns subsidies, loan eligibility, and ISDE 2026 estimates for a given postcode. The `applicant` and `isde` objects are optional. The response always returns the same top-level structure; sections you didn't request return empty arrays or are omitted. **Request body - top level**
FieldTypeRequiredDescription
postcodestringYesDutch postcode in 1234 AB format (with space).
levelarray of stringsNoFilter subsidies by level. One or more of municipality, province, national. Defaults to all three.
limitintegerNoMaximum number of subsidies returned per level.
tagsarray of stringsNoFilter subsidies by topic. See Tags reference.
loan_applicant_profile
objectNoPersonal and financial details for loan eligibility. See Applicant object.
isdeobjectNoProject details for ISDE 2026 calculation. See ISDE object.
**Complete request example** ```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" } ] } } ``` ### Usage flows #### Flow 1 - Discover subsidies only Send `postcode` with optional `level`, `limit`, and `tags`. The response returns subsidies grouped by level. `Loans.eligible_programs` will be empty and the `isde_2026` block will be absent. **Request** ```json { "postcode": "3511 AA", "level": ["municipality", "province", "national"], "limit": 5, "tags": ["Isolatie", "Warmtepompen"] } ``` **Response (truncated)** ```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" } ] } } ``` **Subsidy entry fields** | Field | Type | Description | | ----------------------- | ------ | -------------------------------------------------------------------------------------------------------------- | | `location_name` | string | Municipality, province, or country name. | | `name` | string | Program name (Dutch). | | `description` | string | Program description (Dutch). | | `eligibility` | string | Semicolon-separated eligibility conditions (Dutch). | | `application_deadlines` | string | Deadline string. Formats: `until:` or `from: to:`. Dates in Dutch (e.g. `31 december 2026`). | | `subsidy_amounts` | string | Amount range string. Format: `min:€ max:€`. | | `budget_ceilings` | string | Total budget cap for the program, if specified. | | `application_process` | string | How to apply (Dutch). | | `url` | string | Official program page. | | `contact_info` | string | Contact details for the issuing body. | | `level` | string | One of `municipality`, `province`, `national`. | #### Flow 2 - Loan eligibility Add the `applicant` object to the request. The response returns matching loan programs with applicant-specific calculations (interest rate, monthly payment, total cost). All fields are required when `applicant` is provided unless marked otherwise. | Field | Type | Description | | ---------------------------------- | --------------- | ------------------------------------------------------------------------------------ | | `age` | integer | Applicant's age in years. Some programs (e.g. NWF 1) have age caps. | | `is_homeowner` | boolean | Whether the applicant owns the property. | | `is_occupant` | boolean | Whether the applicant lives in the property. | | `residence_country` | string | Country of residence. Most programs require `Netherlands`. | | `property_use_residential_percent` | integer | Percentage of the property used for residential purposes (0–100). | | `credit_approved` | boolean | Whether the applicant has passed a credit check. | | `previously_rejected_nwf1` | boolean | Whether the applicant was previously rejected for an NWF 1 loan. | | `rejection_reason` | string \| null | Reason for prior rejection, if applicable. | | `requested_amount` | number | Requested loan amount in EUR. | | `existing_nwf_loan_balance` | number | Current outstanding balance on existing NWF loans (EUR). | | `specific_target_group` | boolean | Whether the applicant belongs to a specific target group eligible for special terms. | | `collective_neighborhood` | boolean | Whether the application is part of a collective neighbourhood project. | | `has_mortgage_security` | boolean | Whether a mortgage security is in place. | | `business_part_connected` | boolean \| null | Indicates connection to a business part of the property. | | `gross_household_income` | number | Gross annual household income in EUR. Used for income-based interest tiers. | | `desired_loan_period_years` | integer | Requested repayment period in years. | **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": [] } } ``` **Eligible program fields** | Field | Type | Description | | ------------------------------- | ------------------ | ---------------------------------------------------------------------------------- | | `program_name` | string | Loan product name. | | `description` | string | Short summary of the loan product. | | `min_max_loan_amount` | array `[min, max]` | Allowed loan amount range in EUR. | | `max_loan_period_years` | integer | Maximum repayment period in years. | | `interest_type` | string | Human-readable description of how interest is determined. | | `repayment` | string | Human-readable description of repayment terms. | | `key_features` | array of strings | Bullet points describing the program. | | `loan_amount` | number | Amount applied to this calculation (echoes `applicant.requested_amount`). | | `loan_period_years` | integer | Period applied to this calculation (echoes `applicant.desired_loan_period_years`). | | `applied_interest_rate_percent` | number | Interest rate applied for this specific applicant. | | `total_interest` | number | Total interest over the loan period (EUR). | | `total_cost` | number | Principal + total interest (EUR). | | `monthly_payment` | number | Monthly annuity (EUR), rounded to two decimals. | #### Flow 3 - ISDE 2026 calculation Add the `isde` object to the request. The response returns an `isde_2026` block with the total subsidy estimate, per-category breakdown | Measure | Codes | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Insulation | WB002a, WB002b, WB002c, WB002d, WB002f, WB143, WB001e, WB009a, WB009b, WB009c, WB392, WB207, WB242, WB268, WB361, WB362, WB363, WB004, WB005, WB145, WB212a, WB214b | | Glazing | WB019a, WB019b, WB161a, WB147b, WB147c | | Heat pump | WB112, WB149a, WB149b, WB149c, WB159, WB198, WB199 | | Solar boiler | WB136, WB138, WB157 | | Ventilation | WB405, WB418 | | District heating connection | WB131 | | Electric cooking | ES001 | {% hint style="info" %} By default only the area (`area_m2`) needs to be supplied to **Insulation** and **Glazing** {% endhint %} **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" ] } } ``` **`isde_2026 object`** | Field | Type | Description | | -------------------- | ------- | ------------------------------------------------- | | `total_subsidy_euro` | number | Sum of all category amounts (EUR). | | `category_count` | integer | Number of categories that returned an amount > 0. | | `eligibility` | object | eligibility and conditions per category group. | | `breakdown` | object | Per-category breakdown. See below. | **`breakdown`** Each category (`insulation`, `glazing`, `ventilation`, `heat_pump_primary`, `heat_pump_extra`, `solar_boiler`, `district_heating`, `electric_cooking`) follows the same shape: ``` breakdown": { "category1": { "amount_RVO-code1": 400 }, "category2": { "amount_RVO-code2": 1750 } } ``` | Field | Type | Description | | ----------------- | ------ | -------------------------------------------------- | | `amount_RVO-code` | number | Calculated subsidy amount for this category (EUR). | {% hint style="info" %} Some RVO codes are not eligible for an ISDE subsidy. In such cases, you may receive the following warning: ```json "unrecognized_codes": [ "No ISDE subsidy available for code: WB142a" ] ``` {% endhint %} #### Flow 4 - Combined Send `postcode`, `applicant`, and `isde` in one request to get subsidies, loans, and ISDE calculation in a single response. The top-level response structure is the same as in the Complete request example. ### Tags reference The `tags` field filters subsidies by topic. Pass one or more values, exact case-sensitive match, Dutch only. **Sustainability (general)** `Duurzaamheid`, `Duurzaamheid en samenleving`, `Duurzaam ondernemen`, `Duurzaam bouwen en verbouwen`, `Duurzaam en slim rijden`, `Duurzaam financieren`, `Duurzaam produceren`, `Duurzaam voedsel`, `Verduurzamen` **Climate & emissions** `Klimaatadaptatie`, `Klimaatakkoord`, `Klimaatbeleid`, `Klimaatneutraal`, `Klimaatverandering`, `CO2`, `CO2-neutraal`, `CO2-opslag`, `CO2-reductie`, `Emissiereductie`, `Emissie`, `Emissiehandel`, `Niet-CO2-broeikasgassen` **Air quality** `Fijn stof`, `Luchtkwaliteit`, `NOx-beperkende technieken`, `Stikstof` **Renewable energy** `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` **Energy efficiency & buildings** `Energiebesparing`, `Energieopslag`, `Opslag van elektriciteit`, `Netcongestie`, `Isolatie`, `Isoleren`, `Warmtepompen`, `Warmte Koude Opslag`, `Duurzame warmte en koude`, `Ledverlichting`, `Ventilatie en binnenmilieu`, `Gebouwde omgeving` **Circular economy & materials** `Circulair ondernemen`, `Biobased economy`, `Biobased materialen`, `Afval`, `Grondstoffen`, `Valorisatie` **Nature & environment** `Natuur`, `Natuurbeheer`, `Natuurterreinen`, `Bodem`, `Oppervlaktewater`, `Grondwater`, `Verontreiniging`, `Lucht`, `Milieu`, `Milieuzorg`, `Eco-activiteiten` **Mobility & innovation** `Duurzame mobiliteit`, `Duurzame ontwikkeling`, `Duurzame technologie`, `Duurzame innovatie`, `Elektrisch rijden`, `Mobiliteit en ruimte` **UN SDGs** `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` {% tabs %} {% tab title="200: OK Standard response" %} ``` Successful response. ``` {% endtab %} {% tab title="400: Bad Request Unsuccessful response" %} 
{
// 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."
}

}
{% 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 %} --- # 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/english/sustainability/sustainability-subsidy-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.